API et intégrations

Votre caisse, votre ERP ou votre boutique en ligne créent des tickets, changent leur état et reçoivent chaque étape par webhook. Les clients reçoivent les mêmes notifications que depuis l’app.

Sur demande pendant le lancement : écrivez-nous et nous activons l’API pour votre boutique.

BASEhttps://api.tfa9adni.com/v1

Spécification OpenAPI Nous écrire

Démarrer

Toutes les requêtes partent de cette adresse, en HTTPS, avec du JSON dans les deux sens.

Chaque réponse a la même enveloppe : success et data, ou success à false et une error avec un code. Les montants sont en unités mineures (millimes, centimes) avec la devise et le nombre de décimales. Les dates sont en ISO 8601, en UTC.

GET/v1/shop

Tester la connexion

Renvoie la boutique liée à la clé, sa devise, son fuseau et les droits de la clé.

Créez une clé dans l’app : Boutique › Intégrations. Seul le propriétaire de la boutique peut le faire. Puis testez la connexion :

GET/v1/shop

curl "https://api.tfa9adni.com/v1/shop" \
  -H "Authorization: Bearer $TFA9ADNI_KEY"

const res = await fetch("https://api.tfa9adni.com/v1/shop", {
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
  },
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/shop");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.get(
    "https://api.tfa9adni.com/v1/shop",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": {
    "id": "b7a4…",
    "name": "Atelier Sami",
    "trade": "Cordonnerie",
    "public_code": "k7m2qp9x",
    "country": "TN",
    "currency": "TND",
    "decimals": 3,
    "timezone": "Africa/Tunis",
    "key": {
      "name": "Caisse du comptoir",
      "prefix": "tfk_live_7QX2M9KD…",
      "scopes": [
        "tickets:read",
        "tickets:write"
      ]
    }
  }
}

Authentification

Envoyez la clé dans l’en-tête Authorization. Une clé ne donne accès qu’à sa boutique.

La clé s’affiche une seule fois à sa création. Gardez-la sur votre serveur ou dans votre caisse, jamais dans une page web ni dans un message. Une clé révoquée cesse de marcher en moins d’une minute. Cinq clés actives au plus par boutique.

Droits d’une clé

tickets:readLire les tickets.
tickets:writeCréer des tickets et changer leur état.
clients:readRetrouver un client et lire sa carte de fidélité.
loyalty:writeAjouter des tampons et utiliser une récompense.

« Accès complet » donne les quatre droits, « Lecture seule » donne tickets:read et clients:read.

Tickets

États d’un ticket

workshopÀ l’atelier, en cours.
readyPrêt, en attente du client.
impossiblePas réparable, l’article attend son client.
collectedRécupéré. outcome dit s’il était prêt ou impossible.
abandonedClôturé : jamais récupéré, ou sans nouvelles de la boutique pendant 60 jours. abandon_reason dit lequel (uncollected, no_news).

POST/v1/tickets

Créer un ticket

Crée un ticket à l’atelier. Son numéro suit ceux de l’app.

L’en-tête Idempotency-Key est obligatoire : si le réseau coupe, renvoyez la même requête avec la même clé, vous recevez le même ticket et replayed à true, jamais un doublon. Le numéro suit ceux de l’app.

En-têtes

Idempotency-Key string requis

Une clé unique par tentative : la même requête renvoyée donne le même ticket.

Corps JSON

service string requis

Le service, comme dans l’app.
type string optionnel

repair (réparation) ou prepare (commande). repair par défaut.
item string optionnel

L’article déposé.
description string optionnel

Une note pour l’atelier.
items array optionnel

Plusieurs articles (2 à 20) : label, service, price_minor.
client_id uuid optionnel

Un client qui connaît déjà la boutique.
client_phone string optionnel

Le numéro du client : le ticket lui est proposé.
price_minor integer optionnel

Le prix, en unités mineures.
deposit_minor integer optionnel

L’acompte, en unités mineures.
promised_at datetime optionnel

Le jour promis, en ISO 8601.
external_ref string optionnel

Votre référence, 64 caractères au plus.

client_phone ne relie personne : le ticket est proposé au compte qui porte ce numéro, qui l’accepte ou bloque la boutique. La réponse est la même qu’un compte existe ou non.

POST/v1/tickets

curl -X POST "https://api.tfa9adni.com/v1/tickets" \
  -H "Authorization: Bearer $TFA9ADNI_KEY" \
  -H "Idempotency-Key: caisse-000481" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "repair",
    "service": "Ressemelage",
    "item": "Bottes noires",
    "client_phone": "+216 22 123 456",
    "price_minor": 25000,
    "deposit_minor": 5000,
    "promised_at": "2026-10-02T16:00:00Z",
    "external_ref": "VTE-000481"
  }'

const res = await fetch("https://api.tfa9adni.com/v1/tickets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
    "Idempotency-Key": "caisse-000481",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "repair",
    "service": "Ressemelage",
    "item": "Bottes noires",
    "client_phone": "+216 22 123 456",
    "price_minor": 25000,
    "deposit_minor": 5000,
    "promised_at": "2026-10-02T16:00:00Z",
    "external_ref": "VTE-000481"
  }),
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/tickets");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
  "Idempotency-Key: caisse-000481",
  "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "type" => "repair",
  "service" => "Ressemelage",
  "item" => "Bottes noires",
  "client_phone" => "+216 22 123 456",
  "price_minor" => 25000,
  "deposit_minor" => 5000,
  "promised_at" => "2026-10-02T16:00:00Z",
  "external_ref" => "VTE-000481",
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.post(
    "https://api.tfa9adni.com/v1/tickets",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
        "Idempotency-Key": "caisse-000481",
    },
    json={
      "type": "repair",
      "service": "Ressemelage",
      "item": "Bottes noires",
      "client_phone": "+216 22 123 456",
      "price_minor": 25000,
      "deposit_minor": 5000,
      "promised_at": "2026-10-02T16:00:00Z",
      "external_ref": "VTE-000481"
    },
)
data = res.json()["data"]

Réponse201

{
  "success": true,
  "data": {
    "id": "3f0c9a2e-…",
    "number": 19,
    "number_label": "019",
    "state": "workshop",
    "outcome": null,
    "type": "repair",
    "service": "Ressemelage",
    "item": "Bottes noires",
    "description": null,
    "items": [],
    "money": {
      "currency": "TND",
      "decimals": 3,
      "price_minor": 25000,
      "deposit_minor": 5000,
      "remaining_minor": 20000,
      "before_minor": null
    },
    "quote": null,
    "promised_at": "2026-10-02T16:00:00Z",
    "delay": null,
    "part": null,
    "client": null,
    "client_phone": "21622123456",
    "tracking_code": "FKDE-E34F",
    "tracking_url": "https://api.tfa9adni.com/s/FKDEE34F",
    "photo_url": null,
    "created_at": "2026-09-30T09:12:04Z",
    "updated_at": "2026-09-30T09:12:04Z",
    "ready_at": null,
    "collected_at": null,
    "abandoned_at": null,
    "abandon_reason": null,
    "notified_at": null,
    "created_via": "api",
    "external_ref": "VTE-000481"
  }
}

GET/v1/tickets

Lister les tickets

Filtre, pagine et synchronise les tickets de la boutique.

Filtres : state (plusieurs, séparés par des virgules), number, client_id, phone, external_ref, created_after, created_before, updated_since. limit de 1 à 100 (50 par défaut). Si has_more est vrai, renvoyez next_cursor dans cursor. Avec updated_since, l’ordre suit la date de mise à jour : pratique pour synchroniser.

Paramètres d’URL

state string optionnel

Un ou plusieurs états, séparés par des virgules.
number integer optionnel

Le numéro du ticket.
phone string optionnel

Le numéro saisi sur le ticket.
external_ref string optionnel

Votre référence.
updated_since datetime optionnel

Seulement ce qui a changé depuis cette date.
limit integer optionnel

De 1 à 100, 50 par défaut.
cursor string optionnel

Le next_cursor de la page précédente.

GET/v1/tickets

curl "https://api.tfa9adni.com/v1/tickets?state=ready,impossible&limit=50" \
  -H "Authorization: Bearer $TFA9ADNI_KEY"

const res = await fetch("https://api.tfa9adni.com/v1/tickets?state=ready,impossible&limit=50", {
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
  },
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/tickets?state=ready,impossible&limit=50");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.get(
    "https://api.tfa9adni.com/v1/tickets?state=ready,impossible&limit=50",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": [
    {
      "id": "…",
      "number": 17,
      "number_label": "017",
      "state": "ready",
      "outcome": null,
      "type": "repair",
      "service": "Ressemelage",
      "item": "Bottes noires",
      "description": null,
      "items": [],
      "money": {
        "currency": "TND",
        "decimals": 3,
        "price_minor": 25000,
        "deposit_minor": 5000,
        "remaining_minor": 20000,
        "before_minor": null
      },
      "quote": null,
      "promised_at": "2026-10-02T16:00:00Z",
      "delay": null,
      "part": null,
      "client": null,
      "client_phone": "21622123456",
      "tracking_code": "FKDE-E34F",
      "tracking_url": "https://api.tfa9adni.com/s/FKDEE34F",
      "photo_url": null,
      "created_at": "2026-09-30T09:12:04Z",
      "updated_at": "2026-09-30T09:12:04Z",
      "ready_at": "2026-09-29T17:05:31Z",
      "collected_at": null,
      "abandoned_at": null,
      "abandon_reason": null,
      "notified_at": null,
      "created_via": "api",
      "external_ref": "VTE-000481"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJrIjoi…"
  }
}

GET/v1/tickets/{id}

Lire un ticket

Un ticket par son id. Celui d’une autre boutique répond 404.

GET/v1/tickets/{id}

curl "https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…" \
  -H "Authorization: Bearer $TFA9ADNI_KEY"

const res = await fetch("https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…", {
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
  },
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.get(
    "https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": {
    "id": "3f0c9a2e-…",
    "number": 19,
    "number_label": "019",
    "state": "workshop",
    "outcome": null,
    "type": "repair",
    "service": "Ressemelage",
    "item": "Bottes noires",
    "description": null,
    "items": [],
    "money": {
      "currency": "TND",
      "decimals": 3,
      "price_minor": 25000,
      "deposit_minor": 5000,
      "remaining_minor": 20000,
      "before_minor": null
    },
    "quote": null,
    "promised_at": "2026-10-02T16:00:00Z",
    "delay": null,
    "part": null,
    "client": null,
    "client_phone": "21622123456",
    "tracking_code": "FKDE-E34F",
    "tracking_url": "https://api.tfa9adni.com/s/FKDEE34F",
    "photo_url": null,
    "created_at": "2026-09-30T09:12:04Z",
    "updated_at": "2026-09-30T09:12:04Z",
    "ready_at": null,
    "collected_at": null,
    "abandoned_at": null,
    "abandon_reason": null,
    "notified_at": null,
    "created_via": "api",
    "external_ref": "VTE-000481"
  }
}

GET/v1/tickets/by-number/{n}

Trouver par numéro

Le ticket ouvert le plus récent qui porte ce numéro.

Les numéros repartent à 1 après 9999 : by-number renvoie le ticket ouvert le plus récent, sinon le plus récent, et meta.others liste les autres.

GET/v1/tickets/by-number/{n}

curl "https://api.tfa9adni.com/v1/tickets/by-number/19" \
  -H "Authorization: Bearer $TFA9ADNI_KEY"

const res = await fetch("https://api.tfa9adni.com/v1/tickets/by-number/19", {
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
  },
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/tickets/by-number/19");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.get(
    "https://api.tfa9adni.com/v1/tickets/by-number/19",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": {
    "id": "3f0c9a2e-…",
    "number": 19,
    "number_label": "019",
    "state": "workshop",
    "outcome": null,
    "type": "repair",
    "service": "Ressemelage",
    "item": "Bottes noires",
    "description": null,
    "items": [],
    "money": {
      "currency": "TND",
      "decimals": 3,
      "price_minor": 25000,
      "deposit_minor": 5000,
      "remaining_minor": 20000,
      "before_minor": null
    },
    "quote": null,
    "promised_at": "2026-10-02T16:00:00Z",
    "delay": null,
    "part": null,
    "client": null,
    "client_phone": "21622123456",
    "tracking_code": "FKDE-E34F",
    "tracking_url": "https://api.tfa9adni.com/s/FKDEE34F",
    "photo_url": null,
    "created_at": "2026-09-30T09:12:04Z",
    "updated_at": "2026-09-30T09:12:04Z",
    "ready_at": null,
    "collected_at": null,
    "abandoned_at": null,
    "abandon_reason": null,
    "notified_at": null,
    "created_via": "api",
    "external_ref": "VTE-000481"
  },
  "meta": {
    "others": [
      {
        "id": "91be…",
        "created_at": "2025-11-04T10:21:09Z"
      }
    ]
  }
}

POST/v1/tickets/{id}/status

Changer l’état

Prêt, impossible, retour à l’atelier ou récupéré.

Les mêmes règles que dans l’app : prêt ou impossible depuis l’atelier, récupéré depuis prêt ou impossible, retour à l’atelier depuis prêt ou impossible. Un ticket récupéré peut être rouvert pendant 24 h, ensuite la réponse est 409 avec reason REOPEN_WINDOW. Le client reçoit la même notification, et la fidélité compte comme dans l’app.

Corps JSON

status string requis

ready, impossible, workshop ou collected.

POST/v1/tickets/{id}/status

curl -X POST "https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…/status" \
  -H "Authorization: Bearer $TFA9ADNI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ready"
  }'

const res = await fetch("https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…/status", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "status": "ready"
  }),
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…/status");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
  "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "status" => "ready",
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.post(
    "https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…/status",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
    },
    json={
      "status": "ready"
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": {
    "id": "3f0c9a2e-…",
    "number": 19,
    "number_label": "019",
    "state": "ready",
    "outcome": null,
    "type": "repair",
    "service": "Ressemelage",
    "item": "Bottes noires",
    "description": null,
    "items": [],
    "money": {
      "currency": "TND",
      "decimals": 3,
      "price_minor": 25000,
      "deposit_minor": 5000,
      "remaining_minor": 20000,
      "before_minor": null
    },
    "quote": null,
    "promised_at": "2026-10-02T16:00:00Z",
    "delay": null,
    "part": null,
    "client": null,
    "client_phone": "21622123456",
    "tracking_code": "FKDE-E34F",
    "tracking_url": "https://api.tfa9adni.com/s/FKDEE34F",
    "photo_url": null,
    "created_at": "2026-09-30T09:12:04Z",
    "updated_at": "2026-10-01T15:40:12Z",
    "ready_at": "2026-10-01T15:40:12Z",
    "collected_at": null,
    "abandoned_at": null,
    "abandon_reason": null,
    "notified_at": null,
    "created_via": "api",
    "external_ref": "VTE-000481"
  }
}

POST/v1/tickets/{id}/notified

Client prévenu

Vous avez prévenu le client vous-même.

Vous avez prévenu le client vous-même, par SMS ou par téléphone ? Dites-le, la page du client l’affiche.

Corps JSON

channel string requis

sms, whatsapp ou call.

POST/v1/tickets/{id}/notified

curl -X POST "https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…/notified" \
  -H "Authorization: Bearer $TFA9ADNI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms"
  }'

const res = await fetch("https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…/notified", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "channel": "sms"
  }),
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…/notified");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
  "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "channel" => "sms",
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.post(
    "https://api.tfa9adni.com/v1/tickets/3f0c9a2e-…/notified",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
    },
    json={
      "channel": "sms"
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": {
    "id": "3f0c9a2e-…",
    "number": 19,
    "number_label": "019",
    "state": "ready",
    "outcome": null,
    "type": "repair",
    "service": "Ressemelage",
    "item": "Bottes noires",
    "description": null,
    "items": [],
    "money": {
      "currency": "TND",
      "decimals": 3,
      "price_minor": 25000,
      "deposit_minor": 5000,
      "remaining_minor": 20000,
      "before_minor": null
    },
    "quote": null,
    "promised_at": "2026-10-02T16:00:00Z",
    "delay": null,
    "part": null,
    "client": null,
    "client_phone": "21622123456",
    "tracking_code": "FKDE-E34F",
    "tracking_url": "https://api.tfa9adni.com/s/FKDEE34F",
    "photo_url": null,
    "created_at": "2026-09-30T09:12:04Z",
    "updated_at": "2026-10-01T15:42:00Z",
    "ready_at": "2026-10-01T15:40:12Z",
    "collected_at": null,
    "abandoned_at": null,
    "abandon_reason": null,
    "notified_at": "2026-10-01T15:42:00Z",
    "created_via": "api",
    "external_ref": "VTE-000481"
  }
}

Clients et fidélité

Une boutique ne voit que les clients qui la connaissent déjà : un ticket accepté chez elle ou un passage au comptoir. Chercher un numéro inconnu, ou le numéro d’un client qui a bloqué la boutique, donne la même réponse 404.

Le nom affiché respecte le choix du client : s’il cache son nom, vous voyez « Sana B. ».

GET/v1/clients

Chercher un client

Par téléphone, parmi les clients qui connaissent déjà la boutique.

Paramètres d’URL

phone string requis

Le numéro, au format international.

GET/v1/clients

curl "https://api.tfa9adni.com/v1/clients?phone=%2B21622123456" \
  -H "Authorization: Bearer $TFA9ADNI_KEY"

const res = await fetch("https://api.tfa9adni.com/v1/clients?phone=%2B21622123456", {
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
  },
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/clients?phone=%2B21622123456");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.get(
    "https://api.tfa9adni.com/v1/clients?phone=%2B21622123456",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": {
    "id": "8a21…",
    "display_name": "Sana B.",
    "tickets_open": 1,
    "tickets_total": 4
  }
}

GET/v1/clients/{id}

Lire un client

Nom affiché, tickets ouverts et au total, carte de fidélité.

GET/v1/clients/{id}

curl "https://api.tfa9adni.com/v1/clients/8a21…" \
  -H "Authorization: Bearer $TFA9ADNI_KEY"

const res = await fetch("https://api.tfa9adni.com/v1/clients/8a21…", {
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
  },
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/clients/8a21…");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.get(
    "https://api.tfa9adni.com/v1/clients/8a21…",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": {
    "id": "8a21…",
    "display_name": "Sana B.",
    "tickets_open": 1,
    "tickets_total": 4,
    "loyalty": {
      "balance": 4,
      "lifetime": 14,
      "rewards_available": 0,
      "rewards_redeemed": 1,
      "updated_at": "2026-09-30T09:14:40Z"
    }
  }
}

GET/v1/clients/{id}/loyalty

Carte de fidélité

Le programme de la boutique et la carte du client.

GET/v1/clients/{id}/loyalty

curl "https://api.tfa9adni.com/v1/clients/8a21…/loyalty" \
  -H "Authorization: Bearer $TFA9ADNI_KEY"

const res = await fetch("https://api.tfa9adni.com/v1/clients/8a21…/loyalty", {
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
  },
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/clients/8a21…/loyalty");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.get(
    "https://api.tfa9adni.com/v1/clients/8a21…/loyalty",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": {
    "program": {
      "enabled": true,
      "kind": "stamps",
      "name": "Carte Sami",
      "reward_text": "Un cirage offert",
      "target": 10
    },
    "card": {
      "balance": 4,
      "lifetime": 14,
      "rewards_available": 0,
      "rewards_redeemed": 1,
      "updated_at": "2026-09-30T09:14:40Z"
    }
  }
}

POST/v1/clients/{id}/loyalty/stamps

Ajouter des tampons

Ajoute de 1 à 10 tampons sur la carte.

Tampons et récompenses exigent une Idempotency-Key. 20 tampons au plus par client et par jour et par clé. Si la fidélité est éteinte, la réponse est 409 LOYALTY_OFF.

En-têtes

Idempotency-Key string requis

Obligatoire.

Corps JSON

count integer requis

De 1 à 10.

POST/v1/clients/{id}/loyalty/stamps

curl -X POST "https://api.tfa9adni.com/v1/clients/8a21…/loyalty/stamps" \
  -H "Authorization: Bearer $TFA9ADNI_KEY" \
  -H "Idempotency-Key: caisse-000481-stamp" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 1
  }'

const res = await fetch("https://api.tfa9adni.com/v1/clients/8a21…/loyalty/stamps", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
    "Idempotency-Key": "caisse-000481-stamp",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "count": 1
  }),
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/clients/8a21…/loyalty/stamps");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
  "Idempotency-Key: caisse-000481-stamp",
  "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "count" => 1,
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.post(
    "https://api.tfa9adni.com/v1/clients/8a21…/loyalty/stamps",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
        "Idempotency-Key": "caisse-000481-stamp",
    },
    json={
      "count": 1
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": {
    "program": {
      "enabled": true,
      "kind": "stamps",
      "name": "Carte Sami",
      "reward_text": "Un cirage offert",
      "target": 10
    },
    "card": {
      "balance": 5,
      "lifetime": 15,
      "rewards_available": 0,
      "rewards_redeemed": 1,
      "updated_at": "2026-10-01T15:43:10Z"
    }
  }
}

POST/v1/clients/{id}/loyalty/redeem

Utiliser une récompense

Consomme une récompense disponible sur la carte.

En-têtes

Idempotency-Key string requis

Obligatoire.

POST/v1/clients/{id}/loyalty/redeem

curl -X POST "https://api.tfa9adni.com/v1/clients/8a21…/loyalty/redeem" \
  -H "Authorization: Bearer $TFA9ADNI_KEY" \
  -H "Idempotency-Key: caisse-000481-reward"

const res = await fetch("https://api.tfa9adni.com/v1/clients/8a21…/loyalty/redeem", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TFA9ADNI_KEY}`,
    "Idempotency-Key": "caisse-000481-reward",
  },
});
const { data } = await res.json();

<?php
$ch = curl_init("https://api.tfa9adni.com/v1/clients/8a21…/loyalty/redeem");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . getenv("TFA9ADNI_KEY"),
  "Idempotency-Key: caisse-000481-reward",
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true)["data"];

import os, requests

res = requests.post(
    "https://api.tfa9adni.com/v1/clients/8a21…/loyalty/redeem",
    headers={
        "Authorization": f"Bearer {os.environ['TFA9ADNI_KEY']}",
        "Idempotency-Key": "caisse-000481-reward",
    },
)
data = res.json()["data"]

Réponse200

{
  "success": true,
  "data": {
    "card": {
      "balance": 0,
      "lifetime": 20,
      "rewards_available": 0,
      "rewards_redeemed": 2,
      "updated_at": "2026-10-01T15:44:02Z"
    }
  }
}

Webhooks

Donnez une adresse https dans l’app : Tfa9adni y envoie un POST à chaque étape d’un ticket. Un seul webhook par boutique.

ticket.createdUn ticket est créé, dans l’app ou par l’API.
ticket.readyLe ticket est prêt.
ticket.impossibleLe ticket est marqué impossible.
ticket.reopenedLe ticket revient à l’atelier.
client.notifiedLe client a été prévenu (WhatsApp, app, SMS, appel).
ticket.collectedLe client a récupéré son article.
ticket.abandonedLe ticket est clôturé : prêt et jamais récupéré (60 jours), ou resté à l’atelier sans nouvelles (60 jours). reason vaut uncollected ou no_news.
quote.acceptedLe client accepte un nouveau prix.
client.linkedUn client est relié au ticket.
pingLe bouton « Envoyer un test » de l’app.

Le corps

POST https://votre-caisse.example/webhooks/tfa9adni
Tfa9adni-Signature: t=1759223524,v1=5f2b9c…
Tfa9adni-Event-Id: evt_0d6e…
Tfa9adni-Event-Type: ticket.ready
Tfa9adni-Delivery-Attempt: 1

{
  "id": "evt_0d6e…",
  "type": "ticket.ready",
  "created_at": "2026-09-30T15:40:12Z",
  "api_version": "2026-10-01",
  "shop_id": "b7a4…",
  "data": {
    "ticket": {
      "id": "3f0c…",
      "number": 19,
      "state": "ready"
    }
  }
}

Vérifier la signature

Chaque envoi porte l’en-tête Tfa9adni-Signature : t est l’heure d’envoi en secondes, v1 le HMAC-SHA256 de « t.corps » avec le secret du webhook, en hexadécimal. Calculez-le sur le corps brut, comparez en temps constant, et refusez un t à plus de 5 minutes. Pendant 24 h après un changement de secret, deux v1 sont envoyés.

Bonnes pratiques

Répondez 2xx en moins de 10 secondes, puis traitez plus tard.
Un événement peut arriver deux fois : dédoublonnez sur id.
Ignorez les types que vous ne connaissez pas : de nouveaux arriveront.
Pour rattraper un trou, relisez GET /v1/tickets?updated_since=.

Sans réponse 2xx, nouvel essai après 1 min, 5 min, 30 min, 2 h, 6 h, 12 h et 24 h, puis l’envoi est abandonné. Après 20 échecs d’affilée sur 72 h, ou une réponse 410, le webhook s’éteint et le propriétaire est prévenu. Les redirections ne sont pas suivies, et les adresses privées sont refusées.

Vérifier la signature

import crypto from 'node:crypto';

// rawBody: the request body as received, before JSON.parse
export function verify(rawBody, header, secret) {
  const t = Number(header.match(/t=(\d+)/)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return header.split(',').filter((p) => p.startsWith('v1=')).some((p) => {
    const got = Buffer.from(p.slice(3), 'hex');
    return got.length === 32 && crypto.timingSafeEqual(got, Buffer.from(expected, 'hex'));
  });
}

<?php
function tfa9adni_verify(string $rawBody, string $header, string $secret): bool {
    if (!preg_match('/t=(\d+)/', $header, $m) || abs(time() - (int) $m[1]) > 300) return false;
    $expected = hash_hmac('sha256', $m[1] . '.' . $rawBody, $secret);
    preg_match_all('/v1=([0-9a-f]{64})/', $header, $sigs);
    foreach ($sigs[1] as $sig) if (hash_equals($expected, $sig)) return true;
    return false;
}

import hashlib, hmac, re, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    m = re.search(r"t=(\d+)", header)
    if not m or abs(time.time() - int(m.group(1))) > 300:
        return False
    expected = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s) for s in re.findall(r"v1=([0-9a-f]{64})", header))

Erreurs

En cas d’erreur, success est à false et error.code dit pourquoi. details.reason précise un 409.

400 VALIDATION_ERROR Corps ou paramètre invalide, details dit lequel.

401 UNAUTHENTICATED Clé absente, fausse ou révoquée.

403 FORBIDDEN La clé n’a pas ce droit (details.scope).

403 SHOP_NOT_APPROVED La boutique n’est pas encore validée.

403 ACCOUNT_DEACTIVATED La boutique est désactivée.

403 API_DISABLED L’API n’est pas encore ouverte pour cette boutique.

404 NOT_FOUND Introuvable pour cette boutique.

409 CONFLICT Action impossible dans cet état (details.reason).

422 PROFANITY Le texte contient un mot interdit.

429 TOO_MANY_ATTEMPTS Trop de requêtes ou de tickets, réessayez plus tard.

Limites

120 par minuteRequêtes par clé
30 par minuteÉcritures par clé
150 par heure, 600 par jourTickets par boutique (app et API ensemble)
60 par heure, 300 par jourRecherches de client par téléphone

Chaque réponse porte les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset. Au-delà, la réponse est 429 : attendez RateLimit-Reset secondes.