Intégrez Antera à votre système

Introduction

L'API Antera est une API REST au format JSON qui permet à un système tiers d'opérer sur la plateforme de livraison. Vous pouvez automatiser l'envoi de vos commandes vers Antera, suivre l'avancement de chaque colis et récupérer les informations financières (encaissement à la livraison / COD).

• Style : REST — requêtes et réponses en application/json (en-têtes Content-Type et Accept)
• Authentification : clé API (jeton porteur / Bearer token) dans l'en-tête Authorization
• Relations : référencées par IRI, ex. /api/cities/45
• Isolation : chaque clé est rattachée à un espace (workspace) ; vous ne voyez que vos propres données
• Documentation interactive (OpenAPI / Swagger) : /api/docs

Cas d'usage

Obtenir un accès

L'accès à l'API est réservé aux comptes partenaires. Pour démarrer une intégration :

1. Contactez notre équipe à contact@antera.app pour ouvrir un compte partenaire et un espace dédié.
2. Recevez vos identifiants ainsi que votre clé API (jeton). La clé détermine à elle seule votre espace : ne la partagez jamais.
3. Testez vos appels en environnement de validation, puis passez en production.

Authentification

Chaque requête authentifiée doit inclure votre clé API dans l'en-tête HTTP Authorization, selon le schéma Bearer :

Authorization: Bearer VOTRE_CLE_API

Si vous disposez d'un identifiant e-mail / mot de passe, vous pouvez aussi obtenir un jeton dynamiquement :

curl -X POST https://votre-espace.antera.app/api/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "partenaire@exemple.com", "password": "••••••••" }'

# Réponse
{ "token": "9f8c1e…", "user": { "id": 7, "name": "Ma Boutique" } }

URL de base

Tous les points d'accès sont préfixés par /api sur votre sous-domaine d'espace :

https://votre-espace.antera.app/api

Remplacez votre-espace par le sous-domaine qui vous a été attribué.

Démarrage rapide

Un parcours complet en quatre appels : s'authentifier, trouver la ville de destination, créer la livraison, puis suivre le colis.

# 1) Obtenir un jeton (ou utiliser directement votre clé API permanente)
TOKEN=$(curl -s -X POST https://votre-espace.antera.app/api/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "partenaire@exemple.com", "password": "••••••••" }' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

# 2) Trouver l'IRI de la ville de destination
curl -s "https://votre-espace.antera.app/api/cities?name=Ariana" \
  -H "Authorization: Bearer $TOKEN"
# -> { "member": [ { "@id": "/api/cities/22", "name": "Ariana Ville", ... } ] }

# 3) Créer la livraison
curl -s -X POST https://votre-espace.antera.app/api/deliveries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arrivalContactName": "Mariem Trabelsi",
    "arrivalContactPhone": "+216 22 333 444",
    "arrivalCity": "/api/cities/22",
    "dateTimeBegin": "2026-06-15T10:00:00+01:00"
  }'
# -> 201 { "trackingNumber": "ANT-20260615-000123", "status": "pending", ... }

# 4) Suivre le colis
curl -s https://votre-espace.antera.app/api/parcels/ANT-20260615-000123 \
  -H "Authorization: Bearer $TOKEN"

Créer une livraison

Crée une nouvelle livraison (colis) dans votre espace. La livraison est créée au statut pending ; un numéro de suivi unique et immuable est généré et renvoyé.

Champs obligatoires

Champs recommandés

Champs gérés automatiquement — à ne pas envoyer

Ces champs sont déterminés côté serveur ; toute valeur que vous enverriez serait ignorée ou écrasée :

Exemple minimal (champs obligatoires uniquement)

curl -X POST https://votre-espace.antera.app/api/deliveries \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "arrivalContactName": "Mariem Trabelsi",
    "arrivalContactPhone": "+216 22 333 444",
    "arrivalCity": "/api/cities/22",
    "dateTimeBegin": "2026-06-15T10:00:00+01:00"
  }'

Exemple complet (avec encaissement COD)

curl -X POST https://votre-espace.antera.app/api/deliveries \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "arrivalContactName": "Mariem Trabelsi",
    "arrivalContactPhone": "+216 22 333 444",
    "arrivalAddress": "12 rue de Carthage, Ariana",
    "arrivalCity": "/api/cities/22",
    "arrivalLatitude": 36.8625,
    "arrivalLongitude": 10.1956,
    "dateTimeBegin": "2026-06-15T10:00:00+01:00",
    "designation": "Sneakers x1, T-shirt x2",
    "nombreArticles": 3,
    "poids": "1.500",
    "montant": "129.000",
    "modePaiement": "espece",
    "observation": "Appeler avant livraison"
  }'

Réponse — 201 Created

Avec Accept: application/json, les relations (ville…) sont renvoyées sous forme d'objets imbriqués :

{
  "id": 10245,
  "trackingNumber": "ANT-20260615-000123",
  "status": "pending",
  "qrCode": "uploads/qrcodes/parcel_ANT_20260615_000123.png",
  "dateTimeCreation": "2026-06-15T09:41:12+01:00",
  "dateTimeBegin": "2026-06-15T10:00:00+01:00",
  "arrivalContactName": "Mariem Trabelsi",
  "arrivalContactPhone": "+216 22 333 444",
  "arrivalCity": { "id": 22, "name": "Ariana Ville", "fullName": "Ariana Ville, Ariana" },
  "arrivalAddress": "12 rue de Carthage, Ariana",
  "montant": "129.000",
  "modePaiement": "espece",
  "nombreArticles": 3,
  "designation": "Sneakers x1, T-shirt x2"
}

Exemples de code

Création d'une livraison dans les langages les plus courants. Stockez la clé API hors du code (variable d'environnement) et conservez le trackingNumber renvoyé.

PHP (cURL)

<?php
$apiKey = getenv('ANTERA_API_KEY');

$ch = curl_init('https://votre-espace.antera.app/api/deliveries');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'arrivalContactName'  => 'Mariem Trabelsi',
        'arrivalContactPhone' => '+216 22 333 444',
        'arrivalCity'         => '/api/cities/22',
        'dateTimeBegin'       => '2026-06-15T10:00:00+01:00',
        'montant'             => '129.000',
    ]),
]);

$response = json_decode(curl_exec($ch), true);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 201) {
    echo 'Colis créé : ' . $response['trackingNumber'];
}

Python (requests)

import os, requests

resp = requests.post(
    "https://votre-espace.antera.app/api/deliveries",
    headers={"Authorization": f"Bearer {os.environ['ANTERA_API_KEY']}"},
    json={
        "arrivalContactName": "Mariem Trabelsi",
        "arrivalContactPhone": "+216 22 333 444",
        "arrivalCity": "/api/cities/22",
        "dateTimeBegin": "2026-06-15T10:00:00+01:00",
        "montant": "129.000",
    },
)
resp.raise_for_status()
print("Colis créé :", resp.json()["trackingNumber"])

Node.js (fetch)

const res = await fetch("https://votre-espace.antera.app/api/deliveries", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ANTERA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    arrivalContactName: "Mariem Trabelsi",
    arrivalContactPhone: "+216 22 333 444",
    arrivalCity: "/api/cities/22",
    dateTimeBegin: "2026-06-15T10:00:00+01:00",
    montant: "129.000",
  }),
});

if (!res.ok) throw new Error(`Antera API: HTTP ${res.status}`);
const data = await res.json();
console.log("Colis créé :", data.trackingNumber);

Suivre un colis

Récupère l'état courant d'un colis à partir de son numéro de suivi.

curl https://votre-espace.antera.app/api/parcels/ANT-20260602-000123 \
  -H "Authorization: Bearer VOTRE_CLE_API"

# Réponse
{
  "tracking_number": "ANT-20260615-000123",
  "id": 10245,
  "status": "in_progress",
  "derived_status": "out_for_delivery",
  "custody": { "type": "delivery_man", "description": "Chez le livreur" },
  "shipper": { "id": 7, "name": "Ma Boutique" },
  "recipient": { "name": "Mariem Trabelsi", "address": "12 rue de Carthage, Ariana", "phone": "+216 22 333 444" },
  "cod_amount": "129.000",
  "cod_collected": false,
  "designation": "Sneakers x1, T-shirt x2",
  "qr_code": "uploads/qrcodes/parcel_ANT_20260615_000123.png",
  "created_at": "2026-06-15T09:41:12+01:00"
}

Pour l'historique complet et horodaté des mouvements du colis :

Référentiel des villes

Le champ arrivalCity attend une référence (IRI) vers une ville du référentiel Antera. Recherchez la ville par son nom pour obtenir son identifiant, puis construisez l'IRI /api/cities/{id}.

curl "https://votre-espace.antera.app/api/cities?name=Ariana" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Filtres disponibles : name (recherche partielle), governorate (exact), postalCode (exact).

Statuts de livraison

Le champ status d'une livraison évolue tout au long du cycle de vie du colis :

Codes de réponse

Les erreurs d'authentification renvoient un objet error :

{ "error": "Invalid credentials" }

Les erreurs de validation (422) détaillent chaque champ fautif dans violations :

{
  "status": 422,
  "violations": [
    {
      "propertyPath": "arrivalContactPhone",
      "message": "Le numéro de téléphone du destinataire est obligatoire"
    }
  ],
  "detail": "arrivalContactPhone: Le numéro de téléphone du destinataire est obligatoire",
  "title": "An error occurred"
}

Bonnes pratiques

• Idempotence — conservez la correspondance entre votre référence de commande et le trackingNumber Antera afin de ne jamais créer deux fois la même livraison.
• Reprises — réessayez uniquement sur les erreurs réseau ou 5xx, avec un délai progressif (backoff exponentiel).
• Pagination — paginez systématiquement la lecture des collections volumineuses.
• Sécurité — appels en HTTPS, clé stockée côté serveur, rotation régulière de la clé.
• Journalisation — tracez chaque appel (référence commande ↔ trackingNumber) pour faciliter le support.

Documentation interactive

L'ensemble des ressources et schémas est exposé via une documentation interactive OpenAPI (Swagger), où vous pouvez explorer et tester les endpoints :

Support

Une question sur l'intégration ? Notre équipe technique vous accompagne.

• E-mail : contact@antera.app
• Téléphone : +216 26 491 718
• WhatsApp : +216 26 491 718