POST/cpro/factures/v1/soumettre

Soumettre une facture PDF

Soumettre une facture avec une pièce jointe PDF. La facture doit référencer un fichier préalablement téléchargé.

Marre de gérer PISTE, les certificats et le XML ? Chorus Pay gère tout le flux à votre place - devis accepté, bon de commande, facture déposée sur Chorus Pro.Découvrir Chorus Pay →·Comparer les deux approches

Authentification multiple requise

TOUTES REQUISES

Ce point de terminaison nécessite toutes les méthodes d'authentification suivantes :

Token Bearer

OAuth2 Bearer token

En-tête personnalisé

Chorus Pro account credentials

En-tête requis

cpro-account: base64(login:password)
Comment s'authentifier

Incluez votre token Bearer dans l'en-tête Authorization :

Authorization: Bearer YOUR_API_TOKEN

Vous pouvez obtenir votre token API depuis votre tableau de bord.

Comment s'authentifier

Incluez l'en-tête personnalisé dans votre requête :

cpro-account: base64(login:password)

Paramètres du corps

ParamètreRequisDescription
numeroFactureSaisi
Type: string
RequisInvoice number.
dateFacture
Type: string
RequisInvoice date (YYYY-MM-DD).
cadreDeFacturation.codeCadreFacturation
Type: string
RequisInvoicing framework code (e.g., A1_FACTURE_FOURNISSEUR).
destinataire.codeDestinataire
Type: string
RequisRecipient SIRET.
destinataire.codeServiceExecutant
Type: string
OptionnelRecipient service code. ⚠️ Must be sent EXACTLY as returned by rechercher/services (character-by-character match, including any leading/trailing spaces). A trimmed code triggers GFT_MSG_01.033 (« Le service destinataire ne correspond pas à la structure destinataire ») even if the service exists and is active. Note also that when a service is set, its own parameters (consulter/service → parametres.numeroEngagement) override the structure-level mandatory-field rules.
fournisseur.idFournisseur
Type: number
RequisSupplier structure ID.
fournisseur.codeCoordonneesBancairesFournisseur
Type: number
RequisBank details code.
idUtilisateurCourant
Type: number
RequisCurrent user ID.
lignePoste
Type: array
RequisInvoice line items. Watch the field length limits: lignePosteDenomination and lignePosteReference are varchar(40), lignePosteUnite is varchar(20). Exceeding a limit does NOT return a validation error - the API answers 500 "Erreur interne" with no hint about the faulty field. Truncate before sending.
ligneTva
Type: array
OptionnelVAT summary lines, one per VAT rate. On a mixed invoice (some lines at a rate > 0, some at 0 %) the 0 % line MUST be present too (ligneTvaTauxManuel 0, its HT base, ligneTvaMontantTvaParTaux 0): Chorus checks that the bases of ligneTva sum to montantHtTotal and rejects otherwise with codeRetour 20317 / GDP_MSG_01.089. Observed on the sandbox on 2026-10-07 in SAISIE_API: 100 EUR at 20 % + 50 EUR at 0 %, recap with only the 20 % line -> 20317 "Le montant global HT doit etre la somme des montants de base HT par taux"; recap with both lines -> codeRetour 0, invoice deposited. Only when the WHOLE invoice is VAT-exempt, omit ligneTva entirely and set references.typeTva to SANS_TVA (a lone 0 %/0 line with no positive rate triggers a 500; line-level lignePosteTauxTvaManuel values are then ignored).
modeDepot
Type: string
RequisDeposit mode (DEPOT_PDF_API, SAISIE_API).
montantTotal
Type: object
RequisTotal amounts. Chorus Pro renders amounts with up to 4 decimals exactly as sent: a floating-point residue (e.g. 99.9997 instead of 100.00) shows up verbatim on the generated invoice. Round every amount to the cent (Math.round(x*100)/100) before sending.
pieceJointePrincipale
Type: array
OptionnelMain attached file (required for PDF mode).
references
Type: object
RequisInvoice references (currency, payment method, etc.). typeTva rule: if no ligneTva is provided, typeTva MUST be SANS_TVA; EXONERATION additionally requires motifExonerationTva; otherwise use TVA_SUR_DEBIT or TVA_SUR_ENCAISSEMENT. An inconsistent combination (e.g. TVA_SUR_ENCAISSEMENT with no ligneTva) triggers an unexplained 500.

Exemple de corps de requête

{
  "numeroFactureSaisi": "F333",
  "dateFacture": "2025-11-05",
  "cadreDeFacturation": {
    "codeCadreFacturation": "A1_FACTURE_FOURNISSEUR"
  },
  "destinataire": {
    "codeDestinataire": "19672337516762"
  },
  "fournisseur": {
    "codeCoordonneesBancairesFournisseur": 144050,
    "idFournisseur": 26262962
  },
  "idUtilisateurCourant": 65336344681929,
  "lignePoste": [
    {
      "lignePosteDenomination": "Licence",
      "lignePosteMontantRemiseHT": 0,
      "lignePosteMontantUnitaireHT": 16.6667,
      "lignePosteNumero": 1,
      "lignePosteQuantite": 1,
      "lignePosteReference": "votil_licence",
      "lignePosteTauxTvaManuel": 20,
      "lignePosteUnite": "licence"
    }
  ],
  "ligneTva": [
    {
      "ligneTvaMontantBaseHtParTaux": 16.6667,
      "ligneTvaMontantTvaParTaux": 3.3333,
      "ligneTvaTauxManuel": 20
    }
  ],
  "modeDepot": "DEPOT_PDF_API",
  "montantTotal": {
    "montantAPayer": 20,
    "montantHtTotal": 16.6667,
    "montantRemiseGlobaleTTC": 0,
    "montantTVA": 3.3333,
    "montantTtcTotal": 20
  },
  "pieceJointePrincipale": [
    {
      "pieceJointePrincipaleDesignation": "Facture",
      "pieceJointePrincipaleId": 10321512
    }
  ],
  "references": {
    "deviseFacture": "EUR",
    "modePaiement": "VIREMENT",
    "typeFacture": "FACTURE",
    "typeTva": "TVA_SUR_ENCAISSEMENT"
  }
}

En-têtes

En-têteRequisDescription
Content-Type
RequisContent type
Par défaut: application/json;charset=utf-8
Accept
RequisExpected response type
Par défaut: application/json;charset=utf-8

Réponses

Loading...

⚠️ Constaté sur le terrain

  • NON idempotent, constaté en production (07/09/2026) : la passerelle PISTE coupe la connexion après ~30 s (HTTP 504, corps vide) alors que Chorus Pro poursuit le traitement et crée généralement la facture quand même. Un 504 ou un timeout ne signifie donc PAS « non déposée ». Ne resoumettez jamais à l'aveugle : recherchez d'abord le numéro avec rechercher/fournisseur (numeroFacture à la racine du corps) et ne resoumettez que s'il est absent.
  • Resoumettre le même numeroFactureSaisi au même destinataire renvoie HTTP 200 avec codeRetour 20301 / GDP_MSG_11.051 « Vous avez déjà déposé une demande de paiement avec ce numéro de facture pour cette structure » : l'unicité porte sur le couple (numéro de facture, structure destinataire), ce code prouve donc que le premier dépôt est passé.
  • Constaté sur le bac à sable (08/10/2026) : un 11.051 peut revenir alors que rechercher/fournisseur montre la facture de ce numéro déposée vers un codeDestinataire DIFFÉRENT de celui que vous venez de soumettre (facture déposée en juillet vers un destinataire, resoumise en octobre vers un autre). Après un 11.051, rapprochez sur le numéro seul sans exiger le même destinataire, sinon la facture déposée ne sera jamais adoptée.
  • Sans numeroFactureSaisi, Chorus Pro attribue lui-même le numéro et un retry à l'aveugle crée une vraie facture en double.