احراز هویت

کلید API را از پنل ← کلیدهای API بسازید و در هدر هر درخواست بفرستید. بدنه‌ی درخواست می‌تواند JSON یا فرم معمولی (application/x-www-form-urlencoded) باشد. پاسخ همیشه JSON است.

Authorization: Bearer vrm_live_xxxxxxxxxxxxxxxx
Base URL: https://verimo.ir

کلید را فقط روی سرور نگه دارید، نه در اپ موبایل یا کد مرورگر. اپ شما باید از سرور خودتان درخواست کد بدهد.

خطاها

خطاها با کد HTTP مناسب و بدنه‌ی { "error": "code", ... } برمی‌گردند.

ارسال کد تأیید

ارسال یک کد جدید برای همان شماره، کد قبلی را باطل می‌کند. پاسخ فوری است و ارسال در پس‌زمینه انجام می‌شود.

curl -X POST https://verimo.ir/v1/verify/send \
  -H "Authorization: Bearer $VERIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"09121234567"}'

const r = await fetch("https://verimo.ir/v1/verify/send", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VERIMO_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ phone: "09121234567" }),
});
const v = await r.json(); // { id, status: "pending", ... }

$ch = curl_init("https://verimo.ir/v1/verify/send");
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("VERIMO_KEY")],
  CURLOPT_POSTFIELDS => ["phone" => "09121234567"],
]);
$v = json_decode(curl_exec($ch), true);

import os, requests
v = requests.post("https://verimo.ir/v1/verify/send",
    headers={"Authorization": f"Bearer {os.environ['VERIMO_KEY']}"},
    json={"phone": "09121234567"}).json()

201 Created
{
  "id": "5f0c2a8e-…",
  "phone": "989121234567",
  "status": "pending",
  "channel": null,          // بعد از ارسال: "whatsapp" یا "sms"
  "channels": [],
  "delivered": false,
  "failure": null,
  "expires_at": "2026-10-18T09:15:00.000Z",
  "created_at": "2026-10-18T09:10:00.000Z",
  "verified_at": null
}

بررسی کد

code به‌همراه id (از پاسخ send) یا phone (آخرین کد همان شماره). هر کد حداکثر 5 بار قابل امتحان است.

curl -X POST https://verimo.ir/v1/verify/check \
  -H "Authorization: Bearer $VERIMO_KEY" \
  -d phone=09121234567 -d code=48213

const r = await fetch("https://verimo.ir/v1/verify/check", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VERIMO_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ phone: "09121234567", code: req.body.code }),
});
const { valid } = await r.json();
if (valid) { /* کاربر را وارد کنید */ }

$res = json_decode(curl_exec($ch), true);
if ($res["valid"]) { /* login */ }

200 OK
{ "valid": true,  "status": "approved", "verification": { … } }
{ "valid": false, "status": "pending",  "attempts_left": 3, "verification": { … } }
{ "valid": false, "status": "expired" | "failed" | "canceled", … }

پاسخ «کد اشتباه» هم ۲۰۰ است؛ فقط valid را بررسی کنید.

وضعیت یک کد

برای نمایش «کد از واتساپ فرستاده شد» یا «از پیامک» به کاربر: فیلدهای channel و delivered.

واتساپ: اتصال شماره

هر شماره‌ی واتساپ شما یک instance است. آن را بسازید، QR را با گوشی اسکن کنید (واتساپ ← دستگاه‌های متصل ← اتصال دستگاه) و بعد پیام بفرستید. همین کار از پنل ← واتساپ هم بدون کد ممکن است.

واتساپ: ارسال پیام

curl -X POST https://verimo.ir/v1/whatsapp/messages \
  -H "Authorization: Bearer $VERIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instance_id":"8d1c…","to":"09121234567","text":"سفارش شما ارسال شد"}'

{
  "instance_id": "8d1c…",
  "to": "09121234567",
  "image_url": "https://example.com/invoice.png",
  "text": "فاکتور سفارش #1042"
}

to: موبایل ایران یا هر شماره‌ی بین‌المللی (فقط رقم). status پیام: sent ← delivered ← read یا failed. وضعیت: GET /v1/whatsapp/messages/{id}؛ فهرست: GET /v1/whatsapp/messages?instance_id=…

Webhook

اگر برای شماره webhook_url گذاشته باشید، این رویدادها را با POST (JSON) می‌فرستیم و تا ۸ بار با فاصله‌ی افزایشی تکرار می‌کنیم تا پاسخ 2xx بگیریم:

{ "event": "message.received", "instance_id": "…",
  "message": { "id": "…", "from": "989121234567", "name": "علی", "text": "سلام", "type": "text", "timestamp": 1760000000 } }

{ "event": "message.status", "instance_id": "…", "message_id": "…", "status": "delivered" }

{ "event": "instance.status", "instance_id": "…", "status": "open", "phone": "989121112233" }

هر درخواست امضا دارد: X-Verimo-Signature = HMAC-SHA256 با «کلید امضای webhook» (در تنظیمات پنل) روی {X-Verimo-Timestamp}.{body}.

import crypto from "node:crypto";
function verimoSigned(req, rawBody) {
  const ts = req.headers["x-verimo-timestamp"];
  const sig = crypto.createHmac("sha256", process.env.VERIMO_WEBHOOK_SECRET)
    .update(`${ts}.${rawBody}`).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300 &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.headers["x-verimo-signature"] ?? ""));
}

$raw = file_get_contents("php://input");
$ts  = $_SERVER["HTTP_X_VERIMO_TIMESTAMP"] ?? "";
$sig = hash_hmac("sha256", $ts . "." . $raw, getenv("VERIMO_WEBHOOK_SECRET"));
$ok  = hash_equals($sig, $_SERVER["HTTP_X_VERIMO_SIGNATURE"] ?? "") && abs(time() - (int)$ts) < 300;

موجودی

{ "name": "…", "brand": "فروشگاه من", "balance": 98500, "currency": "IRT",
  "prices": { "verify": 150, "sms": 120, "whatsapp_message": 40 } }

محدودیت‌ها

• هر شماره: یک کد هر 60 ثانیه و حداکثر 5 کد در ساعت
• هر حساب: حداکثر 60 کد در دقیقه (برای حجم بالاتر با پشتیبانی تماس بگیرید)
• هر کد: حداکثر 5 بار امتحان
• واتساپ: حداکثر 20 پیام در دقیقه برای هر شماره، حداکثر 3 شماره برای هر حساب