D’une clé Sandbox à un retour terminé

Commencez par le démarrage rapide de l’API. Utilisez un projet Sandbox dédié pour ces recettes. Alkax enregistre l’avancement physique des livraisons et retours. Votre système commercial gère les remboursements, les stocks, les échanges et les avoirs clients.

Identifiants et environnements

L’hôte de l’API est https://api.alkax.io. Le choix entre Sandbox et Production dépend de l’environnement de l’identifiant, pas d’un chemin d’URL. Ne placez jamais une clé développeur dans du code navigateur ou mobile. Le jeton d’accès d’un compte Alkax est différent d’un identifiant X-Alkax-Key.

Opération	Portée
Créer une expédition ou un retour de référence	delivery:create
Lire l’état privé d’une expédition ou d’un retour	delivery:read
Envoyer des événements de livraison/retour ; enregistrer la réception d’un dépôt	delivery:events
Envoyer une preuve ou des fichiers de preuve de retour	delivery:proof
Confirmer une adresse, approuver/rejeter/annuler un retour de référence, accéder à la collecte, résoudre un RTS	delivery:write

Une intégration complète des livraisons et retours nécessite les portées des opérations qu’elle effectue. Le renouvellement conserve les portées de la clé précédente : émettre une nouvelle clé ne change donc pas les autorisations. L’absence de portée de preuve peut empêcher la réussite de l’événement de finalisation qui en dépend. Copiez uniquement la clé brute. Consultez le dépannage.

Cycle de vie de la livraison initiale

Après la confirmation d’adresse, utilisez l’instantané confirmé immuable comme destination dans POST /api/v1/deliveries. Fournissez un Idempotency-Key et un activationEventId stable. La création renvoie id, trackingNumber et l’état. Ne supposez pas que la référence de commande externe est un numéro de suivi Alkax.

Envoyez POST /api/v1/deliveries/{id}/events avec un UUID eventId stable, un horodatage occurredAt réel et l’une de ces commandes :

Commande	Résultat
MarkInTransit	InTransit
MarkAtLocalDepot	AtLocalDepot
MarkOutForDelivery	OutForDelivery
RecordDeliveryAttempt	DeliveryAttempted
CompleteDelivery	Delivered

Réessayez avec exactement le même événement après une erreur de transport. Une réponse 409 exige d’examiner l’état de référence ; n’inventez pas un nouvel identifiant pour contourner les contrôles de conflit. Les horodatages situés à plus de cinq minutes dans le futur sont rejetés. Les identifiants d’événement sont distincts des identifiants de requête utilisés pour le diagnostic. Ne vous fiez pas aux phrases d’erreur localisées.

Pour la preuve de livraison initiale, appelez d’abord POST /api/v1/deliveries/{id}/proofs avec un proofId stable, method, occurredAt et les champs requis de destinataire/référence. Transmettez ce proofId à CompleteDelivery. Envoyez la preuve avant l’événement qui en dépend. La preuve doit appartenir à la même expédition et au même environnement ; la preuve de retour obéit à un contrat distinct.

Accès du destinataire

Le suivi anonyme ne montre qu’un avancement général. Un numéro de suivi n’autorise ni le rattachement à un compte, ni les demandes de retour, ni l’accès aux instructions privées ou aux preuves. Le rattachement au compte vérifie le contact du destinataire. La correspondance avec une adresse e-mail non vérifiée n’est pas un mécanisme d’autorisation. Le contact de confirmation d’adresse n’est pas automatiquement celui du destinataire de l’expédition de référence.

Un destinataire lié peut demander un retour uniquement après le passage de l’expédition à Delivered. Dans Mes livraisons, choisissez la collecte ou le dépôt et indiquez un motif. La demande reste en attente jusqu’à son approbation ou son rejet. Un dépôt approuvé exige encore l’enregistrement de la réception physique. Une seule demande est prise en charge par colis initial et les décisions sont définitives.

Autorisation de retour par le commerçant

POST /api/v1/returns accepte originalShipmentId, eventId, type, reason, destination, éventuellement origin et des instructions, ainsi que les exigences de preuve de collecte/réception. Utilisez type: RecipientReturn, reason: RecipientChangedMind pour le parcours client minimal. Un retour client exige une expédition initiale à l’état Delivered. Si l’origine est omise, elle provient de l’instantané de la livraison initiale, pas d’une recherche d’adresse modifiable.

L’autorisation est distincte de la logistique. Les retours clients demandés nécessitent POST /api/v1/returns/{id}/approve?eventId={uuid}. Le rejet et l’annulation utilisent la même convention d’identifiant en paramètre de requête. L’annulation n’est possible qu’avant la remise physique. Un retour approuvé commence à AwaitingHandover ; l’approbation seule ne planifie pas de coursier.

Confirmer la collecte et envoyer la preuve de retour

1. Appelez POST /api/v1/returns/{id}/pickup-confirmation avec delivery:write.
2. Transmettez l’URL destinataire renvoyée de manière sécurisée. L’émission d’un lien de remplacement révoque le précédent s’il n’a pas été finalisé. Ne journalisez pas son jeton et ne l’exposez pas dans le suivi public.
3. Le destinataire vérifie ou corrige la collecte dans le parcours public avec jeton. L’instantané confirmé reste distinct de la destination initiale.
4. Si une preuve est requise, recueillez une véritable signature ou photo PNG. Téléversez-la via PUT /api/v1/returns/{id}/proof-assets/{proofId}/signature (ou /photo) avec { "dataUrl": "data:image/png;base64,..." }. Maximum : 2 Mo, 2048 × 2048 pixels.
5. Utilisez la reference renvoyée dans POST /api/v1/returns/{id}/proofs avec le même proofId, purpose: Pickup ou Receipt, la méthode et l’horodatage. Les méthodes de signature exigent des informations sur la personne qui reçoit. Un texte arbitraire ou une URL du commerçant ne remplace pas valablement un fichier de retour téléversé.
6. Incluez cet identifiant de preuve dans l’événement de remise ou de finalisation correspondant.

Les nouvelles tentatives de téléversement doivent utiliser des octets identiques. La preuve de collecte d’un retour ne peut pas satisfaire son exigence de réception, et aucune des deux ne peut réutiliser la preuve de livraison initiale. La lecture comme l’écriture des fichiers privés exigent delivery:proof et un projet/environnement correspondant.

Logistique des retours et RTS après échec de livraison

Envoyez les événements de retour avec des identifiants stables à /api/v1/returns/{id}/events : SchedulePickup, MarkPickedUp, MarkAtReturnHub, MarkInTransit, Complete. Complete produit DeliveredToMerchant pour un retour client et ReturnedToSender pour un échec de livraison. RecordException enregistre une anomalie logistique ; il n’autorise pas à réécrire l’historique.

Pour une expédition DeliveryAttempted, appelez POST /api/v1/deliveries/{id}/resolution avec un evaluationId stable, un failureReason normalisé, un attemptCount positif et une returnDestination confirmée lorsque le retour à l’expéditeur (RTS) est possible. La politique documentée choisit le RTS en cas de refus, de destinataire indisponible après trois tentatives ou de problème de paiement après deux tentatives. Les problèmes d’adresse exigent une correction ; les échecs inconnus sont soumis à un examen manuel. Les éléments normalisés répétés sont dédupliqués. Ne transmettez pas le texte brut d’échec du transporteur comme motif de référence.

Les lectures privées des retours utilisent /api/v1/returns/{id} ou /by-tracking/{trackingNumber}. La route anonyme /api/public/returns/{trackingNumber} omet les contacts, la localisation précise, les instructions et les preuves.

Responsabilités et limites de confiance

Merchant server -- scoped environment key --> Alkax API
Recipient      -- expiring capability ----> Confirm address / pickup
Recipient      -- verified account -------> Linked delivery / return request
Public viewer  -- tracking number --------> Coarse progress only
Alkax webhook  -- signed raw body --------> Merchant webhook receiver
Merchant system -- own business policy ---> Refund / inventory system

Sandbox et Production disposent d’identifiants, de ressources et d’abonnements webhook distincts. Un webhook ne transfère aucune permission vers un autre environnement. Consultez les recettes de webhooks et la liste de contrôle de mise en production.

Utilisez la matrice de tests Sandbox pour les cas de correction, d’expiration, de rejet, de mauvaise portée et de rejeu.