Démarrage rapide

Prérequis

Deux se configurent une seule fois depuis le dashboard ; le troisième se configure par API.

Trois prérequis obligatoires

Aucun appel à POST /shipping n'aboutira tant que le compte n'a pas les trois éléments suivants : un type de client, un contrat commercial accepté, et une adresse d'enlèvement configurée sur le compte.

Les deux premiers se règlent au dashboard : accepter un contrat engage juridiquement. Le troisième se configure par API via PUT /shipping/pickup-address — votre intégration peut donc le corriger seule, sans intervention manuelle. Sans adresse d'enlèvement, la création échoue même si le contrat est signé.

Réponses en cas de prérequis manquant

Chaque prérequis manquant produit un slug stable en 403. Deux exigent une action humaine au dashboard ; l'adresse d'enlèvement peut être corrigée par API.

Manquant	Réponse de POST /shipping	Action
Type de client	`403 CLIENT_TYPE_REQUIRED`	Dashboard uniquement
Contrat accepté	`403 CONTRACT_SIGNATURE_REQUIRED`	Dashboard uniquement
Adresse d'enlèvement	`403 PICKUP_ADDRESS_REQUIRED`	Par API — `PUT /shipping/pickup-address` ou dashboard
Compte suspendu (défaut de paiement)	`403 ACCOUNT_SUSPENDED`	Régularisation via le dashboard

Détection côté client et à la création

Chaque blocage se lit en amont sur GET /account et se signale à la création par un 403 + un slug stable. Sur ces trois cas, le message n'est pas nécessaire pour identifier ce qui manque.

Détecter les trois par programme

Appelez GET /account au démarrage et lisez contractStatus, pickupAddressConfigured et accountStatus avant toute création.

bash

curl -X GET "https://api.arelpro.com/pro/api/v1/account" \
  -H "Authorization: Bearer sk_live_VOTRE_CLE" \
  -H "X-Client-Id: VOTRE_CLIENT_ID"

json

{
  "success": true,
  "account": {
    "id": "664a...",
    "clientId": "VOTRE_CLIENT_ID",
    "company": "Ma Boutique",
    "email": "contact@ma-boutique.fr",
    "accountStatus": "active",
    "paymentStatus": "current",
    "contractStatus": {
      "clientType": null,
      "signed": false,
      "contractVersion": null,
      "currentVersion": "2026-05-03",
      "acceptedAt": null,
      "code": "CLIENT_TYPE_REQUIRED",
      "message": "Veuillez choisir votre type de client et accepter le contrat..."
    },
    "pickupAddress": null,
    "pickupAddressConfigured": false,
    "wallet": { "balance": 42.5, "currency": "EUR" },
    "paymentType": "deferred",
    "creditLimit": 2000,
    "minimumPrice": 7,
    "pricePerKg": null,
    "timeSlots": []
  }
}

Prêt à créer si contractStatus.signed === true, pickupAddressConfigured === true et accountStatus !== "suspended". Ces conditions sont indépendantes ; tester uniquement signed est insuffisant.

Utilisez pickupAddressConfigured

Ce booléen reprend le prédicat exact de la garde de POST /shipping : les deux restent alignés. N'écrivez pas votre propre test sur street/city — il se désynchroniserait si la garde évolue.

pickupAddress vaut null lorsque l'adresse est inexploitable — jamais un objet vide. Vous pouvez aussi tester pickupAddress !== null : les deux champs sont cohérents par construction.

Si signed est faux, contractStatus.code contient le slug exact que POST /shipping renverrait : /account rejoue la même garde que la création.

Attention : ne traitez pas contractVersion !== currentVersion comme un blocage — une signature sur une version antérieure reste valide. Branchez uniquement sur signed.

wallet peut valoir null si la lecture du portefeuille échoue ; /account reste alors joignable et le reste du corps est intact. Ne présumez pas que wallet.balance existe toujours.

Portefeuille : lecture par API, recharge via le dashboard

Le choix de paymentType détermine si une intégration serveur peut se bloquer. GET /account renvoie wallet.balance. En revanche, aucun endpoint de l'API v1 ne recharge le portefeuille : le paiement passe par Stripe et son authentification 3-D Secure, qui exige un navigateur. Une recharge est donc une action de dashboard.

paymentType	À la création
`deferred` — recommandé	Aucun contrôle de solde. Vous êtes facturé périodiquement, dans la limite de `creditLimit`. C'est le défaut.
`credit`	Le solde doit couvrir `minimumPrice`, sinon 403 INSUFFICIENT_BALANCE.

En credit, une intégration serveur qui reçoit INSUFFICIENT_BALANCE n'a aucun recours programmatique : elle ne peut ni recharger, ni réessayer utilement — elle s'arrête jusqu'à une recharge manuelle. Pour une intégration serveur, préférez deferred ; à défaut, surveillez wallet.balance et alertez un opérateur avant que le solde soit insuffisant.

Signature du contrat

Choisir un type de client et accepter le contrat ne sont pas disponibles via l'API : accepter un contrat engage juridiquement et doit être le fait d'une personne. Ces deux actions se font une seule fois, depuis partner.arelpro.com.

Il n'existe pas d'endpoint POST /contract/accept. Si votre intégration reçoit CLIENT_TYPE_REQUIRED ou CONTRACT_SIGNATURE_REQUIRED, la conduite correcte est de remonter l'alerte à un opérateur ; aucun réessai ne la résoudra.

Adresse d'enlèvement configurable par API

Elle n'engage rien juridiquement. PUT /shipping/pickup-address la configure et lève PICKUP_ADDRESS_REQUIRED.

Elle doit être géocodée : ce n'est pas le texte de la rue qui sert à chercher un livreur, c'est un point GPS. L'API s'en charge à partir de l'adresse envoyée ; vous pouvez aussi fournir le point via coordinates. Le résultat se lit dans pickupAddress.location sur GET /account.

Le dashboard (partner.arelpro.com → Paramètres) reste disponible pour la configurer manuellement. Les deux voies écrivent au même endroit.

Parcours complet

1DashboardAcceptez le contrat, choisissez le type de client, créez une clé API et notez votre Client ID.
2GET /accountVérifiez contractStatus.signed === true, pickupAddressConfigured === true, et votre solde.
3PUT /shipping/pickup-addressSi pickupAddressConfigured est false : configurez l'adresse d'enlèvement. Une seule fois, depuis votre code.
4POST /ratesAffichez un prix à votre client (facultatif).
5POST /shippingCréez le bordereau avec un en-tête X-Idempotency-Key. Acceptez 200 ou 201.
6POST /shipping/:id/download-linkRécupérez le PDF, imprimez-le et apposez l'étiquette sur le colis.
7POST /webhooksAbonnez-vous à shipping.delivered pour clore la commande.

Vérifier vos identifiants