/cpro/factures/v1/soumettreSubmit PDF invoice
Submit an invoice with a PDF attachment. The invoice must reference a previously uploaded file.
Multiple Authentication Required
ALL REQUIREDThis endpoint requires all of the following authentication methods:
OAuth2 Bearer token
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_TOKENYou 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
| Parameter | Required | Description |
|---|---|---|
numeroFactureSaisi Type: string | Required | Invoice number. |
dateFacture Type: string | Required | Invoice date (YYYY-MM-DD). |
cadreDeFacturation.codeCadreFacturation Type: string | Required | Invoicing framework code (e.g., A1_FACTURE_FOURNISSEUR). |
destinataire.codeDestinataire Type: string | Required | Recipient SIRET. |
destinataire.codeServiceExecutant Type: string | Optional | Recipient 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 | Required | Supplier structure ID. |
fournisseur.codeCoordonneesBancairesFournisseur Type: number | Required | Bank details code. |
idUtilisateurCourant Type: number | Required | Current user ID. |
lignePoste Type: array | Required | Invoice 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 | Optional | VAT 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 | Required | Deposit mode (DEPOT_PDF_API, SAISIE_API). |
montantTotal Type: object | Required | Total 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 | Optional | Main attached file (required for PDF mode). |
references Type: object | Required | Invoice 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
| Header | Required | Description |
|---|---|---|
Content-Type | Required | Content type Default: application/json;charset=utf-8 |
Accept | Required | Expected response type Default: application/json;charset=utf-8 |
Responses
⚠️ 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.
/cpro/factures/v1/soumettreSubmit PDF invoice
Submit an invoice with a PDF attachment. The invoice must reference a previously uploaded file.
Multiple Authentication Required
ALL REQUIREDThis endpoint requires all of the following authentication methods:
OAuth2 Bearer token
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_TOKENYou 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
| Parameter | Required | Description |
|---|---|---|
numeroFactureSaisi Type: string | Required | Invoice number. |
dateFacture Type: string | Required | Invoice date (YYYY-MM-DD). |
cadreDeFacturation.codeCadreFacturation Type: string | Required | Invoicing framework code (e.g., A1_FACTURE_FOURNISSEUR). |
destinataire.codeDestinataire Type: string | Required | Recipient SIRET. |
destinataire.codeServiceExecutant Type: string | Optional | Recipient 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 | Required | Supplier structure ID. |
fournisseur.codeCoordonneesBancairesFournisseur Type: number | Required | Bank details code. |
idUtilisateurCourant Type: number | Required | Current user ID. |
lignePoste Type: array | Required | Invoice 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 | Optional | VAT 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 | Required | Deposit mode (DEPOT_PDF_API, SAISIE_API). |
montantTotal Type: object | Required | Total 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 | Optional | Main attached file (required for PDF mode). |
references Type: object | Required | Invoice 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
| Header | Required | Description |
|---|---|---|
Content-Type | Required | Content type Default: application/json;charset=utf-8 |
Accept | Required | Expected response type Default: application/json;charset=utf-8 |
Responses
⚠️ 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.