Invoices

Les Invoices permettent d’émettre, envoyer et gérer des factures clients programmatiquement. Chaque facture génère un lien de paiement hébergé et peut être envoyée par email automatiquement. Elle est liée à un Customer et peut contenir une ou plusieurs lignes de produits.

Le flux standard est : créer une facture (draft) → finaliser → envoyer par email → attendre le paiement (paid).

Cycle de vie

draft→open→paid / void / uncollectible

Statut	Signification	Action disponible
`draft`	Brouillon — modifiable, non envoyée.	`/finalize/` pour passer en open.
`open`	Finalisée — lien de paiement actif.	`/send/`, `/pay/`, `/void/`.
`paid`	Réglée — paiement reçu.	Aucune action possible.
`void`	Annulée — lien désactivé.	Créer une nouvelle Invoice.
`uncollectible`	Déclarée irrécouvrable.	Action manuelle uniquement.

Endpoints

Méthode	Endpoint	Description
POST	`/invoices/`	Créer une facture (statut draft)
GET	`/invoices/`	Lister les factures
GET	`/invoices/{id}/`	Récupérer une facture
PATCH	`/invoices/{id}/`	Modifier une facture draft
POST	`/invoices/{id}/finalize/`	Finaliser (draft → open)
POST	`/invoices/{id}/send/`	Envoyer par email au Customer
POST	`/invoices/{id}/void/`	Annuler une facture open
POST	`/invoices/{id}/pay/`	Marquer comme payée manuellement

Cette introduction est-elle claire ?

Schéma de l’objet

Response Objet Invoice

json

{
  "id": "inv_xxxxxxxxxxxx",
  "object": "invoice",
  "invoice_number": "2026-0042",
  "status": "open",
  "customer": "cust_xxxxxxxx",
  "customer_email": "client@email.com",
  "currency": "XAF",
  "subtotal": 50000,
  "tax_amount": 0,
  "discount_amount": 0,
  "total": 50000,
  "amount_paid": 0,
  "amount_remaining": 50000,
  "due_date": "2026-04-01",
  "description": "Facture de conseil — Mars 2026",
  "footer": "Merci de votre confiance.",
  "payment_url": "https://pay.sangho.com/i/inv_xxxx",
  "pdf_url": "https://api.sangho.com/v1/invoices/inv_xxxx/pdf/",
  "line_items": [
    {
      "product": "prod_xxx",
      "description": "Conseil stratégique",
      "quantity": 2,
      "unit_amount": 25000,
      "amount": 50000
    }
  ],
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Créer une Invoice

Crée une facture en statut draft. À ce stade, elle est entièrement modifiable. Aucun email n’est envoyé et aucun lien de paiement n’est actif.

POST Corps de la requête

customer Requis

string cust_...

ID du Customer destinataire de la facture. L’email et le nom du Customer seront utilisés sur la facture PDF et dans l’email d’envoi.

line_items Requis

array[object]

Lignes de facturation. Chaque ligne contient un produit ou un montant libre, une quantité et un prix.

Chaque élément doit contenir : product (ID d’un Product existant) ou description + unit_amount pour une ligne libre. quantity est un entier positif (défaut : 1). La TVA est calculée automatiquement selon la configuration de votre App.

currency Optionnel

string ISO 4217 défaut : devise de l'App

Code devise de la facture. Par défaut, la devise principale de votre App est utilisée.

due_date Optionnel

string YYYY-MM-DD défaut : J+30 ex : 2026-04-01

Date d’échéance de paiement. Affichée sur la facture PDF et dans l’email d’envoi.

Si non fournie, l’échéance est fixée à 30 jours après la date de finalisation (pas de création). Passée l’échéance, la facture reste open — Sangho n’envoie pas de relances automatiques. Vous pouvez implémenter des relances via les webhooks invoice.payment_overdue.

description Optionnel

string

Objet ou description de la facture. Apparaît en en-tête de la facture PDF et dans l’email.

footer Optionnel

string

Texte de pied de page de la facture PDF. Utile pour les mentions légales, IBAN, conditions de paiement.

Max 500 caractères. Affiché uniquement sur le PDF — pas sur la page de paiement en ligne.

metadata Optionnel

object

Données libres — référence de bon de commande, numéro de contrat, etc.

Finaliser, Envoyer, Annuler

Finaliser (/finalize/) : verrouille la facture et génère le lien de paiement. La facture passe en open. Les lignes et le montant ne peuvent plus être modifiés.

Envoyer (/send/) : envoie la facture par email au Customer avec le lien de paiement et le PDF en pièce jointe. Peut être appelé plusieurs fois (relance manuelle).

Finaliser + Envoyer en une seule opération

Vous pouvez appeler /finalize/ puis /send/ immédiatement à la suite. Ou passer auto_send: true dans le corps de /finalize/ pour déclencher l’envoi automatiquement à la finalisation.

Annuler (/void/) : invalide définitivement la facture. Le lien de paiement est désactivé. Irréversible — créez une nouvelle Invoice si nécessaire.

Le cycle de vie des Invoices est-il clair ?

Créer et envoyer une facture

bash

# 1. Créer (draft)
curl -X POST https://api.sangho.com/v1/invoices/ \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cust_xxxxxxxx",
    "currency": "XAF",
    "due_date": "2026-04-15",
    "description": "Prestation de conseil — Avril 2026",
    "footer": "Règlement sous 30 jours. IBAN : GA00 0000 0000.",
    "line_items": [
      { "product": "prod_xxx", "quantity": 2 },
      { "description": "Frais de déplacement", "unit_amount": 5000, "quantity": 1 }
    ]
  }'


# 2. Finaliser
curl -X POST https://api.sangho.com/v1/invoices/inv_xxx/finalize/ \
  -H "Authorization: Bearer sk_live_xxxx"


# 3. Envoyer par email
curl -X POST https://api.sangho.com/v1/invoices/inv_xxx/send/ \
  -H "Authorization: Bearer sk_live_xxxx"

Response 201 Created — Draft

La facture est créée en draft. Aucun email n'est envoyé, aucun lien actif. Modifiable via PATCH.

json

{
  "id": "inv_xxxxxxxxxxxx",
  "object": "invoice",
  "invoice_number": "2026-0042",
  "status": "draft",
  "customer": "cust_xxxxxxxx",
  "total": 55000,
  "currency": "XAF",
  "due_date": "2026-04-15",
  "payment_url": null,
  "pdf_url": null,
  "created_at": "2026-03-15T09:00:00Z"
}

Response 200 OK — Finalisée (open)

La facture est verrouillée. Le lien de paiement est actif. Envoyez /send/ pour notifier le client.

Une fois finalisée, les line_items et le montant total ne peuvent plus être modifiés. Créez une nouvelle Invoice en cas d'erreur.

json

{
  "id": "inv_xxxxxxxxxxxx",
  "status": "open",
  "total": 55000,
  "payment_url": "https://pay.sangho.com/i/inv_xxxx",
  "pdf_url": "https://api.sangho.com/v1/invoices/inv_xxxx/pdf/",
  "updated_at": "2026-03-15T09:05:00Z"
}