{"components":{"schemas":{"Invoice":{"properties":{"buyer":{"$ref":"#/components/schemas/Party"},"currencyCode":{"type":"string"},"invoiceNumber":{"type":"string"},"issueDate":{"format":"date","type":"string"},"lines":{"items":{"$ref":"#/components/schemas/Line"},"type":"array"},"seller":{"$ref":"#/components/schemas/Party"},"totals":{"$ref":"#/components/schemas/Totals"},"vatBreakdown":{"items":{"$ref":"#/components/schemas/VatBreakdown"},"type":"array"}},"required":["invoiceNumber","issueDate","currencyCode","seller","buyer","lines","totals"],"type":"object"},"Line":{"properties":{"id":{"type":"string"},"itemName":{"type":"string"},"quantity":{"type":"number"},"unitPrice":{"type":"number"},"vatRate":{"type":"number"}},"type":"object"},"Party":{"properties":{"city":{"type":"string"},"countryCode":{"type":"string"},"name":{"type":"string"},"postalCode":{"type":"string"},"street":{"type":"string"},"vatId":{"type":"string"}},"type":"object"},"Problem":{"description":"RFC 7807.","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"type":"object"},"Totals":{"properties":{"amountDue":{"type":"number"},"totalVat":{"type":"number"},"totalWithVat":{"type":"number"},"totalWithoutVat":{"type":"number"}},"type":"object"},"ValidationReport":{"properties":{"conforme":{"type":"boolean"},"rulepack":{"type":"object"},"schematronChecked":{"type":"boolean"},"violations":{"items":{"type":"object"},"type":"array"}},"type":"object"},"VatBreakdown":{"properties":{"category":{"type":"string"},"taxableAmount":{"type":"number"},"vatAmount":{"type":"number"}},"type":"object"}},"securitySchemes":{"apiKey":{"description":"En-tête `Authorization: Bearer \u003cclé\u003e`.","scheme":"bearer","type":"http"}}},"info":{"description":"API de génération, validation, conversion et extraction de factures électroniques réglementaires (Factur-X, CII, UBL), conformes EN 16931 / EXTENDED-CTC-FR. Statut au 22/07/2026 : génération, validation (schematron officiel FNFE-MPE réel sur Factur-X/CII et UBL), comptes/facturation self-service, extraction et conversions UBL tous livrés.\n","title":"Heartwood by Canopée Digitale","version":"1"},"openapi":"3.0.3","paths":{"/convert":{"post":{"description":"Combinaisons supportées via `?from=\u0026to=` : cii→ubl (variant requis), ubl→cii, cii→facturx (profile requis, emballage PDF/A-3), facturx→cii (extraction du CII brut, distinct du JSON normalisé de /extract).\n","parameters":[{"in":"query","name":"from","required":true,"schema":{"enum":["cii","ubl","facturx"],"type":"string"}},{"in":"query","name":"to","required":true,"schema":{"enum":["cii","ubl","facturx"],"type":"string"}},{"description":"Requis si to=ubl.","in":"query","name":"variant","required":false,"schema":{"enum":["fr-socle","peppol-bis"],"type":"string"}},{"description":"Requis si to=facturx.","in":"query","name":"profile","required":false,"schema":{"enum":["EN16931","EXTENDED-CTC-FR"],"type":"string"}}],"requestBody":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}},"application/xml":{"schema":{"type":"string"}}},"required":true},"responses":{"200":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}},"application/xml":{"schema":{"type":"string"}}},"description":"Document converti (XML ou PDF selon `to`). En-tête X-Conversion-Warnings (JSON, toujours vide à ce stade — cf. doc)."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Combinaison from/to non supportée, ou paramètre requis manquant."},"413":{"description":"Charge supérieure à 20 Mo."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Document source invalide/mal formé pour le format déclaré."}},"summary":"Convertir entre sérialisations (CII, UBL, Factur-X)"}},"/extract":{"post":{"description":"Accepte un PDF Factur-X (PDF/A-3 + CII embarqué) ou un CII XML autonome. Retourne le JSON au même schéma que l'entrée de `POST /generate/facturx` (aller-retour symétrique, FR-6). Un champ absent du document source est retourné vide/zéro, jamais inventé. Les PDF signés électroniquement sont acceptés (signature ni vérifiée ni altérée, sa présence est signalée dans `digitallySigned`).\n","requestBody":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}},"application/xml":{"schema":{"type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"digitallySigned":{"type":"boolean"},"invoice":{"$ref":"#/components/schemas/Invoice"},"signatureVerified":{"description":"Toujours false — la signature n'est jamais vérifiée (AD-3).","type":"boolean"}},"type":"object"}}},"description":"JSON normalisé extrait."},"413":{"description":"Charge supérieure à 20 Mo, rejetée avant tout parsing."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"PDF chiffré/corrompu, pièce jointe CII absente, ou CII mal formé — cause explicite dans `detail`."}},"summary":"Extraire les données d'un Factur-X ou d'un CII vers JSON normalisé"}},"/generate/facturx":{"post":{"description":"Décode et valide la complétude du JSON pour le profil demandé, puis génère un PDF/A-3 avec le CII embarqué en pièce jointe. ⚠️ Conformité PDF/A-3 non vérifiée par veraPDF à ce jour (voir Story 1.4 — /Metadata et /AF présents, OutputIntent/ICC et embarquement des polices restent à faire).\n","parameters":[{"in":"query","name":"profile","required":true,"schema":{"enum":["EN16931","EXTENDED-CTC-FR"],"type":"string"}},{"description":"Rule pack à cibler. Omis = dernière version stable (ou le placeholder de développement en son absence).","in":"query","name":"rulepack","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"buyer":{"name":"Acheteur SAS"},"currencyCode":"EUR","invoiceNumber":"F-2026-001","issueDate":"2026-07-20","lines":[{"id":"1","itemName":"Prestation","quantity":1,"unitPrice":100,"vatRate":20}],"seller":{"name":"Vendeur SARL"},"totals":{"amountDue":120,"totalVat":20,"totalWithVat":120,"totalWithoutVat":100},"vatBreakdown":[{"category":"S","taxableAmount":100,"vatAmount":20}]},"schema":{"$ref":"#/components/schemas/Invoice"}}},"required":true},"responses":{"200":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}}},"description":"PDF/A-3 Factur-X généré."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Profil non supporté, ou JSON malformé."},"413":{"description":"Charge supérieure à 20 Mo, rejetée avant tout parsing."},"422":{"content":{"application/problem+json":{"example":{"instance":"01ABCXYZ","missing":[{"bt":"BT-1","path":"invoiceNumber"}],"status":422,"title":"Champs requis manquants pour le profil demandé","type":"incomplete-invoice"},"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Facture incomplète pour le profil demandé — la réponse liste les BT-* manquants."},"501":{"description":"JSON accepté et valide, génération non encore implémentée pour ce chemin de code (ne devrait plus survenir depuis Story 1.4)."}},"summary":"Générer une facture Factur-X (PDF/A-3 + CII embarqué)"}},"/generate/ubl":{"post":{"description":"Même JSON d'entrée que /generate/facturx (modèle pivot EN 16931). La variante `xrechnung` n'est PAS exposée (spike licences/corpus J4 non réalisé) — HTTP 400 si demandée.\n","parameters":[{"in":"query","name":"variant","required":true,"schema":{"enum":["fr-socle","peppol-bis"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}},"required":true},"responses":{"200":{"content":{"application/xml":{"schema":{"type":"string"}}},"description":"XML UBL 2.1 généré."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Variante non supportée (y compris xrechnung), ou JSON malformé."},"413":{"description":"Charge supérieure à 20 Mo."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Facture incomplète — la réponse liste les BT-* manquants."}},"summary":"Générer une facture UBL 2.1 (fr-socle ou peppol-bis)"}},"/rulepacks":{"get":{"responses":{"200":{"content":{"application/json":{"example":{"rulepacks":[{"format":"facturx","id":"dev-placeholder-facturx","status":"placeholder","version":"0.0.0-dev"}]}}},"description":"Liste des packs, statut, sources, licences."}},"summary":"Lister les rule packs disponibles"}},"/validate":{"post":{"description":"Le verdict est TOUJOURS accompagné du rule pack appliqué — jamais « conforme à la réglementation ». La validation exécute le schéma XSD ET les règles schematron du rule pack appliqué ; chaque violation est rendue avec son code BR-*.\n","parameters":[{"description":"Profil appliqué par le rule pack. Défaut (si omis) : EXTENDED-CTC-FR (profil exigé en France). Une valeur non reconnue répond 400.","in":"query","name":"profile","required":false,"schema":{"enum":["EN16931","EXTENDED-CTC-FR"],"type":"string"}},{"description":"Cible un rule pack précis. Omis = dernière version stable du format et du profil. Prend le pas sur profile s'il est fourni.","in":"query","name":"rulepack","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/xml":{"schema":{"type":"string"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"conforme":false,"rulepack":{"format":"facturx","id":"dev-placeholder-facturx","status":"placeholder","version":"0.0.0-dev"},"schematronChecked":false,"violations":[{"br":"","message":"cvc-elt.1.a: ...","path":"","severity":"error"}]},"schema":{"$ref":"#/components/schemas/ValidationReport"}}},"description":"Rapport de conformité."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Profil inconnu, rule pack inconnu, ou document mal formé. La réponse liste les packs disponibles si pertinent."},"413":{"description":"Charge supérieure à 20 Mo."}},"summary":"Valider un document (Factur-X, CII) et obtenir un rapport de conformité"}}},"security":[{"apiKey":[]}],"servers":[{"url":"/v1"}]}