Use cases
Idempotent invoice creation (Idempotency-Key)
Prevent duplicates on network retry
The `POST /api/v1/invoices` endpoint accepts an `Idempotency-Key: <uuid>` header that guarantees a replayed call (timeout, HTTP retry, network failure) won't create a duplicate invoice. The server stores the first response for 24h and replays it identically for any subsequent request with the same key. Each key is scoped to the tenant and request body: if you change the body with the same key, the server returns `409 Conflict`. Critical pattern for ISCA self-certified compliance and French fiscal obligations (French invoicing does not allow duplicates).
Key facts
- `Idempotency-Key: <uuid>` header recommended on critical POSTs
- Response stored 24h server-side
- Same body → replayed response (200 / 201)
- Different body with same key → `409 Conflict`
- v4 UUID generated client-side before each attempt
- Compatible with client-side exponential retry
Code example
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]);
}