Émettre des factures via l'API

POST /invoices avec Idempotency-Key, TVA en pourcentage, plus listing, avoir et marquage payé.

Votre première facture en 6 étapes

Envoyez POST /v1/invoices avec un objet buyer et au moins une entrée dans lines.
Ajoutez l’en-tête Idempotency-Key — il est obligatoire, une clé par opération logique.
Envoyez vat_rate en pourcentage (21) et unit_price comme prix unitaire HORS TAXES.
La réponse 201 contient id, number, series, les totaux net/vat/gross et les metadata que vous avez envoyées.
Récupérez le document avec GET /v1/invoices/{id}/pdf ou le XML UBL avec GET /v1/invoices/{id}/xml.

Tous les endpoints

Méthode	Endpoint	Scope	Idempotency-Key	Requêtes / minute
POST	/invoices Émettre une facture ou une proforma	invoices:write	obligatoire	30
GET	/invoices Lister les factures (pagination par curseur)	invoices:read	—	120
POST	/invoices/preview-totals Calculer les totaux sans rien créer	invoices:read	—	120
GET	/invoices/{invoice_id} Récupérer une facture	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Télécharger le PDF de la facture	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Émettre un avoir annulant cette facture	invoices:write	obligatoire	30
POST	/invoices/{invoice_id}/payments Marquer la facture comme payée	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Marquer la facture comme non payée	invoices:write	—	30

Ce qu'est l'API 4invoices

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{
    "buyer": {
      "name": "Exemplu Comert SRL",
      "tax_id": "RO12345678",
      "address": "Str. Fabricii 12",
      "city": "Cluj-Napoca",
      "county": "Cluj",
      "country": "RO",
      "email": "[email protected]"
    },
    "lines": [
      { "description": "Abonament SaaS, iulie", "quantity": 1, "unit_price": 400, "vat_rate": 21, "unit": "buc" },
      { "description": "Implementare", "quantity": 6, "unit_price": 250, "vat_rate": 21, "unit": "ora" }
    ],
    "currency": "RON",
    "document_kind": "factura",
    "due_date": "2026-08-15",
    "metadata": { "order_id": "10457" }
  }'

bash
# Pagination par curseur : suivez next_cursor jusqu'à ce que has_more soit false.
curl -sS "https://api.4invoices.net/v1/invoices?limit=50&status=issued&issued_from=2026-07-01" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"object":"list","data":[...],"has_more":true,"next_cursor":"inv_01J..."}

curl -sS "https://api.4invoices.net/v1/invoices?limit=50&cursor=inv_01J..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/storno \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: storno-inv_01J7ABC-1'

# L'avoir reçoit SON PROPRE numéro fiscal ; le numéro de la facture d'origine n'est jamais réutilisé.

bash
# Marquer comme payée
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Annuler
curl -sS -X DELETE https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Erreurs

Statut	Type	Code
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Erreurs fréquentes

La liste est paginée par curseur : suivez next_cursor jusqu’à ce que has_more vaille false. Les filtres incluent status, document_kind, buyer_tax_id, issued_from, issued_to et q.
Une facture d’annulation (storno) se crée avec POST /v1/invoices/{id}/storno et reçoit son propre numéro fiscal — le numéro d’origine n’est jamais réutilisé.
Une facture pro forma (document_kind proforma) ne consomme aucun numéro fiscal et ne peut pas être déposée dans le système national de facturation électronique.
metadata est renvoyé tel quel lors des lectures : placez-y l’identifiant de votre commande et vous n’aurez plus besoin d’une table de correspondance séparée.
POST /v1/invoices/preview-totals effectue le même calcul sans effet de bord — pratique pour afficher les totaux dans votre propre panier.

Questions et réponses pour développeurs

Combien de lignes une facture peut-elle comporter ?

Entre 1 et 400. description est limité à 1024 caractères, et quantity doit être strictement positif.

Que se passe-t-il si je renvoie la même requête après un timeout ?

Avec la même Idempotency-Key, vous obtenez la facture d’origine ainsi qu’un en-tête Idempotency-Replayed: true. Aucun second document n’est émis.

Comment marquer une facture comme payée ?

POST /v1/invoices/{id}/payments la marque comme payée, et DELETE sur le même chemin annule l’opération. Les deux nécessitent le scope invoices:write.

Voir aussi