Options & obligations

GET /options rend les options que vous pouvez poser sur une mission, au prix de votre grille (les tarifs négociés de votre groupe s’appliquent), et pour chacune ce qu’elle exige de vous. C’est la source à consulter avant POST /transports/{id}/options ou une duplication avec options.add.

Le prix d’une option est figé au moment où elle est posée, dans sa clé (stored_key, par exemple Booster - 60). Une modification ultérieure de votre grille ne change pas les missions déjà créées.

1. Lire le catalogue

GET /options — sans paramètre, le catalogue de votre groupe. Avec ?transport_id=…, celui du donneur d’ordre de la mission, et active_options liste les options déjà posées sur la jambe (?leg=aller|retour).

curl -s "$BASE/options?transport_id=$TID" -H "X-Api-Key: $MED_API_KEY"

const res = await fetch(`${BASE}/options?transport_id=${TID}`, {
  headers: { "X-Api-Key": MED_API_KEY },
});
const { options, renters, active_options } = await res.json();

{
  "transport_id": "-OabcDEF123",
  "leg": "aller",
  "prestation": "livraison",
  "active_options": ["Lavage Extérieur - 19"],
  "options": [
    {
      "key": "Booster",
      "stored_key": "Booster - 60",
      "name": "Booster",
      "price": 60,
      "currency": "EUR",
      "active": false,
      "requirements": { "kind": "standard", "addable": true, "client_only": false, "exclusive_group": null, "fields": [], "documents": [], "driver_documents": [] }
    },
    {
      "key": "PV_DEMATERIALISE",
      "stored_key": "PV dématérialisé - 10",
      "name": "PV dématérialisé",
      "price": 10,
      "currency": "EUR",
      "active": false,
      "requirements": {
        "kind": "pv_demat",
        "addable": true,
        "client_only": false,
        "exclusive_group": "pv",
        "fields": [
          { "name": "renter", "required": true, "type": "renter", "choices": [
            { "id": "arval", "name": "ARVAL", "input": "pin", "tool_url": null, "link_optional": false },
            { "id": "ayvens", "name": "AYVENS", "input": "link", "tool_url": "https://welcome.auto", "link_optional": false }
          ] },
          { "name": "link", "required": "when_renter_input_is_link", "type": "url" },
          { "name": "pin", "required": "when_renter_input_is_pin", "type": "string" },
          { "name": "comment", "required": false, "type": "string" }
        ],
        "documents": [],
        "driver_documents": ["PV_DEMAT_COMPLETE"]
      }
    }
  ],
  "renters": [
    { "id": "arval", "name": "ARVAL", "prestations": ["livraison", "restitution", "restitution loueur"], "input": "pin", "tool_url": null, "link_optional": false, "guide_url": null, "guide_name": null },
    { "id": "ayvens", "name": "AYVENS", "prestations": ["livraison", "restitution", "restitution loueur"], "input": "link", "tool_url": "https://welcome.auto", "link_optional": false, "guide_url": null, "guide_name": null }
  ]
}

2. Lire les obligations (`requirements`)

Champ	Sens
`kind`	`standard`, `pv_papier`, `pv_demat`, `check_accessory`, `wgarage`, `rdv`
`addable`	`false` pour une option posée automatiquement (la prise de rendez-vous suit un créneau `need_appointment`)
`client_only`	facturée au client sans part convoyeur
`exclusive_group`	`pv` : un seul type de PV par jambe — ajouter l’un retire l’autre
`fields`	ce que vous devez fournir dans `params` (`renter`, `link`, `pin`, `comment`, `accessories`) ; `required` vaut `true`, `false` ou une condition
`documents`	documents que vous devez fournir (`PV_PAPIER` pour un PV papier) : déjà déposé, recopié (duplication) ou annoncé dans `pending_documents` / `documents.pending`
`driver_documents`	documents que le convoyeur produira pour clore l’option (information)

Les options que votre grille a désactivées ne sont pas rendues — sauf les deux options PV du catalogue (PV_PAPIER et PV_DEMATERIALISE), qui y sont désactivées parce qu’elles ne se cochent pas comme les autres : elles se posent avec le document à faire signer. Elles restent donc listées et acceptées par POST /options et par options.add. Toute autre option désactivée, y compris une option propre à votre compte, reste refusée (option_disabled). Les loueurs proposés pour un PV dématérialisé dépendent de la prestation de la jambe : seuls les partenaires configurés pour cette prestation apparaissent dans choices. input dit ce que vous devez saisir : un lien de session (link) ou un code PIN (pin). Quand link_optional vaut true, le lien de ce loueur est facultatif : vous pouvez l’omettre (le convoyeur ouvre alors l’outil du loueur) ; un lien fourni reste vérifié.

3. Ajouter une option avec ses obligations

curl -s -X POST "$BASE/transports/$TID/options" \
  -H "X-Api-Key: $MED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "option_key": "PV_DEMATERIALISE",
    "leg": "aller",
    "params": { "renter": "ayvens", "link": "welcome.auto/session/42", "comment": "Portail 3" }
  }'

{
  "option": "PV dématérialisé - 10",
  "new_price": 210,
  "delta": 10,
  "leg": "aller",
  "removed": ["PV papier - 10"],
  "derived": ["metadata/type_doc", "metadata/code_pin_arval", "renter", "lien_pv_demat", "options_comments"],
  "warnings": []
}

Une obligation manquante est refusée avant toute écriture :

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Les obligations de cette option ne sont pas couvertes.",
  "code": "requirements_not_met",
  "errors": [{ "field": "renter", "error": "renter_required" }]
}

Codes possibles dans errors[].error : renter_required, renter_not_eligible, link_required, link_invalid, pin_required, accessories_required, accessories_too_many (100 accessoires au plus), accessory_invalid, document_required (avec documents), option_disabled, not_addable. leg: "retour" sur une mission sans trajet retour est refusé en 422 avec code: "no_return_leg" (rien n’est posé) ; un leg autre que aller / retour renvoie 422 avec errors: [{ "field": "leg", "error": "invalid" }]. Même règle pour ?leg= au retrait. Un document annoncé (pending_documents, ou documents.pending en duplication) ne couvre que sa jambe : PV_PAPIER pour l’aller, PV_PAPIER_RETOUR pour le retour.

4. Retirer une option

DELETE /transports/{id}/options/{option_key}?leg=aller|retour retire l’option (toutes ses variantes de prix) et nettoie ses dérivés : retirer un PV dématérialisé efface le lien, le code PIN et le commentaire. Retirer le dernier PV d’une restitution loueur est refusé (409, code: pv_required_for_restitution).

5. Pendant une duplication

Le même contrat s’applique à POST /transports/{id}/duplicate via options.aller.add / options.retour.add et documents.pending : voir Dupliquer une mission. L’aperçu (/preview) valide les obligations et rend les options finales sans rien créer.

Démarrage

Concepts fondamentaux

Guides

Webhooks

1. Lire le catalogue

2. Lire les obligations (`requirements`)

3. Ajouter une option avec ses obligations

4. Retirer une option

5. Pendant une duplication

​1. Lire le catalogue

​2. Lire les obligations (requirements)

​3. Ajouter une option avec ses obligations

​4. Retirer une option

​5. Pendant une duplication

1. Lire le catalogue

2. Lire les obligations (`requirements`)

3. Ajouter une option avec ses obligations

4. Retirer une option

5. Pendant une duplication