Envoyez vos données produit vers PassportLab via webhook

1. Provisionnement

1. Dans le tableau de bord PassportLab, accédez à Intégrations.
2. Cliquez sur Configurer le webhook dans la tuile Generic Webhook.
3. Donnez un nom à l'intégration (p. ex. SAP S/4HANA Production).
4. À la création, une boîte de dialogue unique affiche l'URL du webhook et le secret de signature. Copiez les deux immédiatement — le secret n'est affiché qu'une seule fois.
5. (Facultatif mais recommandé.) Ouvrez Règles de mappage sur la carte de l'intégration et associez les noms de champs de votre ERP aux champs du passeport DPP. Le bouton Test intégré affiche la sortie normalisée sur un exemple de charge utile.

3. Signature

Nous utilisons le schéma de signature de type Stripe : horodatage + point + corps, HMAC-SHA256, empreinte hexadécimale, préfixée par sha256=.

signing_base = <timestamp> + "." + <raw request body bytes>
signature    = "sha256=" + HMAC-SHA256(secret, signing_base).hexdigest()

Inclure l'horodatage dans la charge utile signée constitue une protection anti-rejeu : même si une requête valide fuite, elle ne peut pas être renvoyée en dehors de la fenêtre de 5 minutes.

import hashlib, hmac, json, time, requests

INTEGRATION_ID = "REPLACE_ME"
SECRET         = "REPLACE_ME"  # from your credential vault
BASE_URL       = "https://api.passportlab.io"

records = [{"name": "Widget Pro", "barcode": "01234567890123"}]
body    = json.dumps({"records": records}).encode("utf-8")
ts      = str(int(time.time()))
sig     = "sha256=" + hmac.new(
    SECRET.encode(), f"{ts}.".encode() + body, hashlib.sha256
).hexdigest()

res = requests.post(
    f"{BASE_URL}/api/v1/integrations/{INTEGRATION_ID}/webhook-ingest",
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-PassportLab-Timestamp": ts,
        "X-PassportLab-Signature": sig,
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())  # → {"jobId": "...", "totalRecords": 1, "enqueued": true}

5. Mappage des champs

Si la structure de la charge utile de votre ERP diffère du schéma DPP (ce qui est presque toujours le cas), définissez des règles de mappage dans le tableau de bord. Chaque règle comporte quatre champs :

7. Recommandations opérationnelles

Idempotence

PassportLab utilise le code DPP (dérivé du GTIN + numéro de série) comme identifiant unique. Renvoyer un enregistrement avec le même GTIN+numéro de série est ignoré, pas dupliqué — la réponse le marque skipped avec le motif "DPP code 'DPP-…' already exists". Peut être retenté sans risque en cas d'erreur transitoire.

Nouvelles tentatives

En cas de 502 / 503 / 504 ou de délais réseau, réessayez avec un backoff exponentiel (1 s, 2 s, 4 s, 8 s, plafonné à 30 s). Jusqu'à 3 tentatives suffisent généralement. Ne réessayez pas en cas de réponse 4xx — la requête échouera à nouveau.

Regroupement par lots

• Petits ERP (< 1 000 SKU) : envoyez le catalogue complet chaque nuit en un seul appel.
• ERP plus volumineux : n'envoyez que le delta (lignes modifiées depuis la dernière synchronisation), par lots de jusqu'à 1 000 enregistrements par requête.