# API : invoices 10 opérations REST du groupe invoices. Base : `/api/v1`. [Conventions](/documentation/api-conventions/) · [Toutes les ressources](/documentation/api-reference/) - GET /invoices : Lister les factures (hors corbeille) - GET /invoices/{id} : Détail d'une facture - POST /invoices/{id}/payments : Marquer payée (échéances soldées, notification - règles UI) - GET /invoices/{id}/pdf : PDF de la facture (si PDF_RENDERER=chromium est actif - 404 sinon) - GET /invoices/{id}/facturx : Factur-X de la facture (PDF/A-3 avec factur-x.xml EN 16931), archivé - généré à la demande s'il n'existe pas - GET /invoices/{id}/einvoicing : Transmissions de la facture électronique et statuts de cycle de vie DGFiP - POST /invoices/{id}/einvoicing/transmissions : Déclarer un dépôt du Factur-X fait par un tiers (plateforme sans adaptateur) - POST /invoices/{id}/einvoicing/events : Pousser un statut de cycle de vie DGFiP (200 à 213) sur la dernière transmission déposée - PUT /invoices/{id}/external-refs/{source} : Poser l'identifiant d'une source sur un facture (idempotent) - DELETE /invoices/{id}/external-refs/{source} : Retirer l'identifiant d'une source sur un facture ## GET /invoices ```json { "summary": "Lister les factures (hors corbeille)", "tags": [ "Factures" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Curseur opaque de la page précédente", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Taille de page - défaut 50, max 200 (clampé)", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "ISO 8601 - objets modifiés depuis (inclusif), le filtre des syncs incrémentales", "type": "string" } }, { "name": "since", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Jours (1 à 365) - objets dans leur statut courant depuis plus de N jours (status_changed_at), combinable avec status (T-1407)", "type": "integer", "minimum": 1, "maximum": 365 } }, { "name": "ids", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Répétable - restriction à une liste d'ids (max 200)", "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "draft", "issued", "paid", "late", "credit" ] } }, { "name": "companyId", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string" } }, { "name": "cycleId", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string" } }, { "name": "businessUnitId", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string" } }, { "name": "externalId", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Objets qui portent cet identifiant externe (exact) - avec `externalSource` pour une source précise", "type": "string" } }, { "name": "externalSource", "in": "query", "required": false, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Source de l'identifiant externe (`tacto`…)", "type": "string" } } ], "security": [ { "oauth2": [ "invoices:read" ] }, { "userSession": [] } ], "responses": { "200": { "description": "Page de factures", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "number": { "description": "Numéro légal, pris à l'émission (#996, ADR-215 D4 b) - null en brouillon ; un brouillon antérieur garde le sien", "type": [ "string", "null" ] }, "quoteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "targetType": { "type": "string", "enum": [ "company", "contact" ] }, "targetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "businessUnitId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "cycleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "amountInclTax": { "type": "string", "description": "TTC, chaîne décimale - négatif pour un avoir" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Devise du document, ISO 4217 (T-1404, ADR-184) - EUR par défaut" }, "fxRate": { "description": "Taux BCE figé, « 1 EUR = fxRate devise » - null en euros", "type": [ "string", "null" ] }, "fxRateDate": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ], "description": "Jour de publication du taux figé - null en euros" }, "amountEur": { "type": "string", "description": "Contre-valeur en euros au taux figé" }, "status": { "type": "string", "enum": [ "draft", "issued", "paid", "late", "credit" ], "description": "late est dérivé : émise à échéance dépassée (même règle que les listes UI)" }, "issuedOn": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "dueOn": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ], "description": "Échéance : conditions de paiement appliquées à la date d'émission (#998)" }, "paymentCondition": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "days", "days_end_of_month", "end_of_month_then_day" ] }, "days": { "type": "integer", "minimum": 0, "maximum": 365 }, "dayOfNextMonth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "null" } ] } }, "required": [ "type", "days", "dayOfNextMonth" ], "additionalProperties": false }, { "type": "null" } ], "description": "#998 : condition de paiement { type, days, dayOfNextMonth } ; null sur un avoir et une facture antérieure" }, "paidOn": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "creditOfInvoiceId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "vatRegime": { "type": "string", "enum": [ "domestic", "reverse_charge" ], "description": "T-1402 : reverse_charge = autoliquidation (client assujetti d'un autre État membre, TVA à 0, amountInclTax = HT)" }, "exportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "statusChangedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Entrée dans le statut courant (T-1407)" }, "externalRefs": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Système source (minuscules) - `tacto`, `erp`…" }, "externalId": { "type": "string" }, "sourceUpdatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "Dernière modification connue dans la source (curseur du delta), null si inconnue" } }, "required": [ "source", "externalId", "sourceUpdatedAt" ], "additionalProperties": false }, "description": "Identifiants de cet objet dans les systèmes tiers (external_ref, ADR-138 D1, ADR-156 D6)" } }, "required": [ "id", "number", "quoteId", "targetType", "targetId", "businessUnitId", "cycleId", "amountInclTax", "currency", "fxRate", "fxRateDate", "amountEur", "status", "issuedOn", "dueOn", "paymentCondition", "paidOn", "creditOfInvoiceId", "vatRegime", "exportedAt", "updatedAt", "statusChangedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "default": { "description": "Erreur - enveloppe problem+json (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } ``` ## GET /invoices/{id} ```json { "summary": "Détail d'une facture", "tags": [ "Factures" ], "security": [ { "oauth2": [ "invoices:read" ] }, { "userSession": [] } ], "responses": { "200": { "description": "Facture", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "number": { "description": "Numéro légal, pris à l'émission (#996, ADR-215 D4 b) - null en brouillon ; un brouillon antérieur garde le sien", "type": [ "string", "null" ] }, "quoteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "targetType": { "type": "string", "enum": [ "company", "contact" ] }, "targetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "businessUnitId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "cycleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "amountInclTax": { "type": "string", "description": "TTC, chaîne décimale - négatif pour un avoir" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Devise du document, ISO 4217 (T-1404, ADR-184) - EUR par défaut" }, "fxRate": { "description": "Taux BCE figé, « 1 EUR = fxRate devise » - null en euros", "type": [ "string", "null" ] }, "fxRateDate": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ], "description": "Jour de publication du taux figé - null en euros" }, "amountEur": { "type": "string", "description": "Contre-valeur en euros au taux figé" }, "status": { "type": "string", "enum": [ "draft", "issued", "paid", "late", "credit" ], "description": "late est dérivé : émise à échéance dépassée (même règle que les listes UI)" }, "issuedOn": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "dueOn": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ], "description": "Échéance : conditions de paiement appliquées à la date d'émission (#998)" }, "paymentCondition": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "days", "days_end_of_month", "end_of_month_then_day" ] }, "days": { "type": "integer", "minimum": 0, "maximum": 365 }, "dayOfNextMonth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "null" } ] } }, "required": [ "type", "days", "dayOfNextMonth" ], "additionalProperties": false }, { "type": "null" } ], "description": "#998 : condition de paiement { type, days, dayOfNextMonth } ; null sur un avoir et une facture antérieure" }, "paidOn": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "creditOfInvoiceId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "vatRegime": { "type": "string", "enum": [ "domestic", "reverse_charge" ], "description": "T-1402 : reverse_charge = autoliquidation (client assujetti d'un autre État membre, TVA à 0, amountInclTax = HT)" }, "exportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "statusChangedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Entrée dans le statut courant (T-1407)" }, "externalRefs": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Système source (minuscules) - `tacto`, `erp`…" }, "externalId": { "type": "string" }, "sourceUpdatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "Dernière modification connue dans la source (curseur du delta), null si inconnue" } }, "required": [ "source", "externalId", "sourceUpdatedAt" ], "additionalProperties": false }, "description": "Identifiants de cet objet dans les systèmes tiers (external_ref, ADR-138 D1, ADR-156 D6)" } }, "required": [ "id", "number", "quoteId", "targetType", "targetId", "businessUnitId", "cycleId", "amountInclTax", "currency", "fxRate", "fxRateDate", "amountEur", "status", "issuedOn", "dueOn", "paymentCondition", "paidOn", "creditOfInvoiceId", "vatRegime", "exportedAt", "updatedAt", "statusChangedAt" ], "additionalProperties": false } } } }, "default": { "description": "Erreur - enveloppe problem+json (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } ``` ## POST /invoices/{id}/payments ```json { "summary": "Marquer payée (échéances soldées, notification - règles UI)", "description": "Permis depuis issued ou late uniquement (422 sinon). Solde les échéances liées, trace l'activité et notifie le commercial comme le geste UI.", "tags": [ "Factures" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "paidOn": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Date de paiement (YYYY-MM-DD)" }, "method": { "description": "Moyen de règlement (défaut : transfer)", "type": "string", "enum": [ "transfer", "card", "other" ] }, "reference": { "description": "Référence du règlement (libellé de virement, identifiant de transaction)", "type": "string", "maxLength": 140 } }, "required": [ "paidOn" ], "additionalProperties": false } } } }, "security": [ { "oauth2": [ "invoices:write" ] }, { "userSession": [] } ], "responses": { "201": { "description": "Facture payée", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "number": { "description": "Numéro légal, pris à l'émission (#996, ADR-215 D4 b) - null en brouillon ; un brouillon antérieur garde le sien", "type": [ "string", "null" ] }, "quoteId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "targetType": { "type": "string", "enum": [ "company", "contact" ] }, "targetId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "businessUnitId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "cycleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "amountInclTax": { "type": "string", "description": "TTC, chaîne décimale - négatif pour un avoir" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Devise du document, ISO 4217 (T-1404, ADR-184) - EUR par défaut" }, "fxRate": { "description": "Taux BCE figé, « 1 EUR = fxRate devise » - null en euros", "type": [ "string", "null" ] }, "fxRateDate": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ], "description": "Jour de publication du taux figé - null en euros" }, "amountEur": { "type": "string", "description": "Contre-valeur en euros au taux figé" }, "status": { "type": "string", "enum": [ "draft", "issued", "paid", "late", "credit" ], "description": "late est dérivé : émise à échéance dépassée (même règle que les listes UI)" }, "issuedOn": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "dueOn": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ], "description": "Échéance : conditions de paiement appliquées à la date d'émission (#998)" }, "paymentCondition": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "days", "days_end_of_month", "end_of_month_then_day" ] }, "days": { "type": "integer", "minimum": 0, "maximum": 365 }, "dayOfNextMonth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "null" } ] } }, "required": [ "type", "days", "dayOfNextMonth" ], "additionalProperties": false }, { "type": "null" } ], "description": "#998 : condition de paiement { type, days, dayOfNextMonth } ; null sur un avoir et une facture antérieure" }, "paidOn": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "creditOfInvoiceId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "vatRegime": { "type": "string", "enum": [ "domestic", "reverse_charge" ], "description": "T-1402 : reverse_charge = autoliquidation (client assujetti d'un autre État membre, TVA à 0, amountInclTax = HT)" }, "exportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "statusChangedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Entrée dans le statut courant (T-1407)" }, "externalRefs": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Système source (minuscules) - `tacto`, `erp`…" }, "externalId": { "type": "string" }, "sourceUpdatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "Dernière modification connue dans la source (curseur du delta), null si inconnue" } }, "required": [ "source", "externalId", "sourceUpdatedAt" ], "additionalProperties": false }, "description": "Identifiants de cet objet dans les systèmes tiers (external_ref, ADR-138 D1, ADR-156 D6)" } }, "required": [ "id", "number", "quoteId", "targetType", "targetId", "businessUnitId", "cycleId", "amountInclTax", "currency", "fxRate", "fxRateDate", "amountEur", "status", "issuedOn", "dueOn", "paymentCondition", "paidOn", "creditOfInvoiceId", "vatRegime", "exportedAt", "updatedAt", "statusChangedAt" ], "additionalProperties": false } } } }, "default": { "description": "Erreur - enveloppe problem+json (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } ``` ## GET /invoices/{id}/pdf ```json { "summary": "PDF de la facture (si PDF_RENDERER=chromium est actif - 404 sinon)", "tags": [ "Factures" ], "security": [ { "oauth2": [ "invoices:read" ] }, { "userSession": [] } ], "responses": { "200": { "description": "Document PDF (application/pdf, attachment)" }, "default": { "description": "Erreur - enveloppe problem+json (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } ``` ## GET /invoices/{id}/facturx ```json { "summary": "Factur-X de la facture (PDF/A-3 avec factur-x.xml EN 16931), archivé - généré à la demande s'il n'existe pas", "tags": [ "Factures" ], "security": [ { "oauth2": [ "invoices:read" ] }, { "userSession": [] } ], "responses": { "200": { "description": "Factur-X (application/pdf, attachment, en-tête X-Cercla-Sha256)" }, "404": { "description": "Facture introuvable, ou module facturation électronique inactif (einvoice-unavailable)" }, "409": { "description": "Facture inéligible (einvoice-ineligible : brouillon, client sans SIRET, totaux)" }, "default": { "description": "Erreur - enveloppe problem+json (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } ``` ## GET /invoices/{id}/einvoicing ```json { "summary": "Transmissions de la facture électronique et statuts de cycle de vie DGFiP", "tags": [ "Factures" ], "security": [ { "oauth2": [ "invoices:read" ] }, { "userSession": [] } ], "responses": { "200": { "description": "Transmissions (plus récente d'abord) avec événements", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transmissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceNumber": { "type": "string" }, "provider": { "type": "string", "description": "mock, qonto, sage, afnor, file, external ou nom donné par le tiers" }, "providerRef": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "queued", "submitted", "failed", "done" ] }, "lastCode": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lastCodeLabel": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "documentFileId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "transmissionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceNumber": { "type": "string" }, "provider": { "type": "string" }, "providerRef": { "type": [ "string", "null" ] }, "code": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "label": { "type": "string" }, "source": { "type": "string", "enum": [ "provider", "api", "manual", "system" ] }, "reason": { "type": [ "string", "null" ] }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "transmissionId", "invoiceId", "invoiceNumber", "provider", "providerRef", "code", "label", "source", "reason", "occurredAt" ], "additionalProperties": false } } }, "required": [ "id", "invoiceId", "invoiceNumber", "provider", "providerRef", "state", "lastCode", "lastCodeLabel", "lastError", "documentFileId", "createdAt", "updatedAt", "events" ], "additionalProperties": false } } }, "required": [ "transmissions" ], "additionalProperties": false } } } }, "default": { "description": "Erreur - enveloppe problem+json (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } ``` ## POST /invoices/{id}/einvoicing/transmissions ```json { "summary": "Déclarer un dépôt du Factur-X fait par un tiers (plateforme sans adaptateur)", "description": "Crée une transmission déposée (événement 200 daté du dépôt), ou rend le dépôt existant pour la même facture, le même fournisseur et la même référence. Après désactivation, conserve seulement la preuve, sans effets secondaires. L'empreinte `documentSha256`, si fournie, doit être celle de l'archive Cercla (409 sinon).", "tags": [ "Factures" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "providerRef": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Identifiant du dépôt chez la plateforme" }, "provider": { "description": "Nom de la plateforme (défaut : external)", "type": "string", "minLength": 1, "maxLength": 80 }, "depositedAt": { "description": "Date du dépôt (défaut : maintenant)", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?:Z))$" } ] }, "documentSha256": { "description": "Empreinte du fichier déposé - vérifiée contre l'archive Cercla (409 sinon)", "type": "string", "pattern": "^[0-9a-f]{64}$" }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "providerRef" ], "additionalProperties": false } } } }, "security": [ { "oauth2": [ "invoices:write" ] }, { "userSession": [] } ], "responses": { "200": { "description": "Dépôt déjà enregistré", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceNumber": { "type": "string" }, "provider": { "type": "string", "description": "mock, qonto, sage, afnor, file, external ou nom donné par le tiers" }, "providerRef": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "queued", "submitted", "failed", "done" ] }, "lastCode": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lastCodeLabel": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "documentFileId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "invoiceId", "invoiceNumber", "provider", "providerRef", "state", "lastCode", "lastCodeLabel", "lastError", "documentFileId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "201": { "description": "Transmission déposée", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceNumber": { "type": "string" }, "provider": { "type": "string", "description": "mock, qonto, sage, afnor, file, external ou nom donné par le tiers" }, "providerRef": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "queued", "submitted", "failed", "done" ] }, "lastCode": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lastCodeLabel": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "documentFileId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "invoiceId", "invoiceNumber", "provider", "providerRef", "state", "lastCode", "lastCodeLabel", "lastError", "documentFileId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "default": { "description": "Erreur - enveloppe problem+json (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } ``` ## POST /invoices/{id}/einvoicing/events ```json { "summary": "Pousser un statut de cycle de vie DGFiP (200 à 213) sur la dernière transmission déposée", "description": "Idempotent par (transmission, code, date) : 200 sans corps si l'événement existait. 210 et 213 notifient les administrateurs si les applications et générations restent actives ; après arrêt, seule la preuve est conservée sans reprise automatique. Aucun statut ne change l'état métier de la facture.", "tags": [ "Factures" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "integer", "minimum": 200, "maximum": 213, "description": "Code de cycle de vie DGFiP (spécifications externes 3.1) : 200 déposée … 213 rejetée" }, "occurredAt": { "description": "Date du statut chez la plateforme (défaut : maintenant)", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?:Z))$" } ] }, "reason": { "description": "Motif de refus ou de rejet (REJ_*)", "type": "string", "maxLength": 2000 }, "transmissionId": { "description": "Cible explicite - défaut : dernière transmission déposée", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "payload": { "description": "Charge utile brute, diagnostic seulement", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code" ], "additionalProperties": false } } } }, "security": [ { "oauth2": [ "invoices:write" ] }, { "userSession": [] } ], "responses": { "201": { "description": "Événement enregistré", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "transmissionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "invoiceNumber": { "type": "string" }, "provider": { "type": "string" }, "providerRef": { "type": [ "string", "null" ] }, "code": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "label": { "type": "string" }, "source": { "type": "string", "enum": [ "provider", "api", "manual", "system" ] }, "reason": { "type": [ "string", "null" ] }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "transmissionId", "invoiceId", "invoiceNumber", "provider", "providerRef", "code", "label", "source", "reason", "occurredAt" ], "additionalProperties": false } } } }, "default": { "description": "Erreur - enveloppe problem+json (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } ``` ## PUT /invoices/{id}/external-refs/{source} ```json { "summary": "Poser l'identifiant d'une source sur un facture (idempotent)", "description": "Une source, un identifiant par objet : la même écriture deux fois ne crée qu'une ligne ; un identifiant déjà porté par un AUTRE objet de la même source répond 409 avec l'objet porteur (jamais déplacé en silence). La source `salesforce` est réservée aux scripts de reprise (403). Même garde que le PATCH de l'objet : hors visibilité 404, hors périmètre d'écriture 403.", "tags": [ "Factures" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceUpdatedAt": { "description": "Dernière modification dans la source - curseur du delta", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } ] } }, "required": [ "externalId" ], "additionalProperties": false } } } }, "security": [ { "oauth2": [ "invoices:write" ] }, { "userSession": [] } ], "responses": { "200": { "description": "Identifiants de l'objet après écriture", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Objet porteur" }, "externalRefs": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Système source (minuscules) - `tacto`, `erp`…" }, "externalId": { "type": "string" }, "sourceUpdatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "Dernière modification connue dans la source (curseur du delta), null si inconnue" } }, "required": [ "source", "externalId", "sourceUpdatedAt" ], "additionalProperties": false }, "description": "Identifiants de cet objet dans les systèmes tiers (external_ref, ADR-138 D1, ADR-156 D6)" } }, "required": [ "id", "externalRefs" ], "additionalProperties": false } } } }, "default": { "description": "Erreur - enveloppe problem+json (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } ``` ## DELETE /invoices/{id}/external-refs/{source} ```json { "summary": "Retirer l'identifiant d'une source sur un facture", "tags": [ "Factures" ], "security": [ { "oauth2": [ "invoices:write" ] }, { "userSession": [] } ], "responses": { "200": { "description": "Identifiants restants", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Objet porteur" }, "externalRefs": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Système source (minuscules) - `tacto`, `erp`…" }, "externalId": { "type": "string" }, "sourceUpdatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "Dernière modification connue dans la source (curseur du delta), null si inconnue" } }, "required": [ "source", "externalId", "sourceUpdatedAt" ], "additionalProperties": false }, "description": "Identifiants de cet objet dans les systèmes tiers (external_ref, ADR-138 D1, ADR-156 D6)" }, "removed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Références retirées (0 si la source n'en portait pas)" } }, "required": [ "id", "externalRefs", "removed" ], "additionalProperties": false } } } }, "default": { "description": "Erreur - enveloppe problem+json (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } ```