Documentation API FretGuard

En production, GET /api/v1/invoices est servi par le gateway FretGuard. Envoyez un jeton d’accès utilisateur valide dans Authorization: Bearer <jeton>. Le compte doit appartenir à une organisation et disposer du droit invoices:read.

Le cookie HttpOnly fg.session appartient au frontend : il ne suffit pas à authentifier cette route du gateway. Ne partagez jamais de jeton dans une conversation. Aucun mécanisme public de clé API ou OAuth pour agent autonome n’est annoncé ici ; contactez FretGuard pour convenir d’un accès machine autorisé.

GET /api/v1/invoices?limit=25&offset=0 retourne les factures de l’organisation autorisée. limit va de 1 à 200 (50 par défaut) ; offset commence à 0. La réponse contient items, total_count, limit, offset et has_more. Les filtres disponibles sont détaillés dans OpenAPI.

Exemple pour une intégration autorisée, avec un jeton conservé dans une variable locale sécurisée :

curl -H "Authorization: Bearer $FRETGUARD_ACCESS_TOKEN" -H "Accept: application/json" "https://fretguard.com/api/v1/invoices?limit=25&offset=0"

Exemple sans authentification pour observer une erreur JSON : curl -i -H "Accept: application/json" https://fretguard.com/api/v1/invoices

Cette spécification décrit une route REST existante. Elle ne fournit ni serveur MCP, ni SDK, ni endpoint GraphQL. Les opérations d’import et de modification restent dans l’application et hors du contrat publié.

Le paquet npm @fretguard/cli permet de consulter OpenAPI et de lire les factures autorisées depuis un terminal. Il nécessite Node.js 22 ou plus récent et ne modifie aucune donnée.

Installation : npm install --global @fretguard/cli. Aide : fretguard --help. Contrat API : fretguard openapi.

Lecture paginée : fretguard invoices list --limit 25 --offset 0. Fournissez FRETGUARD_ACCESS_TOKEN dans votre environnement local ou votre gestionnaire de secrets. Ne passez pas le jeton en argument et ne le partagez pas dans une conversation.

Les résultats JSON sont écrits sur la sortie standard et les erreurs JSON sur la sortie d’erreur. Codes de sortie : 0 succès, 1 erreur d’accès ou de réseau, 2 arguments invalides. Aucun stockage de jeton, aucune redirection suivie, aucun nouvel essai automatique. Respectez retryAfter lorsqu’il est fourni.

Une page publique inexistante retourne HTTP 404. Avec Accept: text/markdown, la réponse explique l’erreur et propose des liens vers la documentation, le sitemap et llms.txt. Les navigateurs conservent la page d’erreur HTML.

Les erreurs d’authentification et de droits utilisent {"error":{"code":"UNAUTHORIZED","message":"Missing authorization header","requestId":"…"}}. requestId permet de retrouver la requête auprès du support. Aucun champ hint n’est garanti.

401 UNAUTHORIZED : fournissez un jeton valide. 403 FORBIDDEN : vérifiez le droit invoices:read. 503 AUTH_SERVICE_UNAVAILABLE : réessayez après un délai. Les paramètres invalides retournent 422, avec error ou un champ historique detail. L’absence d’organisation peut aussi retourner 401 avec detail. Le contrat décrit ces variantes.

Aucun quota ni en-tête RateLimit n’est garanti pour GET /api/v1/invoices. Le gateway limite certaines autres opérations sensibles ; Cloudflare peut également refuser une requête avant son arrivée dans l’API, avec un corps qui n’est pas nécessairement JSON.

Sur 429 ou une panne temporaire, respectez Retry-After lorsqu’il est présent (secondes ou date HTTP). Sinon, espacez les reprises avec un délai exponentiel et une part aléatoire. Ne réessayez pas indéfiniment un refus d’authentification ou de droits.

FretGuard convient au rapprochement des factures transport et des tarifs négociés, à la recherche de doublons et à la documentation des écarts. Préparez les factures, grilles tarifaires, conditions contractuelles et références d’expédition. Un écart détecté n’est pas une somme récupérée.

Pour découvrir le produit : curl -i -H "Accept: text/markdown" https://fretguard.com/ . Le même URL sert du HTML avec Accept: text/html. Le choix respecte les préférences q et les réponses indiquent Vary: Accept. Les types non pris en charge reçoivent 406.

Consultez llms.txt pour les cas d’usage et liens publics. Pour accéder aux données privées, obtenez l’autorisation du titulaire et utilisez un jeton Bearer autorisé pour le gateway. Le schéma OpenAPI fournit un operationId unique, des paramètres typés et des réponses pour l’outillage ; il ne crée pas de droits d’accès.