CodeSMS

Documentação da API

REST API v1 e endpoints compatíveis com SMS-Activate

Cadastre-se grátis

Introdução

A API permite comprar números virtuais com o saldo da sua conta, ler os códigos SMS recebidos e cancelar para obter reembolso. Todas as requisições usam HTTPS; as respostas são em JSON.

Não há exigência de saldo mínimo. Se o seu saldo cobrir o preço do número, a compra é concluída; caso contrário, a API retorna NO_BALANCE.
Seleção de Server (opcional). Para cada serviço e país, os números vêm de Servers com numeração fixa, como «Server 3» ou «Server 7»; cada Server tem seu próprio preço, estoque e taxa de sucesso. Liste-os com GET /api/v1/prices?service=..&country=..&servers=1 e escolha um com o parâmetro server na compra. Se não informar um server, o mais barato é tentado primeiro e o próximo é usado, se necessário.
URL base
https://codesms.org
Formato
JSON (application/json) — form-encoded também é aceito
Moeda
TRY (₺)
Resposta de sucesso
{"success": true, "data": ...}
Resposta de erro
{"success": false, "error": {"code": "NO_BALANCE", "message": "..."}}

Autenticação

Envie sua chave de API em todas as requisições. Você pode obter a chave na página API do seu painel.

curl "https://codesms.org/api/v1/balance" \
  -H "X-API-Key: YOUR_API_KEY"
$ch = curl_init('https://codesms.org/api/v1/balance');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY']]);
requests.get("https://codesms.org/api/v1/balance", headers={"X-API-Key": "YOUR_API_KEY"})
fetch("https://codesms.org/api/v1/balance", { headers: { "X-API-Key": "YOUR_API_KEY" } })

Alternativas: o cabeçalho Authorization: Bearer YOUR_API_KEY ou o parâmetro de consulta ?api_key=YOUR_API_KEY (apenas para testes; a chave pode acabar nos logs).

  • A API não funciona em contas com e-mail não verificado (EMAIL_NOT_VERIFIED).
  • Você pode definir uma lista de IPs permitidos no painel; se a lista estiver definida, as requisições serão aceitas apenas desses endereços.
  • Se sua chave vazar, gere uma nova no painel imediatamente; a chave antiga é invalidada na hora.

Início rápido

Compre um número → aguarde o código → finalize. Se nenhum código chegar, cancele para receber o reembolso.

<?php
$base = 'https://codesms.org';
$key  = 'YOUR_API_KEY';

function api($method, $path, $body = null) {
    global $base, $key;
    $ch = curl_init($base . $path);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => ['X-API-Key: ' . $key, 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => $body ? json_encode($body) : null]);
    return json_decode(curl_exec($ch), true);
}

$r = api('POST', '/api/v1/activations', ['service' => 'tg', 'country' => 'tr']);
if (!$r['success']) { exit('Hata: ' . $r['error']['code']); }
$id = $r['data']['id'];
echo "Numara: {$r['data']['phone']}\n";

for ($i = 0; $i < 120; $i++) {          // en fazla ~6 dk
    sleep(3);
    $s = api('GET', "/api/v1/activations/$id")['data'];
    if ($s['status'] === 'received') { echo "Kod: {$s['code']}\n"; api('POST', "/api/v1/activations/$id/finish"); exit; }
    if (in_array($s['status'], ['canceled', 'expired', 'failed'])) exit("Bitti: {$s['status']}\n");
}
api('POST', "/api/v1/activations/$id/cancel");   // kod gelmedi: iptal et, ücret iade
import time, requests

BASE = "https://codesms.org"
HEAD = {"X-API-Key": "YOUR_API_KEY"}

r = requests.post(f"{BASE}/api/v1/activations", headers=HEAD, json={"service": "tg", "country": "tr"}).json()
if not r["success"]:
    raise SystemExit(f"Hata: {r['error']['code']}")
act = r["data"]
print("Numara:", act["phone"])

for _ in range(120):                       # en fazla ~6 dk
    time.sleep(3)
    s = requests.get(f"{BASE}/api/v1/activations/{act['id']}", headers=HEAD).json()["data"]
    if s["status"] == "received":
        print("Kod:", s["code"])
        requests.post(f"{BASE}/api/v1/activations/{act['id']}/finish", headers=HEAD)
        break
    if s["status"] in ("canceled", "expired", "failed"):
        break
else:
    requests.post(f"{BASE}/api/v1/activations/{act['id']}/cancel", headers=HEAD)   # ücret iade
const BASE = "https://codesms.org";
const HEAD = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };
const api = (method, path, body) => fetch(BASE + path, { method, headers: HEAD, body: body && JSON.stringify(body) }).then(r => r.json());

const r = await api("POST", "/api/v1/activations", { service: "tg", country: "tr" });
if (!r.success) throw new Error(r.error.code);
const { id, phone } = r.data;
console.log("Numara:", phone);

for (let i = 0; i < 120; i++) {              // en fazla ~6 dk
  await new Promise(res => setTimeout(res, 3000));
  const s = (await api("GET", `/api/v1/activations/${id}`)).data;
  if (s.status === "received") { console.log("Kod:", s.code); await api("POST", `/api/v1/activations/${id}/finish`); process.exit(0); }
  if (["canceled", "expired", "failed"].includes(s.status)) process.exit(1);
}
await api("POST", `/api/v1/activations/${id}/cancel`);   // ücret iade

Ciclo de vida da ativação

statusSignificadoAções possíveis
waitingNúmero emitido, aguardando SMS.Consultar, cancelar (se can_cancel=true).
receivedSMS recebido; no campo code.Use o código e finalize; solicite outro SMS se can_retry=true.
completedConcluído (código usado).—
canceledCancelado, reembolsado.—
expiredTempo esgotado, sem SMS; reembolsado.—
failedNão foi possível obter um número; reembolsado.—

A disponibilidade dos botões Cancelar, Solicitar SMS novamente e Concluir depende do número e do serviço: consulte os campos can_cancel, can_retry e can_finish na resposta. Se cancel_in > 0, você precisa aguardar essa quantidade de segundos para cancelar.

Obter saldo

GET/api/v1/balance

Retorna o saldo atual da sua conta.

Requisição
curl "https://codesms.org/api/v1/balance" \
  -H "X-API-Key: YOUR_API_KEY"
$ch = curl_init('https://codesms.org/api/v1/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.get(
    "https://codesms.org/api/v1/balance",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())
const response = await fetch("https://codesms.org/api/v1/balance", {
  method: "GET",
  headers: {
    "X-API-Key": "YOUR_API_KEY"
  }
});
console.log(await response.json());
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/balance", nil)
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/balance");
Console.WriteLine(await response.Content.ReadAsStringAsync());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://codesms.org/api/v1/balance"))
    .header("X-API-Key", "YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'json'

uri = URI("https://codesms.org/api/v1/balance")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body
Resposta 200
{
    "success": true,
    "data": {
        "balance": 125.5,
        "currency": "TRY"
    }
}

Listar serviços

GET/api/v1/services

Stokta numarası bulunan servisler, en düşük fiyat ve toplam stokla.

Requisição
curl "https://codesms.org/api/v1/services" \
  -H "X-API-Key: YOUR_API_KEY"
$ch = curl_init('https://codesms.org/api/v1/services');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.get(
    "https://codesms.org/api/v1/services",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())
const response = await fetch("https://codesms.org/api/v1/services", {
  method: "GET",
  headers: {
    "X-API-Key": "YOUR_API_KEY"
  }
});
console.log(await response.json());
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/services", nil)
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/services");
Console.WriteLine(await response.Content.ReadAsStringAsync());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://codesms.org/api/v1/services"))
    .header("X-API-Key", "YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'json'

uri = URI("https://codesms.org/api/v1/services")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body
Resposta 200
{
    "success": true,
    "data": [
        {
            "code": "tg",
            "slug": "telegram",
            "name": "Telegram",
            "min_price": 2.1,
            "stock": 18540
        }
    ]
}

Listar países

GET/api/v1/countries

Países com números em estoque. "id" é o código numérico de país compatível com o SMS-Activate.

Requisição
curl "https://codesms.org/api/v1/countries" \
  -H "X-API-Key: YOUR_API_KEY"
$ch = curl_init('https://codesms.org/api/v1/countries');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.get(
    "https://codesms.org/api/v1/countries",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())
const response = await fetch("https://codesms.org/api/v1/countries", {
  method: "GET",
  headers: {
    "X-API-Key": "YOUR_API_KEY"
  }
});
console.log(await response.json());
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/countries", nil)
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/countries");
Console.WriteLine(await response.Content.ReadAsStringAsync());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://codesms.org/api/v1/countries"))
    .header("X-API-Key", "YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'json'

uri = URI("https://codesms.org/api/v1/countries")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body
Resposta 200
{
    "success": true,
    "data": [
        {
            "iso": "tr",
            "id": 62,
            "name": "Turkey",
            "name_tr": "Türkiye",
            "dial": "90"
        }
    ]
}

Preço e estoque

GET/api/v1/prices

Preço e estoque atuais por serviço/país. Uma chamada sem filtros retorna a lista completa (até 20.000 linhas).

ParâmetroTipoDescrição
servicestringopcionalCódigo ou slug do serviço (ex.: tg).
countrystringopcionalCódigo ISO do país (tr) ou ID numérico (62).
serversintegeropcionalIf set to 1 (service and country must both be given), the price, stock and success rate of each "Server N" are also returned in the "servers" array. Pass that number as the server parameter when buying.
Requisição
curl "https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1" \
  -H "X-API-Key: YOUR_API_KEY"
$ch = curl_init('https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.get(
    "https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())
const response = await fetch("https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1", {
  method: "GET",
  headers: {
    "X-API-Key": "YOUR_API_KEY"
  }
});
console.log(await response.json());
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1", nil)
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1");
Console.WriteLine(await response.Content.ReadAsStringAsync());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1"))
    .header("X-API-Key", "YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'json'

uri = URI("https://codesms.org/api/v1/prices?service=tg&country=tr&servers=1")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body
Resposta 200
{
    "success": true,
    "data": [
        {
            "service": "tg",
            "country": "tr",
            "price": 8.5,
            "currency": "TRY",
            "stock": 420,
            "success_rate": 87,
            "servers": [
                {
                    "server": 3,
                    "price": 8.5,
                    "stock": 300,
                    "success_rate": 91
                },
                {
                    "server": 7,
                    "price": 9.2,
                    "stock": 120,
                    "success_rate": null
                }
            ]
        }
    ]
}

Comprar um número

POST/api/v1/activations

Abre uma nova ativação (número), debitando do seu saldo. Retorna NO_BALANCE se o saldo for insuficiente e NO_NUMBERS se não houver estoque. Se nenhum SMS chegar ou você cancelar, o valor é reembolsado automaticamente. Recomendado: envie um cabeçalho Idempotency-Key exclusivo em cada compra; se você tentar novamente com a mesma chave após um erro de rede, nenhum segundo número será comprado e a primeira ativação será retornada (válido por 24 horas).

ParâmetroTipoDescrição
servicestringobrigatórioCódigo ou slug do serviço (ex.: tg).
countrystringobrigatórioCódigo ISO do país (tr) ou ID numérico (62).
max_pricenumberopcionalO preço máximo (TRY) que você aceita. Se omitido, aplica-se o menor preço listado; se o preço ultrapassá-lo, será retornado PRICE_CHANGED.
serverintegeropcionalBuy only from this "Server N" (GET /api/v1/prices?servers=1). When given, no other server is tried; NO_NUMBERS is returned if it has none, PRICE_CHANGED if its price exceeds max_price. If omitted, all servers are tried in price order.
Requisição
curl -X POST "https://codesms.org/api/v1/activations" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"tr"}'
$ch = curl_init('https://codesms.org/api/v1/activations');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(['service' => 'tg', 'country' => 'tr']),
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.post(
    "https://codesms.org/api/v1/activations",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"service": "tg", "country": "tr"}
)
print(response.json())
const response = await fetch("https://codesms.org/api/v1/activations", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"service":"tg","country":"tr"})
});
console.log(await response.json());
package main

import (
    "bytes"
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://codesms.org/api/v1/activations", bytes.NewBufferString(`{"service":"tg","country":"tr"}`))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.PostAsync("https://codesms.org/api/v1/activations", new StringContent("{\"service\":\"tg\",\"country\":\"tr\"}", System.Text.Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://codesms.org/api/v1/activations"))
    .header("X-API-Key", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"service\":\"tg\",\"country\":\"tr\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'json'

uri = URI("https://codesms.org/api/v1/activations")
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
req['Content-Type'] = 'application/json'
req.body = '{"service":"tg","country":"tr"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body
Resposta 201
{
    "success": true,
    "data": {
        "id": 1234,
        "status": "waiting",
        "phone": "+905551234567",
        "code": null,
        "text": null,
        "service": {
            "code": "tg",
            "name": "Telegram"
        },
        "country": {
            "iso": "tr",
            "name": "Turkey",
            "dial": "90"
        },
        "server": 3,
        "price": 8.5,
        "currency": "TRY",
        "created_at": "2026-01-15T10:00:00+03:00",
        "expires_at": "2026-01-15T10:20:00+03:00",
        "retry_count": 0,
        "can_cancel": true,
        "can_retry": false,
        "can_finish": false,
        "cancel_in": 0
    }
}

Status da ativação / código SMS

GET/api/v1/activations/1234

Retorna o status da ativação e o código SMS, se tiver chegado. Consulte a cada 3–5 segundos até o código chegar (não é necessário se você usar webhooks).

ParâmetroTipoDescrição
idintegerobrigatórioID da ativação (parâmetro de caminho).
Requisição
curl "https://codesms.org/api/v1/activations/1234" \
  -H "X-API-Key: YOUR_API_KEY"
$ch = curl_init('https://codesms.org/api/v1/activations/1234');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.get(
    "https://codesms.org/api/v1/activations/1234",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())
const response = await fetch("https://codesms.org/api/v1/activations/1234", {
  method: "GET",
  headers: {
    "X-API-Key": "YOUR_API_KEY"
  }
});
console.log(await response.json());
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/activations/1234", nil)
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/activations/1234");
Console.WriteLine(await response.Content.ReadAsStringAsync());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://codesms.org/api/v1/activations/1234"))
    .header("X-API-Key", "YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'json'

uri = URI("https://codesms.org/api/v1/activations/1234")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body
Resposta 200
{
    "success": true,
    "data": {
        "status": "received",
        "code": "482913",
        "text": "Your Telegram code: 482913",
        "can_cancel": false,
        "can_retry": true,
        "can_finish": true,
        "id": 1234,
        "phone": "+905551234567",
        "service": {
            "code": "tg",
            "name": "Telegram"
        },
        "country": {
            "iso": "tr",
            "name": "Turkey",
            "dial": "90"
        },
        "server": 3,
        "price": 8.5,
        "currency": "TRY",
        "created_at": "2026-01-15T10:00:00+03:00",
        "expires_at": "2026-01-15T10:20:00+03:00",
        "retry_count": 0,
        "cancel_in": 0
    }
}

Listar ativações

GET/api/v1/activations

Suas últimas ativações (mais recentes primeiro).

ParâmetroTipoDescrição
statusstringopcionalwaiting, received, completed, canceled, expired, failed
limitintegeropcional1–100 (padrão 30).
Requisição
curl "https://codesms.org/api/v1/activations?status=waiting&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
$ch = curl_init('https://codesms.org/api/v1/activations?status=waiting&limit=20');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.get(
    "https://codesms.org/api/v1/activations?status=waiting&limit=20",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json())
const response = await fetch("https://codesms.org/api/v1/activations?status=waiting&limit=20", {
  method: "GET",
  headers: {
    "X-API-Key": "YOUR_API_KEY"
  }
});
console.log(await response.json());
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://codesms.org/api/v1/activations?status=waiting&limit=20", nil)
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.GetAsync("https://codesms.org/api/v1/activations?status=waiting&limit=20");
Console.WriteLine(await response.Content.ReadAsStringAsync());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://codesms.org/api/v1/activations?status=waiting&limit=20"))
    .header("X-API-Key", "YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'json'

uri = URI("https://codesms.org/api/v1/activations?status=waiting&limit=20")
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body
Resposta 200
{
    "success": true,
    "data": [
        {
            "id": 1234,
            "status": "waiting",
            "phone": "+905551234567",
            "code": null,
            "text": null,
            "service": {
                "code": "tg",
                "name": "Telegram"
            },
            "country": {
                "iso": "tr",
                "name": "Turkey",
                "dial": "90"
            },
            "server": 3,
            "price": 8.5,
            "currency": "TRY",
            "created_at": "2026-01-15T10:00:00+03:00",
            "expires_at": "2026-01-15T10:20:00+03:00",
            "retry_count": 0,
            "can_cancel": true,
            "can_retry": false,
            "can_finish": false,
            "cancel_in": 0
        }
    ]
}

Cancelar e receber reembolso

POST/api/v1/activations/1234/cancel

Se nenhum código chegou, cancela a ativação e reembolsa o valor ao seu saldo. Alguns provedores não permitem cancelar nos primeiros segundos (CANCEL_TOO_EARLY é retornado enquanto cancel_in > 0). Se o provedor não suportar, can_cancel=false.

ParâmetroTipoDescrição
idintegerobrigatórioID da ativação (parâmetro de caminho).
Requisição
curl -X POST "https://codesms.org/api/v1/activations/1234/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
$ch = curl_init('https://codesms.org/api/v1/activations/1234/cancel');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([]),
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.post(
    "https://codesms.org/api/v1/activations/1234/cancel",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={}
)
print(response.json())
const response = await fetch("https://codesms.org/api/v1/activations/1234/cancel", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({})
});
console.log(await response.json());
package main

import (
    "bytes"
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://codesms.org/api/v1/activations/1234/cancel", bytes.NewBufferString(`{}`))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.PostAsync("https://codesms.org/api/v1/activations/1234/cancel", new StringContent("{}", System.Text.Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://codesms.org/api/v1/activations/1234/cancel"))
    .header("X-API-Key", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'json'

uri = URI("https://codesms.org/api/v1/activations/1234/cancel")
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
req['Content-Type'] = 'application/json'
req.body = '{}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body
Resposta 200
{
    "success": true,
    "data": {
        "status": "canceled",
        "can_cancel": false,
        "id": 1234,
        "phone": "+905551234567",
        "code": null,
        "text": null,
        "service": {
            "code": "tg",
            "name": "Telegram"
        },
        "country": {
            "iso": "tr",
            "name": "Turkey",
            "dial": "90"
        },
        "server": 3,
        "price": 8.5,
        "currency": "TRY",
        "created_at": "2026-01-15T10:00:00+03:00",
        "expires_at": "2026-01-15T10:20:00+03:00",
        "retry_count": 0,
        "can_retry": false,
        "can_finish": false,
        "cancel_in": 0
    }
}

Solicitar outro SMS

POST/api/v1/activations/1234/retry

Solicita um novo SMS para o mesmo número após a chegada de um código (somente quando can_retry=true). A ativação volta para "waiting".

ParâmetroTipoDescrição
idintegerobrigatórioID da ativação (parâmetro de caminho).
Requisição
curl -X POST "https://codesms.org/api/v1/activations/1234/retry" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
$ch = curl_init('https://codesms.org/api/v1/activations/1234/retry');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([]),
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.post(
    "https://codesms.org/api/v1/activations/1234/retry",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={}
)
print(response.json())
const response = await fetch("https://codesms.org/api/v1/activations/1234/retry", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({})
});
console.log(await response.json());
package main

import (
    "bytes"
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://codesms.org/api/v1/activations/1234/retry", bytes.NewBufferString(`{}`))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.PostAsync("https://codesms.org/api/v1/activations/1234/retry", new StringContent("{}", System.Text.Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://codesms.org/api/v1/activations/1234/retry"))
    .header("X-API-Key", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'json'

uri = URI("https://codesms.org/api/v1/activations/1234/retry")
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
req['Content-Type'] = 'application/json'
req.body = '{}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body
Resposta 200
{
    "success": true,
    "data": {
        "retry_count": 1,
        "id": 1234,
        "status": "waiting",
        "phone": "+905551234567",
        "code": null,
        "text": null,
        "service": {
            "code": "tg",
            "name": "Telegram"
        },
        "country": {
            "iso": "tr",
            "name": "Turkey",
            "dial": "90"
        },
        "server": 3,
        "price": 8.5,
        "currency": "TRY",
        "created_at": "2026-01-15T10:00:00+03:00",
        "expires_at": "2026-01-15T10:20:00+03:00",
        "can_cancel": true,
        "can_retry": false,
        "can_finish": false,
        "cancel_in": 0
    }
}

Concluir

POST/api/v1/activations/1234/finish

Informa que você usou o código com sucesso e encerra a ativação. Ativações não finalizadas em 15 minutos são finalizadas automaticamente.

ParâmetroTipoDescrição
idintegerobrigatórioID da ativação (parâmetro de caminho).
Requisição
curl -X POST "https://codesms.org/api/v1/activations/1234/finish" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
$ch = curl_init('https://codesms.org/api/v1/activations/1234/finish');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([]),
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.post(
    "https://codesms.org/api/v1/activations/1234/finish",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={}
)
print(response.json())
const response = await fetch("https://codesms.org/api/v1/activations/1234/finish", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({})
});
console.log(await response.json());
package main

import (
    "bytes"
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://codesms.org/api/v1/activations/1234/finish", bytes.NewBufferString(`{}`))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var response = await client.PostAsync("https://codesms.org/api/v1/activations/1234/finish", new StringContent("{}", System.Text.Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://codesms.org/api/v1/activations/1234/finish"))
    .header("X-API-Key", "YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'json'

uri = URI("https://codesms.org/api/v1/activations/1234/finish")
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = 'YOUR_API_KEY'
req['Content-Type'] = 'application/json'
req.body = '{}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
puts res.body
Resposta 200
{
    "success": true,
    "data": {
        "status": "completed",
        "code": "482913",
        "text": "Your Telegram code: 482913",
        "can_cancel": false,
        "can_retry": true,
        "can_finish": true,
        "id": 1234,
        "phone": "+905551234567",
        "service": {
            "code": "tg",
            "name": "Telegram"
        },
        "country": {
            "iso": "tr",
            "name": "Turkey",
            "dial": "90"
        },
        "server": 3,
        "price": 8.5,
        "currency": "TRY",
        "created_at": "2026-01-15T10:00:00+03:00",
        "expires_at": "2026-01-15T10:20:00+03:00",
        "retry_count": 0,
        "cancel_in": 0
    }
}

Webhook

Se você definir uma URL de webhook no painel, enviaremos uma requisição POST assinada para ela quando o código SMS chegar; não é preciso consultar constantemente. Em respostas diferentes de 2xx, o envio é repetido após 1 min, 5 min, 15 min, 1 h e 6 h.

Cabeçalhos
X-SMSOnay-Event
activation.code
X-SMSOnay-Timestamp
Segundos Unix
X-SMSOnay-Signature
sha256=HMAC_SHA256(secret, timestamp + "." + body)
Corpo
{
    "event": "activation.code",
    "activation": {
        "id": 1234,
        "status": "received",
        "phone": "+905551234567",
        "code": "482913",
        "service": {
            "code": "tg"
        },
        "...": "..."
    },
    "timestamp": 1768460000
}
Verificação de assinatura
# HMAC-SHA256(secret, timestamp + "." + rawBody) -> "sha256=" + hex
# Header'lar: X-SMSOnay-Timestamp, X-SMSOnay-Signature
$ts   = $_SERVER['HTTP_X_SMSONAY_TIMESTAMP'];
$sig  = $_SERVER['HTTP_X_SMSONAY_SIGNATURE'];
$body = file_get_contents('php://input');
$calc = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, 'whsec_YOUR_SECRET');
if (!hash_equals($calc, $sig) || abs(time() - (int)$ts) > 300) { http_response_code(401); exit; }
$event = json_decode($body, true);
import hmac, hashlib, time

def verify(ts, signature, body: bytes, secret: str) -> bool:
    calc = 'sha256=' + hmac.new(secret.encode(), ts.encode() + b'.' + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(calc, signature) and abs(time.time() - int(ts)) < 300
const crypto = require('crypto');

function verify(ts, signature, rawBody, secret) {
  const calc = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(calc), Buffer.from(signature)) && Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}
func verify(ts, signature string, body []byte, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(ts + "."))
    mac.Write(body)
    calc := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(calc), []byte(signature))
}
static bool Verify(string ts, string signature, string body, string secret)
{
    using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var calc = "sha256=" + Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes(ts + "." + body))).ToLower();
    return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(calc), Encoding.UTF8.GetBytes(signature));
}
static boolean verify(String ts, String signature, String body, String secret) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    String calc = "sha256=" + HexFormat.of().formatHex(mac.doFinal((ts + "." + body).getBytes(StandardCharsets.UTF_8)));
    return MessageDigest.isEqual(calc.getBytes(), signature.getBytes());
}
require 'openssl'

def verify(ts, signature, body, secret)
  calc = 'sha256=' + OpenSSL::HMAC.hexdigest('SHA256', secret, "#{ts}.#{body}")
  Rack::Utils.secure_compare(calc, signature)
end

Você pode obter seu segredo de assinatura na página da API no painel. Verifique o timestamp (±5 min) e a assinatura; descarte entregas repetidas para a mesma ativação pelo id.

API compatível com SMS-Activate

Se o seu software de cadastro/automação já suporta o protocolo SMS-Activate (handler_api), você pode se conectar a nós apenas alterando o endereço do servidor e a chave da API.

GEThttps://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=...
  • service: código do serviço (tg, wa, ig, go, fb …) — o código de GET /api/v1/services.
  • country: ID do país no SMS-Activate (ex.: 62 = Turquia, 0 = Rússia, 187 = EUA) — o id de GET /api/v1/countries.
  • Os preços estão em liras turcas; maxPrice também é interpretado em TRY.
  • operator: apenas um valor numérico é interpretado como o número do «Server N» (GET /api/v1/prices?servers=1); se omitido, todos os Servers são testados em ordem de preço.
actionParâmetrosExemplo de resposta
getBalance—ACCESS_BALANCE:125.50
getNumberservice, country (ID), [maxPrice], [operator = Server no]ACCESS_NUMBER:1234:905551234567
getNumberV2service, country (ID), [maxPrice], [operator = Server no]{"activationId":"1234","phoneNumber":"905551234567","activationCost":8.5,"countryCode":"62","canGetAnotherSms":true,...}
getStatusidSTATUS_WAIT_CODE | STATUS_OK:482913 | STATUS_WAIT_RETRY:482913 | STATUS_CANCEL
getStatusV2id{"verificationType":0,"sms":{"dateTime":"...","code":"482913","text":"..."},"call":null}
setStatusid, status (3=tekrar SMS, 6=tamamla, 8=iptal)ACCESS_RETRY_GET | ACCESS_ACTIVATION | ACCESS_CANCEL | EARLY_CANCEL_DENIED
getPrices[service], [country]{"62":{"tg":{"cost":8.5,"count":420}}}
getNumbersStatuscountry{"tg_0":420,"wa_0":310}
getCountries—{"62":{"id":62,"eng":"Turkey",...}}
getServicesList—{"status":"success","services":[{"code":"tg","name":"Telegram"}]}
getActiveActivations—{"status":"success","activeActivations":[...]}
Exemplo
curl "https://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=62" \
  -H "X-API-Key: unused"
$ch = curl_init('https://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=62');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: unused'],
]);
$response = json_decode(curl_exec($ch), true);
print_r($response);
import requests

response = requests.get(
    "https://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=62",
    headers={"X-API-Key": "unused"}
)
print(response.json())
const response = await fetch("https://codesms.org/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=tg&country=62", {
  method: "GET",
  headers: {
    "X-API-Key": "unused"
  }
});
console.log(await response.json());

As respostas de erro são em texto simples: BAD_KEY, BAD_ACTION, BAD_SERVICE, NO_NUMBERS, NO_BALANCE, NO_ACTIVATION, EARLY_CANCEL_DENIED, WRONG_MAX_PRICE:price, ACCOUNT_INACTIVE…

Requisições assinadas (opcional)

Se a opção Painel → API → "Requisição assinada obrigatória" estiver ativada, os cabeçalhos a seguir devem ser adicionados a toda requisição REST; mesmo que sua chave seja roubada, não é possível fazer requisições sem o segredo de assinatura, e a mesma requisição não pode ser repetida. O endpoint compatível com SMS-Activate não suporta assinatura, portanto não pode ser usado enquanto esta opção estiver ativada.

  • X-Timestamp: Horário Unix (segundos); pode diferir do horário do servidor em no máximo 5 minutos.
  • X-Nonce: Um novo valor aleatório para cada requisição, de 16 a 64 caracteres (A-Z a-z 0-9 _ -).
  • X-Signature: hex(HMAC-SHA256(imza_sırrı, X-Timestamp + "\n" + X-Nonce + "\n" + METHOD + "\n" + yol?sorgu + "\n" + hex(SHA256(gövde))))
$ts = (string)time(); $nonce = bin2hex(random_bytes(16)); $body = json_encode(['service' => 'tg', 'country' => 'tr']);
$sig = hash_hmac('sha256', "$ts\n$nonce\nPOST\n/api/v1/activations\n" . hash('sha256', $body), $signSecret);
// Başlıklar: X-API-Key, X-Timestamp: $ts, X-Nonce: $nonce, X-Signature: $sig, Content-Type: application/json

Códigos de erro

codeHTTPDescrição
BAD_KEY401A chave da API está ausente ou é inválida.
API_DISABLED403O acesso à API está desativado na sua conta.
EMAIL_NOT_VERIFIED403Seu endereço de e-mail não foi verificado.
IP_NOT_ALLOWED403O endereço IP da solicitação não está na lista de permissões.
ACCOUNT_BANNED403A conta está suspensa.
RATE_LIMIT429O limite de solicitações por minuto foi excedido.
BAD_SERVICE400O código do serviço é inválido ou está ausente.
BAD_COUNTRY400O código do país é inválido ou está ausente.
NO_BALANCE402Saldo insuficiente. (Não há exigência de saldo mínimo; este erro é retornado quando seu saldo é menor que o preço.)
NO_NUMBERS409Não há números para este serviço/país no momento (sem cobrança / reembolsado).
BAD_MAX_PRICE400max_price deve ser um número positivo.
BAD_SERVER400server must be a positive integer (the Server number).
PRICE_CHANGED409Não há mais números disponíveis ao preço que você aceitou; nenhuma cobrança foi feita. error.price na resposta é o preço atual; se você aceitá-lo, repita a mesma requisição com max_price.
TOO_MANY_ACTIVE429O número permitido de ativações ativas simultâneas foi excedido.
NOT_FOUND404Ativação não encontrada.
BAD_STATUS409Esta ação não é possível no estado atual da ativação.
CANCEL_TOO_EARLY409O provedor não permite o cancelamento nesta etapa; tente novamente após cancel_in segundos.
ALREADY_RECEIVED409Não é possível cancelar porque o código já chegou.
UNSUPPORTED409O provedor não suporta esta ação (ex.: outro SMS).
PROVIDER_ERROR502O provedor teve um erro temporário; tente novamente.
PLAN_REQUIRED403API erişimi için etkin bir API paketi gerekiyor (Panel → API).
BAD_SIGNATURE401İmzalı istek zorunlu ve imza eksik/geçersiz ya da zaman damgası 5 dakikadan eski.
BAD_IDEMPOTENCY_KEY400O cabeçalho Idempotency-Key deve ter de 8 a 64 caracteres (letras, dígitos, _ - : .).
IDEMPOTENCY_IN_PROGRESS409Uma solicitação anterior com o mesmo Idempotency-Key ainda está sendo processada; tente novamente em alguns segundos.
REPLAYED_REQUEST401Aynı X-Nonce ikinci kez kullanıldı (tekrar oynatma koruması).
SERVER_ERROR500Erro inesperado no servidor.

Limites e recomendações

  • Limite de requisições: 120 por minuto (por conta).
  • Consulte o status a cada 3–5 segundos; usar webhooks é mais eficiente.
  • Ativações que não recebem SMS são canceladas e reembolsadas automaticamente quando o tempo acaba; você também pode cancelar antes.
  • O número de ativações abertas simultaneamente é limitado (TOO_MANY_ACTIVE).
  • Em caso de tempo limite de rede, reenvie a solicitação de compra com o mesmo cabeçalho Idempotency-Key; nenhum segundo número será comprado. Se você não usar o cabeçalho, verifique antes suas ativações recentes com GET /api/v1/activations.
  • O preço pode mudar conforme o estoque: se não houver mais números ao preço listado, você não será cobrado e o preço atual será informado com PRICE_CHANGED (WRONG_MAX_PRICE:price no endpoint compatível com SMS-Activate). Se você aceitá-lo, repita a requisição com max_price (maxPrice).
  • O campo success_rate na lista de preços é a porcentagem de vendas dos últimos 30 dias para aquele serviço e país em que um código SMS foi recebido; é null quando a amostra é pequena demais.