Créer un OTR

Description

Crée un ordre de transport au statut create. Il devient visible du transporteur une fois validé (voir Valider des OTR).

Clé API expéditeur dans l'en-tête X-API-KEY (ou Authorization: Bearer).

Pour rejouer une requête sans risque de doublon, envoyez un en-tête Idempotency-Key unique : la même clé renvoie la même réponse.

Corps de la requête (JSON)

Champ	Type	Obligatoire	Description
matchcode	string	Oui*	Code du client destinataire dans votre carnet d'adresses
client_id	int	Oui*	Identifiant du client destinataire (alternative au matchcode)
carrier_id	int	Oui	Identifiant du transporteur : un de vos partenaires, avec un abonnement actif
pickup_date	string	Oui	Date d'enlèvement (ISO 8601 ou AAAA-MM-JJTHH:MM), aujourd'hui ou plus tard
delivery_date	string	Oui	Date de livraison prévue, au moins un jour ouvré après l'enlèvement
units	array	Oui	Unités à transporter (au moins une)
packaging	array	Non	Emballages consignés
pickup_name	string	Non	Nom du lieu d'enlèvement (sinon, l'adresse de votre société)
pickup_street	string	Non	Rue
pickup_zip	string	Non	Code postal
pickup_city	string	Non	Ville
pickup_country	string	Non	Pays (code ISO, ex. CH)
pickup_phone	string	Non	Téléphone
delivery_name	string	Non	Nom du lieu de livraison (sinon, l'adresse du client)
delivery_street	string	Non	Rue
delivery_zip	string	Non	Code postal
delivery_city	string	Non	Ville
delivery_country	string	Non	Pays (code ISO, ex. CH)
delivery_phone	string	Non	Téléphone
reference1	string	Non	Votre référence 1
reference2	string	Non	Votre référence 2
temperature_zone	string	Non	Zone de température
delivery_time	string	Non	Heure ou créneau (ex. 08:00 - 12:00, 10:00)
delivery_slot	string	Non	day, morning, afternoon ou fixed
default_instructions	string	Non	Instructions habituelles
instructions	string	Non	Instructions propres à cet OTR
notes	string	Non	Notes

* matchcode ou client_id. Les dates tombant un samedi ou un dimanche sont acceptées, avec un avertissement.

Format des unités et des emballages

Champ	Type	Description
units[].type_unit	string	Type d'unité (ex. palette, colis)
units[].quantity	int	Quantité (1 par défaut)
units[].description	string	Description
units[].weight	number	Poids unitaire en kg
units[].length / width / height	number	Dimensions en cm
units[].volume_cm3	number	Volume en cm³
packaging[].packaging_id	int	Identifiant de l'emballage consigné (voir Emballages dans Shippinova)
packaging[].quantity	int	Quantité

Exemple de requête

curl -X POST "https://shippinova.com/APIs/external/api_create_otr.php" \
  -H "X-API-KEY: votre_cle_api" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-48213" \
  -d '{
    "matchcode": "CLIENT123",
    "carrier_id": 2,
    "pickup_date": "2026-01-22T09:00",
    "delivery_date": "2026-01-23T09:00",
    "units": [ { "type_unit": "palette", "quantity": 2, "description": "Palettes EUR", "weight": 500 } ],
    "packaging": [ { "packaging_id": 1, "quantity": 3 } ],
    "reference1": "REF-OTR-001",
    "delivery_slot": "morning"
  }'

Réponse (succès)

{
  "success": true,
  "otr_id": 123,
  "otr_number": "OTR-20260122-093000-A1B2C3",
  "warnings": [
    "delivery_date is on a weekend (Saturday or Sunday)"
  ]
}

warnings n'est présent que si une date tombe un week-end.

Codes d'erreur

Code	Signification
401	Clé API absente
403	Clé invalide, ou clé transporteur utilisée sur un endpoint expéditeur
400	Champ manquant ou invalide (dates, unités…) : code vaut VALIDATION_ERROR, le détail est dans field_errors
422	Transporteur qui n'est pas votre partenaire ou sans abonnement actif (CARRIER_NOT_ALLOWED), client inconnu (CLIENT_NOT_FOUND)
429	Trop de requêtes (120 par minute, 20 000 par jour) ; réessayer après le délai Retry-After