POST/cpro/factures/v1/soumettre

Submit PDF invoice

Submit an invoice with a PDF attachment. The invoice must reference a previously uploaded file.

Tired of dealing with PISTE, certificates and XML? Chorus Pay handles the whole flow for you - quote acceptance, purchase order, invoice deposited on Chorus Pro.Discover Chorus Pay →·Compare both approaches

Multiple Authentication Required

ALL REQUIRED

This endpoint requires all of the following authentication methods:

Bearer Token

OAuth2 Bearer token

Custom Header

Chorus Pro account credentials

Required Header

cpro-account: base64(login:password)
How to authenticate

Include your Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

You can obtain your API token from your account dashboard.

How to authenticate

Include the custom header in your request:

cpro-account: base64(login:password)

Body Parameters

ParameterRequiredDescription
numeroFactureSaisi
Type: string
RequiredInvoice number.
dateFacture
Type: string
RequiredInvoice date (YYYY-MM-DD).
cadreDeFacturation.codeCadreFacturation
Type: string
RequiredInvoicing framework code (e.g., A1_FACTURE_FOURNISSEUR).
destinataire.codeDestinataire
Type: string
RequiredRecipient SIRET.
destinataire.codeServiceExecutant
Type: string
OptionalRecipient 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
RequiredSupplier structure ID.
fournisseur.codeCoordonneesBancairesFournisseur
Type: number
RequiredBank details code.
idUtilisateurCourant
Type: number
RequiredCurrent user ID.
lignePoste
Type: array
RequiredInvoice 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
OptionalVAT 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
RequiredDeposit mode (DEPOT_PDF_API, SAISIE_API).
montantTotal
Type: object
RequiredTotal 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
OptionalMain attached file (required for PDF mode).
references
Type: object
RequiredInvoice 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.

Example Request Body

{
  "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"
  }
}

Headers

HeaderRequiredDescription
Content-Type
RequiredContent type
Default: application/json;charset=utf-8
Accept
RequiredExpected response type
Default: application/json;charset=utf-8

Responses

Loading...

⚠️ Observed in the field

  • NOT idempotent, observed in production (07/09/2026): the PISTE gateway cuts the connection after ~30 s (HTTP 504, empty body) while Chorus Pro keeps processing and usually creates the invoice anyway. A 504 or a timeout therefore does NOT mean « not deposited ». Never resubmit blindly: first search the number with rechercher/fournisseur (numeroFacture at the root of the body) and resubmit only if it is absent.
  • Resubmitting the same numeroFactureSaisi to the same recipient returns HTTP 200 with 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 », uniqueness is per (invoice number, recipient structure), so that code is in fact proof that the first deposit went through.
  • Observed on the sandbox (08/10/2026): a 11.051 can come back while rechercher/fournisseur shows the invoice with that number deposited to a DIFFERENT codeDestinataire than the one you just submitted (an invoice deposited in July to one recipient, resubmitted in October to another). When you search after a 11.051, match on the number alone and do not require the recipient to match, or you will never adopt the deposited invoice.
  • Without numeroFactureSaisi, Chorus Pro assigns the number itself and a blind retry creates a genuine duplicate invoice.