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

  1. Le commerçant active votre société dans Yaqin (Expédition → Paramètres → Transporteurs) et ajoute son numéro de compte chez vous.
  2. 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.
  3. Vous l'acceptez avec votre numéro de suivi et le lien de l'étiquette (ou le refusez avec un motif).
  4. Vous envoyez chaque changement de statut : enlevé, en transit, en cours de livraison, tentative échouée, livré avec preuve de livraison.
  5. 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

  1. Demandez un compte : depuis la page Contact (sujet : Partenariat), envoyez le nom de la société, les pays, les services et le contact.
  2. Identifiants de test : nous vous envoyons un client_id et un client_secret pour l'environnement de test ; vous ne voyez que les envois des sociétés de test.
  3. 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.
  4. Développez votre connexion : utilisez la référence complète (OpenAPI 3) ; vous pouvez recevoir des webhooks au lieu d'interroger l'API.
  5. 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

CodeSignification
PICKUP_SCHEDULEDEnlèvement planifié
PICKUP_FAILEDEnlèvement échoué
PICKED_UPEnlevé chez le commerçant
AT_HUBAu centre de tri
IN_TRANSITEn transit
OUT_FOR_DELIVERYEn cours de livraison
DELIVERY_ATTEMPT_FAILEDTentative de livraison échouée (motif)
ON_HOLDEn attente
DELIVEREDLivré (avec preuve de livraison)
RETURN_IN_TRANSITRetour en cours vers le commerçant
RETURNEDRetourné au commerçant
LOSTPerdu
DAMAGEDEndommagé

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-Key unique 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.created et shipment.cancelled, signés dans X-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