Factures

L'objet invoice représente une facture B2B française. Le dépôt CII est vérifié selon EN 16931 et les règles CIUS-FR locales ; la variante UBL est vérifiée selon EN 16931 uniquement et ne vaut pas attestation CIUS-FR. Le cycle de vie couvre la création en brouillon, la finalisation atomique (avec attribution de numéro), le dépôt via Plateforme Agréée et le suivi des paiements.

Les historiques volumineux sont archivés en segments au-delà de 512 Kio pour préserver la capacité d’écriture. Les lectures REST et l’export personnel restituent les entrées archivées ; les anciens identifiants de dépôt restent opposables aux retours tardifs.

Endpoints

Créer une facture

$ curl -X POST https://facturino.com/api/v1/invoices \
  -H "Authorization: Bearer fac_test_..." \
  -H "Idempotency-Key: invoice-create-order-7842" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_8f2k4m9n",
    "taxDecisionId": "taxdec_9k2f7p1m",
    "decisionLines": [
      { "taxLineRef": "sprint-3", "unit": "flat_rate" }
    ],
    "buyer": {
      "companyName": "Durand & Associés",
      "siret": "00012345500008",
      "address": {
        "line1": "10 rue de Rivoli",
        "postalCode": "75001", "city": "Paris", "country": "FR"
      }
    },
    "dates": { "issued": "2026-09-22", "due": "2026-10-22" },
    "payment": {
      "terms": "30 jours net",
      "termsDays": 30,
      "method": "transfer",
      "latePaymentRate": "3 fois le taux légal",
      "collectionFee": "40.00 EUR"
    }
  }'

Réponse — objet invoice complet :

{
  "id": "inv_a1b2c3d4e5f6",
  "object": "invoice",
  "status": "draft",
  "taxSource": "facturino",
  "taxDecisionId": "taxdec_9k2f7p1m",
  "number": null,
  "livemode": false,
  "currency": "eur",
  "customer": {
    "ref": "cus_8f2k4m9n",
    "snapshot": {
      "name": "Durand & Associés",
      "siret": "00012345500008"
    }
  },
  "items": [
    {
      "id": "li_3k9d2",
      "description": "Développement web — Sprint 3",
      "quantity": "1",
      "unit": "flat_rate",
      "unitPrice": 150000,
      "vatRate": 2000,
      "vatCode": "S",
      "taxLineRef": "sprint-3",
      "lineAmount": 150000,
      "vatAmount": 30000,
      "lineTotal": 180000
    }
  ],
  "totals": {
    "totalHT": 150000,
    "totalVAT": 30000,
    "totalTTC": 180000
  },
  "dates": {
    "issued": "2026-04-22",
    "due": "2026-05-22"
  },
  "einvoicing": {
    "paId": null,
    "paStatus": null,
    "paStatusCode": null,
    "paTransactionId": null,
    "paErrorCode": null,
    "rejectionReason": null,
    "refusalReason": null,
    "paIdempotencyKey": null,
    "peppolDeliveryId": null,
    "ereportingId": null,
    "sentAt": null,
    "trackingId": null,
    "submissionArtefact": null
  },
  "files": {},
  "created": "2026-04-22T13:48:10.000Z",
  "updated": "2026-04-22T13:48:10.000Z"
}

Formats d'entrée

• Montants : entiers en centimes (150000 = 1 500,00 €). Évite les erreurs de précision flottante.
• Taux TVA : centièmes de pourcent (2000 = 20,00 %) — décidés côté serveur (source facturino) ou fournis par ligne de la décision (source integration), jamais saisis sur la facture.
• Quantités : chaînes décimales ("1.5") — précision arbitraire.
• Dates : ISO 8601 sans heure ("2026-04-22").

Codes TVA (EN 16931)

Le champ vatCode indique la catégorie TVA appliquée à la ligne, selon la liste de codes définie par la norme européenne EN 16931. Il est conclu par la décision fiscale — déterminé par Facturino, ou fourni par l'intégration et validé en cohérence — et sert à générer les mentions légales obligatoires sur le PDF et le XML Factur-X.

Acomptes et échéanciers

Deux modalités de règlement s'ajoutent au corps de création (toutes deux optionnelles) :

• deposits — factures d'acompte (type deposit, code 386) déjà émises au même client. Leur TTC est déduit du montant dû de la facture de solde (BT-113, CGI art. 289). Chaque acompte doit être finalisé ; maximum 20.
• schedule — échéancier de 2 à 12 versements. La somme des montants (en centimes) doit couvrir le montant dû, les dates sont strictement croissantes et la dernière échéance tombe à la date d'échéance de la facture (BT-9). L'échéancier est rendu en texte libre dans les conditions de paiement (BT-20).

Les deux modalités se règlent contre le montant décidé, dans la transaction de création : le total décidé (amountToCharge) n'est jamais modifié — les acomptes alimentent amountPaid (BT-113) et abaissent amountDue (BT-115), et l'échéancier répartit exactement ce qui reste dû. Un acompte non intégralement réglé est refusé : un acompte émis mais non encaissé n'est pas un prépaiement.

# Facture de solde : on déduit deux acomptes déjà émis (386) et on
# échelonne le solde en 2 versements (le dernier tombe à l'échéance).
{
  "customerId": "cus_8f2k4m9n",
  "taxDecisionId": "taxdec_solde01",
  "decisionLines": [ /* ... */ ],
  "buyer": { /* ... */ },
  "dates": { "issued": "2026-09-22", "due": "2026-11-30" },
  "payment": { /* ... */ },
  "deposits": [
    { "invoiceId": "inv_acompte1" },
    { "invoiceId": "inv_acompte2" }
  ],
  "schedule": [
    { "amount": 600000, "dueDate": "2026-05-31", "label": "1er versement" },
    { "amount": 600000, "dueDate": "2026-06-30" }
  ]
}

Émission en un appel (one-shot)

Le flux granulaire (créer → /finalize → /send) reste toujours disponible. Pour émettre en un seul appel, deux champs optionnels à la création :

• autoFinalize (booléen) — finalise la facture (attribue le numéro) dans le même appel.
• autoSend — finalise puis émet : email envoie au client, pa dépose sur la Plateforme Agréée connectée (asynchrone, statut sending). Implique autoFinalize.

# One-shot : créer + finaliser + envoyer (email au client ET dépôt PA) en un appel.
{
  "customerId": "cus_8f2k4m9n",
  "taxDecisionId": "taxdec_9k2f7p1m",
  "decisionLines": [ /* ... */ ],
  "buyer": { /* ... */ },
  "dates": { "issued": "2026-09-22", "due": "2026-10-22" },
  "payment": { /* ... */ },
  "autoSend": { "email": true, "pa": true }
}

Pour une récurrence, le refus de finalisation automatique pour identité masquée laisse la facture générée en brouillon, sans numéro. Le propriétaire reçoit la notification existante recurring_failed, avec un lien vers la facture et l’action à effectuer ; ses préférences de notification et d’e-mail s’appliquent. Pour une autre erreur technique, l’avis invite à vérifier la facture : une étape postérieure à sa finalisation peut avoir échoué. L’avis de génération réussie n’est pas envoyé pour ce même échec.

Cycle de vie

Une facture évolue à travers une machine à états déterministe. Les transitions invalides retournent 400 invalid_status_transition (type invalid_request_error).

Finaliser

La finalisation est une opération atomique qui réserve un numéro depuis le compteur de l'entreprise et passe la facture à finalized. Le numéro n'est jamais réutilisé, même si la facture est ensuite annulée ou rejetée (le numéro est brûlé).

$ curl -X POST https://facturino.com/api/v1/invoices/inv_a1b2c3d4e5f6/finalize \
  -H "Authorization: Bearer fac_test_..."

# Réponse — numéro attribué, statut = "finalized"
{
  "id": "inv_a1b2c3d4e5f6",
  "status": "finalized",
  "number": "FAC2026-00042",
  /* ... */
}

Si la finalisation échoue côté Facturino (timeout, erreur transitoire), un retry avec la même Idempotency-Key retourne le numéro déjà attribué — pas de doublon. Voir Idempotence.

Facture déjà encaissée : émise acquittée

Quand le règlement est reçu avant l'émission — paiement en ligne, au comptoir, prélèvement immédiat —, transmettez-le dans le corps facultatif de finalize. La numérotation et l'encaissement sont appliqués dans la même transaction : le PDF et le Factur-X d'origine sont donc rendus sur une facture déjà réglée, avec la mention « PAYÉE » et les balises BT-113 / BT-115 renseignées.

L'objet payment est exactement celui de POST /v1/invoices/:id/payments : mêmes champs, mêmes méthodes, montant en centimes entiers. Le sous-document d'encaissement créé est indistinguable de celui d'un règlement enregistré après coup.

# Facture déjà encaissée : elle est ÉMISE acquittée, en un seul appel
$ curl -X POST https://facturino.com/api/v1/invoices/inv_a1b2c3d4e5f6/finalize \
  -H "Authorization: Bearer fac_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "payment": {
      "amount": 120000,
      "method": "card",
      "reference": "ch_3Kj9aLZ",
      "paidAt": "2026-05-10T12:00:00.000Z"
    }
  }'

# Réponse — numéro attribué ET encaissement appliqué, dans la même transaction
{
  "id": "inv_a1b2c3d4e5f6",
  "status": "paid",
  "number": "FAC2026-00042",
  "totals": { "totalTTC": 120000, "amountPaid": 120000, "amountDue": 0 },
  /* ... */
}

Tout ou rien. Un encaissement refusé — au-delà du reste dû — répond 422 payment_exceeds_amount_due avec error.issues pointant payment.amount, et la finalisation n'a pas lieu : aucun numéro n'est brûlé, la facture reste un brouillon.

L'original est figé à l'émission ; les copies PDF suivent les encaissements ; le Factur-X ne change jamais. Un règlement postérieur à l'émission fait redessiner la copie PDF de présentation, qui affiche alors le solde à jour ; le Factur-X, lui, reste le document d'origine — c'est lui qui porte la valeur probante et qui est haché dans la chaîne d'archivage. Tant que la copie n'est pas redessinée, GET /v1/invoices/:id/pdf répond 202 avec un job plutôt que de servir une copie périmée.

Déposer via une Plateforme Agréée

En mode live avec une PA configurée (voir Choisir sa PA), send dépose la facture sur la PA choisie via son API ou son flux EDI.

$ curl -X POST https://facturino.com/api/v1/invoices/inv_.../send \
  -H "Authorization: Bearer fac_live_..." \
  -H "Idempotency-Key: send-FAC2026-00042"

# Réponse 202 Accepted — dépôt asynchrone via la PA configurée sur l'entreprise
{
  "id": "inv_a1b2c3d4e5f6",
  "object": "invoice",
  "status": "sending"
}

L'opération est asynchrone — la réponse 202 renvoie l'invoice avec status: "sending". Suivez l'avancement via GET /v1/invoices/{id}/status ou les webhooks : les transitions suivantes (deposited, transmitted, available…) y sont émises.

status est une projection de trois axes lisibles séparément sur la facture : documentStatus, transmissionStatus (avec transmissionDetail) et paymentStatus. Pendant le transit (sending, deposited, transmitted…) c'est la transmission qui donne le mot ; ensuite l'encaissement l'emporte. Une facture encaissée avant son dépôt reste donc status: "paid" une fois approuvée, avec transmissionStatus: "approved" ; l'événement invoice.approved est émis même si status ne change pas.

Les octets déposés sont l'original Factur-X archivé tant qu'il satisfait les règles du CIUS-FR. Si un document figé avant un correctif du générateur ne les satisfait plus (par exemple BT-23, règle BR-FR-08), le dépôt envoie un CII régénéré depuis le document tel qu'émis (même numéro, mêmes montants, encaissement à l'émission et non encaissements postérieurs), enregistré sous files.correctedXmlPath et tracé dans lifecycle ; l'original archivé n'est jamais réécrit. Quand aucune régénération ne suffit, send répond document_not_conformant.

Le dépôt vérifie aussi l’identité figée de l’acheteur, y compris sur une facture finalisée avant ce contrôle. Un marqueur de non-diffusion dans le nom ou l’adresse bloque send avec 400 buyer_identity_not_disclosed, avant lecture des fichiers, régénération ou appel de plateforme ; param indique le champ en cause. Corrigez la fiche client puis établissez un avoir total d’annulation avant une facture de remplacement : le renvoi ne répare pas un instantané figé. Ce contrôle s’applique également en mode test.

Lire le suivi et les fichiers

einvoicing et files sont des objets en lecture seule. Un motif ou un artefact peut être absent sur un document ancien. Un identifiant PA peut être complété après un webhook sans changement de statut ni nouvel événement de cycle de vie.

# PDF lisible — renvoie une URL signée si en cache
$ curl https://facturino.com/api/v1/invoices/inv_.../pdf \
  -H "Authorization: Bearer fac_test_..."

# 200 OK — URL de téléchargement temporaire (à suivre)
{
  "object": "file_url",
  "url": "https://storage.googleapis.com/.../facture.pdf?...",
  "expires_in": 900
}

# Si le fichier n'est pas encore généré → 202 Accepted (génération asynchrone)
{
  "id": "job_3k9d2",
  "object": "job",
  "type": "pdf",
  "status": "pending"
}

# Factur-X (PDF/A-3 avec XML CII intégré) — même contrat file_url / job
$ curl https://facturino.com/api/v1/invoices/inv_.../facturx \
  -H "Authorization: Bearer fac_test_..."

# XML CII brut (BR-FR validé Schematron) — finalized requis (draft → 400)
$ curl https://facturino.com/api/v1/invoices/inv_.../xml?format=cii \
  -H "Authorization: Bearer fac_test_..." \
  -o invoice-cii.xml

# XML UBL 2.1 (?format=ubl)
$ curl https://facturino.com/api/v1/invoices/inv_.../xml?format=ubl \
  -H "Authorization: Bearer fac_test_..." \
  -o invoice-ubl.xml

$ curl "https://facturino.com/api/v1/invoices?status=overdue&date_from=2026-01-01&sort=created&limit=50&expand=customer" \
  -H "Authorization: Bearer fac_test_..."

$ curl -X POST https://facturino.com/api/v1/invoices/inv_.../payments/pay_.../cancel \
  -H "Authorization: Bearer fac_live_..."

# Le paiement passe à "cancelled" (piste d'audit conservée) et le solde est recalculé.
{
  "id": "pay_...",
  "object": "payment",
  "status": "cancelled",
  "invoiceStatus": "partially_paid",
  "amountDue": 60000
}

{
  "id": "inv_00090",
  "object": "invoice",
  "number": "FAC2026-00090",
  "status": "rejected",
  "documentStatus": "finalized",
  "transmissionStatus": "rejected",
  "transmissionDetail": null,
  "paymentStatus": "unpaid",
  "type": "standard",
  "currency": "eur",
  "customer": {
    "ref": "cus_example",
    "snapshot": {
      "name": "INTEK CENTER",
      "address": {
        "line1": "1 rue Exemple",
        "postalCode": "75001",
        "city": "Paris",
        "country": "FR"
      }
    }
  },
  "items": [],
  "totals": {
    "totalHT": 990,
    "totalTVA": 198,
    "totalTTC": 1188,
    "amountPaid": 0,
    "amountDue": 1188
  },
  "einvoicing": {
    "paId": "dep_current",
    "paStatus": "rejected",
    "paStatusCode": "fr:213",
    "paTransactionId": null,
    "paErrorCode": null,
    "rejectionCode": "REJ_ADR",
    "rejectionSource": "platform",
    "rejectionReason": "REJ_ADR — Directory line matricule_plateforme (0037) does not match expected matricule (0022)",
    "rejectionNote": null,
    "rejectionCategory": "addressing_error",
    "refusalReason": null,
    "paIdempotencyKey": "submission_same_attempt",
    "peppolDeliveryId": null,
    "ereportingId": null,
    "ereportingPaymentId": null,
    "sentAt": "2026-09-07T12:36:00.000Z",
    "trackingId": null,
    "routingIdentifier": "0225:73282932000074",
    "buyerReachableAt": null,
    "directoryCheckedAt": null,
    "submissionArtefact": {
      "kind": "cii",
      "path": "invoices/inv_00090/submission.xml",
      "generatedAt": "2026-09-07T12:35:00.000Z",
      "correctedRules": [],
      "routingIdentifier": "0225:73282932000074"
    },
    "previousSubmissions": [
      {
        "paId": "dep_previous",
        "paTransactionId": null,
        "paIdempotencyKey": "submission_previous",
        "paStatus": "rejected",
        "paStatusCode": "fr:213",
        "paErrorCode": null,
        "rejectionReason": "AUTRE — Ce motif nécessite une explication en note de CDV.",
        "rejectionCode": "AUTRE",
        "rejectionSource": "platform",
        "rejectionNote": "L’adresse de réception doit être confirmée.",
        "rejectionCategory": "other",
        "sentAt": "2026-09-07T08:00:00.000Z",
        "closedAt": "2026-09-07T12:35:00.000Z"
      }
    ]
  },
  "livemode": true,
  "created": "2026-09-07T12:00:00.000Z",
  "updated": "2026-09-07T12:36:00.000Z"
}