Aller au contenu principal

Créer une facture

POST 
/api/v1/workspaces/:workspace_id/invoices

Crée une nouvelle facture pour l'espace de travail indiqué.

Avant que la facture ne soit construite, le payload est complété avec les valeurs par défaut côté entreprise :

  • résolution de party_id : une entrée parties portant un party_id (éventuellement billing_address_id) est complétée à partir de l'annuaire de l'entreprise (nom, identifiant/schéma d'immatriculation légale, numéro de TVA, identifiant de routage, adresse de facturation, contact par défaut) et reliée en retour afin que le party_id de la réponse fasse l'aller-retour. La recherche est cantonnée par type STI pour correspondre à direction : buyer sur sales se résout parmi les clients de l'entreprise, seller sur purchases parmi ses fournisseurs ; payee et tax_representative se résolvent dans l'ensemble de l'annuaire. Un party_id sur le rôle propre de l'entreprise (seller sur sales, buyer sur purchases) retourne 422 (api.invoices.errors.party_id_not_allowed_for_company_role) - ce tiers est dérivé de la fiche entreprise, pas de l'annuaire. party_id et billing_address_id doivent être des entiers positifs ; toute autre valeur retourne 422 (api.invoices.errors.invalid_reference_id) plutôt que d'être convertie. Tout attribut voisin également envoyé sur l'entrée remplace la valeur correspondante de l'annuaire. Un party_id non résolvable retourne 422 (api.invoices.errors.party_not_found). Quand la fiche de l'annuaire porte un SIRET déclaré sous le schéma 0009, le tiers est rempli avec le SIREN de l'unité légale - les 9 premiers chiffres - sous le schéma 0002, car BR-FR-11 lit BT-47 sur le sélecteur 0002 et exige exactement 9 chiffres dès lors que la facture est une pièce B2B flux 2 ; une valeur laissée sous 0009 ne remplit pas du tout ce sélecteur et l'assertion est fatale. Seule l'identité que cet endpoint recopie depuis l'annuaire est convertie : un legal_registration_id envoyé explicitement sur l'entrée est l'intention déclarée de l'appelant et passe sans modification, et une immatriculation à 14 chiffres ne portant aucun schéma déclaré n'est pas convertie non plus, puisque la forme seule ne prouve pas une identité française.
  • Valeur par défaut du tiers côté entreprise : quand le payload ne comporte aucune entrée pour le rôle propre de l'entreprise (seller sur direction: sales, buyer sur direction: purchases), une entrée est ajoutée à partir de la Company et de son établissement siège. Une entrée de tiers que l'appelant fournit n'est jamais écrasée.
  • Valeur par défaut de item_notes : quand la clé est OMISE et que direction vaut sales, les mentions légales de l'entreprise sont insérées. Les factures purchases n'en reçoivent aucune. Envoyer un tableau vide explicite vide la collection et elle n'est jamais reremplie - c'est ainsi qu'un intégrateur retire des notes existantes lors d'un PATCH.
  • Valeur par défaut de payment_means : quand la clé est OMISE (un tableau vide explicite vide la collection et elle n'est jamais reremplie), les comptes bancaires de l'entreprise figurant sur la facture sont insérés, dans les deux sens. Sur sales, quand l'acheteur se résout à un client de l'annuaire confidentiellement affacturé, le compte du factor de ce client les remplace. Quand un acheteur sales est présent mais ne peut pas être résolu à un client de l'annuaire (envoyé par nom seul, sans party_id ni lien persistant), aucun moyen de paiement n'est inséré - le statut d'affacturage ne peut pas être déterminé, et émettre les comptes propres de l'entreprise pour un client affacturé acheminerait le paiement au mauvais endroit.
  • Contrôle du profil pour un payeur tiers : une entrée parties portant role: "payer" (le bloc EXT-FR-FE-BG-02) n'est acceptée que lorsque customization_id vaut l'une des deux formes EXTENDED-CTC-FR - urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended (Factur-X/CII) ou urn:cen.eu:en16931:2017#conformant#urn.cpro.gouv.fr:1p0:extended-ctc-fr (UBL). Un customization_id omis, vide ou EN 16931 simple retourne 422 (api.invoices.errors.payer_requires_extended_profile) et n'écrit rien : les générateurs UBL et CII refusent d'émettre un payeur hors EXTENDED-CTC-FR, si bien qu'en accepter un ici créerait une facture dont tous les exports structurés échouent, ce que l'appelant ne découvrirait qu'au moment du téléchargement.
  • Acteurs structurés (XP Z12-014) : buyer_agent (EXT-FR-FE-BG-01), seller_agent (EXT-FR-FE-BG-03), invoicee (EXT-FR-FE-BG-04) et invoicer (EXT-FR-FE-BG-05) sont renvoyés en lecture sous leur propre clé, renseignés sur les documents reçus ; aucun n'est jamais lu comme le vendeur, l'acheteur ou le payeur. Ils sont acceptés à la création comme à la modification sous l'une des deux formes EXTENDED-CTC-FR de customization_id seulement, et les exports UBL et CII les émettent alors ; sous tout autre customization_id, une entrée retourne 422 (api.invoices.errors.extended_role_requires_extended_profile). Chaque entrée doit porter un name (EXT-FR-FE-03 / -66 / -89 / -112, 1..1), envoyé ou rempli depuis party_id, sinon 422 (api.invoices.errors.structured_actor_name_required) ; un identifier doit être accompagné de son identifier_scheme_id (EXT-FR-FE-07 / -70 / -92-1 / -116, 1..1), sinon 422 (api.invoices.errors.structured_actor_identifier_scheme_required) ; un endpoint_id doit être accompagné de son endpoint_scheme_id (EXT-FR-FE-13 / -76 / -99 / -122, 1..1), sinon 422 (api.invoices.errors.structured_actor_endpoint_scheme_required) ; un legal_registration_id doit être accompagné de son legal_registration_scheme_id (EXT-FR-FE-09 / -72 / -95 / -118), sinon 422 (api.invoices.errors.structured_actor_legal_registration_scheme_required) ; une adresse qui renseigne un champ doit porter son country_code (EXT-FR-FE-107 / -130, Factur-X EXTENDED), sinon 422 (api.invoices.errors.structured_actor_country_required), et un country_code qui n'est pas un code ISO 3166-1 alpha-2 retourne 422 (api.invoices.errors.structured_actor_country_unknown) ; endpoint_scheme_id doit appartenir à la liste CEF EAS (BR-CL-25), identifier_scheme_id et legal_registration_scheme_id à la liste ISO 6523 ICD (BR-CL-10 / -11), chacune restreinte aux codes que connaît la table des schémas de Scribee, hors 0231 (réservé à l'assujetti unique), sinon 422 (api.invoices.errors.structured_actor_scheme_outside_code_list) ; un endpoint_id de plus de 125 caractères retourne 422 (api.invoices.errors.structured_actor_endpoint_too_long, BR-FR-25, bloquante) ; l'un de ces trois schémas envoyé sans sa valeur retourne 422 (api.invoices.errors.structured_actor_value_required), puisqu'il n'est émis que comme attribut de la valeur ; un directory_routing_identifier retourne 422 (api.invoices.errors.structured_actor_routing_identifier_unsupported) - il n'adresse que le vendeur et l'acheteur, l'adresse électronique d'un acteur est son endpoint_id, et il n'est pas recopié sur un acteur depuis la fiche de l'annuaire désignée par party_id ; un name ou un schéma qui n'est pas une chaîne compte comme absent ; et une deuxième entrée du même rôle d'acteur retourne 422 (api.invoices.errors.structured_actor_duplicated) ; un buyer_agent ou un invoicee sans buyer, ou un seller_agent ou un invoicer sans seller, retourne 422 (api.invoices.errors.structured_actor_parent_required), puisque l'UBL imbrique l'acteur dans cette partie - la partie côté entreprise ajoutée par l'API compte. Une facture qui nomme un invoicer n'est déposée que si l'entreprise détient, à la date d'émission, un mandat de facturation tiers facturant actif pour ce tiers (XP Z12-014 cas 19a) ; sinon le dépôt retourne 422 et la facture reste un brouillon.
  • Contrôle de role_code : role_code est accepté sur une entrée payer (EXT-FR-FE-44), payee (EXT-FR-FE-26) et sur un acteur structuré (EXT-FR-FE-04 / -67 / -90 / -113). L'envoyer sur tout autre rôle retourne 422 (api.invoices.errors.role_code_not_allowed_on_role), car la valeur d'aucun autre rôle n'est jamais émise sur le fil. Le code de l'invoicee vaut toujours IV et celui de l'invoicer II, et toute autre valeur retourne 422 (api.invoices.errors.role_code_mismatch). Sur chaque rôle accepté, la valeur doit provenir de la liste UN/CEFACT PartyRoleCode D22A - l'espace de valeurs UNCL 3035 - et la casse est significative ; toute autre valeur retourne 422 (api.invoices.errors.invalid_role_code). PR est le code du tiers payeur. Sur une entrée payee, le code exige en outre l'une des deux formes customization_id EXTENDED-CTC-FR : EXT-FR-FE-26 n'est défini que dans les profils EXTENDED et CII-SR-352 / UBL-CR-270 interdisent l'élément en EN 16931 simple, si bien qu'un role_code de bénéficiaire sous tout autre profil retourne 422 (api.invoices.errors.payee_role_code_requires_extended_profile). Un bénéficiaire SANS role_code relève de l'EN 16931 simple (BG-10) et est accepté sous tous les profils.
  • Contrôle de la devise : currency_code (BT-5), tax_currency_code (BT-6) et chaque tax_subtotals[].currency_code doivent porter un code ISO 4217 alpha-3 issu des listes de codes embarquées par Scribee - l'énumération UN/CEFACT ISO3AlphaCurrencyCode réunie à la liste ISO4217 de Peppol BIS. La comparaison est sensible à la casse, si bien que eur est refusé plutôt que mis en majuscules, et toute valeur hors de ces listes retourne 422 (api.invoices.errors.invalid_currency_code) ; le message nomme lequel des trois champs a été refusé. L'acceptation ici n'est pas une conformité Peppol : PEPPOL-EN16931-CL007 est fatal au regard de sa propre liste, plus étroite, si bien qu'une poignée de codes est acceptée à l'écriture et refusée malgré tout à l'export Peppol. Une valeur omise ou vide n'est jamais refusée - BT-5 retombe sur EUR à la création, et sur la devise existante de la facture à la mise à jour.
  • Contrôle de cohérence de la ventilation de TVA (direction: "sales" uniquement) : les tax_subtotals doivent se raccorder aux totaux du document. La somme des amount_without_taxes (BT-116) est comparée au total_amount_excluding_taxes (BT-109), et la somme des vat_amount (BT-117) au total_tax_amount (BT-110), chacune à 0,01 près - la tolérance que la règle PPF F1-START-TOTAL-COHERENCE-G1.53 accorde au dépôt. Un écart au-delà retourne 422 avec code: "operation_failed" (api.invoices.errors.ventilation_not_reconciled) et n'écrit rien ; le message nomme le total, le montant que le document déclare et celui auquel la ventilation s'élève. Chaque moitié est jugée pour elle-même et sort du périmètre quand son total de document est omis ou qu'aucune ligne tax_subtotals n'énonce son montant - un total omis n'est pas un total nul, et c'est ainsi que le schematron le lit lui aussi. direction: "purchases" n'est jamais jugé : un achat enregistré par l'API est le reflet d'une pièce que le tenant a reçue et cette plateforme ne la dépose jamais. Le contrôle existe parce que BT-116 porte la base HORS taxe, si bien qu'un appelant qui le remplissait avec le montant TTC obtenait un 201 ici et un refus PPF quelques heures plus tard.
  • Contrôle de cohérence de l'état déjà payée (direction: "sales" uniquement) : une facture ou un avoir qui déclare l'état déjà payée - invoicing_process_id paid_goods_invoice / paid_services_invoice / paid_goods_and_services_invoice (codes B2 / S2 / M2, BT-23), ou l'un de ces codes dans profile_id - doit déclarer lui-même le règlement : un prepaid_amount (BT-113) égal au tax_inclusive_amount (BT-112), un payable_amount (BT-115) à 0, aucun payable_rounding_amount (BT-114) autre que 0, et la date de paiement dans due_date (BT-9), antérieure ou égale à issue_date. Ce sont la règle fatale flux 2 BR-FR-CO-09 et la règle EN 16931 BR-CO-16. Tout autre cas retourne 422 avec code: "operation_failed" (api.invoices.errors.already_paid_*) et n'écrit rien. L'API ne complète jamais ces totaux et n'en déduit jamais l'état déjà payée : une facture payée peut aussi rester dans la famille B1 / S1 / M1, que ce contrôle ne juge pas. Déclarer cet état ne crée ni enregistrement de paiement ni statut de cycle de vie. Une facture déjà payée ne peut pas non plus désigner une facture d'acompte par document_id dans invoice_references : elle deviendrait une facture définitive soldant des acomptes, dont la famille B4 / S4 / M4 n'a pas de variante déjà payée (XP Z12-014 CU-21) ; l'appel retourne le même 422 et n'écrit rien.

Request​

Responses​

La facture créée, y compris tout champ de tiers, de notes d'article ou de moyens de paiement que l'API a complété à partir des valeurs par défaut de l'annuaire de l'entreprise.