API
رموز OTP عبر واتساب
أرسل رموز التحقق عبر واتساب مع زر «نسخ الرمز»
# رموز OTP عبر واتساب > أرسل رموز التحقق عبر واتساب مع زر «نسخ الرمز» - الصفحة: https://tbit.app/ar/docs/api/otp - عنوان URL الأساسي: `https://rest-api.tbit.app/v1` - المصادقة: ترويسة `X-API-Key` تحمل مفتاحك في كل طلب (تقرأه الأمثلة من متغير البيئة `TBIT_API_KEY`) ## نظرة عامة تُنشئ TBit رمزًا رقميًا وترسله عبر واتساب من خط وكيلك باستخدام قالب مصادقة (زر «نسخ الرمز») ثم تعيده إليك في الاستجابة. يمكنك التحقق منه في نظامك أو ترك TBit تتحقق منه عبر /v1/otp/verify. رموز OTP مجانية ولا تُحتسب من حصة القوالب. ## نقاط النهاية | الطريقة | المسار | الوصف | | --- | --- | --- | | `POST` | `/v1/otp/template` | إنشاء قالب المصادقة | | `GET` | `/v1/otp/template` | حالة قوالب OTP | | `POST` | `/v1/otp/send` | إنشاء رمز وإرساله | | `POST` | `/v1/otp/verify` | التحقق من رمز (اختياري) | ## المتطلبات تحتاج إلى خط واتساب متصل بوكيلك. لا تسمح Meta بقوالب المصادقة إلا للشركات الموثقة في Meta Business (إعدادات النشاط التجاري ← مركز الأمان)؛ وبدون التوثيق يعيد إنشاء القالب الخطأ META_ERROR مع الرسالة «does not have permission to create message template». يُرسل الرمز من رقم خط الوكيل الذي يملك مفتاح الـ API. ## إنشاء القالب مرة واحدة لكل لغة (اسمه tbit_otp_<اللغة>). النص تكتبه Meta ولا يمكن تخصيصه: الرمز وتوصية أمان ومدة الصلاحية في التذييل. حقول اختيارية: language (الافتراضي es) وcode_expiration_minutes (من 1 إلى 90، الافتراضي 10) وchannel_id إذا كان للوكيل أكثر من خط. إذا كان القالب موجودًا تعود الاستجابة created: false مع حالته. عادةً توافق Meta عليه خلال ثوانٍ. `POST /v1/otp/template` ```bash curl -X POST "https://rest-api.tbit.app/v1/otp/template" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "language": "es", "code_expiration_minutes": 10 }' ``` الاستجابة: ```json { "data": { "created": true, "template": { "id": "6ac60aeaa2a9ed0cd9ca7fd4", "name": "tbit_otp_es", "language": "es", "status": "PENDING", "rejected_reason": null, "code_expiration_minutes": 10, "channel_id": "691deef351c7513d0c6a2a6f" } } } ``` ## حالة القالب يعرض قوالب OTP الخاصة بالوكيل. القوالب غير المعتمدة بعد يُستعلم عنها مباشرةً لدى Meta: قيمة status هي PENDING أو APPROVED أو REJECTED. `GET /v1/otp/template` ```bash curl "https://rest-api.tbit.app/v1/otp/template" \ -H "X-API-Key: $TBIT_API_KEY" ``` الاستجابة: ```json { "data": [ { "id": "6ac60aeaa2a9ed0cd9ca7fd4", "name": "tbit_otp_es", "language": "es", "status": "APPROVED", "rejected_reason": null, "code_expiration_minutes": 10, "channel_id": "691deef351c7513d0c6a2a6f" } ] } ``` ## إرسال رمز الحقل to هو رقم الهاتف مع رمز الدولة (المسافات والشرطات و+ مقبولة). length من 4 إلى 8 أرقام (الافتراضي 6) وlanguage يحدد القالب (الافتراضي es). تتضمن الاستجابة الرمز ليستخدمه نظامك؛ ولا يُحفظ الرمز في سجل المحادثة. `POST /v1/otp/send` ```bash curl -X POST "https://rest-api.tbit.app/v1/otp/send" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+57 300 123 4567", "length": 6 }' ``` الاستجابة: ```json { "data": { "request_id": "be4ffa6c-f45a-4410-b38a-882bd3edd9b3", "to": "573001234567", "code": "054381", "expires_in_minutes": 10, "expires_at": "2026-10-07T09:17:26.278Z" } } ``` ## التحقق من رمز اختياري: إذا لم ترغب في حفظ الرمز، تتحقق منه TBit. كل رمز صالح لمرة واحدة وتنتهي صلاحيته مع القالب. بعد 5 محاولات خاطئة يُلغى ويجب طلب رمز جديد. قد تكون قيمة reason هي invalid_code (مع attempts_left) أو too_many_attempts أو expired_or_not_found. الرمز الصحيح يعيد { "valid": true }. `POST /v1/otp/verify` ```bash curl -X POST "https://rest-api.tbit.app/v1/otp/verify" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "573001234567", "code": "054381" }' ``` الاستجابة: ```json { "data": { "valid": false, "reason": "invalid_code", "attempts_left": 4 } } ``` ## الحدود لكل هاتف: إرسال واحد كل 30 ثانية و5 في الساعة. عند تجاوز ذلك تعود الاستجابة 429 OTP_RATE_LIMITED مع الترويسة Retry-After. ويُطبق أيضًا الحد العام البالغ 100 طلب في الدقيقة لكل مفتاح API. ## الأخطاء | الرمز | HTTP | متى | | --- | --- | --- | | `TEMPLATE_NOT_APPROVED` | 409 | قالب OTP لهذه اللغة غير موجود أو لم توافق عليه Meta بعد | | `OTP_RATE_LIMITED` | 429 | رموز كثيرة لهذا الهاتف؛ أعد المحاولة بعد Retry-After | | `META_ERROR` | 422 | رفضت Meta القالب (مثلًا نشاط تجاري غير موثق) | | `SEND_FAILED` | 422 | لم تقبل Meta إرسال الرسالة | | `VALIDATION_ERROR` | 400 | جسم طلب غير صالح: الهاتف أو الطول أو اللغة أو الرمز | | `NOT_FOUND` | 404 | خط واتساب غير موجود أو لا يتبع هذا الوكيل |تُنشئ TBit رمزًا رقميًا وترسله عبر واتساب من خط وكيلك باستخدام قالب مصادقة (زر «نسخ الرمز») ثم تعيده إليك في الاستجابة. يمكنك التحقق منه في نظامك أو ترك TBit تتحقق منه عبر /v1/otp/verify. رموز OTP مجانية ولا تُحتسب من حصة القوالب.
| الطريقة | المسار | الوصف |
|---|---|---|
| POST | /v1/otp/template | إنشاء قالب المصادقة |
| GET | /v1/otp/template | حالة قوالب OTP |
| POST | /v1/otp/send | إنشاء رمز وإرساله |
| POST | /v1/otp/verify | التحقق من رمز (اختياري) |
تحتاج إلى خط واتساب متصل بوكيلك. لا تسمح Meta بقوالب المصادقة إلا للشركات الموثقة في Meta Business (إعدادات النشاط التجاري ← مركز الأمان)؛ وبدون التوثيق يعيد إنشاء القالب الخطأ META_ERROR مع الرسالة «does not have permission to create message template». يُرسل الرمز من رقم خط الوكيل الذي يملك مفتاح الـ API.
مرة واحدة لكل لغة (اسمه tbit_otp_<اللغة>). النص تكتبه Meta ولا يمكن تخصيصه: الرمز وتوصية أمان ومدة الصلاحية في التذييل. حقول اختيارية: language (الافتراضي es) وcode_expiration_minutes (من 1 إلى 90، الافتراضي 10) وchannel_id إذا كان للوكيل أكثر من خط. إذا كان القالب موجودًا تعود الاستجابة created: false مع حالته. عادةً توافق Meta عليه خلال ثوانٍ.
/v1/otp/templatecurl -X POST "https://rest-api.tbit.app/v1/otp/template" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"language": "es",
"code_expiration_minutes": 10
}'const response = await fetch('https://rest-api.tbit.app/v1/otp/template', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
language: 'es',
code_expiration_minutes: 10,
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/otp/template',
{
language: 'es',
code_expiration_minutes: 10,
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/otp/template',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'language': 'es',
'code_expiration_minutes': 10,
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/template');
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([
'language' => 'es',
'code_expiration_minutes' => 10,
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"created": true,
"template": {
"id": "6ac60aeaa2a9ed0cd9ca7fd4",
"name": "tbit_otp_es",
"language": "es",
"status": "PENDING",
"rejected_reason": null,
"code_expiration_minutes": 10,
"channel_id": "691deef351c7513d0c6a2a6f"
}
}
}يعرض قوالب OTP الخاصة بالوكيل. القوالب غير المعتمدة بعد يُستعلم عنها مباشرةً لدى Meta: قيمة status هي PENDING أو APPROVED أو REJECTED.
/v1/otp/templatecurl "https://rest-api.tbit.app/v1/otp/template" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/otp/template', {
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/otp/template',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/otp/template',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/template');
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": "6ac60aeaa2a9ed0cd9ca7fd4",
"name": "tbit_otp_es",
"language": "es",
"status": "APPROVED",
"rejected_reason": null,
"code_expiration_minutes": 10,
"channel_id": "691deef351c7513d0c6a2a6f"
}
]
}الحقل to هو رقم الهاتف مع رمز الدولة (المسافات والشرطات و+ مقبولة). length من 4 إلى 8 أرقام (الافتراضي 6) وlanguage يحدد القالب (الافتراضي es). تتضمن الاستجابة الرمز ليستخدمه نظامك؛ ولا يُحفظ الرمز في سجل المحادثة.
/v1/otp/sendcurl -X POST "https://rest-api.tbit.app/v1/otp/send" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+57 300 123 4567",
"length": 6
}'const response = await fetch('https://rest-api.tbit.app/v1/otp/send', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+57 300 123 4567',
length: 6,
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/otp/send',
{
to: '+57 300 123 4567',
length: 6,
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/otp/send',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+57 300 123 4567',
'length': 6,
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/send');
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([
'to' => '+57 300 123 4567',
'length' => 6,
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"request_id": "be4ffa6c-f45a-4410-b38a-882bd3edd9b3",
"to": "573001234567",
"code": "054381",
"expires_in_minutes": 10,
"expires_at": "2026-10-07T09:17:26.278Z"
}
}اختياري: إذا لم ترغب في حفظ الرمز، تتحقق منه TBit. كل رمز صالح لمرة واحدة وتنتهي صلاحيته مع القالب. بعد 5 محاولات خاطئة يُلغى ويجب طلب رمز جديد. قد تكون قيمة reason هي invalid_code (مع attempts_left) أو too_many_attempts أو expired_or_not_found. الرمز الصحيح يعيد { "valid": true }.
/v1/otp/verifycurl -X POST "https://rest-api.tbit.app/v1/otp/verify" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "573001234567",
"code": "054381"
}'const response = await fetch('https://rest-api.tbit.app/v1/otp/verify', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '573001234567',
code: '054381',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/otp/verify',
{
to: '573001234567',
code: '054381',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/otp/verify',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '573001234567',
'code': '054381',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/verify');
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([
'to' => '573001234567',
'code' => '054381',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"valid": false,
"reason": "invalid_code",
"attempts_left": 4
}
}لكل هاتف: إرسال واحد كل 30 ثانية و5 في الساعة. عند تجاوز ذلك تعود الاستجابة 429 OTP_RATE_LIMITED مع الترويسة Retry-After. ويُطبق أيضًا الحد العام البالغ 100 طلب في الدقيقة لكل مفتاح API.
| الرمز | HTTP | متى |
|---|---|---|
TEMPLATE_NOT_APPROVED | 409 | قالب OTP لهذه اللغة غير موجود أو لم توافق عليه Meta بعد |
OTP_RATE_LIMITED | 429 | رموز كثيرة لهذا الهاتف؛ أعد المحاولة بعد Retry-After |
META_ERROR | 422 | رفضت Meta القالب (مثلًا نشاط تجاري غير موثق) |
SEND_FAILED | 422 | لم تقبل Meta إرسال الرسالة |
VALIDATION_ERROR | 400 | جسم طلب غير صالح: الهاتف أو الطول أو اللغة أو الرمز |
NOT_FOUND | 404 | خط واتساب غير موجود أو لا يتبع هذا الوكيل |