Idempotence et nouvelles tentatives

Une coupure réseau ou un délai dépassé ne vous dit pas si votre requête a abouti. Pour réessayer sans risque d’envoyer deux fois la même lettre ni d’être débité deux fois, ajoutez l’en-tête Idempotency-Key à vos requêtes POST.

Requête

curl -X POST "https://api.vitef.com/v1/mailings" \
  -H "Authorization: Bearer $VITEF_API_KEY" \
  -H "Idempotency-Key: 6f1c2b0e-8d4a-4f7e-9a51-3c2d1e0f9b87" \
  -H "Content-Type: application/json" \
  -d '{
  "letter": "resiliation-box",
  "provider": "sfr",
  "values": {
    "ref": "0612345678",
    "motif": "Déménagement"
  },
  "sender": {
    "name": "Camille Martin",
    "street": "12 rue des Lilas",
    "city": "69003 Lyon"
  },
  "mode": "ar",
  "reference": "BAIL-2026-042"
}'

Réponse 201

{
  "title": "Lettre de résiliation SFR",
  "mode": "ar",
  "modeLabel": "Recommandé avec AR",
  "status": "paid",
  "statusLabel": "Payée",
  "step": 0,
  "lastStep": 5,
  "trackingNumber": "1A15760000001",
  "createdAt": "2026-09-23T10:00:00.000Z",
  "events": [
    {
      "step": 0,
      "status": "paid",
      "label": "Payée",
      "at": "2026-09-23T10:00:00.000Z"
    }
  ],
  "id": "e1209b63-3764-49e3-bf9c-154e9be830da",
  "orderId": null,
  "recipient": [
    "SFR Résiliation",
    "TSA 30103",
    "69947 Lyon Cedex 20"
  ],
  "amountCents": 0,
  "reference": "BAIL-2026-042",
  "test": true,
  "proofs": [],
  "document": {
    "title": "Lettre de résiliation SFR",
    "sender": [
      "Camille Martin",
      "12 rue des Lilas",
      "69003 Lyon"
    ],
    "recipient": [
      "SFR Résiliation",
      "TSA 30103",
      "69947 Lyon Cedex 20"
    ],
    "place": "Lyon",
    "date": "23 septembre 2026",
    "subject": "Résiliation de mon abonnement SFR",
    "body": [
      "Madame, Monsieur,",
      "Par la présente, je vous informe de ma décision de résilier mon abonnement internet SFR, identifiant client 0612345678, en raison de mon déménagement.",
      "Conformément à l’article L224-39 du Code de la consommation, cette résiliation prendra effet dans un délai de 10 jours à compter de la réception de ce courrier.",
      "Je vous remercie de m’en accuser réception et de m’indiquer les modalités de restitution du matériel.",
      "Je vous prie d’agréer, Madame, Monsieur, l’expression de mes salutations distinguées."
    ],
    "signature": "Camille Martin"
  }
}

Règles

Une clé par opération : 1 à 255 caractères ASCII, un UUID v4 de préférence. Générez-la avant le premier envoi et gardez-la avec l’opération (en base, dans votre file de tâches) pour toutes ses nouvelles tentatives.
Pendant 24 h, la même clé avec la même requête (même route, même corps) renvoie la première réponse telle quelle, avec l’en-tête Idempotent-Replayed: true : aucun nouvel envoi, aucun nouveau débit.
La même clé avec une autre requête : 422 idempotency_key_reused. La même requête encore en cours : 409 idempotency_in_progress, réessayez après Retry-After.
Réponses rejouées : succès (2xx), 400, 404 et 422. Ne sont pas gardées, pour qu’une nouvelle tentative s’exécute vraiment : 402 (crédit insuffisant), 409, 429 et les erreurs 5xx.
Les clés sont propres à votre compte et à l’environnement (test ou live) : une clé test ne rejoue jamais une réponse live.
Toutes les routes POST de /v1 l’acceptent. Les GET n’en ont pas besoin : ils ne modifient rien.

Réessayer un envoi

Nouvelles tentatives avec la même clé

import { randomUUID } from 'node:crypto';

const key = randomUUID(); // gardée avec l'opération, réutilisée à chaque tentative
for (const wait of [0, 1000, 5000, 30000]) {
  await new Promise((r) => setTimeout(r, wait));
  try {
    const res = await fetch('https://api.vitef.com/v1/mailings', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.VITEF_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': key,
      },
      body: JSON.stringify(mailing),
      signal: AbortSignal.timeout(60_000),
    });
    if (res.status < 500 && res.status !== 409 && res.status !== 429) return await res.json();
  } catch {
    // coupure ou délai dépassé : on réessaie avec la même clé
  }
}

Dépôt en cours

Si La Poste (via notre prestataire) ne confirme pas le dépôt à temps, l’envoi est quand même créé : la réponse est 201 avec status: "paid", sans numéro de suivi. Vitef redépose automatiquement le courrier pendant 23 h avec la même clé chez le prestataire, sans aucun doublon possible. Vous n’avez rien à refaire : les étapes suivantes arrivent par webhook, ou par GET /v1/mailings/{id}. Si le dépôt est finalement refusé, l’envoi passe en error (webhook mailing.error) et son prix est recrédité.

Étape suivante : la pagination