انتقل إلى المحتوى
القائمة

ابحث في الموقع

اكتب للبحث في الأدلة والمدونة والـ API والمنتج.

↑ ↓ للتنقل · Enter للفتح · Esc للإغلاق

مرجع الـ API

API

رموز OTP عبر واتساب

أرسل رموز التحقق عبر واتساب مع زر «نسخ الرمز»

عرض بصيغة Markdown

تُنشئ 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
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
  }'
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.

GET/v1/otp/template
curl "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). تتضمن الاستجابة الرمز ليستخدمه نظامك؛ ولا يُحفظ الرمز في سجل المحادثة.

POST/v1/otp/send
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
  }'
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 }.

POST/v1/otp/verify
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"
  }'
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_APPROVED409قالب OTP لهذه اللغة غير موجود أو لم توافق عليه Meta بعد
OTP_RATE_LIMITED429رموز كثيرة لهذا الهاتف؛ أعد المحاولة بعد Retry-After
META_ERROR422رفضت Meta القالب (مثلًا نشاط تجاري غير موثق)
SEND_FAILED422لم تقبل Meta إرسال الرسالة
VALIDATION_ERROR400جسم طلب غير صالح: الهاتف أو الطول أو اللغة أو الرمز
NOT_FOUND404خط واتساب غير موجود أو لا يتبع هذا الوكيل