Cas d’usage
Création de factures idempotente (Idempotency-Key)
Empêcher les doublons en cas de retry réseau
L'endpoint `POST /api/v1/invoices` accepte un header `Idempotency-Key: <uuid>` qui garantit qu'un même appel rejoué (timeout, retry HTTP, panne réseau) ne crée pas de facture en double. Le serveur stocke la première réponse pendant 24h et la rejoue à l'identique pour toute requête ultérieure portant la même clé. Chaque clé est scopée au tenant et au body de la requête : si vous changez le body avec la même clé, le serveur retourne `409 Conflict`. Pattern critique pour la conformité ISCA et obligations fiscales françaises (la facturation française n'autorise pas les doublons).
À retenir
- Header `Idempotency-Key: <uuid>` recommandé sur POST critiques
- Réponse stockée 24h côté serveur
- Body identique → réponse rejouée (200 / 201)
- Body différent avec même clé → `409 Conflict`
- UUID v4 généré côté client avant chaque tentative
- Compatible avec retry exponentiel client
Exemple de code
use Scell\Sdk\ScellClient;
use Ramsey\Uuid\Uuid;
$scell = new ScellClient(getenv('SCELL_SECRET_KEY'));
$idempotencyKey = Uuid::uuid4()->toString();
// Si l'appel échoue (timeout, 502), rejouer avec la MÊME clé
try {
$invoice = $scell->invoices()->create([
'format' => 'factur-x',
'buyer' => ['siret' => '98765432109876', 'name' => 'Client SAS'],
'lines' => [['description' => 'Conseil', 'quantity' => 1, 'unit_price' => 1500.00, 'vat_rate' => 20]],
], ['Idempotency-Key' => $idempotencyKey]);
} catch (\Scell\Sdk\Exceptions\TransientException $e) {
// Retry avec la MÊME clé : pas de doublon
$invoice = $scell->invoices()->create($body, ['Idempotency-Key' => $idempotencyKey]);
}