KDEFY SMS API
FR
TXT JSON Générer mon tokenToken
v1.0

KDEFY SMS API

API REST pour acheter des numéros virtuels et recevoir des SMS. Elle utilise le même solde et les mêmes activations que votre compte sur le site.

URL de base
https://kdefy-sms.com/api/v1
AuthentificationX-API-Key
FormatJSON
Limite120 req/min

Toutes les routes

GET /balanceSolde et totaux du compte.
GET /profileUtilisateur, solde et date de création.
GET /countriesListe des pays.
GET /servicesServices d’un pays, avec stock et prix de départ.
GET /operatorsOpérateurs d’un pays.
GET /offersPaliers de prix et stock d’un service dans un pays.
GET POST /number/getAchète un numéro, ou plusieurs avec quantity.
GET /number/statusÉtat de l’activation et codes reçus.
GET POST /number/cancelAnnule et rembourse le montant.
GET POST /number/finishClôture l’activation après le code.
GET /activationsVos activations, y compris celles du site, de la plus récente à la plus ancienne.
GET /transactionsRecharges, achats et remboursements.

Console de test

Générer ou voir mon token →

Ces valeurs valent pour tous les tests de la page. Le token reste uniquement dans cet onglet. Acheter débite réellement votre solde.

Pour commencer

Authentification

Générez le jeton dans API, dans le menu du site, et envoyez-le dans l’en-tête X-API-Key à chaque requête. Authorization: Bearer et ?api_key= fonctionnent aussi, mais la query string finit dans les logs de proxy et l’historique du navigateur. Générer un nouveau jeton invalide immédiatement le précédent. N’utilisez pas le jeton côté 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"

Réponses et langue

  • Toute réponse est en JSON. Succès : { "status": "success", ... }. Erreur : { "status": "error", "error": "code", "message": "texte" }.
  • Décidez à partir du champ error. Il est stable. message est un texte pour humains et peut changer.
  • message et state_label suivent la langue du compte (pt ou en). Pour la forcer : ?lang=pt ou ?lang=en.
  • Les clés JSON et les valeurs de state ne changent pas avec la langue.
  • Montants en BRL avec point décimal. Dates en ISO 8601 (UTC).
Concepts

États

stateSignification
waitingEn attente du premier code.
code_receivedCode reçu. Les nouveaux codes s’ajoutent à codes tant que l’activation est ouverte.
completedTerminée par vous (/number/finish).
cancelledAnnulée. Montant remboursé.
expiredAucun code en 20 min. Montant remboursé automatiquement.

Limites

  • 120 requêtes par minute par compte.
  • Achat : jusqu’à 50 numéros par requête et 50 par minute. Au-delà : limite_de_numeros.
  • Statut : interrogez toutes les 5 s. Plus vite n’accélère pas l’arrivée du code.
Guides

Parcours d’achat

  1. GET /services?country=73 : services du pays et prix de départ.
  2. GET /offers?country=73&service=wa (facultatif) : paliers de prix et stock.
  3. GET /number/get?country=73&service=wa&request_id=... : achète et renvoie phone et id.
  4. GET /number/status?id=ID toutes les 5 s, jusqu’à ce que code soit rempli.
  5. Avec code : GET /number/finish?id=ID. Sans code : GET /number/cancel?id=ID (possible 2 min après l’achat) et le montant revient au solde.

Attendre le code

Interrogez /number/status toutes les 5 s et arrêtez quand code est rempli ou que state passe à cancelled, expired ou completed.

  • Définissez un délai maximal dans votre code (20 min).
  • Avec plusieurs numéros, utilisez /activations?state=active. Un seul appel renvoie toutes les actives.
  • Une activation peut recevoir plus d’un code. Lisez codes[].

Achat en lot

quantity=N achète N numéros en un appel, jusqu’à 50. Un achat partiel est normal : si le stock ou le solde manque en cours de route, le reste n’est pas débité.

  • La réponse contient numbers[], requested, purchased et failed.
  • errors liste le motif des échecs, le cas échéant.
  • Limite de 50 numéros par minute par compte.
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"

Idempotence (request_id)

Envoyez request_id à chaque achat. En cas de timeout, si vous ne savez pas si l’achat a abouti, répétez le même appel avec la même request_id. L’API renvoie la réponse d’origine, avec l’en-tête Idempotent-Replay: true, et ne débite pas à nouveau.

  • Nouvel achat, nouvelle request_id.
  • 8 à 80 caractères (lettres, chiffres, _ . : -). L’en-tête Idempotency-Key fonctionne aussi.
  • La clé dure 24 h et n’est enregistrée que si l’achat a réussi. Un achat échoué peut être répété.
  • Même clé avec des paramètres différents : request_id_reutilizada.

Exemple complet

Achetez, attendez le code et terminez. Si le code n’arrive pas, annulez. L’achat utilise request_id, donc répéter l’appel ne le duplique pas.

// 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

Bonnes pratiques

  • Jeton dans une variable d’environnement. Jamais dans le code, le front-end ou un dépôt.
  • request_id à chaque achat. Appel répété ? Même request_id.
  • Polling de 5 s, avec délai maximal.
  • Plusieurs numéros : /activations?state=active au lieu d’un /number/status par activation.
  • Traitez error, pas message.
  • 429 : attendez retry_in_seconds. 502 : réessayez avec une attente croissante (2 s, 4 s, 6 s).
  • Utilisez max_price_brl comme plafond. Prix et stock changent, consultez donc /offers avant les gros lots.
  • Vérifiez /balance avant les gros lots.
  • Conservez request_id et l’id de l’activation dans vos logs.
  • N’annulez que ce que vous n’utiliserez pas. Après le premier code, pas de remboursement.
Référence des routes

Compte

GET
/api/v1/balance

Solde

Solde et totaux du compte.

Champs de la réponse

ChampTypeDescription
balance_brlnumberSolde disponible.
total_spent_brlnumberTotal dépensé sur le compte.
total_recharged_brlnumberTotal rechargé.
currencystringToujours "BRL".

Exemple

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 .

Réponse

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

Tester

GET
/api/v1/profile

Profil

Utilisateur, solde et date de création.

Champs de la réponse

ChampTypeDescription
usernamestringUtilisateur.
balance_brlnumberSolde disponible.
created_atstringCréation du compte (ISO 8601).

Exemple

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 .

Réponse

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

Tester

Catalogue

GET
/api/v1/countries

Pays

Liste des pays. Utilisez l’id dans country.

Champs de la réponse

ChampTypeDescription
countries[].idintegerID du pays. À utiliser dans country.
countries[].namestringNom.
countries[].dial_codestring | nullIndicatif, ex. : +55.

Exemple

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 .

Réponse

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

Tester

GET
/api/v1/services

Services

Services d’un pays, avec stock et prix de départ. Utilisez code dans service.

Paramètres

NomDescription
countryobligatoireID du pays.

Champs de la réponse

ChampTypeDescription
countryintegerPays interrogé.
services[].codestringCode. À utiliser dans service.
services[].namestringNom.
services[].availableintegerStock.
services[].from_price_brlnumber | nullPrix de l’offre la moins chère.

Erreurs

pais_invalido

Exemple

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 .

Réponse

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

Tester

GET
/api/v1/operators

Opérateurs

Opérateurs d’un pays. Usage facultatif dans operator à l’achat.

Paramètres

NomDescription
countryobligatoireID du pays.

Champs de la réponse

ChampTypeDescription
countryintegerPays interrogé.
operators[].idstringID de l’opérateur. À utiliser dans operator.
operators[].namestringNom.

Erreurs

pais_invalido

Exemple

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 .

Réponse

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

Tester

GET
/api/v1/offers

Offres

Paliers de prix et stock d’un service dans un pays. Les paliers bon marché ont peu de stock ; les plus chers ont en général des numéros.

Paramètres

NomDescription
countryobligatoireID du pays.
serviceobligatoireCode du service.

Champs de la réponse

ChampTypeDescription
offers[].price_brlnumberPrix du palier.
offers[].availableintegerStock du palier.

Erreurs

pais_invalidoservico_invalidosem_numeros_disponiveis

Exemple

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 .

Réponse

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

Tester

Numéros

GETPOST
/api/v1/number/get

Acheter un numéro

Achète un numéro, ou plusieurs avec quantity. Débité immédiatement. Si le numéro est annulé ou expire sans code, le montant revient au solde.

Lots et répétition sûre : voir Achat en lot et Idempotence dans Guides.

Paramètres

NomDescription
countryobligatoireID du pays.
serviceobligatoireCode du service.
max_price_brloptionnelPlafond de prix. Utilise le palier le plus cher qui y rentre. Sans cela, le moins cher.
operatoroptionnelOpérateur. Par défaut : n’importe lequel. Restreint le stock.
quantityoptionnelQuantité, de 1 à 50. Sans cela, achète 1 et la réponse arrive au format simple.
request_idoptionnelClé anti-doublon, 8 à 80 caractères. L’en-tête Idempotency-Key fonctionne aussi. Recommandée.

Champs de la réponse

ChampTypeDescription
idstringID de l’activation. Utilisé dans /number/status, /number/cancel et /number/finish.
servicestringCode du service.
service_namestringNom du service. Fourni par le prestataire, non traduit.
countryintegerID du pays.
country_namestringNom du pays.
phonestringNuméro avec indicatif, chiffres uniquement (5511999999999).
statestringÉtat de l’activation (voir États). Valeur fixe en anglais ; utilisez-la dans votre logique.
state_labelstringÉtat en texte, dans la langue du compte. Pour l’affichage uniquement.
codestring | nullDernier code reçu. null tant qu’il n’est pas arrivé.
codesarrayTous les codes, [{ code, received_at }], du plus ancien au plus récent.
price_brlnumberMontant débité, en reais.
seconds_leftintegerSecondes avant l’expiration de l’activation.
cancel_in_secondsintegerSecondes avant de pouvoir annuler. 0 = déjà possible.
balance_brlnumberSolde après l’achat.
avec quantity
requestedintegerQuantité demandée.
purchasedintegerQuantité achetée.
failedintegerQuantité non achetée (non débitée).
numbersarrayActivations, avec les mêmes champs que ci-dessus.
errorsarrayCodes d’erreur des achats échoués (achat partiel).

Erreurs

pais_invalidoservico_invalidoquantidade_invalidapreco_invalidooperador_invalidorequest_id_invalidorequest_id_reutilizadarequisicao_em_andamentosaldo_insuficientesem_numeros_disponiveispreco_abaixo_do_minimolimite_de_numerosfalha_temporaria

Exemple

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 .

Réponse

{
  "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
}

Réponse avec 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
}

Tester

GET
/api/v1/number/status

Statut et code

État de l’activation et codes reçus.

Paramètres

NomDescription
idobligatoireID de l’activation, issu de l’achat.

Champs de la réponse

ChampTypeDescription
idstringID de l’activation. Utilisé dans /number/status, /number/cancel et /number/finish.
servicestringCode du service.
service_namestringNom du service. Fourni par le prestataire, non traduit.
countryintegerID du pays.
country_namestringNom du pays.
phonestringNuméro avec indicatif, chiffres uniquement (5511999999999).
statestringÉtat de l’activation (voir États). Valeur fixe en anglais ; utilisez-la dans votre logique.
state_labelstringÉtat en texte, dans la langue du compte. Pour l’affichage uniquement.
codestring | nullDernier code reçu. null tant qu’il n’est pas arrivé.
codesarrayTous les codes, [{ code, received_at }], du plus ancien au plus récent.
price_brlnumberMontant débité, en reais.
seconds_leftintegerSecondes avant l’expiration de l’activation.
cancel_in_secondsintegerSecondes avant de pouvoir annuler. 0 = déjà possible.

Erreurs

id_invalidoativacao_nao_encontrada

Exemple

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 .

Réponse

{
  "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
}

Tester

GETPOST
/api/v1/number/cancel

Annuler

Annule et rembourse le montant. Uniquement sans code et 2 min après l’achat ; avant, répond cancelamento_muito_cedo avec retry_in_seconds. Dans l’API, il n’y a pas de pénalité pour des annulations successives.

Paramètres

NomDescription
idobligatoireID de l’activation.

Champs de la réponse

ChampTypeDescription
idstringID de l’activation.
statestringToujours "cancelled".
refunded_brlnumberMontant remboursé.
balance_brlnumberSolde après le remboursement.

Erreurs

id_invalidoativacao_nao_encontradaativacao_nao_cancelavelcancelamento_muito_cedofalha_temporaria

Exemple

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 .

Réponse

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

Tester

GETPOST
/api/v1/number/finish

Terminer

Clôture l’activation après le code. Cesse d’attendre des codes supplémentaires. Sans remboursement.

Paramètres

NomDescription
idobligatoireID de l’activation.

Champs de la réponse

ChampTypeDescription
idstringID de l’activation.
statestringToujours "completed".

Erreurs

id_invalidoativacao_nao_encontradaativacao_nao_finalizavel

Exemple

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 .

Réponse

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

Tester

Historique

GET
/api/v1/activations

Lister les activations

Vos activations, y compris celles du site, de la plus récente à la plus ancienne.

Paramètres

NomDescription
stateoptionnel"active" ne liste que celles en cours.
limitoptionnelNombre maximum d’éléments. Par défaut 50, max 100.

Champs de la réponse

ChampTypeDescription
activations[]arrayActivations, avec les mêmes champs que /number/status.

Exemple

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 .

Réponse

{
  "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
    }
  ]
}

Tester

GET
/api/v1/transactions

Relevé

Recharges, achats et remboursements.

Paramètres

NomDescription
limitoptionnelNombre maximum d’éléments. Par défaut 50, max 200.

Champs de la réponse

ChampTypeDescription
transactions[].typestringType (PURCHASE, REFUND...).
transactions[].amount_brlnumberMontant.
transactions[].balance_after_brlnumberSolde après.
transactions[].descriptionstringDescription.
transactions[].created_atstringDate (ISO 8601).

Exemple

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 .

Réponse

{
  "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"
    }
  ]
}

Tester

Erreurs

Format : { "status": "error", "error": "saldo_insuficiente", "message": "..." }. Décidez à partir du champ error.

HTTPerrorQuandQue faire
401token_nao_informado token_invalido Jeton absent, invalide ou révoqué.Corrigez le jeton. Ne réessayez pas.
403conta_bloqueada token_suspenso Compte banni ou API suspendue par l’admin.Contactez le support.
400pais_invalido servico_invalido id_invalido quantidade_invalida preco_invalido operador_invalido request_id_invalido Paramètre manquant ou invalide.Corrigez l’appel.
402saldo_insuficiente Solde inférieur au prix.Rechargez sur le site.
404sem_numeros_disponiveis oferta_indisponivel Pas de stock dans ce palier pour le moment.Augmentez max_price_brl, changez de pays ou réessayez plus tard.
404ativacao_nao_encontrada ID inexistant ou appartenant à un autre compte.Vérifiez l’id.
409requisicao_em_andamento La request_id est encore en cours de traitement.Attendez et répétez le même appel.
409cancelamento_muito_cedo Moins de 2 min depuis l’achat.Attendez retry_in_seconds.
409ativacao_nao_cancelavel ativacao_nao_finalizavel L’état actuel n’autorise pas l’action.Consultez /number/status.
422request_id_reutilizada Même request_id avec des paramètres différents.Utilisez une nouvelle request_id.
422preco_abaixo_do_minimo max_price_brl inférieur à l’offre la moins chère.Montez à min_price_brl ou plus.
429limite_de_requisicoes limite_de_numeros Limite dépassée.Attendez retry_in_seconds.
502falha_temporaria Instabilité. Vous n’êtes pas débité.Réessayez avec une attente croissante, même request_id.
Aide

Questions fréquentes

Combien de temps met le code ?

En général quelques secondes, mais cela dépend du service. L’activation attend jusqu’à 20 min. Sans code dans ce délai, elle expire et le montant revient au solde.

Mon achat a expiré (timeout). Et maintenant ?

Répétez le même appel avec la même request_id : la réponse d’origine revient et rien n’est débité à nouveau. Si vous n’avez pas utilisé request_id, listez /activations?state=active avant de racheter.

Puis-je annuler juste après l’achat ?

Non. L’annulation devient possible 2 min après l’achat. cancel_in_seconds indique le temps restant.

sem_numeros_disponiveis avec du solde. Pourquoi ?

Le palier de prix est en rupture pour le moment. Augmentez max_price_brl, changez de pays ou voyez où il y a du stock dans /offers.

Le prix peut-il changer entre la consultation et l’achat ?

Oui. Le price_brl de la réponse d’achat fait foi, et max_price_brl empêche de dépasser votre plafond.

Ai-je besoin de request_id ?

Elle n’est pas obligatoire, mais utilisez-la dans toute automatisation. Sans elle, répéter l’appel par erreur achète deux fois.

Peut-on acheter plus de 50 numéros ?

Pas en une seule requête, et le plafond est de 50 par minute par compte. Au-delà, l’API répond limite_de_numeros.

Pourquoi la réponse est-elle en portugais ?

message et state_label suivent la langue du compte. Forcez-la avec ?lang=pt ou ?lang=en. Les clés JSON, state et les codes d’erreur sont toujours les mêmes.

Comment recharger mon solde ?

Sur le site, via PIX. Le solde de l’API est le même que celui du site.

Mon jeton a fuité.

Générez-en un autre dans API, sur le site. L’ancien cesse de fonctionner immédiatement. Si vous avez vu un usage étrange, contactez le support.

Règles d’utilisation

  • Chaque activation attend le code jusqu’à 20 min. Sans code, elle expire et le montant revient au solde.
  • Après le premier code, il n’y a pas de remboursement.
  • Vous ne voyez et ne gérez que vos propres activations.
  • La recharge du solde se fait sur le site (PIX).
  • Chaque requête est enregistrée sur le compte. L’admin consulte l’usage du jeton.
  • Un abus ou une fraude peut entraîner le blocage du compte.