API Yaqin pour les transporteurs
Connectez votre société de livraison à Yaqin une seule fois : vous recevez les envois de tous les commerçants qui vous activent, et les statuts leur reviennent automatiquement.
Pour qui ?
Les sociétés de transport et de livraison (nationales, internationales, le jour même, paiement à la livraison) qui veulent recevoir les envois des commerçants utilisant Yaqin en Arabie saoudite, en Égypte et dans la région, sans connecter chaque commerçant un par un.
Fonctionnement
- Le commerçant active votre société dans Yaqin (Expédition → Paramètres → Transporteurs) et ajoute son numéro de compte chez vous.
- En expédiant une commande, il clique sur « Envoyer à … » : l'envoi apparaît chez vous comme « nouveau », avec expéditeur, destinataire (avec position sur la carte), colis et montant à encaisser.
- Vous l'acceptez avec votre numéro de suivi et le lien de l'étiquette (ou le refusez avec un motif).
- Vous envoyez chaque changement de statut : enlevé, en transit, en cours de livraison, tentative échouée, livré avec preuve de livraison.
- Quand vous reversez l'argent encaissé aux commerçants, vous déclarez le versement et le commerçant le voit sur ses envois.
Se connecter
- Demandez un compte : depuis la page Contact (sujet : Partenariat), envoyez le nom de la société, les pays, les services et le contact.
- Identifiants de test : nous vous envoyons un
client_idet unclient_secretpour l'environnement de test ; vous ne voyez que les envois des sociétés de test. - Essayez dans Postman : téléchargez la collection et l'environnement, collez les identifiants, puis lancez les requêtes dans l'ordre. La collection se connecte toute seule.
- Développez votre connexion : utilisez la référence complète (OpenAPI 3) ; vous pouvez recevoir des webhooks au lieu d'interroger l'API.
- Mise en production : après vérification, nous passons votre compte en production et envoyons les identifiants réels ; les commerçants de vos pays voient alors votre nom.
Exemple rapide
1) Obtenir un jeton (valable une heure) :
curl -X POST https://app.yaqinerp.com/api/shipping/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{"grant_type":"client_credentials","client_id":"yq_test_…","client_secret":"yqs_…"}'2) Nouveaux envois :
curl "https://app.yaqinerp.com/api/shipping/v1/shipments?state=new" \ -H "Authorization: Bearer $TOKEN"
3) Accepter un envoi :
curl -X POST https://app.yaqinerp.com/api/shipping/v1/shipments/shp_3f9a0c1b2d4e5f60/accept \
-H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"tracking_number":"FX100234","label_url":"https://…/FX100234.pdf"}'4) Envoyer un statut :
curl -X POST https://app.yaqinerp.com/api/shipping/v1/shipments/shp_3f9a0c1b2d4e5f60/events \
-H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"status":"DELIVERED","proof_of_delivery":{"receiver_name":"Mohammed"}}'Statuts
| Code | Signification |
|---|---|
| PICKUP_SCHEDULED | Enlèvement planifié |
| PICKUP_FAILED | Enlèvement échoué |
| PICKED_UP | Enlevé chez le commerçant |
| AT_HUB | Au centre de tri |
| IN_TRANSIT | En transit |
| OUT_FOR_DELIVERY | En cours de livraison |
| DELIVERY_ATTEMPT_FAILED | Tentative de livraison échouée (motif) |
| ON_HOLD | En attente |
| DELIVERED | Livré (avec preuve de livraison) |
| RETURN_IN_TRANSIT | Retour en cours vers le commerçant |
| RETURNED | Retourné au commerçant |
| LOST | Perdu |
| DAMAGED | Endommagé |
Règles
- JSON partout ; dates au format ISO 8601 avec fuseau horaire.
- Envoyez
Authorization: Bearer <access_token>à chaque appel ; demandez un nouveau jeton à l'expiration. - Envoyez une
Idempotency-Keyunique avec chaque POST : une nouvelle tentative n'exécute jamais deux fois. - 120 appels par minute et par client ; les listes sont paginées avec
next_cursor. - Erreurs au format
{"error": {"code", "message", "details"}}avec 400, 401, 403, 404, 409, 422, 429. - Webhooks (optionnels) : nous envoyons
shipment.createdetshipment.cancelled, signés dansX-Yaqin-Signature(HMAC-SHA256).
Liens
Prêt à vous connecter ?
Envoyez-nous votre demande : nous envoyons les identifiants de test sous un jour ouvré.
Demander un compte de test