{
  "openapi": "3.1.0",
  "info": {
    "title": "Locatool Pro API by DevSupAi",
    "version": "1.0.0",
    "description": "Official OpenAPI 3.1 specification for Locatool Pro B2B SaaS platform (equipment and vehicle rental management, planning, electronic signatures, and invoicing) developed and maintained by DevSupAi.",
    "contact": {
      "name": "DevSupAi Developer Support",
      "email": "contact@devsupai.fr",
      "url": "https://locatool.devsupai.fr/developers"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://locatool.devsupai.fr/mentions-legales"
    }
  },
  "servers": [
    {
      "url": "https://locatool.devsupai.fr",
      "description": "Production Server"
    }
  ],
  "tags": [
    {
      "name": "Email & Documents",
      "description": "Transactional document dispatching via Brevo SMTP integration"
    },
    {
      "name": "Billing & Subscriptions",
      "description": "Stripe checkout sessions and customer portal management"
    },
    {
      "name": "Machine Readable & Meta",
      "description": "OpenAPI, MCP manifest, and agent discovery endpoints"
    }
  ],
  "paths": {
    "/api/email/send-document": {
      "post": {
        "tags": ["Email & Documents"],
        "summary": "Send rental documents via email",
        "description": "Dispatches quotes, rental contracts, invoices, or packing lists to customers via the organization's configured Brevo SMTP credentials.",
        "operationId": "sendDocumentEmail",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendDocumentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email successfully queued or sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendDocumentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error or missing configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Third-party Brevo SMTP API failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/stripe/checkout": {
      "post": {
        "tags": ["Billing & Subscriptions"],
        "summary": "Create Stripe Checkout session",
        "description": "Initializes a Stripe Checkout session for Starter, Pro, or Business subscriptions.",
        "operationId": "createCheckoutSession",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "example": "https://checkout.stripe.com/c/pay/cs_test_123"
                    },
                    "sessionId": {
                      "type": "string",
                      "example": "cs_test_123"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/stripe/portal": {
      "post": {
        "tags": ["Billing & Subscriptions"],
        "summary": "Create customer portal session",
        "description": "Generates a URL for the Stripe Customer Portal to allow customers to manage payment methods and invoices.",
        "operationId": "createPortalSession",
        "responses": {
          "200": {
            "description": "Portal session URL generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": ["Machine Readable & Meta"],
        "summary": "Retrieve OpenAPI 3.1 Specification in JSON",
        "description": "Returns the complete machine-readable OpenAPI specification for Locatool Pro by DevSupAi.",
        "operationId": "getOpenApiJson",
        "responses": {
          "200": {
            "description": "Valid OpenAPI 3.1.0 document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/mcp.json": {
      "get": {
        "tags": ["Machine Readable & Meta"],
        "summary": "Model Context Protocol (MCP) Manifest",
        "description": "Provides the MCP server manifest for AI agents, autonomous planners, and LLM tool calling.",
        "operationId": "getMcpManifest",
        "responses": {
          "200": {
            "description": "Valid MCP server descriptor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SendDocumentRequest": {
        "type": "object",
        "required": ["organizationId", "to", "subject", "documentHtml", "documentType"],
        "properties": {
          "organizationId": {
            "type": "string",
            "description": "Unique identifier of the tenant organization",
            "example": "org_abc123"
          },
          "to": {
            "type": "string",
            "format": "email",
            "description": "Recipient email address",
            "example": "client@example.com"
          },
          "subject": {
            "type": "string",
            "description": "Subject of the email message",
            "example": "Votre contrat de location Locatool Pro #2026-089"
          },
          "documentHtml": {
            "type": "string",
            "description": "HTML content of the document or message body"
          },
          "documentType": {
            "type": "string",
            "enum": ["devis", "contrat", "facture", "colisage", "custom"],
            "description": "Type of rental document being transmitted"
          }
        }
      },
      "SendDocumentResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "messageId": {
            "type": "string",
            "example": "<20260831.abc1234@smtp-relay.brevo.com>"
          }
        }
      },
      "CheckoutRequest": {
        "type": "object",
        "required": ["planId"],
        "properties": {
          "planId": {
            "type": "string",
            "enum": ["starter", "pro", "business", "starter_yearly", "pro_yearly", "business_yearly"],
            "example": "pro"
          },
          "organizationId": {
            "type": "string",
            "example": "org_abc123"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "resolution", "documentation_url"],
            "properties": {
              "code": {
                "type": "string",
                "example": "API_ENDPOINT_NOT_FOUND"
              },
              "message": {
                "type": "string",
                "example": "The requested API endpoint does not exist."
              },
              "resolution": {
                "type": "string",
                "example": "Consult the OpenAPI specification at https://locatool.devsupai.fr/openapi.json."
              },
              "documentation_url": {
                "type": "string",
                "format": "uri",
                "example": "https://locatool.devsupai.fr/openapi.json"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    }
  }
}