Cas d’usage
Gestion des litiges (POST /v1/invoices/{id}/dispute)
Tracer un litige client conformément aux flux PDP/PPF
À partir de septembre 2026, la facturation électronique en France impose un statut `dispute` (litige) traçable dans les flux PDP/PPF. Scell.io expose `POST /api/v1/invoices/{id}/dispute` pour ouvrir un litige sur une facture émise : champs requis `reason` (enum : `wrong_amount`, `wrong_recipient`, `quality_issue`, `delivery_issue`, `other`), `description` (texte libre, max 2000 chars), pièces jointes optionnelles. L'événement est : (1) journalisé dans l'audit trail immuable, (2) notifié au tenant émetteur via webhook `invoice.disputed`, (3) propagé au PDP/PPF si la facture y a transité. Endpoints complémentaires : `POST /{id}/dispute/resolve` (résolution amiable), `POST /{id}/dispute/escalate` (escalade).
À retenir
- Endpoint `POST /api/v1/invoices/{id}/dispute`
- 5 raisons normalisées (wrong_amount, quality_issue...)
- Webhook `invoice.disputed` au tenant émetteur
- Propagation PDP/PPF si applicable
- Endpoints `resolve` et `escalate` complémentaires
- Trace dans audit trail immuable
Exemple de code
use Scell\Sdk\ScellClient;
$scell = new ScellClient(getenv('SCELL_SECRET_KEY'));
// Ouvrir un litige sur la facture INV-2026-042
$dispute = $scell->invoices()->dispute('inv_42', [
'reason' => 'wrong_amount',
'description' => 'Le montant facturé est de 1500€ TTC alors que le devis signé indique 1200€ TTC.',
'attachments' => [
['name' => 'devis-signe.pdf', 'content_base64' => base64_encode(file_get_contents('/tmp/devis.pdf'))],
],
]);
echo "Litige #{$dispute->id} ouvert. Statut: {$dispute->status}\n";
// Résolution amiable plus tard
$scell->invoices()->resolveDispute('inv_42', [
'resolution' => 'credit_note_issued',
'credit_note_id' => 'cn_99',
]);