APIMis à jour le 18 juin 2026

Factures

Lister, lire, créer, modifier et supprimer des factures via l'API. Champs renvoyés, corps de création et exemples.

La ressource invoices permet de lister vos factures, d'en lire une, et d'en créer de nouvelles au statut brouillon.

Endpoints

Méthode	Chemin	Scope
`GET`	`/api/v1/invoices`	`read:invoices`
`POST`	`/api/v1/invoices`	`write:invoices`
`GET`	`/api/v1/invoices/{id}`	`read:invoices`
`PATCH`	`/api/v1/invoices/{id}`	`write:invoices`
`DELETE`	`/api/v1/invoices/{id}`	`write:invoices`

Lister les factures

Paramètres de requête : limit, offset (voir Pagination) et status.

Le paramètre status accepte l'une des valeurs suivantes : DRAFT, SENT, PARTIAL, PAID, OVERDUE, CANCELLED. Un statut inconnu renvoie une erreur 400.

id, number, title, status, type, clientName, clientCompany, clientEmail, taxRate, discountPercent, reverseCharge, issuedAt, dueAt, paidAt, paidAmount, createdAt, updatedAt.

Créer une facture

Un POST /api/v1/invoices crée une facture au statut brouillon (DRAFT).

Corps de la requête

Champ	Type	Requis	Notes
`clientName`	texte, 1 à 200 caractères	Oui
`clientEmail`	email, 200 caractères max	Oui
`currency`	texte, 3 caractères	Non	`EUR` par défaut
`lines`	tableau, 1 à 100 éléments	Oui	Au moins une ligne
`lines[].title`	texte, 1 à 500 caractères	Oui
`lines[].quantity`	nombre, supérieur à 0	Oui
`lines[].unitPrice`	nombre, 0 ou plus	Oui
`lines[].taxRate`	nombre, entre 0 et 100	Non

Comportement

La facture est créée au statut DRAFT.
Son numéro est attribué automatiquement, de façon séquentielle.
Son échéance est fixée à 30 jours après la création.
La réponse a le code 201 et contient l'objet créé, avec ses lignes :

{ "data": { "id": "…", "status": "DRAFT", "lines": [ /* … */ ] } }

Exemple

curl -X POST "https://app.naskel.io/api/v1/invoices" \
  -H "Authorization: Bearer nsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "ACME SARL",
    "clientEmail": "compta@acme.fr",
    "lines": [{ "title": "Conseil", "quantity": 2, "unitPrice": 500, "taxRate": 20 }]
  }'

Nom des champs de ligne

Le libellé d'une ligne s'envoie dans lines[].title et ressort sous lines[].description en lecture. Le POST accepte l'en-tête Idempotency-Key.

Modifier une facture

PATCH /api/v1/invoices/{id} met à jour une facture en brouillon. Tous les champs sont optionnels : n'envoyez que ceux à changer.

Champ	Type	Notes
`title`	texte	Titre de la facture
`dueAt`	date ISO 8601	Échéance
`paymentTermsDays`	nombre, 0 à 365	Délai de paiement, en jours
`lines`	tableau	Remplace l'intégralité des lignes existantes

Réservé au statut DRAFT : sinon 409 invoice_not_draft.

Supprimer une facture

DELETE /api/v1/invoices/{id} supprime une facture en brouillon (DRAFT uniquement, sinon 409 invoice_not_draft).

Suppression définitive

Contrairement aux contacts ou aux devis (suppression douce), la suppression d'une facture est définitive (hard delete) : elle n'est pas conservée et n'est pas récupérable. Réponse : { "ok": true }.

Voir aussi

Entreprises
Codes d'erreur
Le cycle de vie complet côté application : Devis et factures