Créer une facture
https://api.mobupay.nc/api/v1/billing/invoicesCe que fait cet appel
Crée une facture. Par défaut un brouillon : sans numéro, modifiable, non opposable.
Un paiement, une facture. Un paymentId déjà rattaché à l'une de vos factures, brouillon compris, est refusé en 409 PAYMENT_ALREADY_INVOICED ; details désigne la facture existante (invoiceId, number, status). Retrouvez une facture par son paiement avec GET /api/v1/billing/invoices?paymentId=.
Idempotence. Avec l'en-tête Idempotency-Key, un nouvel envoi de la même demande rend la facture déjà créée (200, dans son état courant) sans en créer une autre. La clé est conservée aussi longtemps que la facture. La même clé avec un contenu différent est refusée en 409 IDEMPOTENCY_KEY_REUSED.
Avec issue: true, la facture est émise dans la foulée si elle est complète. Si des mentions obligatoires manquent, l'appel échoue en 422 avec la liste des manques, et le brouillon est conservé : complétez-le par PUT /api/v1/billing/invoices/{id}, puis émettez-le par POST /api/v1/billing/invoices/{id}/issue, plutôt que d'en créer un second.
Le destinataire exige un nom ET une adresse. Une adresse électronique seule ne suffit jamais, quelle que soit la juridiction. Pour un client professionnel, son numéro d'identification (RID en Nouvelle-Calédonie, SIREN en France) est également obligatoire.
Les taxes se déclarent au niveau du document (`taxDetail`) ou par ligne, jamais les deux. Dès qu'une seule ligne porte un taxDetail, le taxDetail racine est ignoré pour TOUTES les lignes, et une ligne sans taxe devient non taxée. C'est la règle du moteur fiscal : la contourner ferait diverger la facture du paiement qu'elle documente.
Le module s'active séparément en production et en test. Une clé sk_live_ exige le module activé en production, une clé sk_test_ le module activé en test : sinon 403 BILLING_MODULE_NOT_ENABLED. L'émission est en outre suspendue (402) tant que l'abonnement attend son premier paiement ou reste impayé.
Clé détenue par un logiciel intégrateur. La facture porte la marque du logiciel, qui ne voit que les documents qu'il a créés. customerId, paymentId et quoteId doivent désigner une fiche, une vente ou un devis du logiciel (404 sinon), et recipient.billingEmails est refusé (400 FIELD_NOT_ALLOWED_FOR_INTEGRATOR).
Authorization: Bearer sk_test_XXXXLe pool est déduit du préfixe de la clé
Il n'y a pas d'interrupteur test et production sur cette page. sk_test_* ne traite aucun paiement réel, sk_live_* encaisse.
Paramètres
1 en-têteIdempotency-KeystringOptionnelheaderClé d'idempotence facultative, 255 caractères au plus. Un nouvel envoi de la même demande rend la facture déjà créée.
Corps de la requête
application/jsonDestinataire du document. Le nom ET l'adresse sont obligatoires : une adresse électronique seule ne suffit jamais (CGI art. 242 nonies A ann. II 1°, art. Lp. 441-3 du code de commerce NC).
customerIdstringOptionnelFiche client à rattacher (`cus_*`), du même environnement. Ses listes `billingEmails` s'appliquent à défaut de celles du destinataire. Inconnue : `404 CUSTOMER_NOT_FOUND`.
linesarray[object]RequisAu moins une ligne. Chacune exige une désignation précise et une quantité.
productstringRequisDénomination PRÉCISE du bien ou du service. Mention obligatoire : « prestation » ou « divers » ne suffit pas.
descriptionstringOptionnelPrécision libre affichée sous la désignation.
quantitynumberRequisQuantité. Strictement positive, mention obligatoire.
unitPriceCentsintegerRequisPrix unitaire HT, dans la plus petite unité de la devise. Le franc pacifique n'a pas de décimale.
discountCentsintegerOptionnelRemise sur cette ligne. La taxe porte sur la base NETTE, après remise.
unitstringOptionnelUnité de mesure.
periodStartstring · dateOptionnelDébut de la période de prestation de la ligne (AAAA-MM-JJ). À fournir avec `periodEnd`, ou pas du tout. Imprimé sous la désignation.
periodEndstring · dateOptionnelFin de la période de prestation (AAAA-MM-JJ), au plus tôt le jour de `periodStart`.
taxDetailarray[object]OptionnelTaxes de CETTE ligne. Dès qu'une seule ligne en porte, le `taxDetail` du document est ignoré pour toutes les lignes.
catalogItemIdstringOptionnelÉlément de catalogue d'origine (`cti_*`). Les valeurs sont COPIÉES à l'ajout : modifier le catalogue ensuite ne change pas la ligne.
typestringOptionnelNature. Détermine l'exigibilité de la taxe : biens à la livraison, services à l'encaissement.
productstringRequisDénomination PRÉCISE du bien ou du service. Mention obligatoire : « prestation » ou « divers » ne suffit pas.
descriptionstringOptionnelPrécision libre affichée sous la désignation.
quantitynumberRequisQuantité. Strictement positive, mention obligatoire.
unitPriceCentsintegerRequisPrix unitaire HT, dans la plus petite unité de la devise. Le franc pacifique n'a pas de décimale.
discountCentsintegerOptionnelRemise sur cette ligne. La taxe porte sur la base NETTE, après remise.
unitstringOptionnelUnité de mesure.
periodStartstring · dateOptionnelDébut de la période de prestation de la ligne (AAAA-MM-JJ). À fournir avec `periodEnd`, ou pas du tout. Imprimé sous la désignation.
periodEndstring · dateOptionnelFin de la période de prestation (AAAA-MM-JJ), au plus tôt le jour de `periodStart`.
taxDetailarray[object]OptionnelTaxes de CETTE ligne. Dès qu'une seule ligne en porte, le `taxDetail` du document est ignoré pour toutes les lignes.
catalogItemIdstringOptionnelÉlément de catalogue d'origine (`cti_*`). Les valeurs sont COPIÉES à l'ajout : modifier le catalogue ensuite ne change pas la ligne.
typestringOptionnelNature. Détermine l'exigibilité de la taxe : biens à la livraison, services à l'encaissement.
taxDetailarray[object]OptionnelTaxes applicables à TOUTES les lignes. Ignoré dès qu'une ligne porte son propre `taxDetail`.
idstringRequisIdentifiant unique de la taxe (ex: `TVA20`, `TGC5`).
typestringRequisPERCENTAGE = valeur en basis-points (2000 = 20%). FIXED = montant fixe en centimes.
valueintegerRequisValeur (basis-points pour PERCENTAGE, centimes pour FIXED). Entier positif.
discountCentsintegerOptionnelRemise globale, en plus des remises de ligne. Répartie au prorata du poids HT de chaque ligne.
currencystringOptionnelDevise d'affichage du document. Défaut `XPF`.
operationTypestringOptionnelDétermine l'exigibilité de la taxe : biens à la livraison, services à l'encaissement. Déduit des lignes s'il est absent.
operationDatestringOptionnelDate de l'opération (AAAA-MM-JJ). Mention obligatoire, distincte de la date d'émission.
dueDatestringOptionnelÉchéance (AAAA-MM-JJ). Défaut : émission + le délai des paramètres, 30 jours à l'installation. Plafonds légaux contrôlés.
purchaseOrderRefstringOptionnelRéférence du bon de commande du client, quand il en impose une.
customFieldsarray[object]OptionnelChamps libres affichés sur le document.
freeTextstringOptionnelTexte libre en pied de document. Max 2000 caractères.
paymentIdstringOptionnelPaiement Mobupay déjà encaissé à rattacher (`pay_*`). La facture sort alors soldée.
quoteIdstringOptionnelDevis signé dont cette facture est la suite (`qot_*`).
issuebooleanOptionnelÉmettre immédiatement. La facture reçoit son numéro et devient définitive.
Codes de retour
Rejeu d'une demande déjà traitée sous la même Idempotency-Key : la facture d'origine, dans son état courant. Rien n'est créé.
Facture créée.
FIELD_NOT_ALLOWED_FOR_INTEGRATOR : recipient.billingEmails envoyé par la clé d'un logiciel intégrateur.
BILLING_SUBSCRIPTION_SUSPENDED (details.reason : attente_premier_paiement tant que le premier mois n'est pas réglé, sinon impayé) ou BILLING_SUBSCRIPTION_OVERDUE : l'émission est suspendue, le brouillon est conservé.
Permission billing.write absente, ou BILLING_MODULE_NOT_ENABLED : module non activé dans l'environnement de la clé.
CUSTOMER_NOT_FOUND, PAYMENT_NOT_FOUND ou QUOTE_NOT_FOUND : la référence citée n'existe pas pour ce marchand (ou, pour un logiciel intégrateur, n'est pas la sienne).
PAYMENT_ALREADY_INVOICED : ce paiement est déjà rattaché à une de vos factures, désignée dans details. IDEMPOTENCY_KEY_REUSED : la clé a déjà servi à une demande différente.
Mentions obligatoires manquantes : l'émission est refusée, avec le fondement légal de chaque manque.
Langage
Cliquez sur Essayer pour lancer la requête et voir la réponse ici. Ou choisissez un exemple :
application/json