API
جهات الاتصال
استعرض معلومات جهات الاتصال وحدّثها
# جهات الاتصال > استعرض معلومات جهات الاتصال وحدّثها - الصفحة: https://tbit.app/ar/docs/api/contacts - عنوان URL الأساسي: `https://rest-api.tbit.app/v1` - المصادقة: ترويسة `X-API-Key` تحمل مفتاحك في كل طلب (تقرأه الأمثلة من متغير البيئة `TBIT_API_KEY`) ## نظرة عامة تمثّل جهات الاتصال الأشخاص الذين يتفاعلون مع وكيلك عبر قنوات مثل WhatsApp وInstagram والبريد الإلكتروني. لكل جهة اتصال ملف شخصي يحتوي على الاسم ومعرّفات القناة وبيانات وصفية اختيارية. ## نقاط النهاية | الطريقة | المسار | الوصف | | --- | --- | --- | | `GET` | `/v1/contacts` | سرد جهات الاتصال | | `GET` | `/v1/contacts/:id` | عرض تفاصيل جهة اتصال | | `POST` | `/v1/contacts` | إنشاء جهة اتصال | | `PATCH` | `/v1/contacts/:id` | تحديث جهة اتصال | | `PUT` | `/v1/contacts` | إنشاء أو تحديث حسب الهاتف أو البريد (upsert) | | `GET` | `/v1/contacts?phone=\|email=` | البحث عن جهات الاتصال حسب الهاتف أو البريد | | `PATCH` | `/v1/contacts/:id/attributes` | حفظ سمات جهة الاتصال | | `PUT` | `/v1/contacts/:id/stage` | وضع جهة الاتصال في مرحلة من مراحل قمع المبيعات | | `POST` | `/v1/contacts/:id/events` | إضافة حدث إلى خطها الزمني | ## معاملات الاستعلام تدعم نقطة نهاية السرد معاملات الاستعلام التالية: | المعامل | النوع | الوصف | | --- | --- | --- | | `limit` | `number` | النتائج لكل صفحة (الافتراضي: 20، الأقصى: 100) | | `offset` | `number` | عدد النتائج المراد تخطيها (الافتراضي: 0) | ## سرد جهات الاتصال `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?limit=20&offset=0" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## الحصول على تفاصيل جهة الاتصال `GET /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1` ```bash curl "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## تحديث جهة اتصال `PATCH /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1` ```bash curl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "profile_name": "Jane Doe", "email": "[email protected]", "notes": "Preferred language: English" }' ``` ## إنشاء جهة اتصال يتم التحقق من custom_attributes وفقًا لنفس قواعد «حفظ السمات» قبل كتابة أي شيء. إذا كانت قيمة غير صالحة، تستجيب 400 VALIDATION_ERROR مع سبب كل مفتاح (Invalid custom_attributes: «مفتاح»: «سبب») ولا يتم حفظ جهة الاتصال ولا سماتها. تُنشأ السمة غير الموجودة بنوع مستنتج من القيمة. `POST /v1/contacts` ```bash curl -X POST "https://rest-api.tbit.app/v1/contacts" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "channel_id": "573009876543", "channel_type": "whatsapp", "profile_name": "Jane Doe", "custom_attributes": { "city": "Bogota", "plan": "premium" } }' ``` ## إنشاء أو تحديث حسب الهاتف أو البريد تبحث عن جهة اتصال وكيلك عبر WhatsApp الخاص بها (E.164، مع «+» أو بدونه)، وإن لم تظهر، عبر بريدها الإلكتروني. إذا لم تكن موجودة، تُنشئها؛ وإذا كانت موجودة، تضيف إليها القناة الناقصة. لا تستبدل أبدًا اسمًا تمتلكه جهة الاتصال بالفعل. تستجيب 201 عند إنشائها و200 عند العثور عليها. إذا كان الهاتف والبريد الإلكتروني ينتميان إلى جهتي اتصال مختلفتين، تستجيب 409 CONTACT_CONFLICT مع المعرّفين ولا تكتب شيئًا. يتم التحقق من السمات التي ترسلها قبل لمس جهة الاتصال (انظر «حفظ السمات»). `PUT /v1/contacts` ```bash curl -X PUT "https://rest-api.tbit.app/v1/contacts" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone": "+573001234567", "email": "[email protected]", "first_name": "Ana", "last_name": "Pérez", "attributes": { "plan": "premium" } }' ``` الاستجابة: ```json { "data": { "created": true, "matched_by": null, "contact": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "first_name": "Ana", "last_name": "Pérez", "profile_name": "Ana Pérez", "phone": "573001234567", "email": "[email protected]", "channels": [ { "channel_type": "whatsapp", "channel_id": "573001234567" }, { "channel_type": "email", "channel_id": "[email protected]" } ], "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "stages": [ { "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "funnel_name": "Clientes", "stage": "prueba", "stage_name": "En prueba" } ], "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-08T15:00:00.000Z" } } } ``` ## البحث حسب الهاتف أو البريد تُرجع حتى 10 جهات اتصال من وكيلك لديها ذلك WhatsApp (بأي من كتاباته) أو ذلك البريد الإلكتروني، مع سماتها ومراحل قمع المبيعات التي توجد فيها. بدون phone أو email، تظل نقطة النهاية هي قائمة السرد المعتادة. `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?email=ana%40example.com" \ -H "X-API-Key: $TBIT_API_KEY" ``` الاستجابة: ```json { "data": [ { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "first_name": "Ana", "last_name": "Pérez", "profile_name": "Ana Pérez", "phone": "573001234567", "email": "[email protected]", "channels": [ { "channel_type": "whatsapp", "channel_id": "573001234567" }, { "channel_type": "email", "channel_id": "[email protected]" } ], "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "stages": [ { "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "funnel_name": "Clientes", "stage": "prueba", "stage_name": "En prueba" } ], "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-08T15:00:00.000Z" } ] } ``` ## حفظ السمات المفاتيح هي اسم السمة، كما يظهر في «بيانات جهة الاتصال» (بغض النظر عن حالة الأحرف أو علامات التشكيل). الكل أو لا شيء: إذا لم يوجد مفتاح، تستجيب 422 UNKNOWN_ATTRIBUTES مع القائمة في details.missing، وإذا كانت قيمة لا تناسب نوعها (خيار غير موجود في القائمة، رقم ليس رقمًا، تاريخ لا يمكن قراءته)، تستجيب 422 INVALID_VALUE؛ وفي كلتا الحالتين لا يتم حفظ أي منها. التواريخ: تُقبل أربع صيغ: تاريخ كامل (2026-11-14)، سنة وشهر (2026-11)، يوم وشهر بدون سنة (--11-14) أو الشهر فقط (--11). التاريخ مع وقت (2026-11-14T15:00:00Z) يُحفظ بيومه، ويعيده الـ API دائمًا بدون وقت (2026-11-14). قوائم الكائنات، مثل «التواريخ الخاصة»: يُتحقق من كل عنصر وفق مخططه. تستخدم حقول التاريخ تلك الصيغ الأربع، ولا يمكن أن تكون الحقول الإلزامية فارغة، ويجب أن تكون حقول الخيارات واحدة من القائمة (دون اعتبار لحالة الأحرف أو الحركات؛ تُحفظ مكتوبة كما في الخيار). مع create_missing: true تُنشأ الحقول الناقصة (يُستنتج النوع من القيمة). null يمحو القيمة. كل قيمة جديدة تُحتسب «حقلًا معبأ»: قمع بقاعدة على ذلك الحقل ينقل البطاقة تمامًا كما يفعل عندما تعبئه الذكاء الاصطناعي. `PATCH /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes` ```bash curl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "create_missing": false }' ``` الاستجابة: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "updated": [ "plan", "ciudad" ], "created_attributes": [] } } ``` ## الوضع في مرحلة من قمع يحدد القمع بـ funnel_id أو باسمه (funnel) والمرحلة بـ slug. إذا لم يكن جهة الاتصال في ذلك القمع يضيفها؛ وإذا كانت في مرحلة أخرى ينقلها؛ وإذا كانت هناك بالفعل لا يفعل شيئًا (changed: false). تُنفَّذ إجراءات دخول المرحلة ويُسجَّل في سجل جهة الاتصال. افتراضيًا لا يرن جرس الفريق: أرسل notify: true إذا أردت الإشعار. الأخطاء: 404 FUNNEL_NOT_FOUND و 422 UNKNOWN_STAGE (مع قائمة المراحل). `PUT /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage` ```bash curl -X PUT "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "funnel": "Clientes", "stage": "prueba" }' ``` الاستجابة: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "stage": "prueba", "previous_stage": "registrado", "changed": true } } ``` ## إضافة حدث إلى الخط الزمني يترك علامة فارقة في بطاقة جهة الاتصال، مع تاريخها (occurred_at، افتراضيًا الآن؛ لا يمكن أن يكون في المستقبل). مع idempotency_key لا يتكرر الحدث نفسه: إعادة الطلب تعيد 200 مع duplicate: true والحدث الأصلي. يقبل data حتى 20 مفتاحًا بنص أو رقم أو قيمة منطقية. جهات اتصال وكيل آخر تعيد 404، تمامًا كواحدة غير موجودة. `POST /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events` ```bash curl -X POST "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Empezó la prueba gratis", "description": "Termina el 15 de octubre", "occurred_at": "2026-10-08T15:00:00Z", "idempotency_key": "trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08", "data": { "plan": "monthly" } }' ``` الاستجابة: ```json { "data": { "id": "6ac85d7e32e0335e1dcac4fd", "contact_id": "64f1a2b3c4d5e6f7a8b9c0d1", "name": "Empezó la prueba gratis", "occurred_at": "2026-10-08T15:00:00.000Z", "duplicate": false } } ``` ## تنسيق الاستجابة تعيد نقاط نهاية السرد نتائج مقسّمة إلى صفحات: ```json { "data": [ { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "profile_name": "Jane Doe", "email": "[email protected]", "notes": "Preferred language: English", "channels": [ { "channel_id": "573001234567", "channel_type": "whatsapp" } ], "custom_attributes": { "city": "Bogota", "plan": "premium" }, "created_at": "2024-09-01T12:00:00Z", "updated_at": "2024-09-01T14:30:00Z" } ], "pagination": { "total": 50, "limit": 20, "offset": 0, "has_more": true } } ```تمثّل جهات الاتصال الأشخاص الذين يتفاعلون مع وكيلك عبر قنوات مثل WhatsApp وInstagram والبريد الإلكتروني. لكل جهة اتصال ملف شخصي يحتوي على الاسم ومعرّفات القناة وبيانات وصفية اختيارية.
| الطريقة | المسار | الوصف |
|---|---|---|
| GET | /v1/contacts | سرد جهات الاتصال |
| GET | /v1/contacts/:id | عرض تفاصيل جهة اتصال |
| POST | /v1/contacts | إنشاء جهة اتصال |
| PATCH | /v1/contacts/:id | تحديث جهة اتصال |
| PUT | /v1/contacts | إنشاء أو تحديث حسب الهاتف أو البريد (upsert) |
| GET | /v1/contacts?phone=|email= | البحث عن جهات الاتصال حسب الهاتف أو البريد |
| PATCH | /v1/contacts/:id/attributes | حفظ سمات جهة الاتصال |
| PUT | /v1/contacts/:id/stage | وضع جهة الاتصال في مرحلة من مراحل قمع المبيعات |
| POST | /v1/contacts/:id/events | إضافة حدث إلى خطها الزمني |
تدعم نقطة نهاية السرد معاملات الاستعلام التالية:
| المعامل | النوع | الوصف |
|---|---|---|
limit | number | النتائج لكل صفحة (الافتراضي: 20، الأقصى: 100) |
offset | number | عدد النتائج المراد تخطيها (الافتراضي: 0) |
/v1/contactscurl "https://rest-api.tbit.app/v1/contacts?limit=20&offset=0" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/contacts?limit=20&offset=0', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/contacts?limit=20&offset=0',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/contacts?limit=20&offset=0',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts?limit=20&offset=0');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1curl "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1curl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"profile_name": "Jane Doe",
"email": "[email protected]",
"notes": "Preferred language: English"
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1', {
method: 'PATCH',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
profile_name: 'Jane Doe',
email: '[email protected]',
notes: 'Preferred language: English',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
{
profile_name: 'Jane Doe',
email: '[email protected]',
notes: 'Preferred language: English',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'profile_name': 'Jane Doe',
'email': '[email protected]',
'notes': 'Preferred language: English',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'profile_name' => 'Jane Doe',
'email' => '[email protected]',
'notes' => 'Preferred language: English',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);يتم التحقق من custom_attributes وفقًا لنفس قواعد «حفظ السمات» قبل كتابة أي شيء. إذا كانت قيمة غير صالحة، تستجيب 400 VALIDATION_ERROR مع سبب كل مفتاح (Invalid custom_attributes: «مفتاح»: «سبب») ولا يتم حفظ جهة الاتصال ولا سماتها. تُنشأ السمة غير الموجودة بنوع مستنتج من القيمة.
/v1/contactscurl -X POST "https://rest-api.tbit.app/v1/contacts" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "573009876543",
"channel_type": "whatsapp",
"profile_name": "Jane Doe",
"custom_attributes": {
"city": "Bogota",
"plan": "premium"
}
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
channel_id: '573009876543',
channel_type: 'whatsapp',
profile_name: 'Jane Doe',
custom_attributes: {
city: 'Bogota',
plan: 'premium',
},
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/contacts',
{
channel_id: '573009876543',
channel_type: 'whatsapp',
profile_name: 'Jane Doe',
custom_attributes: {
city: 'Bogota',
plan: 'premium',
},
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/contacts',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'channel_id': '573009876543',
'channel_type': 'whatsapp',
'profile_name': 'Jane Doe',
'custom_attributes': {
'city': 'Bogota',
'plan': 'premium',
},
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'channel_id' => '573009876543',
'channel_type' => 'whatsapp',
'profile_name' => 'Jane Doe',
'custom_attributes' => [
'city' => 'Bogota',
'plan' => 'premium',
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);تبحث عن جهة اتصال وكيلك عبر WhatsApp الخاص بها (E.164، مع «+» أو بدونه)، وإن لم تظهر، عبر بريدها الإلكتروني. إذا لم تكن موجودة، تُنشئها؛ وإذا كانت موجودة، تضيف إليها القناة الناقصة. لا تستبدل أبدًا اسمًا تمتلكه جهة الاتصال بالفعل. تستجيب 201 عند إنشائها و200 عند العثور عليها.
إذا كان الهاتف والبريد الإلكتروني ينتميان إلى جهتي اتصال مختلفتين، تستجيب 409 CONTACT_CONFLICT مع المعرّفين ولا تكتب شيئًا. يتم التحقق من السمات التي ترسلها قبل لمس جهة الاتصال (انظر «حفظ السمات»).
/v1/contactscurl -X PUT "https://rest-api.tbit.app/v1/contacts" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"email": "[email protected]",
"first_name": "Ana",
"last_name": "Pérez",
"attributes": {
"plan": "premium"
}
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts', {
method: 'PUT',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
phone: '+573001234567',
email: '[email protected]',
first_name: 'Ana',
last_name: 'Pérez',
attributes: {
plan: 'premium',
},
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.put(
'https://rest-api.tbit.app/v1/contacts',
{
phone: '+573001234567',
email: '[email protected]',
first_name: 'Ana',
last_name: 'Pérez',
attributes: {
plan: 'premium',
},
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.put(
'https://rest-api.tbit.app/v1/contacts',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'phone': '+573001234567',
'email': '[email protected]',
'first_name': 'Ana',
'last_name': 'Pérez',
'attributes': {
'plan': 'premium',
},
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'phone' => '+573001234567',
'email' => '[email protected]',
'first_name' => 'Ana',
'last_name' => 'Pérez',
'attributes' => [
'plan' => 'premium',
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"created": true,
"matched_by": null,
"contact": {
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"first_name": "Ana",
"last_name": "Pérez",
"profile_name": "Ana Pérez",
"phone": "573001234567",
"email": "[email protected]",
"channels": [
{
"channel_type": "whatsapp",
"channel_id": "573001234567"
},
{
"channel_type": "email",
"channel_id": "[email protected]"
}
],
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"stages": [
{
"funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa",
"funnel_name": "Clientes",
"stage": "prueba",
"stage_name": "En prueba"
}
],
"created_at": "2026-10-01T12:00:00.000Z",
"updated_at": "2026-10-08T15:00:00.000Z"
}
}
}تُرجع حتى 10 جهات اتصال من وكيلك لديها ذلك WhatsApp (بأي من كتاباته) أو ذلك البريد الإلكتروني، مع سماتها ومراحل قمع المبيعات التي توجد فيها. بدون phone أو email، تظل نقطة النهاية هي قائمة السرد المعتادة.
/v1/contactscurl "https://rest-api.tbit.app/v1/contacts?email=ana%40example.com" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/contacts?email=ana%40example.com', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/contacts?email=ana%40example.com',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/contacts?email=ana%40example.com',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts?email=ana%40example.com');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": [
{
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"first_name": "Ana",
"last_name": "Pérez",
"profile_name": "Ana Pérez",
"phone": "573001234567",
"email": "[email protected]",
"channels": [
{
"channel_type": "whatsapp",
"channel_id": "573001234567"
},
{
"channel_type": "email",
"channel_id": "[email protected]"
}
],
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"stages": [
{
"funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa",
"funnel_name": "Clientes",
"stage": "prueba",
"stage_name": "En prueba"
}
],
"created_at": "2026-10-01T12:00:00.000Z",
"updated_at": "2026-10-08T15:00:00.000Z"
}
]
}المفاتيح هي اسم السمة، كما يظهر في «بيانات جهة الاتصال» (بغض النظر عن حالة الأحرف أو علامات التشكيل). الكل أو لا شيء: إذا لم يوجد مفتاح، تستجيب 422 UNKNOWN_ATTRIBUTES مع القائمة في details.missing، وإذا كانت قيمة لا تناسب نوعها (خيار غير موجود في القائمة، رقم ليس رقمًا، تاريخ لا يمكن قراءته)، تستجيب 422 INVALID_VALUE؛ وفي كلتا الحالتين لا يتم حفظ أي منها.
التواريخ: تُقبل أربع صيغ: تاريخ كامل (2026-11-14)، سنة وشهر (2026-11)، يوم وشهر بدون سنة (--11-14) أو الشهر فقط (--11). التاريخ مع وقت (2026-11-14T15:00:00Z) يُحفظ بيومه، ويعيده الـ API دائمًا بدون وقت (2026-11-14). قوائم الكائنات، مثل «التواريخ الخاصة»: يُتحقق من كل عنصر وفق مخططه. تستخدم حقول التاريخ تلك الصيغ الأربع، ولا يمكن أن تكون الحقول الإلزامية فارغة، ويجب أن تكون حقول الخيارات واحدة من القائمة (دون اعتبار لحالة الأحرف أو الحركات؛ تُحفظ مكتوبة كما في الخيار).
مع create_missing: true تُنشأ الحقول الناقصة (يُستنتج النوع من القيمة). null يمحو القيمة. كل قيمة جديدة تُحتسب «حقلًا معبأ»: قمع بقاعدة على ذلك الحقل ينقل البطاقة تمامًا كما يفعل عندما تعبئه الذكاء الاصطناعي.
/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributescurl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"create_missing": false
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes', {
method: 'PATCH',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
attributes: {
plan: 'premium',
ciudad: 'Bogotá',
},
create_missing: false,
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes',
{
attributes: {
plan: 'premium',
ciudad: 'Bogotá',
},
create_missing: false,
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'attributes': {
'plan': 'premium',
'ciudad': 'Bogotá',
},
'create_missing': False,
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'attributes' => [
'plan' => 'premium',
'ciudad' => 'Bogotá',
],
'create_missing' => false,
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"updated": [
"plan",
"ciudad"
],
"created_attributes": []
}
}يحدد القمع بـ funnel_id أو باسمه (funnel) والمرحلة بـ slug. إذا لم يكن جهة الاتصال في ذلك القمع يضيفها؛ وإذا كانت في مرحلة أخرى ينقلها؛ وإذا كانت هناك بالفعل لا يفعل شيئًا (changed: false). تُنفَّذ إجراءات دخول المرحلة ويُسجَّل في سجل جهة الاتصال.
افتراضيًا لا يرن جرس الفريق: أرسل notify: true إذا أردت الإشعار. الأخطاء: 404 FUNNEL_NOT_FOUND و 422 UNKNOWN_STAGE (مع قائمة المراحل).
/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stagecurl -X PUT "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"funnel": "Clientes",
"stage": "prueba"
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage', {
method: 'PUT',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
funnel: 'Clientes',
stage: 'prueba',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.put(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage',
{
funnel: 'Clientes',
stage: 'prueba',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.put(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'funnel': 'Clientes',
'stage': 'prueba',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'funnel' => 'Clientes',
'stage' => 'prueba',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa",
"stage": "prueba",
"previous_stage": "registrado",
"changed": true
}
}يترك علامة فارقة في بطاقة جهة الاتصال، مع تاريخها (occurred_at، افتراضيًا الآن؛ لا يمكن أن يكون في المستقبل). مع idempotency_key لا يتكرر الحدث نفسه: إعادة الطلب تعيد 200 مع duplicate: true والحدث الأصلي. يقبل data حتى 20 مفتاحًا بنص أو رقم أو قيمة منطقية.
جهات اتصال وكيل آخر تعيد 404، تمامًا كواحدة غير موجودة.
/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/eventscurl -X POST "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Empezó la prueba gratis",
"description": "Termina el 15 de octubre",
"occurred_at": "2026-10-08T15:00:00Z",
"idempotency_key": "trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08",
"data": {
"plan": "monthly"
}
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Empezó la prueba gratis',
description: 'Termina el 15 de octubre',
occurred_at: '2026-10-08T15:00:00Z',
idempotency_key: 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
data: {
plan: 'monthly',
},
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events',
{
name: 'Empezó la prueba gratis',
description: 'Termina el 15 de octubre',
occurred_at: '2026-10-08T15:00:00Z',
idempotency_key: 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
data: {
plan: 'monthly',
},
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'name': 'Empezó la prueba gratis',
'description': 'Termina el 15 de octubre',
'occurred_at': '2026-10-08T15:00:00Z',
'idempotency_key': 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
'data': {
'plan': 'monthly',
},
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Empezó la prueba gratis',
'description' => 'Termina el 15 de octubre',
'occurred_at' => '2026-10-08T15:00:00Z',
'idempotency_key' => 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
'data' => [
'plan' => 'monthly',
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"id": "6ac85d7e32e0335e1dcac4fd",
"contact_id": "64f1a2b3c4d5e6f7a8b9c0d1",
"name": "Empezó la prueba gratis",
"occurred_at": "2026-10-08T15:00:00.000Z",
"duplicate": false
}
}تعيد نقاط نهاية السرد نتائج مقسّمة إلى صفحات:
{
"data": [
{
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"profile_name": "Jane Doe",
"email": "[email protected]",
"notes": "Preferred language: English",
"channels": [
{
"channel_id": "573001234567",
"channel_type": "whatsapp"
}
],
"custom_attributes": {
"city": "Bogota",
"plan": "premium"
},
"created_at": "2024-09-01T12:00:00Z",
"updated_at": "2024-09-01T14:30:00Z"
}
],
"pagination": {
"total": 50,
"limit": 20,
"offset": 0,
"has_more": true
}
}