KDEFY SMS API
PT
TXT JSON Gerar meu tokenToken
v1.0

KDEFY SMS API

API REST para comprar números virtuais e receber SMS. Usa o mesmo saldo e as mesmas ativações da sua conta no site.

Base URL
https://kdefy-sms.com/api/v1
AutenticaçãoX-API-Key
FormatoJSON
Limite120 req/min

Todas as rotas

GET /balanceSaldo e totais da conta.
GET /profileUsuário, saldo e data de criação.
GET /countriesLista de países.
GET /servicesServiços de um país, com estoque e preço inicial.
GET /operatorsOperadoras de um país.
GET /offersFaixas de preço e estoque de um serviço num país.
GET POST /number/getCompra um número, ou vários com quantity.
GET /number/statusEstado da ativação e códigos recebidos.
GET POST /number/cancelCancela e devolve o valor.
GET POST /number/finishEncerra a ativação depois do código.
GET /activationsSuas ativações, inclusive as do site, da mais nova para a mais antiga.
GET /transactionsRecargas, compras e reembolsos.

Console de teste

Gerar ou ver meu token →

Estes valores valem para todos os testes da página. O token fica só nesta aba. Comprar debita saldo de verdade.

Começando

Autenticação

Gere o token em API, no menu do site, e mande no header X-API-Key em toda requisição. Authorization: Bearer e ?api_key= também funcionam, mas a query string vai parar em logs de proxy e no histórico do navegador. Gerar outro token invalida o anterior na hora. Não use o token em front-end.

curl "https://kdefy-sms.com/api/v1/balance" -H "X-API-Key: SEU_TOKEN"
curl "https://kdefy-sms.com/api/v1/balance" -H "Authorization: Bearer SEU_TOKEN"
curl "https://kdefy-sms.com/api/v1/balance?api_key=SEU_TOKEN"

Respostas e idioma

  • Toda resposta é JSON. Sucesso: { "status": "success", ... }. Erro: { "status": "error", "error": "codigo", "message": "texto" }.
  • Decida pelo campo error. Ele é estável. message é texto para humano e pode mudar.
  • message e state_label seguem o idioma da conta (pt ou en). Para forçar: ?lang=pt ou ?lang=en.
  • As chaves do JSON e os valores de state não mudam com o idioma.
  • Valores em BRL com ponto decimal. Datas em ISO 8601 (UTC).
Conceitos

Estados

stateSignificado
waitingEsperando o primeiro código.
code_receivedCódigo recebido. Códigos novos entram em codes enquanto a ativação estiver aberta.
completedFinalizada por você (/number/finish).
cancelledCancelada. Valor devolvido.
expiredSem código em 20 min. Valor devolvido automaticamente.

Limites

  • 120 requisições por minuto por conta.
  • Compra: até 50 números por requisição e 50 por minuto. Acima disso: limite_de_numeros.
  • Status: consulte a cada 5 s. Mais rápido não antecipa o código.
Guias

Fluxo de compra

  1. GET /services?country=73: serviços do país e preço inicial.
  2. GET /offers?country=73&service=wa (opcional): faixas de preço e estoque.
  3. GET /number/get?country=73&service=wa&request_id=...: compra e devolve phone e id.
  4. GET /number/status?id=ID a cada 5 s, até code vir preenchido.
  5. Com código: GET /number/finish?id=ID. Sem código: GET /number/cancel?id=ID (libera 2 min após a compra) e o valor volta ao saldo.

Esperando o código

Consulte /number/status a cada 5 s e pare quando code vier preenchido ou state virar cancelled, expired ou completed.

  • Defina um prazo máximo no seu código (20 min).
  • Com vários números, use /activations?state=active. Uma chamada traz todas as ativas.
  • Uma ativação pode receber mais de um código. Leia codes[].

Compra em lote

quantity=N compra N números numa chamada, até 50. Compra parcial é normal: se o estoque ou o saldo acabar no meio, o resto não é cobrado.

  • A resposta traz numbers[], requested, purchased e failed.
  • errors lista o motivo das falhas, quando houver.
  • Limite de 50 números por minuto por conta.
curl "https://kdefy-sms.com/api/v1/number/get?country=73&service=wa&quantity=3&request_id=pedido-0001" \
  -H "X-API-Key: $KDEFY_API_KEY"

Idempotência (request_id)

Mande request_id em toda compra. Se der timeout e você não sabe se a compra saiu, repita a mesma chamada com a mesma request_id. A API devolve a resposta original, com o header Idempotent-Replay: true, e não cobra de novo.

  • Compra nova, request_id nova.
  • 8 a 80 caracteres (letras, números, _ . : -). O header Idempotency-Key também vale.
  • A chave dura 24 h e só é salva quando a compra deu certo. Compra que falhou pode ser repetida.
  • Mesma chave com parâmetros diferentes: request_id_reutilizada.

Exemplo completo

Compra, espera o código e finaliza. Se o código não chega, cancela. A compra usa request_id, então repetir a chamada não duplica.

// Node 18+. Rode com: KDEFY_API_KEY=seu_token node kdefy.mjs
import { randomUUID } from "node:crypto";

const BASE = "https://kdefy-sms.com/api/v1";
const KEY = process.env.KDEFY_API_KEY;
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function api(path, params = {}) {
  const qs = new URLSearchParams(params).toString();
  const res = await fetch(`${BASE}${path}${qs ? "?" + qs : ""}`, {
    headers: { "X-API-Key": KEY },
    signal: AbortSignal.timeout(20000),
  });
  const body = await res.json();
  if (body.status !== "success") {
    const err = new Error(body.message);
    err.code = body.error;
    err.http = res.status;
    err.retryIn = body.retry_in_seconds;
    throw err;
  }
  return body;
}

async function buy(country, service) {
  const requestId = randomUUID(); // uma por compra
  for (let attempt = 1; attempt <= 4; attempt++) {
    try {
      return await api("/number/get", { country, service, request_id: requestId });
    } catch (e) {
      const transient = e.name === "TimeoutError" || e.name === "TypeError" || e.http === 502 || e.code === "requisicao_em_andamento";
      if (!transient || attempt === 4) throw e;
      await sleep(2000 * attempt); // repete com a mesma request_id
    }
  }
}

async function waitForCode(id, maxMinutes = 20) {
  const deadline = Date.now() + maxMinutes * 60_000;
  while (Date.now() < deadline) {
    const s = await api("/number/status", { id });
    if (s.code || ["cancelled", "expired", "completed"].includes(s.state)) return s;
    await sleep(5000);
  }
  return null;
}

const number = await buy(73, "wa");
console.log("Número:", number.phone);

const result = await waitForCode(number.id);
if (result?.code) {
  console.log("Código:", result.code);
  await api("/number/finish", { id: number.id });
} else {
  try {
    await api("/number/cancel", { id: number.id });
  } catch (e) {
    if (e.code !== "cancelamento_muito_cedo") throw e;
    await sleep((e.retryIn + 1) * 1000);
    await api("/number/cancel", { id: number.id });
  }
  console.log("Cancelado e reembolsado.");
}
# Python 3.9+. pip install requests
# Rode com: KDEFY_API_KEY=seu_token python kdefy.py
import os, time, uuid, requests

BASE = "https://kdefy-sms.com/api/v1"
HEADERS = {"X-API-Key": os.environ["KDEFY_API_KEY"]}

class ApiError(Exception):
    def __init__(self, body, http):
        super().__init__(body.get("message"))
        self.code = body.get("error")
        self.http = http
        self.retry_in = body.get("retry_in_seconds")

def api(path, **params):
    r = requests.get(BASE + path, params=params, headers=HEADERS, timeout=20)
    body = r.json()
    if body.get("status") != "success":
        raise ApiError(body, r.status_code)
    return body

def buy(country, service):
    request_id = str(uuid.uuid4())  # uma por compra
    for attempt in range(1, 5):
        try:
            return api("/number/get", country=country, service=service, request_id=request_id)
        except requests.RequestException:
            pass
        except ApiError as e:
            if not (e.http == 502 or e.code == "requisicao_em_andamento"):
                raise
        if attempt == 4:
            raise RuntimeError("não foi possível comprar agora")
        time.sleep(2 * attempt)  # repete com a mesma request_id

def wait_for_code(activation_id, max_minutes=20):
    deadline = time.time() + max_minutes * 60
    while time.time() < deadline:
        s = api("/number/status", id=activation_id)
        if s["code"] or s["state"] in ("cancelled", "expired", "completed"):
            return s
        time.sleep(5)
    return None

number = buy(73, "wa")
print("Número:", number["phone"])

result = wait_for_code(number["id"])
if result and result["code"]:
    print("Código:", result["code"])
    api("/number/finish", id=number["id"])
else:
    try:
        api("/number/cancel", id=number["id"])
    except ApiError as e:
        if e.code != "cancelamento_muito_cedo":
            raise
        time.sleep((e.retry_in or 5) + 1)
        api("/number/cancel", id=number["id"])
    print("Cancelado e reembolsado.")
<?php
// PHP 8+ com ext-curl. Rode com: KDEFY_API_KEY=seu_token php kdefy.php
const BASE = "https://kdefy-sms.com/api/v1";

function api(string $path, array $params = []): array {
    $ch = curl_init(BASE . $path . ($params ? "?" . http_build_query($params) : ""));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 20,
        CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
    ]);
    $raw = curl_exec($ch);
    if ($raw === false) throw new RuntimeException("rede: " . curl_error($ch));
    $body = json_decode($raw, true);
    if (($body["status"] ?? null) !== "success") {
        $e = new RuntimeException($body["error"] ?? "erro_desconhecido");
        $e->retryIn = $body["retry_in_seconds"] ?? 0;
        throw $e;
    }
    return $body;
}

$requestId = bin2hex(random_bytes(16)); // uma por compra
$n = api("/number/get", ["country" => 73, "service" => "wa", "request_id" => $requestId]);
echo "Número: {$n['phone']}\n";

$deadline = time() + 20 * 60;
while (time() < $deadline) {
    $s = api("/number/status", ["id" => $n["id"]]);
    if (!empty($s["code"]) || in_array($s["state"], ["cancelled", "expired", "completed"], true)) break;
    sleep(5);
}

if (!empty($s["code"])) {
    echo "Código: {$s['code']}\n";
    api("/number/finish", ["id" => $n["id"]]);
} else {
    api("/number/cancel", ["id" => $n["id"]]);
    echo "Cancelado e reembolsado.\n";
}
# Ruby 3+. Rode com: KDEFY_API_KEY=seu_token ruby kdefy.rb
require "net/http"
require "json"
require "securerandom"

BASE = "https://kdefy-sms.com/api/v1"

def api(path, params = {})
  uri = URI(BASE + path)
  uri.query = URI.encode_www_form(params) unless params.empty?
  req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |h| h.request(req) }
  body = JSON.parse(res.body)
  raise "#{body['error']}: #{body['message']}" unless body["status"] == "success"
  body
end

n = api("/number/get", country: 73, service: "wa", request_id: SecureRandom.uuid) # uma por compra
puts "Número: #{n['phone']}"

deadline = Time.now + 20 * 60
s = nil
while Time.now < deadline
  s = api("/number/status", id: n["id"])
  break if s["code"] || %w[cancelled expired completed].include?(s["state"])
  sleep 5
end

if s && s["code"]
  puts "Código: #{s['code']}"
  api("/number/finish", id: n["id"])
else
  api("/number/cancel", id: n["id"])
  puts "Cancelado e reembolsado."
end
#!/usr/bin/env bash
# Requer curl e jq. Rode com: KDEFY_API_KEY=seu_token bash kdefy.sh
set -euo pipefail
BASE="https://kdefy-sms.com/api/v1"

api() { # api /rota chave=valor ...
  local path="$1"; shift
  local args=(); for kv in "$@"; do args+=(--data-urlencode "$kv"); done
  curl -sS --max-time 20 -G "$BASE$path" -H "X-API-Key: $KDEFY_API_KEY" "${args[@]}"
}

num=$(api /number/get country=73 service=wa "request_id=$(uuidgen)") # uma por compra
[ "$(jq -r .status <<<"$num")" = success ] || { jq . <<<"$num"; exit 1; }
id=$(jq -r .id <<<"$num")
echo "Número: $(jq -r .phone <<<"$num")"

for _ in $(seq 240); do # 240 x 5 s = 20 min
  st=$(api /number/status "id=$id")
  code=$(jq -r '.code // empty' <<<"$st")
  state=$(jq -r .state <<<"$st")
  [ -n "$code" ] && break
  case "$state" in cancelled|expired|completed) break ;; esac
  sleep 5
done

if [ -n "${code:-}" ]; then
  echo "Código: $code"
  api /number/finish "id=$id" >/dev/null
else
  api /number/cancel "id=$id" >/dev/null
  echo "Cancelado e reembolsado."
fi

Boas práticas

  • Token em variável de ambiente. Nunca no código, no front-end ou em repositório.
  • request_id em toda compra. Repetiu a chamada? Mesma request_id.
  • Polling de 5 s, com prazo máximo.
  • Vários números: /activations?state=active em vez de um /number/status por ativação.
  • Trate error, não message.
  • 429: espere retry_in_seconds. 502: tente de novo com espera crescente (2 s, 4 s, 6 s).
  • Use max_price_brl como teto. Preço e estoque mudam, então consulte /offers antes de lotes grandes.
  • Confira /balance antes de lotes grandes.
  • Guarde request_id e id da ativação nos logs.
  • Cancele só o que não vai usar. Depois do primeiro código não há reembolso.
Referência das rotas

Conta

GET
/api/v1/balance

Saldo

Saldo e totais da conta.

Campos da resposta

CampoTipoDescrição
balance_brlnumberSaldo disponível.
total_spent_brlnumberTotal gasto na conta.
total_recharged_brlnumberTotal recarregado.
currencystringSempre "BRL".

Exemplo

curl "https://kdefy-sms.com/api/v1/balance" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/balance", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/balance",
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/balance");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/balance")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/balance" \
  -H "X-API-Key: $KDEFY_API_KEY" | jq .

Resposta

{
  "status": "success",
  "balance_brl": 25.4,
  "total_spent_brl": 12.1,
  "total_recharged_brl": 37.5,
  "currency": "BRL"
}

Testar

GET
/api/v1/profile

Perfil

Usuário, saldo e data de criação.

Campos da resposta

CampoTipoDescrição
usernamestringUsuário.
balance_brlnumberSaldo disponível.
created_atstringCriação da conta (ISO 8601).

Exemplo

curl "https://kdefy-sms.com/api/v1/profile" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/profile", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/profile",
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/profile");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/profile")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/profile" \
  -H "X-API-Key: $KDEFY_API_KEY" | jq .

Resposta

{
  "status": "success",
  "username": "maria",
  "balance_brl": 25.4,
  "created_at": "2026-09-01T12:00:00.000Z"
}

Testar

Catálogo

GET
/api/v1/countries

Países

Lista de países. Use o id em country.

Campos da resposta

CampoTipoDescrição
countries[].idintegerID do país. Use em country.
countries[].namestringNome.
countries[].dial_codestring | nullDDI, ex.: +55.

Exemplo

curl "https://kdefy-sms.com/api/v1/countries" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/countries", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/countries",
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/countries");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/countries")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/countries" \
  -H "X-API-Key: $KDEFY_API_KEY" | jq .

Resposta

{
  "status": "success",
  "countries": [
    {
      "id": 73,
      "name": "Brasil",
      "dial_code": "+55"
    }
  ]
}

Testar

GET
/api/v1/services

Serviços

Serviços de um país, com estoque e preço inicial. Use code em service.

Parâmetros

NomeDescrição
countryobrigatórioID do país.

Campos da resposta

CampoTipoDescrição
countryintegerPaís consultado.
services[].codestringCódigo. Use em service.
services[].namestringNome.
services[].availableintegerEstoque.
services[].from_price_brlnumber | nullPreço da oferta mais barata.

Erros

pais_invalido

Exemplo

curl "https://kdefy-sms.com/api/v1/services?country=73" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/services?country=73", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/services",
    params={"country": 73},
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/services?country=73");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/services?country=73")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/services" \
  -H "X-API-Key: $KDEFY_API_KEY" \
  --data-urlencode "country=73" | jq .

Resposta

{
  "status": "success",
  "country": 73,
  "services": [
    {
      "code": "wa",
      "name": "WhatsApp",
      "available": 1240,
      "from_price_brl": 7.1
    }
  ]
}

Testar

GET
/api/v1/operators

Operadoras

Operadoras de um país. Uso opcional em operator na compra.

Parâmetros

NomeDescrição
countryobrigatórioID do país.

Campos da resposta

CampoTipoDescrição
countryintegerPaís consultado.
operators[].idstringID da operadora. Use em operator.
operators[].namestringNome.

Erros

pais_invalido

Exemplo

curl "https://kdefy-sms.com/api/v1/operators?country=73" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/operators?country=73", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/operators",
    params={"country": 73},
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/operators?country=73");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/operators?country=73")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/operators" \
  -H "X-API-Key: $KDEFY_API_KEY" \
  --data-urlencode "country=73" | jq .

Resposta

{
  "status": "success",
  "country": 73,
  "operators": [
    {
      "id": "vivo",
      "name": "vivo"
    }
  ]
}

Testar

GET
/api/v1/offers

Ofertas

Faixas de preço e estoque de um serviço num país. Faixas baratas têm pouco estoque; as mais caras tendem a ter número.

Parâmetros

NomeDescrição
countryobrigatórioID do país.
serviceobrigatórioCódigo do serviço.

Campos da resposta

CampoTipoDescrição
offers[].price_brlnumberPreço da faixa.
offers[].availableintegerEstoque da faixa.

Erros

pais_invalidoservico_invalidosem_numeros_disponiveis

Exemplo

curl "https://kdefy-sms.com/api/v1/offers?country=73&service=wa" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/offers?country=73&service=wa", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/offers",
    params={"country": 73, "service": "wa"},
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/offers?country=73&service=wa");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/offers?country=73&service=wa")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/offers" \
  -H "X-API-Key: $KDEFY_API_KEY" \
  --data-urlencode "country=73" \
  --data-urlencode "service=wa" | jq .

Resposta

{
  "status": "success",
  "country": 73,
  "service": "wa",
  "offers": [
    {
      "price_brl": 7.1,
      "available": 12
    },
    {
      "price_brl": 8.4,
      "available": 340
    }
  ]
}

Testar

Números

GETPOST
/api/v1/number/get

Comprar número

Compra um número, ou vários com quantity. Debita na hora. Se o número cancelar ou expirar sem código, o valor volta ao saldo.

Lote e repetição segura: veja Compra em lote e Idempotência em Guias.

Parâmetros

NomeDescrição
countryobrigatórioID do país.
serviceobrigatórioCódigo do serviço.
max_price_brlopcionalTeto de preço. Usa a faixa mais cara que couber nele. Sem isso, usa a mais barata.
operatoropcionalOperadora. Padrão: qualquer. Restringe o estoque.
quantityopcionalQuantidade, de 1 a 50. Sem isso compra 1 e a resposta vem no formato simples.
request_idopcionalChave anti-duplicação, 8 a 80 caracteres. O header Idempotency-Key também vale. Recomendada.

Campos da resposta

CampoTipoDescrição
idstringID da ativação. Vai em /number/status, /number/cancel e /number/finish.
servicestringCódigo do serviço.
service_namestringNome do serviço. Vem do provedor, não é traduzido.
countryintegerID do país.
country_namestringNome do país.
phonestringNúmero com DDI, só dígitos (5511999999999).
statestringEstado da ativação (veja Estados). Valor fixo em inglês; use este na lógica.
state_labelstringEstado em texto, no idioma da conta. Só para exibir.
codestring | nullÚltimo código recebido. null enquanto não chegou.
codesarrayTodos os códigos, [{ code, received_at }], do mais antigo ao mais novo.
price_brlnumberValor cobrado, em reais.
seconds_leftintegerSegundos até a ativação expirar.
cancel_in_secondsintegerSegundos até liberar o cancelamento. 0 = já pode.
balance_brlnumberSaldo depois da compra.
com quantity
requestedintegerQuantidade pedida.
purchasedintegerQuantidade comprada.
failedintegerQuantidade não comprada (não é cobrada).
numbersarrayAtivações, com os mesmos campos acima.
errorsarrayCódigos de erro das compras que falharam (compra parcial).

Erros

pais_invalidoservico_invalidoquantidade_invalidapreco_invalidooperador_invalidorequest_id_invalidorequest_id_reutilizadarequisicao_em_andamentosaldo_insuficientesem_numeros_disponiveispreco_abaixo_do_minimolimite_de_numerosfalha_temporaria

Exemplo

curl "https://kdefy-sms.com/api/v1/number/get?country=73&service=wa&request_id=pedido-0001" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/number/get?country=73&service=wa&request_id=pedido-0001", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/number/get",
    params={"country": 73, "service": "wa", "request_id": "pedido-0001"},
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/number/get?country=73&service=wa&request_id=pedido-0001");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/number/get?country=73&service=wa&request_id=pedido-0001")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/number/get" \
  -H "X-API-Key: $KDEFY_API_KEY" \
  --data-urlencode "country=73" \
  --data-urlencode "service=wa" \
  --data-urlencode "request_id=pedido-0001" | jq .

Resposta

{
  "id": "1842",
  "service": "wa",
  "service_name": "WhatsApp",
  "country": 73,
  "country_name": "Brasil",
  "phone": "5511999999999",
  "state": "waiting",
  "state_label": "Aguardando código",
  "code": null,
  "codes": [],
  "price_brl": 8.4,
  "seconds_left": 1200,
  "cancel_in_seconds": 120,
  "status": "success",
  "balance_brl": 17
}

Resposta com quantity=2

{
  "status": "success",
  "requested": 2,
  "purchased": 2,
  "failed": 0,
  "numbers": [
    {
      "id": "1842",
      "service": "wa",
      "service_name": "WhatsApp",
      "country": 73,
      "country_name": "Brasil",
      "phone": "5511999999999",
      "state": "waiting",
      "state_label": "Aguardando código",
      "code": null,
      "codes": [],
      "price_brl": 8.4,
      "seconds_left": 1200,
      "cancel_in_seconds": 120
    },
    {
      "id": "1843",
      "service": "wa",
      "service_name": "WhatsApp",
      "country": 73,
      "country_name": "Brasil",
      "phone": "5511988887777",
      "state": "waiting",
      "state_label": "Aguardando código",
      "code": null,
      "codes": [],
      "price_brl": 8.4,
      "seconds_left": 1200,
      "cancel_in_seconds": 120
    }
  ],
  "balance_brl": 8.6
}

Testar

GET
/api/v1/number/status

Status e código

Estado da ativação e códigos recebidos.

Parâmetros

NomeDescrição
idobrigatórioID da ativação, vem da compra.

Campos da resposta

CampoTipoDescrição
idstringID da ativação. Vai em /number/status, /number/cancel e /number/finish.
servicestringCódigo do serviço.
service_namestringNome do serviço. Vem do provedor, não é traduzido.
countryintegerID do país.
country_namestringNome do país.
phonestringNúmero com DDI, só dígitos (5511999999999).
statestringEstado da ativação (veja Estados). Valor fixo em inglês; use este na lógica.
state_labelstringEstado em texto, no idioma da conta. Só para exibir.
codestring | nullÚltimo código recebido. null enquanto não chegou.
codesarrayTodos os códigos, [{ code, received_at }], do mais antigo ao mais novo.
price_brlnumberValor cobrado, em reais.
seconds_leftintegerSegundos até a ativação expirar.
cancel_in_secondsintegerSegundos até liberar o cancelamento. 0 = já pode.

Erros

id_invalidoativacao_nao_encontrada

Exemplo

curl "https://kdefy-sms.com/api/v1/number/status?id=1842" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/number/status?id=1842", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/number/status",
    params={"id": "1842"},
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/number/status?id=1842");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/number/status?id=1842")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/number/status" \
  -H "X-API-Key: $KDEFY_API_KEY" \
  --data-urlencode "id=1842" | jq .

Resposta

{
  "status": "success",
  "id": "1842",
  "service": "wa",
  "service_name": "WhatsApp",
  "country": 73,
  "country_name": "Brasil",
  "phone": "5511999999999",
  "state": "code_received",
  "state_label": "Código recebido",
  "code": "123456",
  "codes": [
    {
      "code": "123456",
      "received_at": "2026-10-19T14:02:11.000Z"
    }
  ],
  "price_brl": 8.4,
  "seconds_left": 1103,
  "cancel_in_seconds": 0
}

Testar

GETPOST
/api/v1/number/cancel

Cancelar

Cancela e devolve o valor. Só sem código e 2 min após a compra; antes disso responde cancelamento_muito_cedo com retry_in_seconds. Na API não há multa por cancelamentos seguidos.

Parâmetros

NomeDescrição
idobrigatórioID da ativação.

Campos da resposta

CampoTipoDescrição
idstringID da ativação.
statestringSempre "cancelled".
refunded_brlnumberValor devolvido.
balance_brlnumberSaldo depois do reembolso.

Erros

id_invalidoativacao_nao_encontradaativacao_nao_cancelavelcancelamento_muito_cedofalha_temporaria

Exemplo

curl "https://kdefy-sms.com/api/v1/number/cancel?id=1842" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/number/cancel?id=1842", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/number/cancel",
    params={"id": "1842"},
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/number/cancel?id=1842");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/number/cancel?id=1842")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/number/cancel" \
  -H "X-API-Key: $KDEFY_API_KEY" \
  --data-urlencode "id=1842" | jq .

Resposta

{
  "status": "success",
  "id": "1842",
  "state": "cancelled",
  "refunded_brl": 8.4,
  "balance_brl": 25.4
}

Testar

GETPOST
/api/v1/number/finish

Finalizar

Encerra a ativação depois do código. Para de esperar códigos extras. Sem reembolso.

Parâmetros

NomeDescrição
idobrigatórioID da ativação.

Campos da resposta

CampoTipoDescrição
idstringID da ativação.
statestringSempre "completed".

Erros

id_invalidoativacao_nao_encontradaativacao_nao_finalizavel

Exemplo

curl "https://kdefy-sms.com/api/v1/number/finish?id=1842" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/number/finish?id=1842", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/number/finish",
    params={"id": "1842"},
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/number/finish?id=1842");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/number/finish?id=1842")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/number/finish" \
  -H "X-API-Key: $KDEFY_API_KEY" \
  --data-urlencode "id=1842" | jq .

Resposta

{
  "status": "success",
  "id": "1842",
  "state": "completed"
}

Testar

Histórico

GET
/api/v1/activations

Listar ativações

Suas ativações, inclusive as do site, da mais nova para a mais antiga.

Parâmetros

NomeDescrição
stateopcional"active" lista só as em andamento.
limitopcionalMáximo de itens. Padrão 50, máx. 100.

Campos da resposta

CampoTipoDescrição
activations[]arrayAtivações, com os mesmos campos de /number/status.

Exemplo

curl "https://kdefy-sms.com/api/v1/activations?state=active" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/activations?state=active", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/activations",
    params={"state": "active"},
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/activations?state=active");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/activations?state=active")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/activations" \
  -H "X-API-Key: $KDEFY_API_KEY" \
  --data-urlencode "state=active" | jq .

Resposta

{
  "status": "success",
  "activations": [
    {
      "id": "1842",
      "service": "wa",
      "service_name": "WhatsApp",
      "country": 73,
      "country_name": "Brasil",
      "phone": "5511999999999",
      "state": "waiting",
      "state_label": "Aguardando código",
      "code": null,
      "codes": [],
      "price_brl": 8.4,
      "seconds_left": 1200,
      "cancel_in_seconds": 120
    }
  ]
}

Testar

GET
/api/v1/transactions

Extrato

Recargas, compras e reembolsos.

Parâmetros

NomeDescrição
limitopcionalMáximo de itens. Padrão 50, máx. 200.

Campos da resposta

CampoTipoDescrição
transactions[].typestringTipo (PURCHASE, REFUND...).
transactions[].amount_brlnumberValor.
transactions[].balance_after_brlnumberSaldo depois.
transactions[].descriptionstringDescrição.
transactions[].created_atstringData (ISO 8601).

Exemplo

curl "https://kdefy-sms.com/api/v1/transactions?limit=20" \
  -H "X-API-Key: $KDEFY_API_KEY"
const res = await fetch("https://kdefy-sms.com/api/v1/transactions?limit=20", {
  headers: { "X-API-Key": process.env.KDEFY_API_KEY },
});
const data = await res.json();
if (data.status !== "success") throw new Error(data.error);
console.log(data);
import os, requests

r = requests.get(
    "https://kdefy-sms.com/api/v1/transactions",
    params={"limit": 20},
    headers={"X-API-Key": os.environ["KDEFY_API_KEY"]},
    timeout=20,
)
data = r.json()
if data["status"] != "success":
    raise RuntimeError(data["error"])
print(data)
<?php
$ch = curl_init("https://kdefy-sms.com/api/v1/transactions?limit=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("KDEFY_API_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
if (($data["status"] ?? null) !== "success") {
    throw new RuntimeException($data["error"] ?? "erro_desconhecido");
}
print_r($data);
require "net/http"
require "json"

uri = URI("https://kdefy-sms.com/api/v1/transactions?limit=20")
req = Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("KDEFY_API_KEY"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 20) { |http| http.request(req) }
data = JSON.parse(res.body)
abort(data["error"]) unless data["status"] == "success"
puts JSON.pretty_generate(data)
#!/usr/bin/env bash
curl -sS --max-time 20 -G "https://kdefy-sms.com/api/v1/transactions" \
  -H "X-API-Key: $KDEFY_API_KEY" \
  --data-urlencode "limit=20" | jq .

Resposta

{
  "status": "success",
  "transactions": [
    {
      "type": "PURCHASE",
      "amount_brl": 8.4,
      "balance_after_brl": 17,
      "description": "Compra WhatsApp · Brasil (API)",
      "created_at": "2026-10-19T14:00:00.000Z"
    }
  ]
}

Testar

Erros

Formato: { "status": "error", "error": "saldo_insuficiente", "message": "..." }. Decida pelo campo error.

HTTPerrorQuandoO que fazer
401token_nao_informado token_invalido Token ausente, inválido ou revogado.Corrija o token. Não repita.
403conta_bloqueada token_suspenso Conta banida ou API suspensa pelo admin.Fale com o suporte.
400pais_invalido servico_invalido id_invalido quantidade_invalida preco_invalido operador_invalido request_id_invalido Parâmetro ausente ou inválido.Corrija a chamada.
402saldo_insuficiente Saldo menor que o preço.Recarregue no site.
404sem_numeros_disponiveis oferta_indisponivel Sem estoque nessa faixa agora.Suba max_price_brl, troque o país ou tente depois.
404ativacao_nao_encontrada ID inexistente ou de outra conta.Confira o id.
409requisicao_em_andamento A request_id ainda está sendo processada.Espere e repita a mesma chamada.
409cancelamento_muito_cedo Menos de 2 min desde a compra.Espere retry_in_seconds.
409ativacao_nao_cancelavel ativacao_nao_finalizavel O estado atual não permite a ação.Consulte /number/status.
422request_id_reutilizada Mesma request_id com parâmetros diferentes.Use uma request_id nova.
422preco_abaixo_do_minimo max_price_brl menor que a oferta mais barata.Suba para min_price_brl ou mais.
429limite_de_requisicoes limite_de_numeros Passou do limite.Espere retry_in_seconds.
502falha_temporaria Instabilidade. Você não é cobrado.Repita com espera crescente, mesma request_id.
Ajuda

Perguntas frequentes

Quanto o código demora?

Em geral segundos, mas depende do serviço. A ativação espera até 20 min. Sem código nesse prazo, expira e o valor volta ao saldo.

Dei timeout na compra. E agora?

Repita a mesma chamada com a mesma request_id: a resposta original volta e nada é cobrado de novo. Se você não usou request_id, liste /activations?state=active antes de comprar outra vez.

Posso cancelar logo depois de comprar?

Não. O cancelamento libera 2 min após a compra. cancel_in_seconds mostra quanto falta.

sem_numeros_disponiveis com saldo. Por quê?

A faixa de preço está sem estoque agora. Suba max_price_brl, troque o país ou veja onde há estoque em /offers.

O preço muda entre a consulta e a compra?

Pode mudar. Vale o price_brl da resposta da compra, e max_price_brl impede que passe do seu teto.

Preciso de request_id?

Não é obrigatória, mas use em qualquer automação. Sem ela, repetir a chamada por engano compra duas vezes.

Dá para comprar mais de 50 números?

Não numa requisição, e o teto é 50 por minuto por conta. Acima disso a API responde limite_de_numeros.

Por que a resposta vem em português?

message e state_label seguem o idioma da conta. Force com ?lang=pt ou ?lang=en. Chaves do JSON, state e códigos de erro são sempre os mesmos.

Como recarrego o saldo?

Pelo site, com PIX. O saldo da API é o mesmo do site.

O token vazou.

Gere outro em API, no site. O antigo para de funcionar na hora. Se viu uso estranho, fale com o suporte.

Regras de uso

  • Cada ativação espera o código por até 20 min. Sem código, expira e o valor volta ao saldo.
  • Depois do primeiro código não há reembolso.
  • Você só enxerga e opera as suas ativações.
  • Recarga de saldo é pelo site (PIX).
  • Toda requisição fica registrada na conta. O admin consulta o uso do token.
  • Abuso ou fraude pode bloquear a conta.