Getting Started

Bienvenue dans l'API TrackFlow. Notre API REST vous permet de suivre des expéditions, recevoir des événements en temps réel via webhooks et intégrer le suivi dans n'importe quelle application. Toutes les requêtes se font sur HTTPS et toutes les réponses sont au format JSON.

L'URL de base de l'API est https://api.trackflow.io/v1. Toutes les requêtes doivent être authentifiées avec une clé API.

1. Récupérez votre clé API

Créez un compte, puis générez une clé API depuis votre tableau de bord développeur.

2. Faites votre première requête

Cette requête récupère le statut d'une expédition.

cURL
1curl https://api.trackflow.io/v1/shipments/shp_8f2k1 \
2  -H "Authorization: Bearer sk_live_xxxxx"

Authentication

TrackFlow utilise des clés API pour authentifier les requêtes. Passez votre clé secrète dans l'en-tête Authorization en utilisant le schéma Bearer.

Header
1Authorization: Bearer sk_live_51H8xY...
Ne partagez jamais votre clé secrète et ne l'exposez pas côté client. Toute requête sans authentification valide renvoie une erreur 401 Unauthorized.

Environnements

Les clés préfixées sk_test_ ciblent l'environnement de test ;sk_live_ cible la production.

API Keys

Gérez vos clés depuis le tableau de bord. Chaque clé peut être révoquée à tout moment et des clés restreintes peuvent limiter les permissions par ressource.

sk_live_…secret

Clé secrète de production. À garder côté serveur uniquement.

sk_test_…secret

Clé secrète de test. N'affecte aucune donnée réelle.

pk_live_…publishable

Clé publiable, utilisable côté client pour les ressources publiques.

Rotation d'une clé

cURL
1curl -X POST https://api.trackflow.io/v1/api-keys/roll \
2  -H "Authorization: Bearer sk_live_xxxxx"

REST API Overview

L'API TrackFlow suit les conventions REST : URLs orientées ressources, verbes HTTP standard et codes de statut explicites. Les corps de requête et de réponse sont en JSON.

Verbes HTTP

GETlecture

Récupère une ressource ou une liste de ressources.

POSTcréation

Crée une nouvelle ressource (expédition, webhook…).

PUTmise à jour

Remplace entièrement une ressource existante.

DELETEsuppression

Supprime une ressource.

Ressources principales

GET/v1/shipments
POST/v1/shipments
GET/v1/webhooks

Shipment Tracking

Récupérez le statut et l'historique complet d'une expédition par son identifiant.

GET/v1/shipments/{id}

Paramètres de chemin

idstringRequis

Identifiant unique de l'expédition (ex. shp_8f2k1).

Exemple de requête

cURL
1curl https://api.trackflow.io/v1/shipments/shp_8f2k1 \
2  -H "Authorization: Bearer sk_live_xxxxx"

Exemple de réponse

200 OK
1{
2  "id": "shp_8f2k1",
3  "carrier": "ups",
4  "tracking_number": "1Z999AA10123456784",
5  "status": "in_transit",
6  "estimated_delivery": "2026-06-25T18:00:00Z",
7  "events": [
8    {
9      "status": "picked_up",
10      "location": "Paris, FR",
11      "timestamp": "2026-06-22T09:14:00Z"
12    },
13    {
14      "status": "in_transit",
15      "location": "Lyon, FR",
16      "timestamp": "2026-06-22T16:42:00Z"
17    }
18  ]
19}

Webhook Events

Configurez une URL de webhook pour recevoir des événements en temps réel lorsque le statut d'une expédition change. Chaque événement est envoyé en POST avec une signature à vérifier.

Événements disponibles

shipment.createdevent

Une expédition a été créée.

shipment.in_transitevent

L'expédition est en cours d'acheminement.

shipment.deliveredevent

L'expédition a été livrée.

shipment.exceptionevent

Un incident de livraison est survenu.

Payload d'un événement

POST vers votre endpoint
1{
2  "id": "evt_2c9a",
3  "type": "shipment.delivered",
4  "created": 1779884400,
5  "data": {
6    "object": {
7      "id": "shp_8f2k1",
8      "status": "delivered",
9      "delivered_at": "2026-06-25T15:32:00Z"
10    }
11  }
12}
Vérifiez l'en-tête TrackFlow-Signature avec votre secret de webhook pour confirmer l'authenticité de l'événement.

Pagination

Les endpoints de liste utilisent une pagination par curseur. Utilisezlimit et starting_after pour parcourir les résultats.

limitinteger

Nombre d'éléments par page (1–100, défaut 25).

starting_afterstring

ID de l'objet après lequel commencer la page suivante.

cURL
1curl "https://api.trackflow.io/v1/shipments?limit=25&starting_after=shp_8f2k1" \
2  -H "Authorization: Bearer sk_live_xxxxx"
Réponse
1{
2  "object": "list",
3  "has_more": true,
4  "data": [ { "id": "shp_9a3b" }, { "id": "shp_9a3c" } ]
5}

Rate Limits

L'API limite les requêtes à 100 req/s en production et25 req/s en test. Les en-têtes de réponse indiquent votre quota restant.

X-RateLimit-Limitheader

Nombre maximum de requêtes par fenêtre.

X-RateLimit-Remainingheader

Requêtes restantes dans la fenêtre actuelle.

X-RateLimit-Resetheader

Timestamp Unix de réinitialisation du quota.

Au dépassement, l'API renvoie 429 Too Many Requests. Implémentez un backoff exponentiel.

Error Codes

TrackFlow utilise les codes de statut HTTP conventionnels pour indiquer le succès ou l'échec.

200OK

La requête a réussi.

400Bad Request

Requête invalide, souvent un paramètre manquant.

401Unauthorized

Clé API manquante ou invalide.

403Forbidden

La clé n'a pas la permission requise.

404Not Found

La ressource demandée n'existe pas.

429Too Many Requests

Limite de débit dépassée.

500Server Error

Une erreur est survenue côté TrackFlow.

Format d'erreur

Réponse d'erreur
1{
2  "error": {
3    "type": "invalid_request_error",
4    "code": "resource_missing",
5    "message": "No such shipment: shp_unknown"
6  }
7}

Request Examples

Création d'une nouvelle expédition à suivre.

POST/v1/shipments
cURL
1curl -X POST https://api.trackflow.io/v1/shipments \
2  -H "Authorization: Bearer sk_live_xxxxx" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "carrier": "ups",
6    "tracking_number": "1Z999AA10123456784"
7  }'

Response Examples

Réponse renvoyée après la création réussie d'une expédition.

201 Created
1{
2  "id": "shp_9a3b",
3  "object": "shipment",
4  "carrier": "ups",
5  "tracking_number": "1Z999AA10123456784",
6  "status": "created",
7  "created": 1779800000,
8  "estimated_delivery": null
9}

SDK Examples

TrackFlow propose des SDK officiels pour les langages les plus courants. Installez le SDK correspondant à votre stack, puis initialisez-le avec votre clé API.

Installation

npm
1npm install @trackflow/sdk
pip
1pip install trackflow
composer
1composer require trackflow/trackflow-php
Chaque SDK lit la clé depuis la variable d'environnement TRACKFLOW_API_KEY si aucune n'est fournie.

JavaScript

Utilisation du SDK dans le navigateur ou avec un bundler moderne (ESM).

JavaScript
1import { TrackFlow } from '@trackflow/sdk';
2
3const client = new TrackFlow('sk_live_xxxxx');
4
5async function track(id) {
6  const shipment = await client.shipments.retrieve(id);
7  console.log(shipment.status, shipment.estimated_delivery);
8}
9
10track('shp_8f2k1');

Node.js

Exemple côté serveur avec gestion d'erreur et CommonJS.

Node.js
1const { TrackFlow } = require('@trackflow/sdk');
2
3const client = new TrackFlow(process.env.TRACKFLOW_API_KEY);
4
5async function main() {
6  try {
7    const list = await client.shipments.list({ limit: 10 });
8    for (const shipment of list.data) {
9      console.log(shipment.id, '->', shipment.status);
10    }
11  } catch (err) {
12    console.error('TrackFlow error:', err.message);
13  }
14}
15
16main();

Python

Le SDK Python expose une interface synchrone simple.

Python
1import trackflow
2
3client = trackflow.Client(api_key="sk_live_xxxxx")
4
5shipment = client.shipments.retrieve("shp_8f2k1")
6print(shipment.status, shipment.estimated_delivery)
7
8# Lister avec pagination
9page = client.shipments.list(limit=25)
10for s in page.data:
11    print(s.id, s.status)

PHP

Intégration avec l'autoloader Composer.

PHP
1<?php
2require 'vendor/autoload.php';
3
4use TrackFlow\Client;
5
6$client = new Client('sk_live_xxxxx');
7
8$shipment = $client->shipments->retrieve('shp_8f2k1');
9
10echo $shipment->status . PHP_EOL;
11echo $shipment->estimated_delivery . PHP_EOL;

Go

Le client Go renvoie des erreurs idiomatiques à vérifier explicitement.

Go
1package main
2
3import (
4  "fmt"
5  "log"
6
7  "github.com/trackflow/trackflow-go"
8)
9
10func main() {
11  client := trackflow.NewClient("sk_live_xxxxx")
12
13  shipment, err := client.Shipments.Retrieve("shp_8f2k1")
14  if err != nil {
15    log.Fatal(err)
16  }
17
18  fmt.Println(shipment.Status, shipment.EstimatedDelivery)
19}

cURL

Exemples bruts en ligne de commande, utiles pour le débogage rapide.

Récupérer une expédition

cURL
1curl https://api.trackflow.io/v1/shipments/shp_8f2k1 \
2  -H "Authorization: Bearer sk_live_xxxxx"

Créer un webhook

cURL
1curl -X POST https://api.trackflow.io/v1/webhooks \
2  -H "Authorization: Bearer sk_live_xxxxx" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://example.com/hooks/trackflow",
6    "events": ["shipment.delivered", "shipment.exception"]
7  }'