Guides de la Tolls API

Tout pour intégrer le calcul de péages via API ou MCP : authentification, facturation à crédits, erreurs et limites.

Mis à jour 2026-11-02

⚡ Démarrage rapide

1. Créez un compte sur le tableau de bord (dash.tolls.cargoffer.com).
2. Rechargez des crédits (ou utilisez un code) dans la section Wallet.
3. Créez une clé API (préfixe tk_live_ ; affichée une seule fois).
4. Appelez POST /api/tolls/calculate (1 crédit par calcul).

# Définissez TOLLS_API_KEY avec votre clé ; conservez une clé unique par calcul.
export TOLLS_API_KEY='YOUR_TOLLS_API_KEY'
curl -X POST https://api.tolls.cargoffer.com/api/tolls/calculate \
  -H "Authorization: Bearer $TOLLS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: route-estimate-001" \
  -d '{
    "origin": {"lat": 40.4168, "lng": -3.7038},
    "destination": {"lat": 41.3874, "lng": 2.1686},
    "vehicleType": "pesado_1"
  }'

Les crédits ne sont débités que si le calcul est servi. En cas d’échec du moteur, le crédit est remboursé automatiquement. Une clé déjà traitée renvoie 409 et n’est pas facturée une seconde fois, mais l’API ne rejoue pas la réponse initiale. Conservez la réponse avec la clé et utilisez-en une nouvelle pour chaque nouveau calcul.

🔑 Authentification

Authentifiez chaque requête avec Authorization: Bearer <token>. Utilisez une clé API ou le JWT de session du tableau de bord.

Vérifiez n’importe quel token via GET /api/auth/validate : sujet, type et scopes. MCP : les clients peuvent utiliser le serveur officiel https://mcp.tolls.cargoffer.com/mcp (streamable HTTP, Bearer obligatoire à chaque requête).

🧭 Erreurs

⏱️ Limites et démo

• Limites séparées selon le mode d'authentification, pour qu'un flux anonyme ne bloque pas les clients payants : clé API 200 req/min par clé, session du tableau de bord 300 req/min par IP, non authentifié 50 req/min par IP. Si dépassement : 429 avec en-tête Retry-After.
• Démo POST /api/demo/calculate : 5 req/min par IP et 500 calculs/jour en pool partagé (429 si épuisé). Sans auth, sans coût.
• Jusqu'à 10 clés API actives par compte ; en révoquer une libère une place. GET /api/keys/limits publie la limite en vigueur.
• Chaque calcul servi consomme 1 crédit et est journalisé dans GET /api/history.

🎟️ Codes promo

Un code crédite directement le portefeuille, sans paiement : POST /api/wallet/redeem avec {"code":"…"}. Chaque compte peut utiliser chaque code une seule fois (409 sinon) ; les codes peuvent être limités à un email ou à N utilisations.

🧩 Odoo

Pour Odoo, effectuez la requête depuis un module personnalisé ou un worker Python autorisé aux appels HTTP. Gardez une Idempotency-Key par calcul logique et réutilisez-la uniquement pour réessayer cette opération :

Le contexte et les variables des Server Actions dépendent de la version et de la configuration d’Odoo. Cet exemple est un modèle d’intégration Python ; consultez la documentation officielle avant de l’exécuter dans Odoo : documentation officielle des Server Actions (Odoo 19)

import os
import requests

# Lisez un UUID persistant pour ce calcul ; réutilisez-le uniquement en cas de réessai.
calculation_id = "persisted-uuid-for-this-calculation"
response = requests.post(
    "https://api.tolls.cargoffer.com/api/tolls/calculate",
    headers={
        "Authorization": f"Bearer {os.environ['TOLLS_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": f"odoo-toll-{calculation_id}",
    },
    json={
        "origin": {"lat": 40.4168, "lng": -3.7038},
        "destination": {"lat": 41.3874, "lng": 2.1686},
        "vehicleType": "pesado_1",
    },
    timeout=30,
)
response.raise_for_status()
tolls = response.json()

Exemple Node.js (18+) :

const apiKey = process.env.TOLLS_API_KEY;
const idempotencyKey = process.env.TOLLS_IDEMPOTENCY_KEY; // À conserver par calcul logique.
const response = await fetch('https://api.tolls.cargoffer.com/api/tolls/calculate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({
    origin: { lat: 40.4168, lng: -3.7038 },
    destination: { lat: 41.3874, lng: 2.1686 },
    vehicleType: 'pesado_1',
  }),
});
if (!response.ok) throw new Error(`Tolls API HTTP ${response.status}`);
const tolls = await response.json();

Une clé déjà traitée renvoie 409 : elle n’est pas facturée une seconde fois, mais la réponse initiale n’est pas rejouée. Conservez la réponse avec la clé et utilisez-en une nouvelle pour un nouveau calcul.

📜 Changelog