# POST /partner/dispatch/shipments

Ouvrir une commande B2B pour un distributeur, rejouable sur la référence de commande. Droit dispatch:write.

Source : https://docs.sealtrust.io/reference/post-partner-dispatch-shipments/

---

Vous ouvrez une commande B2B : la référence de commande de votre ERP ou de
votre logisticien, et le distributeur qui la reçoit. Les unités s'y ajoutent
ensuite, au fil de la préparation. Le parcours complet est dans le guide [Rattacher chaque unité à sa commande](/expedition-b2b/).

L'adresse complète est `https://api.sealtrust.io/v1/partner/dispatch/shipments`.

Cet appel est rejouable. La même `order_ref` renvoie la même expédition, avec
le code 200 et `created` à `false`. La même `order_ref` pour un autre
distributeur est refusée en 409 : nous ne réécrivons jamais où des unités sont
parties.

## Autorisation

Clef d'API dans l'en-tête `Authorization`, au format `Bearer`, avec le droit
`dispatch:write`. Une clef sans ce droit reçoit un 403 dont le message nomme le
droit manquant. L'offre de la marque de la clef doit comprendre l'accès API, et
la marque de l'expédition doit être sur l'offre Conformité + Identité.

```http
Authorization: Bearer votre_clef
```

## Plafond d'appels

Le même que les autres routes partenaires : un compteur par clef et un compteur
pour la somme des clefs de votre marque, 120 appels par fenêtre de 60 secondes
par défaut. Chaque appel qui écrit prélève 1 unité du quota journalier de la
clef, quel que soit le nombre d'unités qu'il porte.

## Corps de la requête

Format `application/json`. Tout champ inconnu fait refuser la requête en 422.

| Nom | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `order_ref` | `string` | oui | Votre numéro de commande, 1 à 100 caractères. Unique dans votre marque. |
| `distributor_code` | `string` | oui | Le code du distributeur, un point de vente actif de type « Distributeur ». |
| `ship_date` | `string` | non | Date d'expédition, au format `AAAA-MM-JJ`. |
| `ship_to_country` | `string` | non | Pays de livraison, code ISO à deux lettres. Absent, c'est le pays du distributeur. |
| `brand_code` | `string` | non | Avec une clef revendeur, le code public d'une de vos marques clientes. Absent, c'est la marque de la clef. |

Le territoire vérifié par l'alerte est celui du distributeur, jamais
`ship_to_country`, qui n'est qu'informatif.

## Requête d'exemple

```bash
curl -i -X POST "https://api.sealtrust.io/v1/partner/dispatch/shipments" \
  -H "Authorization: Bearer st_live_0000000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"order_ref": "SO-2026-1042", "distributor_code": "DIST-DE", "ship_date": "2026-10-09"}'
```

## Réponse d'exemple

Code HTTP 201 à la création, 200 quand la commande existait déjà.

```json
{
  "id": 318,
  "brand_id": 42,
  "order_ref": "SO-2026-1042",
  "status": "open",
  "ship_date": "2026-10-09",
  "ship_to_country": "DE",
  "distributor": {
    "id": 77,
    "code": "DIST-DE",
    "name": "Acme Distribution GmbH",
    "country": "DE",
    "territory_countries": ["DE", "AT"]
  },
  "units_allocated": 0,
  "created_by": "api-key:st_live_000",
  "created_at": "2026-10-09T07:12:44.120391+00:00",
  "closed_at": null,
  "created": true
}
```

## Erreurs

| Code | Condition | Que faire |
| --- | --- | --- |
| 401 | Clef absente, mal formée ou inconnue. | Envoyez `Authorization: Bearer <votre clef>` avec la clef entière. |
| 403 | La clef n'a pas le droit `dispatch:write`. Message `Missing required scopes: dispatch:write`. | Créez une clef qui porte ce droit. |
| 403 | La marque est sur l'offre Conformité. `detail.code` vaut `OFFER_EXCLUDES_IDENTITY` et `detail.feature` vaut `dispatch`. Rien n'est enregistré. | Passez à l'offre Conformité + Identité. Réessayer ne changera rien. |
| 429 | Plafond de débit ou quota journalier atteint. | Attendez le nombre de secondes de `Retry-After`, ou minuit en temps universel pour le quota. |
| 404 | Aucun distributeur actif de votre marque ne porte ce code. `detail.code` vaut `distributor_not_found`. | Créez le distributeur dans la console, onglet Points de vente. |
| 409 | Cette `order_ref` existe déjà pour un autre distributeur. `detail.code` vaut `order_ref_other_distributor`. | Vérifiez la référence de commande. |
| 422 | Le point de vente existe mais n'est pas de type distributeur (`retailer_is_not_a_distributor`), ou le corps est invalide : un caractère de contrôle, ou une `order_ref` qui commence par `=`, `+`, `-` ou `@`, qu'un tableur exécuterait comme une formule. | Changez son type dans la console, ou corrigez le corps. |