Authentification
Authentification
Deux en-têtes sont requis sur chaque requête.
En-têtes
Authorization: Bearer sk_live_...
X-Client-Id: VOTRE_CLIENT_ID
Le Client ID est aussi accepté en paramètre de requête (?clientId=...) ou dans le body, mais l'en-tête est la forme recommandée — la seule qui fonctionne identiquement sur toutes les méthodes. Si la clé et le Client ID n'appartiennent pas au même compte, la réponse est 403 INVALID_CLIENT_ID.
Obtenir vos identifiants
Rendez-vous sur partner.arelpro.com → Paramètres → Développeur.
- Votre Client ID y est affiché en permanence.
- La clé API complète n'est affichée qu'une seule fois, à sa création. Elle est stockée hashée (SHA-256) : personne, pas même le support Arel, ne peut vous la relire. Perdue = à révoquer puis recréer.
- Maximum 10 clés actives par compte.
La création de clé passe nécessairement par le dashboard (session navigateur) : c'est l'étape d'amorçage, comme chez la plupart des fournisseurs.
Permissions (scopes)
Le scope requis est déduit de la méthode HTTP, jamais de l'endpoint.
| Méthode HTTP | Scope requis |
|---|---|
GET | read |
POST, PUT, PATCH | write |
DELETE | delete |
Défaut à la création d'une clé : ["read", "write"]. Ce défaut couvre la création de bordereaux, l'annulation, les liens PDF et la gestion des webhooks — sauf leur suppression.
Scope delete requis pour DELETE
Le scope delete n'est pas inclus dans le défaut. Une clé par défaut reçoit 403 INSUFFICIENT_PERMISSIONS sur DELETE /webhooks/:id — le seul DELETE de l'API. Demandez explicitement les trois scopes à la création de la clé, dans le dashboard.
Alternative sans delete : PUT /webhooks/:id avec {"isActive": false} désactive un webhook (scope write).
Attention : le scope se déduit de la méthode, donc des lectures de forme POST exigent write — POST /rates (devis), /pdf/export, /view-link, /download-link. Une clé strictement ["read"] ne peut pas demander un tarif.
Limites de débit
60
par minute
1 000
par heure
10 000
par jour
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1768588800
Ces en-têtes décrivent la fenêtre minute uniquement. X-RateLimit-Reset est un timestamp Unix en secondes. En cas de dépassement : 429, avec un champ window indiquant la fenêtre saturée (minute, hour ou day).
HTTP 429 : erreur transitoire
Un 429 indique un quota atteint, non une requête invalide. Traitez-le comme un 5xx : réessayez, et sur POST /shipping rejouez la même clé d'idempotence.
Le corps d'un 429 ne porte aucun slug error — seulement { success, message, window }. Un client qui ne reconnaît que les slugs et les 5xx laisse donc le 429 aboutir à un échec définitif. Traitez le 429 avant de lire error, comme pour un 5xx.
Délai d'attente. Il n'y a pas d'en-tête Retry-After. X-RateLimit-Reset est émis y compris sur la réponse 429, mais il ne décrit que la fenêtre minute. Sur un 429 window: "hour" ou "day", il sous-estime l'attente : lisez window d'abord, et ne l'honorez que sur "minute". Sur hour / day, remettez la commande dans votre file plutôt que de boucler — la clé stockée garantit que le rejeu ne créera pas de doublon.