{
  "openapi": "3.1.0",
  "info": {
    "title": "API FACTURE",
    "version": "1.0.0 (brouillon pour validation)",
    "description": "API partenaire de FACTURE : créer les entreprises de vos clients, émettre factures, devis et avoirs, récupérer les PDF, signaler les paiements. Documentation : ${PUBLIC_SITE_URL}/developpeurs",
    "contact": {
      "name": "FACTURE",
      "url": "https://gestion-hc-2026-0003.demo.dalaone.com/developpeurs"
    }
  },
  "servers": [
    {
      "url": "https://gestion-hc-2026-0003.demo.dalaone.com/api/v1",
      "description": "Production (clés `ffp_live_…` et `ffp_test_…`)"
    }
  ],
  "security": [
    {
      "partnerKey": []
    }
  ],
  "tags": [
    {
      "name": "Entreprises",
      "description": "Les entreprises des clients finaux du partenaire."
    },
    {
      "name": "Factures",
      "description": "Émission et lecture des factures."
    },
    {
      "name": "Paiements",
      "description": "Règlements signalés par l'ERP."
    },
    {
      "name": "Avoirs",
      "description": "Corrections des factures émises."
    },
    {
      "name": "Devis",
      "description": "Émission, suivi et transformation en facture."
    }
  ],
  "paths": {
    "/companies": {
      "post": {
        "operationId": "createCompany",
        "tags": [
          "Entreprises"
        ],
        "summary": "Créer une entreprise",
        "description": "Crée l'entreprise d'un client final. Elle est immédiatement utilisable : aucun abonnement, la facturation passe par le contrat partenaire. Avec une clé de test, l'entreprise est créée en mode `test`.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Clé unique par opération (UUID conseillé), conservée 24 h. Renvoyer la même requête avec la même clé renvoie le même résultat sans rien créer de plus.",
            "schema": {
              "type": "string",
              "maxLength": 100,
              "example": "5f2b7a1e-8c0d-4c1e-9a7b-2d3f4e5a6b7c"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompanyInput"
              },
              "example": {
                "external_ref": "ERP-CLIENT-0042",
                "name": "Kivu Services SARL",
                "email": "facturation@kivu-services.cd",
                "phone": "+243 810 000 000",
                "address": "45 avenue de la Paix, Goma",
                "rccm": "CD/GOM/RCCM/22-B-0123",
                "id_nat": "01-234-N56789",
                "tax_number": "A1234567B",
                "currency": "USD",
                "vat_rate": "16",
                "branding": {
                  "logo_url": "https://erp.exemple.com/logos/kivu.png",
                  "brand_color": "#0F766E",
                  "header_color": "#0F172A",
                  "invoice_template": "classic"
                },
                "numbering": {
                  "invoice_prefix": "FAC-",
                  "quote_prefix": "DEV-",
                  "credit_prefix": "AV-",
                  "include_year": true
                },
                "document_texts": {
                  "payment_terms": "Paiement à 30 jours.",
                  "bank_details": "Rawbank · CD00 0000 0000 0000",
                  "legal_mentions": null
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Entreprise créée.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                },
                "example": {
                  "id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                  "mode": "live",
                  "external_ref": "ERP-CLIENT-0042",
                  "name": "Kivu Services SARL",
                  "email": "facturation@kivu-services.cd",
                  "phone": "+243 810 000 000",
                  "address": "45 avenue de la Paix, Goma",
                  "rccm": "CD/GOM/RCCM/22-B-0123",
                  "id_nat": "01-234-N56789",
                  "tax_number": "A1234567B",
                  "currency": "USD",
                  "vat_rate": "16",
                  "branding": {
                    "logo_url": "https://erp.exemple.com/logos/kivu.png",
                    "brand_color": "#0F766E",
                    "header_color": "#0F172A",
                    "invoice_template": "classic"
                  },
                  "numbering": {
                    "invoice_prefix": "FAC-",
                    "quote_prefix": "DEV-",
                    "credit_prefix": "AV-",
                    "include_year": true
                  },
                  "document_texts": {
                    "payment_terms": "Paiement à 30 jours.",
                    "bank_details": "Rawbank · CD00 0000 0000 0000",
                    "legal_mentions": null
                  },
                  "created_at": "2026-10-14T09:12:00Z",
                  "updated_at": "2026-10-14T09:12:00Z"
                }
              }
            }
          },
          "400": {
            "description": "Requête mal formée (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflit : référence externe déjà utilisée, clé d'idempotence réutilisée avec un autre contenu, ou document verrouillé (`conflict`, `document_locked`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Données invalides (`validation_error`, `amount_exceeds_balance`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Trop d'appels (`rate_limited`, réessayer après `Retry-After` secondes) ou plafond mensuel de documents atteint (`limit_reached`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listCompanies",
        "tags": [
          "Entreprises"
        ],
        "summary": "Lister les entreprises",
        "description": "Les entreprises créées par le partenaire.",
        "parameters": [
          {
            "name": "external_ref",
            "in": "query",
            "description": "Retrouve l'élément par la référence de l'ERP.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "description": "Ne renvoie que les éléments modifiés depuis cette date (ISO 8601, UTC). Pour la synchronisation incrémentale.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-10-14T08:00:00Z"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Nombre d'éléments par page (1 à 100).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Curseur renvoyé par la page précédente (`next_cursor`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Une page d'entreprises (`data` : liste de `Company`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                },
                "example": {
                  "data": [
                    {
                      "id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                      "mode": "live",
                      "external_ref": "ERP-CLIENT-0042",
                      "name": "Kivu Services SARL",
                      "email": "facturation@kivu-services.cd",
                      "phone": "+243 810 000 000",
                      "address": "45 avenue de la Paix, Goma",
                      "rccm": "CD/GOM/RCCM/22-B-0123",
                      "id_nat": "01-234-N56789",
                      "tax_number": "A1234567B",
                      "currency": "USD",
                      "vat_rate": "16",
                      "branding": {
                        "logo_url": "https://erp.exemple.com/logos/kivu.png",
                        "brand_color": "#0F766E",
                        "header_color": "#0F172A",
                        "invoice_template": "classic"
                      },
                      "numbering": {
                        "invoice_prefix": "FAC-",
                        "quote_prefix": "DEV-",
                        "credit_prefix": "AV-",
                        "include_year": true
                      },
                      "document_texts": {
                        "payment_terms": "Paiement à 30 jours.",
                        "bank_details": "Rawbank · CD00 0000 0000 0000",
                        "legal_mentions": null
                      },
                      "created_at": "2026-10-14T09:12:00Z",
                      "updated_at": "2026-10-14T09:12:00Z"
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Trop d'appels (`rate_limited`, réessayer après `Retry-After` secondes) ou plafond mensuel de documents atteint (`limit_reached`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}": {
      "get": {
        "operationId": "getCompany",
        "tags": [
          "Entreprises"
        ],
        "summary": "Lire une entreprise",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L'entreprise.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                },
                "example": {
                  "id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                  "mode": "live",
                  "external_ref": "ERP-CLIENT-0042",
                  "name": "Kivu Services SARL",
                  "email": "facturation@kivu-services.cd",
                  "phone": "+243 810 000 000",
                  "address": "45 avenue de la Paix, Goma",
                  "rccm": "CD/GOM/RCCM/22-B-0123",
                  "id_nat": "01-234-N56789",
                  "tax_number": "A1234567B",
                  "currency": "USD",
                  "vat_rate": "16",
                  "branding": {
                    "logo_url": "https://erp.exemple.com/logos/kivu.png",
                    "brand_color": "#0F766E",
                    "header_color": "#0F172A",
                    "invoice_template": "classic"
                  },
                  "numbering": {
                    "invoice_prefix": "FAC-",
                    "quote_prefix": "DEV-",
                    "credit_prefix": "AV-",
                    "include_year": true
                  },
                  "document_texts": {
                    "payment_terms": "Paiement à 30 jours.",
                    "bank_details": "Rawbank · CD00 0000 0000 0000",
                    "legal_mentions": null
                  },
                  "created_at": "2026-10-14T09:12:00Z",
                  "updated_at": "2026-10-14T09:12:00Z"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteCompany",
        "tags": [
          "Entreprises"
        ],
        "summary": "Supprimer une entreprise de test",
        "description": "Efface une entreprise en mode `test` et tout son contenu (clients, factures, devis, avoirs, paiements), pour repartir d'une base propre pendant le développement. Une entreprise de production ne peut pas être supprimée (`403 forbidden`) : ses documents doivent être conservés.",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Entreprise supprimée (réponse sans corps)."
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateCompany",
        "tags": [
          "Entreprises"
        ],
        "summary": "Modifier une entreprise",
        "description": "Seuls les champs envoyés sont modifiés. Les documents déjà émis ne changent pas ; les suivants reprennent les nouvelles informations.",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompanyUpdate"
              },
              "example": {
                "phone": "+243 820 000 000",
                "branding": {
                  "invoice_template": "detailed"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "L'entreprise modifiée.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                },
                "example": {
                  "id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                  "mode": "live",
                  "external_ref": "ERP-CLIENT-0042",
                  "name": "Kivu Services SARL",
                  "email": "facturation@kivu-services.cd",
                  "phone": "+243 810 000 000",
                  "address": "45 avenue de la Paix, Goma",
                  "rccm": "CD/GOM/RCCM/22-B-0123",
                  "id_nat": "01-234-N56789",
                  "tax_number": "A1234567B",
                  "currency": "USD",
                  "vat_rate": "16",
                  "branding": {
                    "logo_url": "https://erp.exemple.com/logos/kivu.png",
                    "brand_color": "#0F766E",
                    "header_color": "#0F172A",
                    "invoice_template": "classic"
                  },
                  "numbering": {
                    "invoice_prefix": "FAC-",
                    "quote_prefix": "DEV-",
                    "credit_prefix": "AV-",
                    "include_year": true
                  },
                  "document_texts": {
                    "payment_terms": "Paiement à 30 jours.",
                    "bank_details": "Rawbank · CD00 0000 0000 0000",
                    "legal_mentions": null
                  },
                  "created_at": "2026-10-14T09:12:00Z",
                  "updated_at": "2026-10-14T09:12:00Z"
                }
              }
            }
          },
          "400": {
            "description": "Requête mal formée (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Données invalides (`validation_error`, `amount_exceeds_balance`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/invoices": {
      "post": {
        "operationId": "createInvoice",
        "tags": [
          "Factures"
        ],
        "summary": "Émettre une facture",
        "description": "Crée et émet la facture : FACTURE attribue le numéro, calcule les totaux et produit le PDF. Une facture émise n'est plus modifiable ; toute correction passe par un avoir.",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Clé unique par opération (UUID conseillé), conservée 24 h. Renvoyer la même requête avec la même clé renvoie le même résultat sans rien créer de plus.",
            "schema": {
              "type": "string",
              "maxLength": 100,
              "example": "5f2b7a1e-8c0d-4c1e-9a7b-2d3f4e5a6b7c"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceInput"
              },
              "example": {
                "external_ref": "ERP-FAC-2026-1187",
                "customer": {
                  "external_ref": "ERP-TIERS-778",
                  "name": "Aline Mbuyi",
                  "company": "Studio Kivu",
                  "email": "compta@studio-kivu.cd",
                  "phone": "+243 811 111 111",
                  "address": "12 avenue du Lac, Goma",
                  "tax_id": "A7654321C"
                },
                "issue_date": "2026-10-14",
                "due_date": "2026-11-13",
                "currency": "USD",
                "vat_rate": "16",
                "discount": "50.00",
                "order_number": "BC-2026-031",
                "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                "lines": [
                  {
                    "description": "Audit des comptes annuels 2025",
                    "quantity": "1",
                    "unit_price": "1200.00"
                  },
                  {
                    "description": "Rapport de recommandations",
                    "quantity": "2",
                    "unit_price": "150.00"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Facture émise.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                },
                "example": {
                  "id": "8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d",
                  "company_id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                  "external_ref": "ERP-FAC-2026-1187",
                  "number": "FAC-2026-00059",
                  "status": "issued",
                  "customer": {
                    "id": "1b2c3d4e-5f60-4718-9a0b-1c2d3e4f5a6b",
                    "external_ref": "ERP-TIERS-778",
                    "name": "Aline Mbuyi",
                    "company": "Studio Kivu",
                    "email": "compta@studio-kivu.cd",
                    "phone": "+243 811 111 111",
                    "address": "12 avenue du Lac, Goma",
                    "tax_id": "A7654321C"
                  },
                  "issue_date": "2026-10-14",
                  "due_date": "2026-11-13",
                  "currency": "USD",
                  "order_number": "BC-2026-031",
                  "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                  "lines": [
                    {
                      "description": "Audit des comptes annuels 2025",
                      "quantity": "1",
                      "unit_price": "1200.00",
                      "total": "1200.00"
                    },
                    {
                      "description": "Rapport de recommandations",
                      "quantity": "2",
                      "unit_price": "150.00",
                      "total": "300.00"
                    }
                  ],
                  "subtotal": "1500.00",
                  "discount": "50.00",
                  "shipping_amount": "0.00",
                  "adjustment_amount": "0.00",
                  "taxable_base": "1450.00",
                  "vat_rate": "16",
                  "vat_amount": "232.00",
                  "total": "1682.00",
                  "amount_paid": "0.00",
                  "amount_credited": "0.00",
                  "balance_due": "1682.00",
                  "first_viewed_at": "2026-10-14T10:32:00Z",
                  "last_viewed_at": "2026-10-16T08:05:00Z",
                  "view_count": 2,
                  "public_url": "https://gestion-hc-2026-0003.demo.dalaone.com/p/invoice/kQ3v…",
                  "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/invoices/8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d/pdf",
                  "created_at": "2026-10-14T09:30:00Z",
                  "updated_at": "2026-10-14T09:30:00Z"
                }
              }
            }
          },
          "400": {
            "description": "Requête mal formée (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflit : référence externe déjà utilisée, clé d'idempotence réutilisée avec un autre contenu, ou document verrouillé (`conflict`, `document_locked`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Données invalides (`validation_error`, `amount_exceeds_balance`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Trop d'appels (`rate_limited`, réessayer après `Retry-After` secondes) ou plafond mensuel de documents atteint (`limit_reached`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listInvoices",
        "tags": [
          "Factures"
        ],
        "summary": "Lister les factures",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filtre par statut.",
            "schema": {
              "type": "string",
              "enum": [
                "issued",
                "partially_paid",
                "paid",
                "overdue",
                "cancelled"
              ]
            }
          },
          {
            "name": "external_ref",
            "in": "query",
            "description": "Retrouve l'élément par la référence de l'ERP.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "description": "Ne renvoie que les éléments modifiés depuis cette date (ISO 8601, UTC). Pour la synchronisation incrémentale.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-10-14T08:00:00Z"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Nombre d'éléments par page (1 à 100).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Curseur renvoyé par la page précédente (`next_cursor`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Une page de factures (`data` : liste d'`Invoice`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                },
                "example": {
                  "data": [
                    {
                      "id": "8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d",
                      "company_id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                      "external_ref": "ERP-FAC-2026-1187",
                      "number": "FAC-2026-00059",
                      "status": "issued",
                      "customer": {
                        "id": "1b2c3d4e-5f60-4718-9a0b-1c2d3e4f5a6b",
                        "external_ref": "ERP-TIERS-778",
                        "name": "Aline Mbuyi",
                        "company": "Studio Kivu",
                        "email": "compta@studio-kivu.cd",
                        "phone": "+243 811 111 111",
                        "address": "12 avenue du Lac, Goma",
                        "tax_id": "A7654321C"
                      },
                      "issue_date": "2026-10-14",
                      "due_date": "2026-11-13",
                      "currency": "USD",
                      "order_number": "BC-2026-031",
                      "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                      "lines": [
                        {
                          "description": "Audit des comptes annuels 2025",
                          "quantity": "1",
                          "unit_price": "1200.00",
                          "total": "1200.00"
                        },
                        {
                          "description": "Rapport de recommandations",
                          "quantity": "2",
                          "unit_price": "150.00",
                          "total": "300.00"
                        }
                      ],
                      "subtotal": "1500.00",
                      "discount": "50.00",
                      "shipping_amount": "0.00",
                      "adjustment_amount": "0.00",
                      "taxable_base": "1450.00",
                      "vat_rate": "16",
                      "vat_amount": "232.00",
                      "total": "1682.00",
                      "amount_paid": "0.00",
                      "amount_credited": "0.00",
                      "balance_due": "1682.00",
                      "first_viewed_at": "2026-10-14T10:32:00Z",
                      "last_viewed_at": "2026-10-16T08:05:00Z",
                      "view_count": 2,
                      "public_url": "https://gestion-hc-2026-0003.demo.dalaone.com/p/invoice/kQ3v…",
                      "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/invoices/8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d/pdf",
                      "created_at": "2026-10-14T09:30:00Z",
                      "updated_at": "2026-10-14T09:30:00Z"
                    }
                  ],
                  "next_cursor": "eyJjIjoiMjAyNi0xMC0xNFQwOTozMDowMFoifQ"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Trop d'appels (`rate_limited`, réessayer après `Retry-After` secondes) ou plafond mensuel de documents atteint (`limit_reached`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/invoices/preview": {
      "post": {
        "operationId": "previewInvoice",
        "tags": [
          "Factures"
        ],
        "summary": "Aperçu d'une facture avant émission",
        "description": "Produit le PDF du document tel qu'il serait émis, marqué **APERÇU**, avec un numéro provisoire. Rien n'est enregistré, aucun numéro n'est consommé : l'utilisateur vérifie le rendu dans l'ERP avant de cliquer « Émettre ».",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoicePreviewInput"
              },
              "example": {
                "customer": {
                  "external_ref": "ERP-TIERS-778",
                  "name": "Aline Mbuyi",
                  "company": "Studio Kivu",
                  "email": "compta@studio-kivu.cd",
                  "phone": "+243 811 111 111",
                  "address": "12 avenue du Lac, Goma",
                  "tax_id": "A7654321C"
                },
                "issue_date": "2026-10-14",
                "due_date": "2026-11-13",
                "currency": "USD",
                "vat_rate": "16",
                "discount": "50.00",
                "order_number": "BC-2026-031",
                "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                "lines": [
                  {
                    "description": "Audit des comptes annuels 2025",
                    "quantity": "1",
                    "unit_price": "1200.00"
                  },
                  {
                    "description": "Rapport de recommandations",
                    "quantity": "2",
                    "unit_price": "150.00"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Le PDF d'aperçu.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Requête mal formée (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Données invalides (`validation_error`, `amount_exceeds_balance`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Trop d'appels (`rate_limited`, réessayer après `Retry-After` secondes) ou plafond mensuel de documents atteint (`limit_reached`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/invoices/{invoice_id}": {
      "get": {
        "operationId": "getInvoice",
        "tags": [
          "Factures"
        ],
        "summary": "Lire une facture",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Identifiant de la facture.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "La facture.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                },
                "example": {
                  "id": "8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d",
                  "company_id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                  "external_ref": "ERP-FAC-2026-1187",
                  "number": "FAC-2026-00059",
                  "status": "issued",
                  "customer": {
                    "id": "1b2c3d4e-5f60-4718-9a0b-1c2d3e4f5a6b",
                    "external_ref": "ERP-TIERS-778",
                    "name": "Aline Mbuyi",
                    "company": "Studio Kivu",
                    "email": "compta@studio-kivu.cd",
                    "phone": "+243 811 111 111",
                    "address": "12 avenue du Lac, Goma",
                    "tax_id": "A7654321C"
                  },
                  "issue_date": "2026-10-14",
                  "due_date": "2026-11-13",
                  "currency": "USD",
                  "order_number": "BC-2026-031",
                  "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                  "lines": [
                    {
                      "description": "Audit des comptes annuels 2025",
                      "quantity": "1",
                      "unit_price": "1200.00",
                      "total": "1200.00"
                    },
                    {
                      "description": "Rapport de recommandations",
                      "quantity": "2",
                      "unit_price": "150.00",
                      "total": "300.00"
                    }
                  ],
                  "subtotal": "1500.00",
                  "discount": "50.00",
                  "shipping_amount": "0.00",
                  "adjustment_amount": "0.00",
                  "taxable_base": "1450.00",
                  "vat_rate": "16",
                  "vat_amount": "232.00",
                  "total": "1682.00",
                  "amount_paid": "0.00",
                  "amount_credited": "0.00",
                  "balance_due": "1682.00",
                  "first_viewed_at": "2026-10-14T10:32:00Z",
                  "last_viewed_at": "2026-10-16T08:05:00Z",
                  "view_count": 2,
                  "public_url": "https://gestion-hc-2026-0003.demo.dalaone.com/p/invoice/kQ3v…",
                  "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/invoices/8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d/pdf",
                  "created_at": "2026-10-14T09:30:00Z",
                  "updated_at": "2026-10-14T09:30:00Z"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/invoices/{invoice_id}/pdf": {
      "get": {
        "operationId": "getInvoicePdf",
        "tags": [
          "Factures"
        ],
        "summary": "Télécharger le PDF d'une facture",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Identifiant de la facture.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Le document PDF, au modèle de l'entreprise.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/invoices/{invoice_id}/payments": {
      "post": {
        "operationId": "createPayment",
        "tags": [
          "Paiements"
        ],
        "summary": "Enregistrer un paiement",
        "description": "Signale à FACTURE un règlement reçu dans l'ERP. Le statut de la facture suit : `partially_paid`, puis `paid` quand le reste à payer atteint 0. Un montant supérieur au reste à payer est refusé (`amount_exceeds_balance`).",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Identifiant de la facture.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Clé unique par opération (UUID conseillé), conservée 24 h. Renvoyer la même requête avec la même clé renvoie le même résultat sans rien créer de plus.",
            "schema": {
              "type": "string",
              "maxLength": 100,
              "example": "5f2b7a1e-8c0d-4c1e-9a7b-2d3f4e5a6b7c"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentInput"
              },
              "example": {
                "external_ref": "ERP-REG-5521",
                "amount": "1000.00",
                "paid_at": "2026-10-20T14:05:00Z",
                "method": "bank_transfer",
                "reference": "VIR-RAW-778812"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Paiement enregistré.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                },
                "example": {
                  "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
                  "invoice_id": "8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d",
                  "external_ref": "ERP-REG-5521",
                  "amount": "1000.00",
                  "paid_at": "2026-10-20T14:05:00Z",
                  "method": "bank_transfer",
                  "reference": "VIR-RAW-778812",
                  "created_at": "2026-10-20T14:06:10Z"
                }
              }
            }
          },
          "400": {
            "description": "Requête mal formée (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflit : référence externe déjà utilisée, clé d'idempotence réutilisée avec un autre contenu, ou document verrouillé (`conflict`, `document_locked`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Données invalides (`validation_error`, `amount_exceeds_balance`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Trop d'appels (`rate_limited`, réessayer après `Retry-After` secondes) ou plafond mensuel de documents atteint (`limit_reached`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listPayments",
        "tags": [
          "Paiements"
        ],
        "summary": "Lister les paiements d'une facture",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Identifiant de la facture.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Les paiements (`data` : liste de `Payment`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                },
                "example": {
                  "data": [
                    {
                      "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
                      "invoice_id": "8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d",
                      "external_ref": "ERP-REG-5521",
                      "amount": "1000.00",
                      "paid_at": "2026-10-20T14:05:00Z",
                      "method": "bank_transfer",
                      "reference": "VIR-RAW-778812",
                      "created_at": "2026-10-20T14:06:10Z"
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/invoices/{invoice_id}/credit-notes": {
      "post": {
        "operationId": "createCreditNote",
        "tags": [
          "Avoirs"
        ],
        "summary": "Émettre un avoir",
        "description": "Seule façon de corriger une facture émise. Sans lignes : avoir total, la facture passe `cancelled`. Avec lignes : avoir partiel, déduit du reste à payer. Le total des avoirs ne peut pas dépasser le total de la facture.",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Identifiant de la facture.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Clé unique par opération (UUID conseillé), conservée 24 h. Renvoyer la même requête avec la même clé renvoie le même résultat sans rien créer de plus.",
            "schema": {
              "type": "string",
              "maxLength": 100,
              "example": "5f2b7a1e-8c0d-4c1e-9a7b-2d3f4e5a6b7c"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreditNoteInput"
              },
              "example": {
                "external_ref": "ERP-AV-2026-0007",
                "issue_date": "2026-10-22",
                "reason": "Remise commerciale accordée après réclamation",
                "lines": [
                  {
                    "description": "Geste commercial",
                    "quantity": "1",
                    "unit_price": "100.00"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Avoir émis.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditNote"
                },
                "example": {
                  "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
                  "invoice_id": "8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d",
                  "number": "AV-2026-00003",
                  "external_ref": "ERP-AV-2026-0007",
                  "issue_date": "2026-10-22",
                  "reason": "Remise commerciale accordée après réclamation",
                  "lines": [
                    {
                      "description": "Geste commercial",
                      "quantity": "1",
                      "unit_price": "100.00",
                      "total": "100.00"
                    }
                  ],
                  "subtotal": "100.00",
                  "vat_rate": "16",
                  "vat_amount": "16.00",
                  "total": "116.00",
                  "currency": "USD",
                  "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/credit-notes/9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a/pdf",
                  "created_at": "2026-10-22T10:00:00Z"
                }
              }
            }
          },
          "400": {
            "description": "Requête mal formée (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflit : référence externe déjà utilisée, clé d'idempotence réutilisée avec un autre contenu, ou document verrouillé (`conflict`, `document_locked`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Données invalides (`validation_error`, `amount_exceeds_balance`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Trop d'appels (`rate_limited`, réessayer après `Retry-After` secondes) ou plafond mensuel de documents atteint (`limit_reached`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/credit-notes/{credit_note_id}": {
      "get": {
        "operationId": "getCreditNote",
        "tags": [
          "Avoirs"
        ],
        "summary": "Lire un avoir",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "credit_note_id",
            "in": "path",
            "required": true,
            "description": "Identifiant de l'avoir.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "L'avoir.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditNote"
                },
                "example": {
                  "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
                  "invoice_id": "8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d",
                  "number": "AV-2026-00003",
                  "external_ref": "ERP-AV-2026-0007",
                  "issue_date": "2026-10-22",
                  "reason": "Remise commerciale accordée après réclamation",
                  "lines": [
                    {
                      "description": "Geste commercial",
                      "quantity": "1",
                      "unit_price": "100.00",
                      "total": "100.00"
                    }
                  ],
                  "subtotal": "100.00",
                  "vat_rate": "16",
                  "vat_amount": "16.00",
                  "total": "116.00",
                  "currency": "USD",
                  "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/credit-notes/9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a/pdf",
                  "created_at": "2026-10-22T10:00:00Z"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/credit-notes/{credit_note_id}/pdf": {
      "get": {
        "operationId": "getCreditNotePdf",
        "tags": [
          "Avoirs"
        ],
        "summary": "Télécharger le PDF d'un avoir",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "credit_note_id",
            "in": "path",
            "required": true,
            "description": "Identifiant de l'avoir.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Le document PDF, au modèle de l'entreprise.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/quotes": {
      "post": {
        "operationId": "createQuote",
        "tags": [
          "Devis"
        ],
        "summary": "Émettre un devis",
        "description": "Crée et émet le devis : numéro attribué par FACTURE, totaux calculés, PDF disponible.",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Clé unique par opération (UUID conseillé), conservée 24 h. Renvoyer la même requête avec la même clé renvoie le même résultat sans rien créer de plus.",
            "schema": {
              "type": "string",
              "maxLength": 100,
              "example": "5f2b7a1e-8c0d-4c1e-9a7b-2d3f4e5a6b7c"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteInput"
              },
              "example": {
                "external_ref": "ERP-DEV-2026-0311",
                "customer": {
                  "external_ref": "ERP-TIERS-778",
                  "name": "Aline Mbuyi",
                  "company": "Studio Kivu",
                  "email": "compta@studio-kivu.cd",
                  "phone": "+243 811 111 111",
                  "address": "12 avenue du Lac, Goma",
                  "tax_id": "A7654321C"
                },
                "issue_date": "2026-10-14",
                "currency": "USD",
                "vat_rate": "16",
                "discount": "50.00",
                "order_number": "BC-2026-031",
                "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                "lines": [
                  {
                    "description": "Audit des comptes annuels 2025",
                    "quantity": "1",
                    "unit_price": "1200.00"
                  },
                  {
                    "description": "Rapport de recommandations",
                    "quantity": "2",
                    "unit_price": "150.00"
                  }
                ],
                "valid_until": "2026-11-14"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Devis émis.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                },
                "example": {
                  "id": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
                  "company_id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                  "external_ref": "ERP-DEV-2026-0311",
                  "number": "DEV-2026-00008",
                  "status": "issued",
                  "customer": {
                    "id": "1b2c3d4e-5f60-4718-9a0b-1c2d3e4f5a6b",
                    "external_ref": "ERP-TIERS-778",
                    "name": "Aline Mbuyi",
                    "company": "Studio Kivu",
                    "email": "compta@studio-kivu.cd",
                    "phone": "+243 811 111 111",
                    "address": "12 avenue du Lac, Goma",
                    "tax_id": "A7654321C"
                  },
                  "issue_date": "2026-10-14",
                  "currency": "USD",
                  "order_number": "BC-2026-031",
                  "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                  "lines": [
                    {
                      "description": "Audit des comptes annuels 2025",
                      "quantity": "1",
                      "unit_price": "1200.00",
                      "total": "1200.00"
                    },
                    {
                      "description": "Rapport de recommandations",
                      "quantity": "2",
                      "unit_price": "150.00",
                      "total": "300.00"
                    }
                  ],
                  "subtotal": "1500.00",
                  "discount": "50.00",
                  "shipping_amount": "0.00",
                  "adjustment_amount": "0.00",
                  "taxable_base": "1450.00",
                  "vat_rate": "16",
                  "vat_amount": "232.00",
                  "total": "1682.00",
                  "first_viewed_at": "2026-10-14T10:32:00Z",
                  "last_viewed_at": "2026-10-16T08:05:00Z",
                  "view_count": 2,
                  "public_url": "https://gestion-hc-2026-0003.demo.dalaone.com/p/quote/Zp8w…",
                  "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/quotes/5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716/pdf",
                  "created_at": "2026-10-14T09:30:00Z",
                  "updated_at": "2026-10-14T09:30:00Z",
                  "valid_until": "2026-11-14",
                  "invoice_id": null
                }
              }
            }
          },
          "400": {
            "description": "Requête mal formée (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflit : référence externe déjà utilisée, clé d'idempotence réutilisée avec un autre contenu, ou document verrouillé (`conflict`, `document_locked`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Données invalides (`validation_error`, `amount_exceeds_balance`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Trop d'appels (`rate_limited`, réessayer après `Retry-After` secondes) ou plafond mensuel de documents atteint (`limit_reached`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listQuotes",
        "tags": [
          "Devis"
        ],
        "summary": "Lister les devis",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filtre par statut.",
            "schema": {
              "type": "string",
              "enum": [
                "issued",
                "accepted",
                "refused",
                "invoiced"
              ]
            }
          },
          {
            "name": "external_ref",
            "in": "query",
            "description": "Retrouve l'élément par la référence de l'ERP.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "description": "Ne renvoie que les éléments modifiés depuis cette date (ISO 8601, UTC). Pour la synchronisation incrémentale.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2026-10-14T08:00:00Z"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Nombre d'éléments par page (1 à 100).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Curseur renvoyé par la page précédente (`next_cursor`).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Une page de devis (`data` : liste de `Quote`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                },
                "example": {
                  "data": [
                    {
                      "id": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
                      "company_id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                      "external_ref": "ERP-DEV-2026-0311",
                      "number": "DEV-2026-00008",
                      "status": "issued",
                      "customer": {
                        "id": "1b2c3d4e-5f60-4718-9a0b-1c2d3e4f5a6b",
                        "external_ref": "ERP-TIERS-778",
                        "name": "Aline Mbuyi",
                        "company": "Studio Kivu",
                        "email": "compta@studio-kivu.cd",
                        "phone": "+243 811 111 111",
                        "address": "12 avenue du Lac, Goma",
                        "tax_id": "A7654321C"
                      },
                      "issue_date": "2026-10-14",
                      "currency": "USD",
                      "order_number": "BC-2026-031",
                      "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                      "lines": [
                        {
                          "description": "Audit des comptes annuels 2025",
                          "quantity": "1",
                          "unit_price": "1200.00",
                          "total": "1200.00"
                        },
                        {
                          "description": "Rapport de recommandations",
                          "quantity": "2",
                          "unit_price": "150.00",
                          "total": "300.00"
                        }
                      ],
                      "subtotal": "1500.00",
                      "discount": "50.00",
                      "shipping_amount": "0.00",
                      "adjustment_amount": "0.00",
                      "taxable_base": "1450.00",
                      "vat_rate": "16",
                      "vat_amount": "232.00",
                      "total": "1682.00",
                      "first_viewed_at": "2026-10-14T10:32:00Z",
                      "last_viewed_at": "2026-10-16T08:05:00Z",
                      "view_count": 2,
                      "public_url": "https://gestion-hc-2026-0003.demo.dalaone.com/p/quote/Zp8w…",
                      "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/quotes/5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716/pdf",
                      "created_at": "2026-10-14T09:30:00Z",
                      "updated_at": "2026-10-14T09:30:00Z",
                      "valid_until": "2026-11-14",
                      "invoice_id": null
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Trop d'appels (`rate_limited`, réessayer après `Retry-After` secondes) ou plafond mensuel de documents atteint (`limit_reached`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/quotes/preview": {
      "post": {
        "operationId": "previewQuote",
        "tags": [
          "Devis"
        ],
        "summary": "Aperçu d'un devis avant émission",
        "description": "Produit le PDF du document tel qu'il serait émis, marqué **APERÇU**, avec un numéro provisoire. Rien n'est enregistré, aucun numéro n'est consommé : l'utilisateur vérifie le rendu dans l'ERP avant de cliquer « Émettre ».",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuotePreviewInput"
              },
              "example": {
                "customer": {
                  "external_ref": "ERP-TIERS-778",
                  "name": "Aline Mbuyi",
                  "company": "Studio Kivu",
                  "email": "compta@studio-kivu.cd",
                  "phone": "+243 811 111 111",
                  "address": "12 avenue du Lac, Goma",
                  "tax_id": "A7654321C"
                },
                "issue_date": "2026-10-14",
                "currency": "USD",
                "vat_rate": "16",
                "discount": "50.00",
                "order_number": "BC-2026-031",
                "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                "lines": [
                  {
                    "description": "Audit des comptes annuels 2025",
                    "quantity": "1",
                    "unit_price": "1200.00"
                  },
                  {
                    "description": "Rapport de recommandations",
                    "quantity": "2",
                    "unit_price": "150.00"
                  }
                ],
                "valid_until": "2026-11-14"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Le PDF d'aperçu.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Requête mal formée (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Données invalides (`validation_error`, `amount_exceeds_balance`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Trop d'appels (`rate_limited`, réessayer après `Retry-After` secondes) ou plafond mensuel de documents atteint (`limit_reached`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/quotes/{quote_id}": {
      "get": {
        "operationId": "getQuote",
        "tags": [
          "Devis"
        ],
        "summary": "Lire un devis",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "quote_id",
            "in": "path",
            "required": true,
            "description": "Identifiant du devis.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Le devis.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                },
                "example": {
                  "id": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
                  "company_id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                  "external_ref": "ERP-DEV-2026-0311",
                  "number": "DEV-2026-00008",
                  "status": "issued",
                  "customer": {
                    "id": "1b2c3d4e-5f60-4718-9a0b-1c2d3e4f5a6b",
                    "external_ref": "ERP-TIERS-778",
                    "name": "Aline Mbuyi",
                    "company": "Studio Kivu",
                    "email": "compta@studio-kivu.cd",
                    "phone": "+243 811 111 111",
                    "address": "12 avenue du Lac, Goma",
                    "tax_id": "A7654321C"
                  },
                  "issue_date": "2026-10-14",
                  "currency": "USD",
                  "order_number": "BC-2026-031",
                  "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                  "lines": [
                    {
                      "description": "Audit des comptes annuels 2025",
                      "quantity": "1",
                      "unit_price": "1200.00",
                      "total": "1200.00"
                    },
                    {
                      "description": "Rapport de recommandations",
                      "quantity": "2",
                      "unit_price": "150.00",
                      "total": "300.00"
                    }
                  ],
                  "subtotal": "1500.00",
                  "discount": "50.00",
                  "shipping_amount": "0.00",
                  "adjustment_amount": "0.00",
                  "taxable_base": "1450.00",
                  "vat_rate": "16",
                  "vat_amount": "232.00",
                  "total": "1682.00",
                  "first_viewed_at": "2026-10-14T10:32:00Z",
                  "last_viewed_at": "2026-10-16T08:05:00Z",
                  "view_count": 2,
                  "public_url": "https://gestion-hc-2026-0003.demo.dalaone.com/p/quote/Zp8w…",
                  "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/quotes/5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716/pdf",
                  "created_at": "2026-10-14T09:30:00Z",
                  "updated_at": "2026-10-14T09:30:00Z",
                  "valid_until": "2026-11-14",
                  "invoice_id": null
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/quotes/{quote_id}/pdf": {
      "get": {
        "operationId": "getQuotePdf",
        "tags": [
          "Devis"
        ],
        "summary": "Télécharger le PDF d'un devis",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "quote_id",
            "in": "path",
            "required": true,
            "description": "Identifiant du devis.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Le document PDF, au modèle de l'entreprise.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/quotes/{quote_id}/accept": {
      "post": {
        "operationId": "acceptQuote",
        "tags": [
          "Devis"
        ],
        "summary": "Marquer un devis accepté",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "quote_id",
            "in": "path",
            "required": true,
            "description": "Identifiant du devis.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Le devis, `accepted`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                },
                "example": {
                  "id": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
                  "company_id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                  "external_ref": "ERP-DEV-2026-0311",
                  "number": "DEV-2026-00008",
                  "status": "accepted",
                  "customer": {
                    "id": "1b2c3d4e-5f60-4718-9a0b-1c2d3e4f5a6b",
                    "external_ref": "ERP-TIERS-778",
                    "name": "Aline Mbuyi",
                    "company": "Studio Kivu",
                    "email": "compta@studio-kivu.cd",
                    "phone": "+243 811 111 111",
                    "address": "12 avenue du Lac, Goma",
                    "tax_id": "A7654321C"
                  },
                  "issue_date": "2026-10-14",
                  "currency": "USD",
                  "order_number": "BC-2026-031",
                  "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                  "lines": [
                    {
                      "description": "Audit des comptes annuels 2025",
                      "quantity": "1",
                      "unit_price": "1200.00",
                      "total": "1200.00"
                    },
                    {
                      "description": "Rapport de recommandations",
                      "quantity": "2",
                      "unit_price": "150.00",
                      "total": "300.00"
                    }
                  ],
                  "subtotal": "1500.00",
                  "discount": "50.00",
                  "shipping_amount": "0.00",
                  "adjustment_amount": "0.00",
                  "taxable_base": "1450.00",
                  "vat_rate": "16",
                  "vat_amount": "232.00",
                  "total": "1682.00",
                  "first_viewed_at": "2026-10-14T10:32:00Z",
                  "last_viewed_at": "2026-10-16T08:05:00Z",
                  "view_count": 2,
                  "public_url": "https://gestion-hc-2026-0003.demo.dalaone.com/p/quote/Zp8w…",
                  "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/quotes/5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716/pdf",
                  "created_at": "2026-10-14T09:30:00Z",
                  "updated_at": "2026-10-14T09:30:00Z",
                  "valid_until": "2026-11-14",
                  "invoice_id": null
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflit : référence externe déjà utilisée, clé d'idempotence réutilisée avec un autre contenu, ou document verrouillé (`conflict`, `document_locked`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/quotes/{quote_id}/refuse": {
      "post": {
        "operationId": "refuseQuote",
        "tags": [
          "Devis"
        ],
        "summary": "Marquer un devis refusé",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "quote_id",
            "in": "path",
            "required": true,
            "description": "Identifiant du devis.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Le devis, `refused`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                },
                "example": {
                  "id": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
                  "company_id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                  "external_ref": "ERP-DEV-2026-0311",
                  "number": "DEV-2026-00008",
                  "status": "refused",
                  "customer": {
                    "id": "1b2c3d4e-5f60-4718-9a0b-1c2d3e4f5a6b",
                    "external_ref": "ERP-TIERS-778",
                    "name": "Aline Mbuyi",
                    "company": "Studio Kivu",
                    "email": "compta@studio-kivu.cd",
                    "phone": "+243 811 111 111",
                    "address": "12 avenue du Lac, Goma",
                    "tax_id": "A7654321C"
                  },
                  "issue_date": "2026-10-14",
                  "currency": "USD",
                  "order_number": "BC-2026-031",
                  "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                  "lines": [
                    {
                      "description": "Audit des comptes annuels 2025",
                      "quantity": "1",
                      "unit_price": "1200.00",
                      "total": "1200.00"
                    },
                    {
                      "description": "Rapport de recommandations",
                      "quantity": "2",
                      "unit_price": "150.00",
                      "total": "300.00"
                    }
                  ],
                  "subtotal": "1500.00",
                  "discount": "50.00",
                  "shipping_amount": "0.00",
                  "adjustment_amount": "0.00",
                  "taxable_base": "1450.00",
                  "vat_rate": "16",
                  "vat_amount": "232.00",
                  "total": "1682.00",
                  "first_viewed_at": "2026-10-14T10:32:00Z",
                  "last_viewed_at": "2026-10-16T08:05:00Z",
                  "view_count": 2,
                  "public_url": "https://gestion-hc-2026-0003.demo.dalaone.com/p/quote/Zp8w…",
                  "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/quotes/5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716/pdf",
                  "created_at": "2026-10-14T09:30:00Z",
                  "updated_at": "2026-10-14T09:30:00Z",
                  "valid_until": "2026-11-14",
                  "invoice_id": null
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflit : référence externe déjà utilisée, clé d'idempotence réutilisée avec un autre contenu, ou document verrouillé (`conflict`, `document_locked`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/companies/{company_id}/quotes/{quote_id}/convert": {
      "post": {
        "operationId": "convertQuote",
        "tags": [
          "Devis"
        ],
        "summary": "Transformer un devis en facture",
        "description": "Émet une facture reprenant les lignes et le client du devis, qui passe `invoiced`. Le corps fixe la référence ERP et les dates de la facture.",
        "parameters": [
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "description": "Identifiant FACTURE de l'entreprise (client final du partenaire).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "quote_id",
            "in": "path",
            "required": true,
            "description": "Identifiant du devis.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Clé unique par opération (UUID conseillé), conservée 24 h. Renvoyer la même requête avec la même clé renvoie le même résultat sans rien créer de plus.",
            "schema": {
              "type": "string",
              "maxLength": 100,
              "example": "5f2b7a1e-8c0d-4c1e-9a7b-2d3f4e5a6b7c"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "external_ref",
                  "issue_date"
                ],
                "properties": {
                  "external_ref": {
                    "type": "string",
                    "description": "Référence de la facture dans l'ERP."
                  },
                  "issue_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "due_date": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date"
                  }
                }
              },
              "example": {
                "external_ref": "ERP-FAC-2026-1203",
                "issue_date": "2026-10-25",
                "due_date": "2026-11-24"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "La facture émise.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                },
                "example": {
                  "id": "8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d",
                  "company_id": "3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b",
                  "external_ref": "ERP-FAC-2026-1203",
                  "number": "FAC-2026-00059",
                  "status": "issued",
                  "customer": {
                    "id": "1b2c3d4e-5f60-4718-9a0b-1c2d3e4f5a6b",
                    "external_ref": "ERP-TIERS-778",
                    "name": "Aline Mbuyi",
                    "company": "Studio Kivu",
                    "email": "compta@studio-kivu.cd",
                    "phone": "+243 811 111 111",
                    "address": "12 avenue du Lac, Goma",
                    "tax_id": "A7654321C"
                  },
                  "issue_date": "2026-10-14",
                  "due_date": "2026-11-13",
                  "currency": "USD",
                  "order_number": "BC-2026-031",
                  "notes": "Merci de rappeler le numéro de facture lors du paiement.",
                  "lines": [
                    {
                      "description": "Audit des comptes annuels 2025",
                      "quantity": "1",
                      "unit_price": "1200.00",
                      "total": "1200.00"
                    },
                    {
                      "description": "Rapport de recommandations",
                      "quantity": "2",
                      "unit_price": "150.00",
                      "total": "300.00"
                    }
                  ],
                  "subtotal": "1500.00",
                  "discount": "50.00",
                  "shipping_amount": "0.00",
                  "adjustment_amount": "0.00",
                  "taxable_base": "1450.00",
                  "vat_rate": "16",
                  "vat_amount": "232.00",
                  "total": "1682.00",
                  "amount_paid": "0.00",
                  "amount_credited": "0.00",
                  "balance_due": "1682.00",
                  "first_viewed_at": "2026-10-14T10:32:00Z",
                  "last_viewed_at": "2026-10-16T08:05:00Z",
                  "view_count": 2,
                  "public_url": "https://gestion-hc-2026-0003.demo.dalaone.com/p/invoice/kQ3v…",
                  "pdf_url": "/api/v1/companies/3f1c2b4a-5d6e-4f70-8a9b-0c1d2e3f4a5b/invoices/8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d/pdf",
                  "created_at": "2026-10-14T09:30:00Z",
                  "updated_at": "2026-10-14T09:30:00Z"
                }
              }
            }
          },
          "400": {
            "description": "Requête mal formée (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Clé absente, invalide ou révoquée (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Ressource hors du périmètre de la clé (`forbidden`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Introuvable (`not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflit : référence externe déjà utilisée, clé d'idempotence réutilisée avec un autre contenu, ou document verrouillé (`conflict`, `document_locked`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Données invalides (`validation_error`, `amount_exceeds_balance`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Maintenance en cours (`maintenance`). Réessayer après `Retry-After` secondes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "partnerKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Clé partenaire `ffp_live_…` ou `ffp_test_…`."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Toutes les erreurs ont cette forme.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid_request",
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "conflict",
                  "document_locked",
                  "validation_error",
                  "amount_exceeds_balance",
                  "rate_limited",
                  "limit_reached",
                  "maintenance",
                  "server_error"
                ],
                "description": "Code stable, à utiliser dans le code de l'ERP."
              },
              "message": {
                "type": "string",
                "description": "Explication lisible (en français)."
              },
              "details": {
                "type": "array",
                "description": "Pour `validation_error` : un élément par champ refusé.",
                "items": {
                  "type": "object",
                  "properties": {
                    "field": {
                      "type": "string",
                      "example": "lines[0].quantity"
                    },
                    "message": {
                      "type": "string",
                      "example": "Doit être supérieur à 0."
                    }
                  }
                }
              },
              "request_id": {
                "type": "string",
                "description": "Identifiant de l'appel, à communiquer au support."
              }
            }
          }
        }
      },
      "CompanyInput": {
        "type": "object",
        "description": "Entreprise d'un client final du partenaire.",
        "required": [
          "external_ref",
          "name",
          "currency"
        ],
        "properties": {
          "external_ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Référence de l'entreprise dans l'ERP. Unique par partenaire."
          },
          "name": {
            "type": "string",
            "maxLength": 200,
            "description": "Raison sociale, telle qu'elle figure sur les documents."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "description": "E-mail de contact imprimé sur les documents."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Téléphone imprimé sur les documents."
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Adresse du siège."
          },
          "rccm": {
            "type": [
              "string",
              "null"
            ],
            "description": "Registre du commerce et du crédit mobilier."
          },
          "id_nat": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identification nationale."
          },
          "tax_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numéro d'impôt."
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Devise par défaut (ISO 4217).",
            "example": "USD"
          },
          "vat_rate": {
            "type": "string",
            "description": "Taux de TVA par défaut, en pourcentage.",
            "example": "16"
          },
          "branding": {
            "type": "object",
            "description": "Apparence des PDF. Le logo est copié chez FACTURE à l'enregistrement.",
            "properties": {
              "logo_url": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri",
                "description": "Adresse HTTPS d'une image PNG ou JPEG (5 Mo au plus)."
              },
              "brand_color": {
                "type": "string",
                "pattern": "^#[0-9A-Fa-f]{6}$",
                "description": "Couleur de marque.",
                "example": "#0F766E"
              },
              "header_color": {
                "type": "string",
                "pattern": "^#[0-9A-Fa-f]{6}$",
                "description": "Couleur d'en-tête.",
                "example": "#0F172A"
              },
              "invoice_template": {
                "type": "string",
                "enum": [
                  "classic",
                  "clean",
                  "compact",
                  "sidebar",
                  "centered",
                  "letterhead",
                  "detailed",
                  "receipt",
                  "thermal",
                  "bilingual",
                  "bold"
                ],
                "default": "classic",
                "description": "Modèle de mise en page des factures et devis."
              }
            }
          },
          "numbering": {
            "type": "object",
            "description": "Numérotation des documents. Les numéros sont attribués par FACTURE, sans trou.",
            "properties": {
              "invoice_prefix": {
                "type": "string",
                "default": "FAC-",
                "maxLength": 20,
                "description": "Préfixe des factures."
              },
              "quote_prefix": {
                "type": "string",
                "default": "DEV-",
                "maxLength": 20,
                "description": "Préfixe des devis."
              },
              "credit_prefix": {
                "type": "string",
                "default": "AV-",
                "maxLength": 20,
                "description": "Préfixe des avoirs."
              },
              "include_year": {
                "type": "boolean",
                "default": false,
                "description": "Ajoute l'année (FAC-2026-00059) ; le compteur repart à 1 chaque 1er janvier."
              }
            }
          },
          "document_texts": {
            "type": "object",
            "description": "Textes imprimés en bas des documents.",
            "properties": {
              "payment_terms": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Conditions de paiement."
              },
              "bank_details": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Coordonnées bancaires."
              },
              "legal_mentions": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Mentions légales."
              }
            }
          }
        }
      },
      "Company": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "Identifiant FACTURE."
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ],
            "readOnly": true,
            "description": "`test` pour les entreprises créées avec une clé de test."
          },
          "external_ref": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100,
            "description": "Référence de l'entreprise dans l'ERP. `null` pour votre propre entreprise (abonné FACTURE), tant que vous ne lui en donnez pas."
          },
          "name": {
            "type": "string",
            "maxLength": 200,
            "description": "Raison sociale, telle qu'elle figure sur les documents."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "description": "E-mail de contact imprimé sur les documents."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Téléphone imprimé sur les documents."
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Adresse du siège."
          },
          "rccm": {
            "type": [
              "string",
              "null"
            ],
            "description": "Registre du commerce et du crédit mobilier."
          },
          "id_nat": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identification nationale."
          },
          "tax_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numéro d'impôt."
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Devise par défaut (ISO 4217).",
            "example": "USD"
          },
          "vat_rate": {
            "type": "string",
            "description": "Taux de TVA par défaut, en pourcentage.",
            "example": "16"
          },
          "branding": {
            "type": "object",
            "description": "Apparence des PDF. Le logo est copié chez FACTURE à l'enregistrement.",
            "properties": {
              "logo_url": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri",
                "description": "Adresse HTTPS d'une image PNG ou JPEG (5 Mo au plus)."
              },
              "brand_color": {
                "type": "string",
                "pattern": "^#[0-9A-Fa-f]{6}$",
                "description": "Couleur de marque.",
                "example": "#0F766E"
              },
              "header_color": {
                "type": "string",
                "pattern": "^#[0-9A-Fa-f]{6}$",
                "description": "Couleur d'en-tête.",
                "example": "#0F172A"
              },
              "invoice_template": {
                "type": "string",
                "enum": [
                  "classic",
                  "clean",
                  "compact",
                  "sidebar",
                  "centered",
                  "letterhead",
                  "detailed",
                  "receipt",
                  "thermal",
                  "bilingual",
                  "bold"
                ],
                "default": "classic",
                "description": "Modèle de mise en page des factures et devis."
              }
            }
          },
          "numbering": {
            "type": "object",
            "description": "Numérotation des documents. Les numéros sont attribués par FACTURE, sans trou.",
            "properties": {
              "invoice_prefix": {
                "type": "string",
                "default": "FAC-",
                "maxLength": 20,
                "description": "Préfixe des factures."
              },
              "quote_prefix": {
                "type": "string",
                "default": "DEV-",
                "maxLength": 20,
                "description": "Préfixe des devis."
              },
              "credit_prefix": {
                "type": "string",
                "default": "AV-",
                "maxLength": 20,
                "description": "Préfixe des avoirs."
              },
              "include_year": {
                "type": "boolean",
                "default": false,
                "description": "Ajoute l'année (FAC-2026-00059) ; le compteur repart à 1 chaque 1er janvier."
              }
            }
          },
          "document_texts": {
            "type": "object",
            "description": "Textes imprimés en bas des documents.",
            "properties": {
              "payment_terms": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Conditions de paiement."
              },
              "bank_details": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Coordonnées bancaires."
              },
              "legal_mentions": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Mentions légales."
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "CustomerInput": {
        "type": "object",
        "description": "Client destinataire du document. Créé ou mis à jour à chaque document, retrouvé par `external_ref` : l'ERP n'a pas à gérer les clients séparément.",
        "required": [
          "external_ref",
          "name"
        ],
        "properties": {
          "external_ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Référence du client dans l'ERP. Unique par entreprise."
          },
          "name": {
            "type": "string",
            "maxLength": 200,
            "description": "Nom du contact ou de la personne."
          },
          "company": {
            "type": [
              "string",
              "null"
            ],
            "description": "Raison sociale (imprimée en premier si présente)."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "tax_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numéro fiscal du client."
          }
        }
      },
      "Customer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "Identifiant FACTURE du client."
          },
          "external_ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Référence du client dans l'ERP. Unique par entreprise."
          },
          "name": {
            "type": "string",
            "maxLength": 200,
            "description": "Nom du contact ou de la personne."
          },
          "company": {
            "type": [
              "string",
              "null"
            ],
            "description": "Raison sociale (imprimée en premier si présente)."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "tax_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numéro fiscal du client."
          }
        }
      },
      "LineInput": {
        "type": "object",
        "required": [
          "description",
          "quantity",
          "unit_price"
        ],
        "properties": {
          "description": {
            "type": "string",
            "maxLength": 1000,
            "description": "Désignation."
          },
          "quantity": {
            "type": "string",
            "pattern": "^\\d{1,9}(\\.\\d{1,3})?$",
            "description": "Quantité, supérieure à 0 (trois décimales au plus).",
            "example": "2"
          },
          "unit_price": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Prix unitaire hors taxes.",
            "example": "150.00"
          }
        }
      },
      "Line": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "quantity": {
            "type": "string",
            "example": "2"
          },
          "unit_price": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Prix unitaire hors taxes.",
            "example": "150.00"
          },
          "total": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "quantité × prix unitaire, arrondi au centime.",
            "example": "300.00",
            "readOnly": true
          }
        }
      },
      "InvoiceInput": {
        "type": "object",
        "description": "Facture à émettre.",
        "required": [
          "external_ref",
          "customer",
          "issue_date",
          "lines"
        ],
        "properties": {
          "external_ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Référence du document dans l'ERP. Unique par entreprise : un deuxième envoi est refusé (`conflict`)."
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerInput"
          },
          "issue_date": {
            "type": "string",
            "format": "date",
            "description": "Date d'émission (AAAA-MM-JJ)."
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Devise ; par défaut celle de l'entreprise."
          },
          "vat_rate": {
            "type": "string",
            "description": "Taux de TVA en pourcentage ; par défaut celui de l'entreprise.",
            "example": "16"
          },
          "discount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Remise globale, hors taxes.",
            "example": "50.00"
          },
          "shipping_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Frais d'expédition, hors taxes.",
            "example": "0.00"
          },
          "adjustment_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Ajustement hors taxes, positif ou négatif.",
            "example": "0.00"
          },
          "order_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numéro de commande du client."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2000,
            "description": "Note imprimée sur le document."
          },
          "lines": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/LineInput"
            }
          },
          "due_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date d'échéance."
          }
        }
      },
      "QuoteInput": {
        "type": "object",
        "description": "Devis à émettre.",
        "required": [
          "external_ref",
          "customer",
          "issue_date",
          "lines"
        ],
        "properties": {
          "external_ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Référence du document dans l'ERP. Unique par entreprise : un deuxième envoi est refusé (`conflict`)."
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerInput"
          },
          "issue_date": {
            "type": "string",
            "format": "date",
            "description": "Date d'émission (AAAA-MM-JJ)."
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Devise ; par défaut celle de l'entreprise."
          },
          "vat_rate": {
            "type": "string",
            "description": "Taux de TVA en pourcentage ; par défaut celui de l'entreprise.",
            "example": "16"
          },
          "discount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Remise globale, hors taxes.",
            "example": "50.00"
          },
          "shipping_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Frais d'expédition, hors taxes.",
            "example": "0.00"
          },
          "adjustment_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Ajustement hors taxes, positif ou négatif.",
            "example": "0.00"
          },
          "order_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numéro de commande du client."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2000,
            "description": "Note imprimée sur le document."
          },
          "lines": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/LineInput"
            }
          },
          "valid_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date de fin de validité de l'offre."
          }
        }
      },
      "Invoice": {
        "type": "object",
        "description": "Les montants sont calculés par FACTURE : base taxable = sous-total + frais + ajustement − remise (jamais négative) ; TVA = base × taux ; total = base + TVA ; arrondis au centime.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "Identifiant FACTURE."
          },
          "company_id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true
          },
          "external_ref": {
            "type": "string"
          },
          "number": {
            "type": "string",
            "readOnly": true,
            "description": "Numéro attribué par FACTURE.",
            "example": "FAC-2026-00059"
          },
          "status": {
            "type": "string",
            "readOnly": true,
            "enum": [
              "issued",
              "partially_paid",
              "paid",
              "overdue",
              "cancelled"
            ],
            "description": "`issued` émise · `partially_paid` partiellement payée · `paid` payée · `overdue` échéance dépassée · `cancelled` annulée par un avoir total."
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "issue_date": {
            "type": "string",
            "format": "date"
          },
          "due_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "currency": {
            "type": "string"
          },
          "order_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Line"
            }
          },
          "subtotal": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Somme des lignes, hors taxes.",
            "example": "1500.00",
            "readOnly": true
          },
          "discount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Remise globale.",
            "example": "50.00"
          },
          "shipping_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Frais d'expédition.",
            "example": "0.00"
          },
          "adjustment_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Ajustement.",
            "example": "0.00"
          },
          "taxable_base": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Base taxable.",
            "example": "1450.00",
            "readOnly": true
          },
          "vat_rate": {
            "type": "string",
            "example": "16"
          },
          "vat_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Montant de TVA.",
            "example": "232.00",
            "readOnly": true
          },
          "total": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Total TTC.",
            "example": "1682.00",
            "readOnly": true
          },
          "amount_paid": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Total des paiements enregistrés.",
            "example": "0.00",
            "readOnly": true
          },
          "amount_credited": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Total des avoirs émis sur la facture.",
            "example": "0.00",
            "readOnly": true
          },
          "balance_due": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Reste à payer : total − payé − avoirs.",
            "example": "1682.00",
            "readOnly": true
          },
          "first_viewed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "readOnly": true,
            "description": "Première ouverture du lien `public_url` par le client (sans compte). Les ouvertures par l'entreprise elle-même ne comptent pas."
          },
          "last_viewed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "readOnly": true,
            "description": "Dernière ouverture du lien par le client."
          },
          "view_count": {
            "type": "integer",
            "readOnly": true,
            "description": "Nombre de consultations (les ouvertures à moins de 30 minutes d'intervalle comptent pour une)."
          },
          "public_url": {
            "type": "string",
            "format": "uri",
            "readOnly": true,
            "description": "Page de consultation pour le client, sans compte."
          },
          "pdf_url": {
            "type": "string",
            "readOnly": true,
            "description": "Chemin du PDF dans l'API (même authentification)."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "Quote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "Identifiant FACTURE."
          },
          "company_id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true
          },
          "external_ref": {
            "type": "string"
          },
          "number": {
            "type": "string",
            "readOnly": true,
            "example": "DEV-2026-00008"
          },
          "status": {
            "type": "string",
            "readOnly": true,
            "enum": [
              "issued",
              "accepted",
              "refused",
              "invoiced"
            ],
            "description": "`issued` émis · `accepted` accepté · `refused` refusé · `invoiced` transformé en facture."
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "issue_date": {
            "type": "string",
            "format": "date"
          },
          "valid_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "currency": {
            "type": "string"
          },
          "order_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Line"
            }
          },
          "subtotal": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Somme des lignes, hors taxes.",
            "example": "1500.00",
            "readOnly": true
          },
          "discount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Remise globale.",
            "example": "50.00"
          },
          "shipping_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Frais d'expédition.",
            "example": "0.00"
          },
          "adjustment_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Ajustement.",
            "example": "0.00"
          },
          "taxable_base": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Base taxable.",
            "example": "1450.00",
            "readOnly": true
          },
          "vat_rate": {
            "type": "string",
            "example": "16"
          },
          "vat_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Montant de TVA.",
            "example": "232.00",
            "readOnly": true
          },
          "total": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Total TTC.",
            "example": "1682.00",
            "readOnly": true
          },
          "invoice_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "readOnly": true,
            "description": "Facture issue du devis, une fois transformé."
          },
          "first_viewed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "readOnly": true,
            "description": "Première ouverture du lien `public_url` par le client (sans compte). Les ouvertures par l'entreprise elle-même ne comptent pas."
          },
          "last_viewed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "readOnly": true,
            "description": "Dernière ouverture du lien par le client."
          },
          "view_count": {
            "type": "integer",
            "readOnly": true,
            "description": "Nombre de consultations (les ouvertures à moins de 30 minutes d'intervalle comptent pour une)."
          },
          "public_url": {
            "type": "string",
            "format": "uri",
            "readOnly": true
          },
          "pdf_url": {
            "type": "string",
            "readOnly": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "PaymentInput": {
        "type": "object",
        "required": [
          "external_ref",
          "amount",
          "paid_at",
          "method"
        ],
        "properties": {
          "external_ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Référence du règlement dans l'ERP. Unique par entreprise."
          },
          "amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Montant réglé, au plus égal au reste à payer.",
            "example": "1000.00"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time",
            "description": "Date et heure du règlement."
          },
          "method": {
            "type": "string",
            "enum": [
              "cash",
              "bank_transfer",
              "card",
              "mobile_money",
              "cheque",
              "other"
            ],
            "description": "Moyen de paiement."
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200,
            "description": "Référence bancaire ou de transaction."
          }
        }
      },
      "Payment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "Identifiant FACTURE."
          },
          "invoice_id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true
          },
          "external_ref": {
            "type": "string"
          },
          "amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Montant réglé.",
            "example": "1000.00"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time"
          },
          "method": {
            "type": "string",
            "enum": [
              "cash",
              "bank_transfer",
              "card",
              "mobile_money",
              "cheque",
              "other"
            ]
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "CreditNoteInput": {
        "type": "object",
        "required": [
          "external_ref",
          "issue_date",
          "reason"
        ],
        "properties": {
          "external_ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Référence de l'avoir dans l'ERP. Unique par entreprise."
          },
          "issue_date": {
            "type": "string",
            "format": "date"
          },
          "reason": {
            "type": "string",
            "maxLength": 500,
            "description": "Motif, imprimé sur l'avoir."
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineInput"
            },
            "description": "Lignes de l'avoir. Absentes : avoir total, qui reprend toute la facture et l'annule (`cancelled`)."
          }
        }
      },
      "CreditNote": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "Identifiant FACTURE."
          },
          "invoice_id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true
          },
          "external_ref": {
            "type": "string"
          },
          "number": {
            "type": "string",
            "readOnly": true,
            "example": "AV-2026-00003"
          },
          "issue_date": {
            "type": "string",
            "format": "date"
          },
          "reason": {
            "type": "string"
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Line"
            }
          },
          "subtotal": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Total hors taxes.",
            "example": "100.00",
            "readOnly": true
          },
          "vat_rate": {
            "type": "string",
            "description": "Taux de la facture d'origine."
          },
          "vat_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "TVA.",
            "example": "16.00",
            "readOnly": true
          },
          "total": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Total TTC, déduit du reste à payer de la facture.",
            "example": "116.00",
            "readOnly": true
          },
          "currency": {
            "type": "string",
            "readOnly": true
          },
          "pdf_url": {
            "type": "string",
            "readOnly": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "Page": {
        "type": "object",
        "description": "Réponse des listes.",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Éléments de la page, du plus récent au plus ancien."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "À passer dans `cursor` pour la page suivante ; `null` à la dernière page."
          }
        }
      },
      "CompanyUpdate": {
        "type": "object",
        "description": "Les champs de `CompanyInput`, tous facultatifs : seuls les champs envoyés sont modifiés.",
        "properties": {
          "external_ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Référence de l'entreprise dans l'ERP. Unique par partenaire."
          },
          "name": {
            "type": "string",
            "maxLength": 200,
            "description": "Raison sociale, telle qu'elle figure sur les documents."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "description": "E-mail de contact imprimé sur les documents."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Téléphone imprimé sur les documents."
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Adresse du siège."
          },
          "rccm": {
            "type": [
              "string",
              "null"
            ],
            "description": "Registre du commerce et du crédit mobilier."
          },
          "id_nat": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identification nationale."
          },
          "tax_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numéro d'impôt."
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Devise par défaut (ISO 4217).",
            "example": "USD"
          },
          "vat_rate": {
            "type": "string",
            "description": "Taux de TVA par défaut, en pourcentage.",
            "example": "16"
          },
          "branding": {
            "type": "object",
            "description": "Apparence des PDF. Le logo est copié chez FACTURE à l'enregistrement.",
            "properties": {
              "logo_url": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri",
                "description": "Adresse HTTPS d'une image PNG ou JPEG (5 Mo au plus)."
              },
              "brand_color": {
                "type": "string",
                "pattern": "^#[0-9A-Fa-f]{6}$",
                "description": "Couleur de marque.",
                "example": "#0F766E"
              },
              "header_color": {
                "type": "string",
                "pattern": "^#[0-9A-Fa-f]{6}$",
                "description": "Couleur d'en-tête.",
                "example": "#0F172A"
              },
              "invoice_template": {
                "type": "string",
                "enum": [
                  "classic",
                  "clean",
                  "compact",
                  "sidebar",
                  "centered",
                  "letterhead",
                  "detailed",
                  "receipt",
                  "thermal",
                  "bilingual",
                  "bold"
                ],
                "default": "classic",
                "description": "Modèle de mise en page des factures et devis."
              }
            }
          },
          "numbering": {
            "type": "object",
            "description": "Numérotation des documents. Les numéros sont attribués par FACTURE, sans trou.",
            "properties": {
              "invoice_prefix": {
                "type": "string",
                "default": "FAC-",
                "maxLength": 20,
                "description": "Préfixe des factures."
              },
              "quote_prefix": {
                "type": "string",
                "default": "DEV-",
                "maxLength": 20,
                "description": "Préfixe des devis."
              },
              "credit_prefix": {
                "type": "string",
                "default": "AV-",
                "maxLength": 20,
                "description": "Préfixe des avoirs."
              },
              "include_year": {
                "type": "boolean",
                "default": false,
                "description": "Ajoute l'année (FAC-2026-00059) ; le compteur repart à 1 chaque 1er janvier."
              }
            }
          },
          "document_texts": {
            "type": "object",
            "description": "Textes imprimés en bas des documents.",
            "properties": {
              "payment_terms": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Conditions de paiement."
              },
              "bank_details": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Coordonnées bancaires."
              },
              "legal_mentions": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Mentions légales."
              }
            }
          }
        }
      },
      "InvoicePreviewInput": {
        "type": "object",
        "description": "Les champs de `InvoiceInput` ; `external_ref` est facultatif.",
        "required": [
          "customer",
          "issue_date",
          "lines"
        ],
        "properties": {
          "external_ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Référence du document dans l'ERP. Unique par entreprise : un deuxième envoi est refusé (`conflict`)."
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerInput"
          },
          "issue_date": {
            "type": "string",
            "format": "date",
            "description": "Date d'émission (AAAA-MM-JJ)."
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Devise ; par défaut celle de l'entreprise."
          },
          "vat_rate": {
            "type": "string",
            "description": "Taux de TVA en pourcentage ; par défaut celui de l'entreprise.",
            "example": "16"
          },
          "discount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Remise globale, hors taxes.",
            "example": "50.00"
          },
          "shipping_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Frais d'expédition, hors taxes.",
            "example": "0.00"
          },
          "adjustment_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Ajustement hors taxes, positif ou négatif.",
            "example": "0.00"
          },
          "order_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numéro de commande du client."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2000,
            "description": "Note imprimée sur le document."
          },
          "lines": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/LineInput"
            }
          },
          "due_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date d'échéance."
          }
        }
      },
      "QuotePreviewInput": {
        "type": "object",
        "description": "Les champs de `QuoteInput` ; `external_ref` est facultatif.",
        "required": [
          "customer",
          "issue_date",
          "lines"
        ],
        "properties": {
          "external_ref": {
            "type": "string",
            "maxLength": 100,
            "description": "Référence du document dans l'ERP. Unique par entreprise : un deuxième envoi est refusé (`conflict`)."
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerInput"
          },
          "issue_date": {
            "type": "string",
            "format": "date",
            "description": "Date d'émission (AAAA-MM-JJ)."
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Devise ; par défaut celle de l'entreprise."
          },
          "vat_rate": {
            "type": "string",
            "description": "Taux de TVA en pourcentage ; par défaut celui de l'entreprise.",
            "example": "16"
          },
          "discount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Remise globale, hors taxes.",
            "example": "50.00"
          },
          "shipping_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Frais d'expédition, hors taxes.",
            "example": "0.00"
          },
          "adjustment_amount": {
            "type": "string",
            "pattern": "^-?\\d{1,12}(\\.\\d{1,2})?$",
            "description": "Ajustement hors taxes, positif ou négatif.",
            "example": "0.00"
          },
          "order_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Numéro de commande du client."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2000,
            "description": "Note imprimée sur le document."
          },
          "lines": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/LineInput"
            }
          },
          "valid_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date de fin de validité de l'offre."
          }
        }
      }
    }
  }
}