Intégrer Livraison Facile dans un site e-commerce

Authentification

Chaque partenaire dispose d’une clé API privée. La clé se transmet côté serveur via X-LF-API-Key ou Authorization: Bearer. Elle ne doit pas être exposée dans du JavaScript public.

La génération des clés est réservée à l’administration Livraison Facile. Pour obtenir une clé, remplissez le formulaire de demande avec le nom du site et les domaines autorisés.

Créer un lien de préremplissage

Endpoint recommandé pour démarrer : le site marchand envoie les informations connues, reçoit une URL courte vers /creer, puis laisse le client vérifier et compléter la consigne.

curl -X POST https://www.livraison-facile.fr/api/v1/prefills \
  -H "Content-Type: application/json" \
  -H "X-LF-API-Key: lf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "order_reference": "CMD-2026-001",
    "return_url": "https://boutique.example/commande/CMD-2026-001",
    "recipient_name": "Marie Dupont",
    "delivery_address": "15 Rue des Lilas, 75019 Paris",
    "delivery_address_postcode": "75019",
    "delivery_address_city": "Paris",
    "access_pin": "4826"
  }'

{
  "success": true,
  "prefill_token": "6d7e...",
  "create_url": "https://www.livraison-facile.fr/creer?prefill=6d7e...",
  "expires_at": "2026-05-31T18:30:00+02:00",
  "pin_required": true
}

Créer une consigne directement

Endpoint serveur à serveur pour les parcours maîtrisés. delivery_address et delivery_notes sont obligatoires. La réponse fournit aussi qr_url, une page prête à afficher, imprimer ou télécharger.

curl -X POST https://www.livraison-facile.fr/api/v1/consignes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "order_reference": "CMD-2026-001",
    "return_url": "https://boutique.example/commande/CMD-2026-001",
    "delivery_address": "15 Rue des Lilas, 75019 Paris",
    "gate_access_code": "#2458#",
    "door_access_code": "2580A",
    "intercom_access_code": "DUPONT",
    "building_access": "Entrée secondaire après le portail",
    "delivery_point": "3e étage, porte droite",
    "delivery_notes": "Déposer devant la porte, ne pas sonner.",
    "delivery_flags": ["do_not_ring", "call_on_arrival", "drop_authorized"],
    "validity_minutes": 0,
    "access_pin": "4826"
  }'

{
  "success": true,
  "code": "HGDF354F",
  "url": "https://www.livraison-facile.fr/c/hgdf354f",
  "qr_url": "https://www.livraison-facile.fr/qr/hgdf354f",
  "qr_api_url": "https://www.livraison-facile.fr/api/v1/consignes/hgdf354f/qr",
  "expires_at": null,
  "never_expires": true,
  "pin_required": true,
  "delivery_flags": ["do_not_ring", "call_on_arrival", "drop_authorized"]
}

Un code PIN temporaire par boutique et par livraison

Pour une consigne créée et administrée par un particulier, ne remplacez pas son code PIN principal. Le client vous autorise d’abord depuis son espace Livraison Facile. Votre clé API peut ensuite préparer un accès pour une commande et l’activer au départ du livreur.

Plusieurs boutiques peuvent posséder des codes PIN valides en même temps. Chaque boutique ne voit, ne renouvelle et ne révoque que ses propres accès. Une rotation invalide immédiatement l’ancien code PIN de cette livraison, sans modifier ceux des autres entreprises.

# 1. Préparer un accès pour une commande
curl -X POST https://www.livraison-facile.fr/api/v1/delivery-accesses \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-CMD-2026-001-creation" \
  -d '{
    "consigne_code": "QJJS6RCT",
    "order_reference": "CMD-2026-001",
    "validity_minutes": 1440,
    "max_validations": 3
  }'

# 2. Au départ du livreur, générer le code PIN
curl -X POST https://www.livraison-facile.fr/api/v1/delivery-accesses/01K.../activate \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: commande-CMD-2026-001-activation"

{
  "success": true,
  "data": {
    "access_id": "01K...",
    "consigne_code": "QJJS6RCT",
    "order_reference": "CMD-2026-001",
    "status": "active",
    "expires_at": "2026-08-16T10:42:18+02:00",
    "access_pin": "482913",
    "pin_displayed_once": true
  },
  "message": "Conservez ce code PIN maintenant : il ne pourra pas être récupéré plus tard."
}

# Remplacer uniquement le code PIN de cette livraison
curl -X POST https://www.livraison-facile.fr/api/v1/delivery-accesses/01K.../rotate-pin \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: commande-CMD-2026-001-rotation-2"

# Révoquer immédiatement cet accès
curl -X DELETE https://www.livraison-facile.fr/api/v1/delivery-accesses/01K... \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Affichage unique : le code PIN temporaire n’est présent que dans la première réponse d’activation ou de rotation. Chaque opération de création, d’activation ou de rotation exige un en-tête Idempotency-Key de 16 à 128 caractères.

Récupérer le QR code par API

Utilisez qr_api_url avec la même clé API. Le endpoint renvoie directement une image PNG et vérifie que la consigne appartient au partenaire et qu’elle est encore active. Le header X-LF-Pin-Required indique si la lecture demandera un code PIN.

curl https://www.livraison-facile.fr/api/v1/consignes/HGDF354F/qr \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  --output consigne-HGDF354F-qr.png

Ajouter, remplacer ou retirer un code PIN

Le partenaire propriétaire de la consigne peut activer la protection après la création avec PUT, ou la retirer avec DELETE. Le code PIN brut n’est jamais renvoyé. Une modification du code PIN invalide automatiquement les sessions de lecture précédemment autorisées.

# Définir ou remplacer le code PIN
curl -X PUT https://www.livraison-facile.fr/api/v1/consignes/HGDF354F/pin \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"access_pin":"4826"}'

# Retirer la protection par code PIN
curl -X DELETE https://www.livraison-facile.fr/api/v1/consignes/HGDF354F/pin \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Suivre la consultation et les validations du code PIN

Le partenaire propriétaire peut savoir si la fiche a été consultée, récupérer les dates de première et dernière consultation et détecter une nouvelle validation réussie du code PIN grâce à pin_validations_count. La réponse ne divulgue ni le code PIN, ni l’adresse IP du lecteur, ni le contenu privé de la consigne.

curl https://www.livraison-facile.fr/api/v1/consignes/HGDF354F/status \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "success": true,
  "code": "HGDF354F",
  "status": "active",
  "is_active": true,
  "consulted": true,
  "first_viewed_at": "2026-08-13T20:45:12+02:00",
  "last_viewed_at": "2026-08-13T20:45:12+02:00",
  "views_count": 1,
  "expires_at": null,
  "never_expires": true,
  "pin_required": true,
  "pin_validations_count": 2,
  "last_pin_validated_at": "2026-08-14T10:42:18+02:00"
}

Voir le guide domotique et accessibilité pour limiter l’interrogation à une plage de livraison et choisir des actions non critiques.

Modifier la validité d’une consigne existante

Le partenaire authentifié et propriétaire peut redéfinir la durée à partir du moment de la requête. Utilisez 0 pour rendre la consigne active sans expiration ; une durée positive la rend de nouveau temporaire. Dans le formulaire public, une adresse e-mail de gestion est obligatoire pour ce choix.

curl -X PUT https://www.livraison-facile.fr/api/v1/consignes/HGDF354F/validity \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"validity_minutes":0}'

Champs acceptés

Sécurité et quotas

• Les clés sont stockées sous forme de hash, la valeur brute n’est affichée qu’à la génération.
• Le code PIN principal n’est jamais renvoyé. Un code PIN temporaire généré pour une livraison est retourné une seule fois, puis seule son empreinte reste stockée.
• Après trois codes PIN incorrects pour une consigne et une origine, la lecture est bloquée 5 minutes ; les récidives passent progressivement à 15 minutes puis 1 heure sans bloquer les autres réseaux.
• Les signalements publics sont limités, liés à une empreinte pseudonymisée de l’origine et vérifiés avant toute désactivation.
• Les photos sont réencodées sans métadonnées, stockées hors du dossier public et supprimées au plus tard après 30 jours ou à l’expiration de la consigne.
• Les origines CORS sont limitées par partenaire. Sans origine déclarée, l’usage reste serveur à serveur.
• L’offre gratuite comprend 1 000 appels API par jour calendaire et par entreprise. Les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset permettent de suivre le quota.
• Des limites horaires complémentaires protègent les préremplissages et les créations directes contre les rafales anormales.
• Les événements API sont journalisés dans le stockage local pour faciliter le suivi administratif.