Des numéros pour recevoir des SMS — depuis votre logiciel

Démarrage rapide

1. Connectez-vous et ouvrez Solde → API → Créer une clé. La clé n'est affichée qu'une fois — conservez-la.
2. Rechargez jusqu'à 20 $ ou plus : les achats par l'API ne passent qu'avec ce solde. Garder une clé avec un solde nul ne pose aucun problème.
3. Indiquez dans votre logiciel le serveur https://relysms.pro/stubs/handler_api.php et votre clé à la place de celle du service précédent.
4. Achetez un numéro (getNumber), puis interrogez le statut toutes les 5 à 10 secondes (getStatus) jusqu'à recevoir STATUS_OK avec le code.
5. Terminez la commande (setStatus=6). Sans code, annulez après 2 minutes (setStatus=8) ou laissez la fenêtre se terminer : l'argent revient tout seul.

Règles et limites

• Les achats par l'API exigent un solde d'au moins 20 $. En dessous, getNumber répond NO_BALANCE ; les autres méthodes fonctionnent.
• Le numéro est à vous pendant 20 minutes. Sans code, la commande se ferme d'elle-même et l'argent revient sur votre solde.
• Vous pouvez annuler 2 minutes après l'achat si aucun code n'est arrivé. L'argent revient aussitôt.
• Dès le premier code, la commande est payée et non remboursable. Tant que la fenêtre est ouverte, d'autres codes peuvent encore arriver.
• Jusqu'à 20 requêtes et 5 achats par seconde et par clé ; jusqu'à 50 commandes ouvertes à la fois.
• Le prix est fixé à l'achat. maxPrice vous évite d'acheter au-dessus de votre limite.
• Les conditions du service s'appliquent : spam, fraude et inscriptions en masse à ces fins sont interdits.

Méthodes

Chaque requête est un GET ou un POST vers une seule adresse, avec les paramètres dans l'URL ou dans un formulaire. La clé va dans api_key, l'action dans action.

GET https://relysms.pro/stubs/handler_api.php?api_key=KEY&action=getBalance

ACCESS_BALANCE:25.00

GET https://relysms.pro/stubs/handler_api.php?api_key=KEY&action=getNumber&service=tg&country=187&maxPrice=0.80

ACCESS_NUMBER:1042:15550001111

GET https://relysms.pro/stubs/handler_api.php?api_key=KEY&action=getNumberV2&service=tg&country=187&maxPrice=0.80

{
  "activationId": 1042,
  "phoneNumber": "15550001111",
  "activationCost": 0.59,
  "countryCode": "187",
  "canGetAnotherSms": true,
  "activationTime": "2026-10-27T10:00:00.000Z",
  "activationEndTime": "2026-10-27T10:20:00.000Z"
}

GET https://relysms.pro/stubs/handler_api.php?api_key=KEY&action=getStatus&id=1042

STATUS_OK:48213

GET https://relysms.pro/stubs/handler_api.php?api_key=KEY&action=setStatus&id=1042&status=6

ACCESS_ACTIVATION

GET https://relysms.pro/stubs/handler_api.php?api_key=KEY&action=getActiveActivations

{
  "status": "success",
  "activeActivations": [
    {
      "activationId": 1042,
      "serviceCode": "tg",
      "phoneNumber": "15550001111",
      "activationCost": 0.59,
      "activationStatus": "2",
      "smsCode": ["48213"],
      "smsText": ["Telegram code: 48213"],
      "activationTime": "2026-10-27T10:00:00.000Z",
      "countryCode": "187"
    }
  ]
}

GET https://relysms.pro/stubs/handler_api.php?api_key=KEY&action=getPrices&service=tg&country=187

{ "187": { "tg": { "cost": 0.59, "count": 1000 } } }

GET https://relysms.pro/stubs/handler_api.php?api_key=KEY&action=getCountries

{ "187": { "id": 187, "rus": "США", "eng": "United States", "visible": 1 } }

GET https://relysms.pro/stubs/handler_api.php?api_key=KEY&action=getServicesList

{ "status": "success", "services": [{ "code": "tg", "name": "Telegram" }] }

Statuts

Valeurs de status dans setStatus :

• status=1 → ACCESS_READY — Le numéro est saisi dans le service, en attente du code. Ne change rien ; conservé pour la compatibilité.
• status=3 → ACCESS_RETRY_GET — Demander un autre code sur le même numéro — après le premier code, tant que la commande est ouverte. Gratuit. En attendant, getStatus répond STATUS_WAIT_RETRY.
• status=6 → ACCESS_ACTIVATION — Terminer la commande après le code. Aucun nouveau SMS n'arrivera sur le numéro.
• status=8 → ACCESS_CANCEL — Annuler une commande sans code (pas avant 2 minutes). L'argent revient sur votre solde.

Réponses de getStatus :

• STATUS_WAIT_CODE — Pas encore de code — redemandez dans 5 à 10 secondes.
• STATUS_OK:48213 — Le code est arrivé ; après les deux-points figure le code (ou le texte du SMS s'il n'en contient pas).
• STATUS_WAIT_RETRY:48213 — Un autre code a été demandé et n'est pas encore arrivé ; après les deux-points figure le code précédent.
• STATUS_CANCEL — Annulée ou close sans code ; l'argent est déjà revenu sur le solde.

Erreurs

Les erreurs sont des chaînes de texte, comme le veut l'usage de ce protocole. Toutes, sauf RATE_LIMIT, arrivent avec le statut 200.

Codes des services et pays

Les codes sont ceux, standard, du protocole : tg — Telegram, wa — WhatsApp, etc. ; le pays 187 — les États-Unis. getServicesList et getCountries renvoient les listes complètes — prenez les codes là, pas dans d'anciens tableaux : services et pays évoluent avec le stock.

API REST v1

Les mêmes numéros et les mêmes règles que handler_api.php, en JSON : services par nom (telegram), pays par code ISO (US), statuts HTTP et codes d'erreur sur lesquels un programme peut s'appuyer. Utilisez-la pour du code neuf ; gardez handler_api.php pour les logiciels qui le parlent déjà.

https://relysms.pro/api/v1

Webhooks

Plutôt que d'interroger GET /orders/{id}, définissez une adresse HTTPS avec PUT /webhook : nous y envoyons un POST quand il arrive quelque chose à une commande passée par l'API. Le corps contient la commande telle qu'elle est au moment de l'envoi. Répondez par n'importe quel 2xx sous 10 secondes ; une commande peut produire plusieurs événements, et le même événement peut arriver deux fois après une nouvelle tentative : appuyez-vous sur l'id de livraison.

• order.code_received — Un code est arrivé (chaque nouveau code le renvoie).
• order.finished — La commande est terminée — par vous, ou à la fin de son temps après un code.
• order.cancelled — Annulée sans code ; l'argent est revenu sur le solde.
• order.expired — Temps écoulé sans code ; l'argent est revenu sur le solde.
• ping — Un test depuis POST /webhook/test ; order vaut null.

POST /relysms-hook HTTP/1.1
Content-Type: application/json
X-RelySMS-Event: order.code_received
X-RelySMS-Delivery: cm…
X-RelySMS-Signature: t=1793095272,v1=5f2b…

{
  "id": "cm…",
  "event": "order.code_received",
  "createdAt": "2026-10-27T10:01:12.000Z",
  "order": { "id": 1042, "status": "received", "codes": [{ "code": "48213", … }], … }
}

Chaque requête porte X-RelySMS-Signature: t=<heure unix>,v1=<signature>. La signature est le HMAC-SHA256 de la chaîne « t.corps » (le corps brut, octet pour octet) avec le secret du webhook, en hexadécimal. Vérifiez-la, ainsi que t date de moins de 5 minutes, avant de faire confiance au corps.

Python

import hashlib, hmac, time

def verify(secret: str, body: bytes, header: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, sig = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, rawBody, header, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > tolerance) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1?.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Si votre serveur ne répond pas 2xx, nous réessayons après 10 secondes, 1 minute, 5 minutes, 30 minutes, 2 heures et 6 heures — 7 tentatives en tout — puis abandonnons. GET /webhook/deliveries montre ce qui est parti et ce qui a échoué.

Points d'accès

curl -H "Authorization: Bearer $KEY" https://relysms.pro/api/v1/balance

{ "balance": 25, "currency": "USD", "canBuy": true, "apiMinimum": 20 }

curl -H "Authorization: Bearer $KEY" "https://relysms.pro/api/v1/services?lang=en"

{ "services": [{ "id": "telegram", "name": "Telegram", "protocolCode": "tg" }] }

curl -H "Authorization: Bearer $KEY" "https://relysms.pro/api/v1/countries?lang=en"

{ "countries": [{ "id": "US", "name": "United States", "protocolCode": 187 }] }

curl -H "Authorization: Bearer $KEY" "https://relysms.pro/api/v1/prices?service=telegram"

{ "prices": [{ "service": "telegram", "country": "US", "price": 0.59, "stock": 1000 }] }

curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f0e2a-run-1" \
  -d '{"service":"telegram","country":"US","maxPrice":0.8}' \
  https://relysms.pro/api/v1/orders

{
  "order": {
    "id": 1042,
    "service": "telegram",
    "country": "US",
    "phone": "15550001111",
    "price": 0.59,
    "status": "waiting",
    "refunded": false,
    "codes": [],
    "awaitingAnotherCode": false,
    "createdAt": "2026-10-27T10:00:00.000Z",
    "expiresAt": "2026-10-27T10:20:00.000Z",
    "cancelableAt": "2026-10-27T10:02:00.000Z"
  }
}

curl -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f0e2a-batch-1" \
  -d '{"service":"telegram","country":"US","quantity":5}' \
  https://relysms.pro/api/v1/orders/batch

{
  "orders": [{ "id": 1043, "phone": "15550001112", … }, { "id": 1044, … }],
  "requested": 5,
  "placed": 2,
  "stoppedBy": { "code": "no_numbers", "message": "…" }
}

curl -H "Authorization: Bearer $KEY" "https://relysms.pro/api/v1/orders?status=all&limit=50"

{ "orders": [{ "id": 1042, … }], "next": "1001" }

curl -H "Authorization: Bearer $KEY" https://relysms.pro/api/v1/orders/1042

{
  "order": {
    "id": 1042,
    "status": "received",
    "codes": [{ "code": "48213", "text": "Telegram code: 48213", "receivedAt": "2026-10-27T10:01:12.000Z" }],
    …
  }
}

curl -X POST -H "Authorization: Bearer $KEY" https://relysms.pro/api/v1/orders/1042/finish

{ "order": { "id": 1042, "status": "finished", … } }

curl -X POST -H "Authorization: Bearer $KEY" https://relysms.pro/api/v1/orders/1042/another-code

{ "order": { "id": 1042, "status": "received", "awaitingAnotherCode": true, … } }

curl -X POST -H "Authorization: Bearer $KEY" https://relysms.pro/api/v1/orders/1042/cancel

{ "order": { "id": 1042, "status": "cancelled", "refunded": true, … } }

curl -H "Authorization: Bearer $KEY" https://relysms.pro/api/v1/webhook

{ "webhook": { "url": "https://example.com/relysms-hook", "secret": "whsec_…", "createdAt": "2026-10-27T10:00:00.000Z" } }

curl -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/relysms-hook"}' \
  https://relysms.pro/api/v1/webhook

{ "webhook": { "url": "https://example.com/relysms-hook", "secret": "whsec_…", "createdAt": "2026-10-27T10:00:00.000Z" } }

curl -X DELETE -H "Authorization: Bearer $KEY" https://relysms.pro/api/v1/webhook

{ "webhook": null }

curl -X POST -H "Authorization: Bearer $KEY" https://relysms.pro/api/v1/webhook/test

{ "delivery": { "id": "cm…" } }

curl -H "Authorization: Bearer $KEY" https://relysms.pro/api/v1/webhook/deliveries

{
  "deliveries": [{
    "id": "cm…", "event": "order.code_received", "orderId": 1042,
    "status": "pending", "attempts": 2, "lastHttpStatus": 502, "lastError": "HTTP 502",
    "createdAt": "2026-10-27T10:01:12.000Z", "deliveredAt": null, "nextAttemptAt": "2026-10-27T10:02:22.000Z"
  }]
}

Statuts de commande

Le champ status d'une commande :

• waiting — Le numéro est à vous et aucun code n'est encore arrivé.
• received — Un code est arrivé ; il est dans codes. D'autres peuvent arriver tant que la commande est ouverte.
• finished — Vous avez terminé la commande (ou son temps s'est écoulé après un code).
• cancelled — Annulée sans code ; refunded vaut true et l'argent est sur le solde.
• expired — Le temps s'est écoulé sans code ; l'argent est revenu sur le solde.

Erreurs

Une erreur, c'est un statut HTTP et un JSON avec code pour le programme et message pour les humains. Certaines portent des champs en plus (price, cancelableAt, apiMinimum).

{ "error": { "code": "price_above_max", "message": "The price is above maxPrice.", "price": 0.59 } }

Exemples REST

Acheter un numéro, attendre le code, terminer la commande.

Python

import time, uuid, requests

BASE = "https://relysms.pro/api/v1"
S = requests.Session()
S.headers["Authorization"] = "Bearer rs_your_key"

r = S.post(f"{BASE}/orders",
           json={"service": "telegram", "country": "US", "maxPrice": 0.8},
           headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=30)
if r.status_code != 201:
    raise SystemExit(r.json()["error"])   # no_numbers, below_api_minimum, …
order = r.json()["order"]
print("number:", order["phone"])

while order["status"] == "waiting":       # up to 20 minutes
    time.sleep(10)
    order = S.get(f"{BASE}/orders/{order['id']}", timeout=30).json()["order"]

if order["status"] == "received":
    print("code:", order["codes"][-1]["code"])
    S.post(f"{BASE}/orders/{order['id']}/finish", timeout=30)
# "expired" or "cancelled": the money is back on the balance

Node.js

const BASE = "https://relysms.pro/api/v1";
const headers = { Authorization: "Bearer rs_your_key", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/orders`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ service: "telegram", country: "US", maxPrice: 0.8 }),
});
if (res.status !== 201) throw new Error((await res.json()).error.code);
let { order } = await res.json();
console.log("number:", order.phone);

while (order.status === "waiting") {
  await new Promise((r) => setTimeout(r, 10_000));
  ({ order } = await (await fetch(`${BASE}/orders/${order.id}`, { headers })).json());
}
if (order.status === "received") {
  console.log("code:", order.codes.at(-1).code);
  await fetch(`${BASE}/orders/${order.id}/finish`, { method: "POST", headers });
}

Exemples

Le cycle complet : acheter un numéro, attendre le code, terminer la commande.

curl

KEY=rs_your_key
BASE=https://relysms.pro/stubs/handler_api.php

curl "$BASE?api_key=$KEY&action=getBalance"
curl "$BASE?api_key=$KEY&action=getNumber&service=tg&country=187&maxPrice=0.80"
# → ACCESS_NUMBER:1042:15550001111
curl "$BASE?api_key=$KEY&action=getStatus&id=1042"
# → STATUS_WAIT_CODE … then STATUS_OK:48213
curl "$BASE?api_key=$KEY&action=setStatus&id=1042&status=6"

Python

import time, requests

BASE = "https://relysms.pro/stubs/handler_api.php"
KEY = "rs_your_key"

def call(action, **params):
    r = requests.get(BASE, params={"api_key": KEY, "action": action, **params}, timeout=30)
    r.raise_for_status()
    return r.text

answer = call("getNumber", service="tg", country="187", maxPrice="0.80")
if not answer.startswith("ACCESS_NUMBER"):
    raise SystemExit(answer)          # NO_NUMBERS, NO_BALANCE, …
_, order_id, phone = answer.split(":")
print("number:", phone)

for _ in range(120):                  # up to 20 minutes, every 10 s
    status = call("getStatus", id=order_id)
    if status.startswith("STATUS_OK:"):
        print("code:", status.split(":", 1)[1])
        call("setStatus", id=order_id, status=6)
        break
    if status == "STATUS_CANCEL":
        break                         # refunded automatically
    time.sleep(10)

Node.js

const BASE = "https://relysms.pro/stubs/handler_api.php";
const KEY = "rs_your_key";

async function call(action, params = {}) {
  const url = new URL(BASE);
  url.search = new URLSearchParams({ api_key: KEY, action, ...params });
  const res = await fetch(url);
  return res.text();
}

const answer = await call("getNumber", { service: "tg", country: "187", maxPrice: "0.80" });
if (!answer.startsWith("ACCESS_NUMBER")) throw new Error(answer);
const [, id, phone] = answer.split(":");
console.log("number:", phone);

for (let i = 0; i < 120; i++) {
  const status = await call("getStatus", { id });
  if (status.startsWith("STATUS_OK:")) {
    console.log("code:", status.slice("STATUS_OK:".length));
    await call("setStatus", { id, status: "6" });
    break;
  }
  if (status === "STATUS_CANCEL") break; // refunded automatically
  await new Promise((r) => setTimeout(r, 10_000));
}

Questions

Pour les assistants IA

La documentation complète en un seul texte pour ChatGPT, Claude et d'autres modèles se trouve sur /fr/developers.md, et une carte courte sur /llms.txt. Donnez le lien au modèle et demandez-lui de connecter RelySMS à votre code.

Lis https://relysms.pro/fr/developers.md et connecte RelySMS à mon script.

developers.md · llms.txt