Documentation de l'API

Bac à sable · Dernière mise à jour : 2 novembre 2026

Avant de commencer

Il vous faut deux choses :

• Une clé API Tampa. Remplissez le formulaire d'inscription : la clé vous est envoyée par e-mail tout de suite. La clé commence par tk_ et n'est affichée qu'une fois : gardez-la côté serveur, jamais dans une application mobile ou une page web.
• Un jeton e-MECeF de test pour l'entreprise qui facture. Il s'obtient sur le portail développeur de la DGI (developper.impots.bj), avec l'IFU de l'entreprise. Tampa vérifie ce jeton auprès de la DGI, le chiffre et ne le renvoie jamais.

Adresse et clé

Dans les exemples, la clé est lue dans la variable d'environnement TAMPA_API_KEY : définissez-la dans votre terminal plutôt que de coller la clé dans vos commandes.

Un compte Tampa peut gérer plusieurs entreprises, chacune avec son IFU et son jeton. Une entreprise n'est visible que par le compte qui l'a ajoutée.

1. Ajouter une entreprise

Enregistrez une fois chaque entreprise qui facture. Tampa vérifie le jeton auprès de la DGI et contrôle qu'il correspond bien à l'IFU.

curl -X POST https://sandbox.otampa.com/taxpayers \
  -H "Authorization: Bearer $TAMPA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ifu": "0000000000000",
    "name": "Boutique Exemple",
    "emecef_token": "JETON_E_MECEF_DE_TEST",
    "address": "Rue 123, Cotonou",
    "city": "Cotonou",
    "phone": "+229 01 00 00 00 00",
    "email": "contact@boutique-exemple.bj"
  }'

Réponse 201 : notez l'id, il sert à facturer pour cette entreprise.

{
  "id": "3f1c2a8e-…",
  "ifu": "0000000000000",
  "name": "Boutique Exemple",
  "nim": "TS01…",
  "token_valid_until": "2027-…",
  …
}

Seuls ifu (13 chiffres), name et emecef_token sont obligatoires. Les coordonnées apparaissent sur le PDF.

2. Certifier une facture

Tampa transmet la facture à la DGI, vérifie le total calculé par la DGI, puis confirme. La réponse arrive quand la facture est certifiée (quelques secondes).

curl -X POST https://sandbox.otampa.com/invoices \
  -H "Authorization: Bearer $TAMPA_API_KEY" \
  -H "Idempotency-Key: commande-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "taxpayer_id": "3f1c2a8e-…",
    "invoice": {
      "type": "FV",
      "operator": { "name": "Caisse 1" },
      "client": { "name": "Client Exemple", "contact": "+229 01 00 00 00 01" },
      "items": [
        { "name": "Sac de riz 25 kg", "price": 11800, "quantity": 2, "taxGroup": "B" },
        { "name": "Livraison", "price": 1000, "quantity": 1, "taxGroup": "B" }
      ],
      "payment": [ { "name": "MOBILEMONEY", "amount": 24600 } ]
    }
  }'

Réponse 201 (extrait) :

{
  "id": "9b0d…",
  "status": "certified",
  "totals": { "uid": "…", "total": 24600, … },
  "security": {
    "code_mecef_dgi": "TEST-XXXX-XXXX-XXXX-XXXX-XXXX",
    "counters": "…",
    "nim": "TS01…",
    "date_time": "…",
    "qr_code": "F;TS01…"
  },
  "pdf_url": "/invoices/9b0d…/pdf"
}

La clé d'idempotence

L'en-tête Idempotency-Key est obligatoire : une valeur unique par facture, par exemple votre numéro de commande. Si la connexion coupe, renvoyez la même requête avec la même clé : Tampa renvoie la facture déjà certifiée (code 200) au lieu d'en créer une deuxième.

Les champs de la facture

L'IFU du vendeur n'est pas à envoyer : Tampa le prend dans l'entreprise désignée par taxpayer_id.

3. Récupérer le PDF

curl https://sandbox.otampa.com/invoices/9b0d…/pdf \
  -H "Authorization: Bearer $TAMPA_API_KEY" \
  -o facture.pdf

Le PDF reprend les lignes, les totaux par groupe de taxe, le code MECeF/DGI, les compteurs et le QR code. Il est généré à la demande pour une facture certifiée.

Toutes les routes

Codes DGI

Types de facture

Groupes de taxe (taxGroup)

Le choix du groupe dépend de la situation fiscale du vendeur et du produit : en cas de doute, demandez à son comptable.

Moyens de paiement (payment[].name)

ESPECES, VIREMENT, CARTEBANCAIRE, MOBILEMONEY, CHEQUES, CREDIT, AUTRE.

Erreurs

Chaque erreur renvoie un detail en français et un request_id. Citez ce request_id si vous écrivez au support.

{ "detail": "Clé API invalide ou révoquée.", "request_id": "…" }

Besoin d'aide ?

Question technique, clé API ou démonstration : contact@otampa.com. L'utilisation du bac à sable est soumise aux conditions d'utilisation.