Invoices

Créer un brouillon de facture

Crée une facture au statut brouillon (non numérotée, non émise, non transmise à la sphère publique), émise depuis l'organisation de la clé. Le client est optionnel (complété ensuite dans l'app). Scope requis : invoices:draft.

curl

curl -X POST https://api.swipify.fr/api/v1/invoices/draft \
  -H "X-API-Key: sk_live_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"lines":[{"description":"Pose carrelage","quantity":3,"unit":"jour","unitPrice":280,"vatRate":10}]}'

JavaScript

await fetch("https://api.swipify.fr/api/v1/invoices/draft", {
  method: "POST",
  headers: { "X-API-Key": "sk_live_...", "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ lines: [{ description: "Pose carrelage", quantity: 3, unitPrice: 280, vatRate: 10 }] }),
}).then((r) => r.json());
post/invoices/draft

Request

  • Base URL: https://api.swipify.fr/api/v1
  • URL: https://api.swipify.fr/api/v1/invoices/draft
  • Auth: API key in header X-API-Key

Headers

Idempotency-Keystring

Clé d'idempotence (un UUID est recommandé). Optionnelle mais conseillée sur les retries réseau : la première réponse 2xx est mémorisée par (organisation, clé) ~24 h et rejouée au lieu de recréer la ressource (évite les doublons de facture/devis/client). Réutiliser la même clé pour une autre requête (méthode/chemin différents) renvoie 422. L'en-tête X-Idempotency-Key est accepté comme alias équivalent.

Request body

clientIdinteger

Référence un client existant (exclusif avec customer).

objectstring nullable
paymentModestring nullable
brandProfileKeystring

Profil de marque mémorisé sur le brouillon et relu à la validation dans l'app. Absent → profil par défaut. Voir GET /brand-profiles pour la clé (elle diffère du nom affiché). Clé inconnue → 400.

Example request

{
  "object": "Rénovation salle de bain",
  "customer": {
    "type": "individual",
    "firstName": "Jean",
    "lastName": "Dupont",
    "email": "jean.dupont@example.com"
  },
  "lines": [
    {
      "description": "Pose de carrelage",
      "quantity": 3,
      "unit": "jour",
      "unitPrice": 280,
      "vatRate": 10
    },
    {
      "description": "Fourniture carrelage",
      "quantity": 25,
      "unit": "m²",
      "unitPrice": 32,
      "vatRate": 20
    }
  ]
}

Response

Brouillon créé

idinteger
numberstring nullable
draftNumberstring nullable
statusstring
objectstring nullable
datestring date-time nullable
dueDatestring date-time nullable
paidDatestring date-time nullable
totalHTstring
totalVATstring
totalTTCstring
einvoiceStatus'pending' | 'delivered' | 'accepted' | 'rejected' | 'paid' | 'reported' | 'error' | 'null' nullable

Statut de cycle de vie e-invoice (PA). null si pas de cycle (brouillon/non conforme). rejected = refusée par la plateforme. reported = vente à un particulier, transmise en e-reporting : pas d'e-facture, donc ni remise ni acceptation client.

brandProfileKeystring nullable

Profil de marque du document. null = profil par défaut.

reminderCountinteger

Nombre de relances d'impayé envoyées (manuelles et automatiques). L'envoi d'une relance reste un geste dans l'application, jamais un appel API.

reminderLastSentAtstring date-time nullable

Date de la dernière relance d'impayé, null si jamais relancée.

remindersPausedboolean

true si les relances automatiques sont suspendues pour cette facture.

recurringboolean

true si la facture a été générée par une facture récurrente.

createdAtstring date-time

Example response

{
  "id": 1234,
  "number": "FAC-2026-0042",
  "status": "paid",
  "totalHT": "850.00",
  "totalVAT": "170.00",
  "totalTTC": "1020.00",
  "brandProfileKey": "boutique-lyon",
  "reminderCount": 1
}

Changes

No recorded changes to this operation across all 1 revision of this API.