Introduction à l'API

L'API REST de Naskel vous permet de lire et créer vos factures, devis, contacts, entreprises et opportunités, et de gérer vos produits et stocks depuis vos propres outils. Cette page couvre l'essentiel pour faire votre premier appel.

Base URL

Tous les appels se font sur :

https://app.naskel.io/api/v1

Authentification

Chaque requête doit porter une clé API dans l'en-tête Authorization, sous la forme d'un jeton Bearer :

Authorization: Bearer nsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Format des clés

Une clé commence par nsk_live_, suivi de 32 caractères hexadécimaux (41 caractères en tout). Par exemple (clé factice) :

nsk_live_0123456789abcdef0123456789abcdef

Générer une clé

Les clés se créent dans l'application : Paramètres → API et intégrations → Clés API publiques. L'écran est réservé au propriétaire de l'espace.

Vous y nommez la clé, cochez ses scopes, et fixez une date d'expiration si besoin. Le secret n'est affiché qu'une fois, à la création : copiez-le tout de suite. Vous pouvez aussi révoquer une clé existante.

Votre premier appel

Récupérer vos 20 dernières factures payées :

curl -H "Authorization: Bearer nsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     "https://app.naskel.io/api/v1/invoices?limit=20&status=PAID"

Le même appel en JavaScript (Node 18+ ou navigateur, avec fetch) :

const res = await fetch(
  "https://app.naskel.io/api/v1/invoices?limit=20&status=PAID",
  { headers: { Authorization: `Bearer ${process.env.NASKEL_API_KEY}` } },
);

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.message}`);
}

const { data, pagination } = await res.json();
console.log(`${data.length} factures sur ${pagination.total}`);

Une écriture, en passant le corps JSON et, pour les opérations sensibles, un en-tête d'idempotence :

await fetch("https://app.naskel.io/api/v1/stock-movements", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NASKEL_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    movements: [{ productId: "prod_123", quantity: -2, reason: "Casse" }],
  }),
});

Portée de l'API

L'API v1 couvre la lecture, la création, la mise à jour et la suppression ciblée de vos données :

• Lecture (GET) sur toutes les ressources documentées ;
• Création (POST) des factures, devis, contacts, entreprises et opportunités ;
• Mise à jour (PATCH) des factures, devis, contacts, entreprises et opportunités. Sur les factures et les devis, la modification est réservée au statut brouillon (DRAFT) ;
• Suppression (DELETE) des factures (brouillon, définitive), devis (brouillon), contacts et opportunités ;
• Écritures de stock : ajustement d'un produit et mouvements de stock.

Les méthodes exactes et leurs contraintes (statuts autorisés, idempotence) sont détaillées sur chaque page de ressource. Les produits ne se créent pas par l'API (voir Produits) ; seul leur stock s'ajuste.

Idempotence

Les écritures acceptent un en-tête Idempotency-Key : une chaîne unique que vous choisissez pour identifier une opération.

Idempotency-Key: a1b2c3d4-…

Si vous rejouez le même appel avec la même clé, le serveur renvoie le même résultat sans ré-exécuter l'opération. C'est la garantie qui vous permet de retenter sans risque après une coupure réseau : vous ne savez pas si le premier appel est passé, vous le rejouez avec la même clé, et au pire vous récupérez simplement la réponse du premier.

• Générez une clé par opération (un UUID convient), et réutilisez-la uniquement pour rejouer cette opération-là.
• L'en-tête est supporté sur les écritures, notamment POST /products/{id}/adjust et POST /stock-movements.

La suite

• Scopes et permissions : ce qu'une clé a le droit de faire.
• Limites de débit : combien de requêtes par minute.
• Pagination et format des réponses
• Codes d'erreur
• Factures et Entreprises : les ressources documentées en détail.