Guide d'intégration
Pour les équipes techniques qui branchent un TMS, un babillard ou une plateforme d'affacturage ou d'assurance à HaulProof. Tout ce qui suit fonctionne aujourd'hui sur https://haulproof.ca. OpenAPI 3.1 · État du service · support@haulproof.ca
1. Clés
hp_test_: bac à sable, 10 transporteurs fictifs (USDOT 99990001 à 99990010) pour les dossiers, la recherche, les niveaux, les fichiers, les insignes et les webhooks. Rien n'est facturé.hp_live_: clé partenaire, tous les transporteurs, 25 requêtes par seconde avec pointes de 100, portées convenues.
Envoyez la clé à chaque appel : Authorization: Bearer <clé>. Les clés sont montrées une seule fois, conservées seulement sous forme de hachage SHA-256, peuvent avoir une date de fin et être révoquées une à une. Portées : read, search, watchlists, alerts. Les erreurs sont en JSON; un 429 inclut Retry-After.
curl -H "Authorization: Bearer hp_test_…" "https://haulproof.ca/v1/tiers?ids=99990007,MC123456"2. Le fichier des niveaux de la nuit (pour afficher un niveau à côté de chaque transporteur)
GET /v1/tier-files renvoie des liens valides une heure : « all » couvre chaque transporteur américain actif et chaque profil provincial canadien (environ 2,2 millions de lignes, environ 47 Mo compressés); « watchlist » couvre une de vos listes. CSV compressé, UTF-8, avec en-tête. Colonnes : key, usdot, docket, nsc, cvor, nir, name, jurisdiction, status, tier, hard_rules, reasons, as_of. Refait après la mise à jour de la nuit, terminée à 7 h (heure de Toronto).
3. Niveaux de 100 transporteurs par appel
GET /v1/tiers?ids=... accepte un USDOT, MC123456, un CNS (MB9002108, AB123-4567), un IUVU de l'Ontario (9 chiffres), un NIR du Québec (R-123456-7) ou une clé, et renvoie pour chacun : key, name, dot_number, provinces, tier, hard_rules, reasons [{signal, weight, label}] et as_of, ou error: not_found. Ajoutez lang=fr pour les libellés en français. Non facturé.
4. Webhooks signés pour les changements
- POST /v1/watchlists, puis POST /v1/watchlists/{id}/items/bulk (jusqu'à 10 000 identifiants par appel; les inconnus sont renvoyés).
- POST /v1/webhooks {"url", "min_severity"} renvoie une seule fois le secret de signature.
- POST /v1/webhooks/{id}/test envoie tout de suite une alerte d'essai signée.
Chaque alerte est envoyée en JSON {"event": "alert.created", "data": {...}} avec X-HaulProof-Timestamp et X-HaulProof-Signature : sha256=<HMAC-SHA256(secret, "<horodatage>.<corps brut>")>. Répondez 2xx en moins de 10 secondes; sinon, nouvel envoi après 1, 5 et 30 minutes, 2 heures et 12 heures. Types : authority.revoked, insurance.bipd_dropped, safety.placed_oos, safety.risk_elevated, canada.tier_changed, entre autres. Sans webhook : GET /v1/alerts?since_id=.
5. Le dossier complet sur demande
GET /v1/carriers/{id} : le dossier américain et canadien fusionné (statut, autorisation et historique, assurance et annulations, 24 mois d'inspections et d'accidents, équipement, transporteurs liés, cotes provinciales, niveau et raisons). Un appel = une consultation facturée; les réponses sont en cache jusqu'à la prochaine mise à jour et incluent as_of.
6. Un insigne à intégrer
GET /v1/badges/{id}.svg?lang=fr renvoie un SVG de 230×44 avec le niveau du transporteur et « Vérifié avec HaulProof » (ou « Vérifié par HaulProof » si le transporteur a vérifié son profil). Récupérez-le côté serveur avec votre clé et gardez-le en cache jusqu'à la prochaine mise à jour.
7. Exemples de code
curl.sh: Chaque appel avec curlhaulproof.mjs: Client Node 18+ : niveaux, dossier, liste en lot, fichier des niveaux, test de webhookhaulproof.py: La même chose en Python 3 (bibliothèque standard seulement)verify-webhook.mjs: Récepteur de webhook qui vérifie la signature (Node)verify_webhook.py: Récepteur de webhook qui vérifie la signature (Python)
Tous lisent la clé dans HP_KEY (et le secret du webhook dans HP_WEBHOOK_SECRET). Essayez-les d'abord avec une clé de bac à sable.
8. Limites
- Par clé : 10 requêtes par seconde, pointes de 30; clés partenaires 25 par seconde, pointes de 100.
- /v1/tiers : 100 identifiants par appel. Liste en lot : 10 000 éléments par appel. Liens des fichiers : valides 1 heure.
- Mise à jour des données : chaque nuit, terminée à 7 h (heure de Toronto).