الواجهة البرمجية والتكامل

ينشئ نظام نقاط البيع أو ERP أو متجرك الإلكتروني التذاكر، ويغيّر حالتها، ويتلقى كل مرحلة عبر webhook. ويتلقى الزبائن الإشعارات نفسها كما من التطبيق.

متاحة عند الطلب خلال فترة الإطلاق: راسلنا ونفعّل واجهة API لمحلّك.

BASEhttps://api.tfa9adni.com/v1

مواصفات OpenAPI راسلنا

البداية

كل الطلبات تُرسل إلى هذا العنوان، عبر HTTPS، وبصيغة JSON في الاتجاهين.

لكل ردّ الغلاف نفسه: success و data، أو success بقيمة false مع error فيه رمز. المبالغ بالوحدات الصغرى (المليم، السنتيم) مع العملة وعدد الأرقام العشرية. التواريخ بصيغة ISO 8601 وبتوقيت UTC.

GET/v1/shop

اختبار الاتصال

يعيد المحل المرتبط بالمفتاح وعملته ومنطقته الزمنية وصلاحيات المفتاح.

أنشئ مفتاحًا في التطبيق: المحل › واجهة API. صاحب المحل وحده يستطيع ذلك. ثم جرّب الاتصال:

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"]

الرد200

{
  "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"
      ]
    }
  }
}

المصادقة

أرسل المفتاح في ترويسة Authorization. المفتاح لا يصل إلا إلى محله.

يظهر المفتاح مرة واحدة عند إنشائه. احفظه في خادمك أو في برنامج الصندوق، ولا تضعه في صفحة ويب أو في رسالة. المفتاح الملغى يتوقف عن العمل خلال دقيقة. خمسة مفاتيح فعّالة على الأكثر لكل محل.

صلاحيات المفتاح

tickets:readقراءة التذاكر.
tickets:writeإنشاء التذاكر وتغيير حالتها.
clients:readإيجاد زبون وقراءة بطاقة الوفاء.
loyalty:writeإضافة أختام واستعمال مكافأة.

« وصول كامل » يمنح الصلاحيات الأربع، و« قراءة فقط » يمنح tickets:read و clients:read.

التذاكر

حالات التذكرة

workshopفي الورشة، قيد العمل.
readyجاهزة، في انتظار الزبون.
impossibleتعذّر الإصلاح، والغرض في انتظار صاحبه.
collectedاستُلمت. يبيّن outcome هل كانت جاهزة أم تعذّر إصلاحها.
abandonedمغلقة: لم تُستلم أبدًا، أو دون أخبار من المحل طوال 60 يومًا. يوضّح abandon_reason السبب (uncollected أو no_news).

POST/v1/tickets

إنشاء تذكرة

ينشئ تذكرة في الورشة. رقمها يتبع أرقام التطبيق.

ترويسة Idempotency-Key إلزامية: إذا انقطعت الشبكة، أعد إرسال الطلب نفسه بالمفتاح نفسه فتصلك التذكرة نفسها مع replayed بقيمة true، ولا تُنشأ نسخة ثانية. الأرقام تتبع أرقام التطبيق.

الترويسات

Idempotency-Key string إلزامي

مفتاح فريد لكل محاولة: إعادة الطلب نفسه تعيد التذكرة نفسها.

محتوى JSON

service string إلزامي

الخدمة، كما في التطبيق.
type string اختياري

repair للإصلاح أو prepare للطلبية. القيمة الافتراضية repair.
item string اختياري

الغرض المودَع.
description string اختياري

ملاحظة للورشة.
items array اختياري

عدة أغراض (من 2 إلى 20): label و service و price_minor.
client_id uuid اختياري

زبون يعرف المحل من قبل.
client_phone string اختياري

رقم الزبون: تُعرض عليه التذكرة.
price_minor integer اختياري

السعر بالوحدات الصغرى.
deposit_minor integer اختياري

العربون بالوحدات الصغرى.
promised_at datetime اختياري

اليوم الموعود، بصيغة ISO 8601.
external_ref string اختياري

مرجعك الخاص، 64 حرفًا على الأكثر.

client_phone لا يربط أحدًا: تُعرض التذكرة على الحساب الذي يحمل هذا الرقم، فيقبلها أو يحظر المحل. الرد واحد سواء وُجد حساب أم لا.

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"]

الرد201

{
  "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

عرض التذاكر

تصفية تذاكر المحل وتقسيمها إلى صفحات ومزامنتها.

المرشحات: state (عدة قيم مفصولة بفواصل)، number، client_id، phone، external_ref، created_after، created_before، updated_since. قيمة limit من 1 إلى 100 (50 افتراضيًا). إذا كانت has_more صحيحة، أعد next_cursor في cursor. مع updated_since يتبع الترتيب وقت التحديث، وهذا مفيد للمزامنة.

معاملات الرابط

state string اختياري

حالة أو أكثر، مفصولة بفواصل.
number integer اختياري

رقم التذكرة.
phone string اختياري

الرقم المكتوب على التذكرة.
external_ref string اختياري

مرجعك.
updated_since datetime اختياري

ما تغيّر منذ هذا التاريخ فقط.
limit integer اختياري

من 1 إلى 100، و50 افتراضيًا.
cursor string اختياري

قيمة next_cursor من الصفحة السابقة.

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"]

الرد200

{
  "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}

قراءة تذكرة

تذكرة واحدة بمعرّفها. تذكرة محل آخر تعيد 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"]

الرد200

{
  "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}

البحث بالرقم

أحدث تذكرة مفتوحة تحمل هذا الرقم.

تعود الأرقام إلى 1 بعد 9999: يعيد by-number أحدث تذكرة مفتوحة، وإلا الأحدث، ويذكر meta.others البقية.

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"]

الرد200

{
  "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

تغيير الحالة

جاهز أو تعذّر أو العودة إلى الورشة أو تم الاستلام.

القواعد نفسها كما في التطبيق: جاهزة أو تعذّر الإصلاح من الورشة، مستلمة من جاهزة أو تعذّر الإصلاح، والعودة إلى الورشة من جاهزة أو تعذّر الإصلاح. يمكن إعادة فتح تذكرة مستلمة خلال 24 ساعة، وبعدها يكون الرد 409 مع reason بقيمة REOPEN_WINDOW. يتلقى الزبون الإشعار نفسه، ويُحتسب الوفاء كما في التطبيق.

محتوى JSON

status string إلزامي

ready أو impossible أو workshop أو 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"]

الرد200

{
  "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

تم إعلام الزبون

أعلمت الزبون بنفسك.

أعلمت الزبون بنفسك برسالة أو مكالمة؟ أخبرنا بذلك لتظهر في صفحته.

محتوى JSON

channel string إلزامي

sms أو whatsapp أو 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"]

الرد200

{
  "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"
  }
}

الزبائن والوفاء

لا يرى المحل إلا الزبائن الذين يعرفونه: تذكرة قُبلت عنده أو مرور بالمحل. البحث عن رقم غير معروف، أو عن رقم زبون حظر المحل، يعطي الرد نفسه 404.

الاسم الظاهر يحترم اختيار الزبون: إن أخفى اسمه ترى « سناء ب. ».

GET/v1/clients

البحث عن زبون

بالهاتف، بين الزبائن الذين يعرفون المحل من قبل.

معاملات الرابط

phone string إلزامي

الرقم بالصيغة الدولية.

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"]

الرد200

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

GET/v1/clients/{id}

قراءة زبون

الاسم الظاهر والتذاكر المفتوحة ومجموعها وبطاقة الوفاء.

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"]

الرد200

{
  "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

بطاقة الوفاء

برنامج المحل وبطاقة الزبون.

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"]

الرد200

{
  "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

إضافة أختام

يضيف من 1 إلى 10 أختام إلى البطاقة.

الأختام والمكافآت تتطلب Idempotency-Key. عشرون ختمًا على الأكثر لكل زبون في اليوم ولكل مفتاح. إذا كان برنامج الوفاء متوقفًا فالرد 409 LOYALTY_OFF.

الترويسات

Idempotency-Key string إلزامي

إلزامي.

محتوى JSON

count integer إلزامي

من 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"]

الرد200

{
  "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

استعمال مكافأة

يستعمل مكافأة متاحة في البطاقة.

الترويسات

Idempotency-Key string إلزامي

إلزامي.

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"]

الرد200

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

Webhooks

أدخل عنوان https في التطبيق: يرسل إليه تفقدني طلب POST عند كل مرحلة من التذكرة. webhook واحد لكل محل.

ticket.createdأُنشئت تذكرة، من التطبيق أو عبر الواجهة البرمجية.
ticket.readyالتذكرة جاهزة.
ticket.impossibleسُجّلت التذكرة كمتعذّرة الإصلاح.
ticket.reopenedعادت التذكرة إلى الورشة.
client.notifiedأُعلِم الزبون (واتساب، التطبيق، رسالة، مكالمة).
ticket.collectedاستلم الزبون غرضه.
ticket.abandonedأُغلقت التذكرة: جاهزة ولم تُستلم (60 يومًا)، أو بقيت في الورشة دون أخبار (60 يومًا). قيمة reason هي uncollected أو no_news.
quote.acceptedقبل الزبون سعرًا جديدًا.
client.linkedرُبط زبون بالتذكرة.
pingزر « إرسال تجربة » في التطبيق.

محتوى الطلب

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"
    }
  }
}

التحقق من التوقيع

يحمل كل إرسال ترويسة Tfa9adni-Signature: قيمة t هي وقت الإرسال بالثواني، و v1 هي HMAC-SHA256 للنص « t.body » بسرّ الـ webhook، بالنظام الست عشري. احسبها على المحتوى الخام، وقارن في زمن ثابت، وارفض أي t يبعد أكثر من 5 دقائق. خلال 24 ساعة بعد تغيير السرّ تُرسل قيمتان v1.

ممارسات جيدة

أجب بـ 2xx في أقل من 10 ثوانٍ، ثم عالج الطلب لاحقًا.
قد يصل الحدث مرتين: استبعد المكرّر حسب id.
تجاهل الأنواع التي لا تعرفها: ستُضاف أنواع جديدة.
لسدّ أي نقص، أعد قراءة GET /v1/tickets?updated_since=.

دون ردّ 2xx، تُعاد المحاولة بعد دقيقة، ثم 5 دقائق، و30 دقيقة، وساعتين، و6 ساعات، و12 ساعة، و24 ساعة، ثم يُترك الإرسال. بعد 20 إخفاقًا متتاليًا خلال 72 ساعة، أو ردّ 410، يتوقف الـ webhook ويُعلَم صاحب المحل. لا تُتبع التحويلات، وتُرفض العناوين الخاصة.

التحقق من التوقيع

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))

الأخطاء

عند الخطأ تكون success بقيمة false ويبيّن error.code السبب. ويوضّح details.reason سبب الرد 409.

400 VALIDATION_ERROR محتوى أو مُعامِل غير صالح، ويبيّن details أيّها.

401 UNAUTHENTICATED مفتاح غائب أو خاطئ أو ملغى.

403 FORBIDDEN المفتاح لا يملك هذه الصلاحية (details.scope).

403 SHOP_NOT_APPROVED المحل لم يُوثَّق بعد.

403 ACCOUNT_DEACTIVATED المحل معطّل.

403 API_DISABLED الواجهة البرمجية غير مفتوحة لهذا المحل بعد.

404 NOT_FOUND غير موجود لهذا المحل.

409 CONFLICT غير ممكن في هذه الحالة (details.reason).

422 PROFANITY النص يحتوي على كلمة ممنوعة.

429 TOO_MANY_ATTEMPTS طلبات أو تذاكر كثيرة، أعد المحاولة لاحقًا.

الحدود

120 في الدقيقةالطلبات لكل مفتاح
30 في الدقيقةعمليات الكتابة لكل مفتاح
150 في الساعة، 600 في اليومالتذاكر لكل محل (التطبيق والواجهة معًا)
60 في الساعة، 300 في اليومالبحث عن زبون برقم الهاتف

يحمل كل ردّ الترويسات RateLimit-Limit و RateLimit-Remaining و RateLimit-Reset. بعد تجاوز الحد يكون الرد 429: انتظر عدد الثواني في RateLimit-Reset.