MobupayMobupay
Chargement de vos clés API…

Créer une facture

POSThttps://api.mobupay.nc/api/v1/billing/invoices

Ce 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).

En-tête d'authentification
Authorization: Bearer sk_test_XXXX

Le 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ête
Idempotency-KeystringOptionnelheader

Clé 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/json
objectRequis

Destinataire 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).

customerIdstringOptionnel

Fiche 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]Requis

Au moins une ligne. Chacune exige une désignation précise et une quantité.

lines[0]
productstringRequis

Dénomination PRÉCISE du bien ou du service. Mention obligatoire : « prestation » ou « divers » ne suffit pas.

descriptionstringOptionnel

Précision libre affichée sous la désignation.

quantitynumberRequis

Quantité. Strictement positive, mention obligatoire.

unitPriceCentsintegerRequis

Prix unitaire HT, dans la plus petite unité de la devise. Le franc pacifique n'a pas de décimale.

discountCentsintegerOptionnel

Remise sur cette ligne. La taxe porte sur la base NETTE, après remise.

unitstringOptionnel

Unité de mesure.

periodStartstring · dateOptionnel

Dé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 · dateOptionnel

Fin de la période de prestation (AAAA-MM-JJ), au plus tôt le jour de `periodStart`.

taxDetailarray[object]Optionnel

Taxes 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.

typestringOptionnel

Nature. Détermine l'exigibilité de la taxe : biens à la livraison, services à l'encaissement.

lines[1]
productstringRequis

Dénomination PRÉCISE du bien ou du service. Mention obligatoire : « prestation » ou « divers » ne suffit pas.

descriptionstringOptionnel

Précision libre affichée sous la désignation.

quantitynumberRequis

Quantité. Strictement positive, mention obligatoire.

unitPriceCentsintegerRequis

Prix unitaire HT, dans la plus petite unité de la devise. Le franc pacifique n'a pas de décimale.

discountCentsintegerOptionnel

Remise sur cette ligne. La taxe porte sur la base NETTE, après remise.

unitstringOptionnel

Unité de mesure.

periodStartstring · dateOptionnel

Dé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 · dateOptionnel

Fin de la période de prestation (AAAA-MM-JJ), au plus tôt le jour de `periodStart`.

taxDetailarray[object]Optionnel

Taxes 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.

typestringOptionnel

Nature. Détermine l'exigibilité de la taxe : biens à la livraison, services à l'encaissement.

taxDetailarray[object]Optionnel

Taxes applicables à TOUTES les lignes. Ignoré dès qu'une ligne porte son propre `taxDetail`.

taxDetail[0]
idstringRequis

Identifiant unique de la taxe (ex: `TVA20`, `TGC5`).

typestringRequis

PERCENTAGE = valeur en basis-points (2000 = 20%). FIXED = montant fixe en centimes.

valueintegerRequis

Valeur (basis-points pour PERCENTAGE, centimes pour FIXED). Entier positif.

discountCentsintegerOptionnel

Remise globale, en plus des remises de ligne. Répartie au prorata du poids HT de chaque ligne.

currencystringOptionnel

Devise d'affichage du document. Défaut `XPF`.

operationTypestringOptionnel

Détermine l'exigibilité de la taxe : biens à la livraison, services à l'encaissement. Déduit des lignes s'il est absent.

operationDatestringOptionnel

Date 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.

purchaseOrderRefstringOptionnel

Référence du bon de commande du client, quand il en impose une.

customFieldsarray[object]Optionnel

Champs libres affichés sur le document.

freeTextstringOptionnel

Texte libre en pied de document. Max 2000 caractères.

paymentIdstringOptionnel

Paiement Mobupay déjà encaissé à rattacher (`pay_*`). La facture sort alors soldée.

quoteIdstringOptionnel

Devis 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

200

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éé.

201

Facture créée.

400

FIELD_NOT_ALLOWED_FOR_INTEGRATOR : recipient.billingEmails envoyé par la clé d'un logiciel intégrateur.

402

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é.

403

Permission billing.write absente, ou BILLING_MODULE_NOT_ENABLED : module non activé dans l'environnement de la clé.

404

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).

409

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.

422

Mentions obligatoires manquantes : l'émission est refusée, avec le fondement légal de chaque manque.

Langage

Requête cURLpostExemple
1curl --request POST \
2 --url https://api.mobupay.nc/api/v1/billing/invoices \
3 --header 'authorization: Bearer sk_test_XXXX' \
4 --header 'content-type: application/json' \
5 --data '{ "recipient": { "name": "SARL Le Bon Plat", "address": { "line1": "12 rue de l'\''Alma", "postalCode": "98800", "city": "Nouméa", "country": "NC" }, "email": "compta@lebonplat.nc", "registrationId": "1234567.001", "isBusiness": true }, "lines": [ { "product": "Prestation de conseil", "quantity": 3, "unitPriceCents": 25000, "unit": "day", "type": "SERVICE" }, { "product": "Frais de déplacement", "quantity": 1, "unitPriceCents": 8000, "type": "SERVICE" } ], "taxDetail": [ { "id": "TGC11", "type": "PERCENTAGE", "value": 1100 } ], "dueDate": "2026-09-15", "issue": true }'
Réponse

Cliquez sur Essayer pour lancer la requête et voir la réponse ici. Ou choisissez un exemple :

application/json