API de gateway SMS pentru codurile de verificare de pe propriile tale numere

Autentificare

Creează o cheie în panou, la API REST. Începe cu bsk_live_ și este afișată o singură dată, așa că păstreaz-o ca secret, de exemplu în BUSYSMS_API_KEY. Trimite-o la fiecare cerere, în oricare dintre aceste anteturi:

Authorization: Bearer bsk_live_xxxxxxxx
# or
X-API-Key: bsk_live_xxxxxxxx

O cheie aparține unei persoane și vede doar telefoanele acelei persoane, plus numerele partajate cu ea. O cheie creată în panou poate citi coduri, lista telefoanele și numerele tale, citi starea contului și trezi un telefon pus pe pauză; nu poate șterge un dispozitiv și nu poate gestiona contul, așa că o cheie scursă nu poate schimba ce plătești. Totuși, ține cheile pe server: oricine are una îți poate citi codurile.

Endpointuri

URL de bază https://busysms.net/api/v1. Cererile sunt simple GET-uri, iar răspunsurile sunt JSON.

• GET /codes: cel mai nou cod de pe toate numerele tale. Cu timeoutMs așteaptă următorul, până la 90 de secunde. Filtre: service, phone, deviceId.
• GET /devices: telefoanele tale gateway cu id, nume, număr, platformă și starea online, verificat și pe pauză, plus numerele partajate cu tine.
• GET /numbers: doar numerele tale, fiecare cu canReceive și, când nu poate primi, un reason: unverified, verification_pending, inactive, gateway_off sau phone_unreachable.
• GET /devices/:id/messages: mesajele capturate recent pe un telefon, cele mai noi primele. Acceptă service, limit (implicit 50, cel mult 200) și since.
• GET /account: contul tău, cu starea perioadei gratuite și a abonamentului.

Așteaptă un cod: curl, Node.js și Python

Apelul de care au nevoie cele mai multe integrări este un long-poll imediat după ce ceva declanșează un SMS. Pornește așteptarea, declanșează autentificarea, iar cererea revine imediat ce sosește un cod potrivit.

curl -s -H "Authorization: Bearer $BUSYSMS_API_KEY" \
  "https://busysms.net/api/v1/codes?service=exampleapp&timeoutMs=60000"

const params = new URLSearchParams({ service: "exampleapp", timeoutMs: "60000" });
const res = await fetch(`https://busysms.net/api/v1/codes?${params}`, {
  headers: { Authorization: `Bearer ${process.env.BUSYSMS_API_KEY}` },
});

if (res.status === 402) throw new Error("Trial over or subscription inactive");
if (!res.ok) throw new Error(`BusySMS ${res.status}: ${await res.text()}`);

const { code, message } = await res.json();
if (code) console.log(`${code} from ${message.sender}`);
else console.log("No new code within 60 seconds");

import os
import requests

r = requests.get(
    "https://busysms.net/api/v1/codes",
    params={"service": "exampleapp", "timeoutMs": 60000},
    headers={"Authorization": f"Bearer {os.environ['BUSYSMS_API_KEY']}"},
    timeout=75,
)
if r.status_code == 402:
    raise RuntimeError("Trial over or subscription inactive")
r.raise_for_status()

data = r.json()
if data["code"]:
    print(data["code"], "from", data["message"]["sender"])
else:
    print("No new code within 60 seconds")

Ordinea contează mai puțin decât ai crede: un cod sosit cu până la aproximativ o secundă înainte de începerea cererii contează tot ca nou, iar unul mai vechi nu. În teste, pornește întâi cererea și declanșează SMS-ul după aceea; ghidul de automatizare OTP arată cum, în Playwright, Selenium și Cypress.

Ce primești înapoi

Fiecare răspuns de la /codes are aceeași formă (obiectul message este prescurtat aici):

{
  "code": "482913",
  "message": {
    "otpCode": "482913",
    "phone": "+447700900123",
    "sender": "ExampleApp",
    "service": "exampleapp",
    "serviceLabel": "ExampleApp",
    "bodyPreview": "Your ExampleApp verification code is 482913",
    "receivedAt": 1792674000000,
    "deviceName": "Test phone"
  }
}

code este null când nu a sosit nimic nou la timp: în timpul așteptării, API-ul nu revine niciodată la un cod mai vechi. receivedAt este în milisecunde epoch. service este un id scurt pe care BusySMS îl dă fiecărui mesaj: un brand cunoscut, ca google, telegram sau microsoft, altfel un slug din numele expeditorului. Transmite-l ca service= ca să aștepți doar codul de la acel expeditor.

Erori și cum le tratezi

• 401: cheia lipsește, este greșit formatată sau a fost revocată. O cheie revocată spune asta prin key_revoked.
• 402 payment_required: perioada gratuită s-a încheiat și nu există un abonament activ. Citirea codurilor se oprește, dar /devices răspunde în continuare, ca să vezi ce nu e în regulă, iar corpul răspunsului conține un billingUrl.
• 403: dispozitivul aparține altui cont sau cheia nu are drepturile necesare pentru rută (insufficient_scope).
• 404: dispozitivul nu există.
• 409 number_unverified: numărul acelui telefon nu a fost încă verificat, așa că mesajele lui nu pot fi citite.
• 429: limită de cereri depășită. Așteaptă retryAfterMs înainte să reîncerci.

Limite și bune practici

• O așteptare durează cel mult 90 de secunde. Dacă un cod poate întârzia mai mult, apelează din nou cu un timeout nou, în loc să ții o cerere deschisă.
• Cu mai multe numere, filtrează: phone= cu numărul care primește sau deviceId= pentru unul dintre telefoane, ca să nu primești un cod destinat altei autentificări.
• Dacă niciunul dintre telefoanele tale nu capturează când începe o așteptare, BusySMS trimite telefonului o notificare prin care cere repornirea gateway-ului. Nu pornește niciodată captura de la distanță; o persoană trebuie să atingă notificarea.
• Mesajele capturate sunt păstrate cel mult 7 zile, apoi sunt șterse.
• Citirea codurilor necesită o perioadă gratuită sau un abonament activ: $5 per număr verificat pe lună după 7 zile gratuite. Nu se plătește per cerere.

Dincolo de API REST

Aceleași coduri sunt disponibile pentru agenții AI prin serverul MCP BusySMS (vezi coduri SMS pentru agenți AI) și pentru oameni prin extensia Chrome, care completează codul pe site în locul tău.

Sunt incluse și numerele partajate cu tine. Când un coleg partajează codurile unui număr, /codes le returnează alături de ale tale, iar phone= selectează acel număr.

Întrebări

Întrebări frecvente