Suivi et preuves d’envoi

Un envoi passe par des étapes numérotées (step, jusqu’à lastStep) : 0 payée, 1 imprimée, 2 remise à La Poste, 3 en cours d’acheminement, 4 distribuée, 5 accusé de réception signé (recommandé avec AR). Il peut aussi finir en returned (retourné), error ou canceled.

Lire un envoi

GET/v1/mailings/{id}

Requête

curl "https://api.vitef.com/v1/mailings/e1209b63-3764-49e3-bf9c-154e9be830da" \
  -H "Authorization: Bearer $VITEF_API_KEY"

Réponse 200

{
  "title": "Lettre de résiliation SFR",
  "mode": "ar",
  "modeLabel": "Recommandé avec AR",
  "status": "posted",
  "statusLabel": "Remise à La Poste",
  "step": 2,
  "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"
    },
    {
      "step": 1,
      "status": "printed",
      "label": "Imprimée",
      "at": "2026-09-23T10:00:00.000Z"
    },
    {
      "step": 2,
      "status": "posted",
      "label": "Remise à La Poste",
      "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": [
    {
      "kind": "filing",
      "label": "Preuve de dépôt"
    }
  ],
  "document": "… (lettre envoyée)"
}

Plutôt que d’interroger l’API en boucle, recevez chaque étape par webhook.

Lister vos envois

GET/v1/mailings

Du plus récent au plus ancien, filtrables par reference et status, paginés par curseur (voir pagination).

Requête

curl "https://api.vitef.com/v1/mailings?reference=BAIL-2026-042" \
  -H "Authorization: Bearer $VITEF_API_KEY"

Réponse 200

{
  "data": [
    {
      "title": "Lettre de résiliation SFR",
      "mode": "ar",
      "modeLabel": "Recommandé avec AR",
      "status": "posted",
      "statusLabel": "Remise à La Poste",
      "step": 2,
      "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"
        },
        {
          "step": 1,
          "status": "printed",
          "label": "Imprimée",
          "at": "2026-09-23T10:00:00.000Z"
        },
        {
          "step": 2,
          "status": "posted",
          "label": "Remise à La Poste",
          "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": [
        {
          "kind": "filing",
          "label": "Preuve de dépôt"
        }
      ],
      "document": "… (lettre envoyée)"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Télécharger une preuve

GET/v1/mailings/{id}/proofs/{kind}

proofs liste les preuves disponibles. kind : filing (preuve de dépôt), delivery (accusé de réception), return (pli retourné). La réponse donne un lien de téléchargement valable quelques minutes : demandez-le au moment d’en avoir besoin, ne le stockez pas.

Requête

curl "https://api.vitef.com/v1/mailings/e1209b63-3764-49e3-bf9c-154e9be830da/proofs/filing" \
  -H "Authorization: Bearer $VITEF_API_KEY"

Réponse 200

{
  "kind": "filing",
  "label": "Preuve de dépôt",
  "url": "https://api.vitef.com/app/sandbox/proof.pdf?kind=filing"
}

En bac à sable, le lien mène à un PDF fictif.

Étape suivante : les webhooks