{
  "openapi": "3.1.0",
  "info": {
    "title": "FacturX.app API",
    "version": "1.0.0",
    "description": "Validation et génération de factures Factur-X (EN 16931). Les fichiers sont traités en mémoire et jamais conservés.",
    "contact": { "email": "contact@facturx.app" }
  },
  "servers": [{ "url": "https://facturx.app" }],
  "security": [{ "apiKey": [] }],
  "paths": {
    "/api/v1/validate": {
      "post": {
        "summary": "Valider un fichier Factur-X ou CII",
        "operationId": "validateInvoice",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": { "type": "string", "format": "binary", "description": "PDF (Factur-X) ou XML (CII), 10 Mo max" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rapport de validation",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationReport" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/generate": {
      "post": {
        "summary": "Générer une facture Factur-X (PDF/A-3 + XML EN 16931)",
        "operationId": "generateInvoice",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["invoice"],
                "properties": {
                  "invoice": { "$ref": "#/components/schemas/InvoicePayload" },
                  "source_pdf_base64": {
                    "type": ["string", "null"],
                    "description": "PDF source en base64 : le XML y sera embarqué (sinon, visuel généré)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fichier Factur-X",
            "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "fxk_..." }
    },
    "responses": {
      "Error": {
        "description": "Erreur",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "object",
                  "properties": {
                    "code": { "type": "string" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "ValidationReport": {
        "type": "object",
        "properties": {
          "valid": { "type": "boolean" },
          "file_type": { "type": "string", "enum": ["pdf", "xml", "unknown"] },
          "profile": { "type": ["string", "null"], "enum": ["minimum", "basicwl", "basic", "en16931", "extended", null] },
          "profile_label": { "type": ["string", "null"] },
          "guideline": { "type": ["string", "null"] },
          "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } },
          "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } },
          "pdfa3_checks": {
            "type": ["array", "null"],
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "label": { "type": "string" },
                "passed": { "type": "boolean" },
                "detail": { "type": ["string", "null"] }
              }
            }
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "source": { "type": "string", "enum": ["xsd", "schematron", "structure", "pdfa3"] },
          "rule_id": { "type": ["string", "null"], "description": "Identifiant de règle EN 16931 (ex. BR-CO-15)" },
          "severity": { "type": "string", "enum": ["fatal", "warning"] },
          "location": { "type": ["string", "null"] },
          "message": { "type": "string" },
          "message_fr": { "type": "string" },
          "hint_fr": { "type": "string" }
        }
      },
      "InvoicePayload": {
        "type": "object",
        "required": ["invoice_number", "issue_date", "seller", "buyer", "lines"],
        "properties": {
          "invoice_number": { "type": "string", "maxLength": 50 },
          "issue_date": { "type": "string", "format": "date" },
          "due_date": { "type": ["string", "null"], "format": "date" },
          "delivery_date": { "type": ["string", "null"], "format": "date" },
          "currency": { "type": "string", "default": "EUR" },
          "type_code": { "type": "string", "enum": ["380", "381"], "default": "380" },
          "seller": { "$ref": "#/components/schemas/Party" },
          "buyer": { "$ref": "#/components/schemas/Party" },
          "lines": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/InvoiceLine" } },
          "payment_terms": { "type": ["string", "null"] },
          "notes": { "type": ["string", "null"] },
          "buyer_reference": { "type": ["string", "null"] },
          "vat_exemption_reason": { "type": ["string", "null"] }
        }
      },
      "Party": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string" },
          "siren": { "type": ["string", "null"], "pattern": "^\\d{9}$" },
          "vat_number": { "type": ["string", "null"] },
          "address": {
            "type": "object",
            "properties": {
              "line1": { "type": ["string", "null"] },
              "line2": { "type": ["string", "null"] },
              "postcode": { "type": ["string", "null"] },
              "city": { "type": ["string", "null"] },
              "country": { "type": "string", "default": "FR" }
            }
          }
        }
      },
      "InvoiceLine": {
        "type": "object",
        "required": ["description", "quantity", "unit_price"],
        "properties": {
          "description": { "type": "string" },
          "quantity": { "type": "string", "description": "Décimal en chaîne, ex. \"2\"" },
          "unit_code": { "type": "string", "default": "C62" },
          "unit_price": { "type": "string", "description": "Prix unitaire HT, ex. \"85.00\"" },
          "vat_rate": { "type": "string", "default": "20" },
          "vat_category": { "type": "string", "enum": ["S", "Z", "E", "AE"], "default": "S" }
        }
      }
    }
  }
}