KDEFY SMS API
DE
TXT JSON Meinen Token erzeugenToken
v1.0

KDEFY SMS API

REST-API zum Kaufen virtueller Nummern und Empfangen von SMS. Sie nutzt dasselbe Guthaben und dieselben Aktivierungen wie Ihr Konto auf der Website.

Basis-URL
https://kdefy-sms.com/api/v1
AuthentifizierungX-API-Key
FormatJSON
Limit120 Anf./Min.

Alle Routen

GET /balanceKontoguthaben und Summen.
GET /profileBenutzername, Guthaben und Erstellungsdatum.
GET /countriesListe der Länder.
GET /servicesDienste eines Landes mit Bestand und Startpreis.
GET /operatorsNetzbetreiber eines Landes.
GET /offersPreisstufen und Bestand eines Dienstes in einem Land.
GET POST /number/getKauft eine Nummer oder mehrere mit quantity.
GET /number/statusAktivierungsstatus und empfangene Codes.
GET POST /number/cancelStorniert und erstattet den Betrag.
GET POST /number/finishBeendet die Aktivierung nach dem Code.
GET /activationsIhre Aktivierungen, auch die von der Website, von der neuesten zur ältesten.
GET /transactionsAufladungen, Käufe und Erstattungen.

Testkonsole

Meinen Token erzeugen oder ansehen →

Diese Werte gelten für alle Tests auf der Seite. Der Token bleibt nur in diesem Tab. Kaufen belastet Ihr Guthaben tatsächlich.

Erste Schritte

Authentifizierung

Erzeugen Sie den Token unter API im Menü der Website und senden Sie ihn bei jeder Anfrage im Header X-API-Key. Authorization: Bearer und ?api_key= funktionieren ebenfalls, aber die Query-String landet in Proxy-Logs und im Browserverlauf. Ein neuer Token macht den vorherigen sofort ungültig. Verwenden Sie den Token nicht im Frontend.

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"

Antworten und Sprache

  • Jede Antwort ist JSON. Erfolg: { "status": "success", ... }. Fehler: { "status": "error", "error": "code", "message": "text" }.
  • Entscheiden Sie anhand des Felds error. Es ist stabil. message ist Text für Menschen und kann sich ändern.
  • message und state_label folgen der Kontosprache (pt oder en). Zum Erzwingen: ?lang=pt oder ?lang=en.
  • JSON-Schlüssel und state-Werte ändern sich nicht mit der Sprache.
  • Beträge in BRL mit Dezimalpunkt. Datumsangaben in ISO 8601 (UTC).
Konzepte

Zustände

stateBedeutung
waitingWartet auf den ersten Code.
code_receivedCode empfangen. Neue Codes landen in codes, solange die Aktivierung offen ist.
completedVon Ihnen abgeschlossen (/number/finish).
cancelledStorniert. Betrag erstattet.
expiredKein Code innerhalb von 20 Min. Betrag wird automatisch erstattet.

Limits

  • 120 Anfragen pro Minute pro Konto.
  • Kauf: bis zu 50 Nummern pro Anfrage und 50 pro Minute. Darüber: limite_de_numeros.
  • Status: alle 5 s abfragen. Schnelleres Abfragen beschleunigt den Code nicht.
Anleitungen

Kaufablauf

  1. GET /services?country=73: Dienste des Landes und Startpreis.
  2. GET /offers?country=73&service=wa (optional): Preisstufen und Bestand.
  3. GET /number/get?country=73&service=wa&request_id=...: kauft und liefert phone und id.
  4. GET /number/status?id=ID alle 5 s, bis code gefüllt ist.
  5. Mit Code: GET /number/finish?id=ID. Ohne Code: GET /number/cancel?id=ID (2 Min. nach dem Kauf möglich) und der Betrag geht zurück aufs Guthaben.

Auf den Code warten

Fragen Sie /number/status alle 5 s ab und hören Sie auf, wenn code gefüllt ist oder state cancelled, expired oder completed wird.

  • Legen Sie in Ihrem Code ein Zeitlimit fest (20 Min.).
  • Bei mehreren Nummern nutzen Sie /activations?state=active. Ein Aufruf liefert alle aktiven.
  • Eine Aktivierung kann mehr als einen Code erhalten. Lesen Sie codes[].

Stapelkauf

quantity=N kauft N Nummern in einem Aufruf, bis zu 50. Ein Teilkauf ist normal: Gehen Bestand oder Guthaben mittendrin aus, wird der Rest nicht berechnet.

  • Die Antwort enthält numbers[], requested, purchased und failed.
  • errors listet gegebenenfalls die Fehlerursachen auf.
  • Limit von 50 Nummern pro Minute pro Konto.
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"

Idempotenz (request_id)

Senden Sie bei jedem Kauf eine request_id. Bei einem Timeout und Unklarheit, ob der Kauf durchging, wiederholen Sie denselben Aufruf mit derselben request_id. Die API liefert die ursprüngliche Antwort mit dem Header Idempotent-Replay: true und berechnet nicht erneut.

  • Neuer Kauf, neue request_id.
  • 8 bis 80 Zeichen (Buchstaben, Zahlen, _ . : -). Der Header Idempotency-Key funktioniert ebenfalls.
  • Der Schlüssel gilt 24 Std. und wird nur gespeichert, wenn der Kauf erfolgreich war. Ein fehlgeschlagener Kauf kann wiederholt werden.
  • Derselbe Schlüssel mit anderen Parametern: request_id_reutilizada.

Vollständiges Beispiel

Kaufen, auf den Code warten und abschließen. Kommt der Code nicht an, stornieren. Der Kauf nutzt request_id, daher dupliziert ein wiederholter Aufruf ihn nicht.

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

Best Practices

  • Token in einer Umgebungsvariable. Nie im Code, im Frontend oder in einem Repository.
  • request_id bei jedem Kauf. Aufruf wiederholt? Dieselbe request_id.
  • Polling alle 5 s, mit Zeitlimit.
  • Mehrere Nummern: /activations?state=active statt eines /number/status pro Aktivierung.
  • Behandeln Sie error, nicht message.
  • 429: retry_in_seconds abwarten. 502: mit zunehmender Wartezeit erneut versuchen (2 s, 4 s, 6 s).
  • Verwenden Sie max_price_brl als Obergrenze. Preis und Bestand ändern sich, prüfen Sie daher /offers vor großen Stapeln.
  • Prüfen Sie /balance vor großen Stapeln.
  • Speichern Sie request_id und Aktivierungs-id in Ihren Logs.
  • Stornieren Sie nur, was Sie nicht nutzen. Nach dem ersten Code gibt es keine Erstattung.
Routenreferenz

Konto

GET
/api/v1/balance

Guthaben

Kontoguthaben und Summen.

Antwortfelder

FeldTypBeschreibung
balance_brlnumberVerfügbares Guthaben.
total_spent_brlnumberGesamtausgaben des Kontos.
total_recharged_brlnumberInsgesamt aufgeladen.
currencystringImmer "BRL".

Beispiel

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 .

Antwort

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

Testen

GET
/api/v1/profile

Profil

Benutzername, Guthaben und Erstellungsdatum.

Antwortfelder

FeldTypBeschreibung
usernamestringBenutzername.
balance_brlnumberVerfügbares Guthaben.
created_atstringKontoerstellung (ISO 8601).

Beispiel

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 .

Antwort

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

Testen

Katalog

GET
/api/v1/countries

Länder

Liste der Länder. Verwenden Sie die id in country.

Antwortfelder

FeldTypBeschreibung
countries[].idintegerLänder-ID. In country verwenden.
countries[].namestringName.
countries[].dial_codestring | nullVorwahl, z. B. +55.

Beispiel

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 .

Antwort

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

Testen

GET
/api/v1/services

Dienste

Dienste eines Landes mit Bestand und Startpreis. Verwenden Sie code in service.

Parameter

NameBeschreibung
countryerforderlichLänder-ID.

Antwortfelder

FeldTypBeschreibung
countryintegerAbgefragtes Land.
services[].codestringCode. In service verwenden.
services[].namestringName.
services[].availableintegerBestand.
services[].from_price_brlnumber | nullPreis des günstigsten Angebots.

Fehler

pais_invalido

Beispiel

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 .

Antwort

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

Testen

GET
/api/v1/operators

Netzbetreiber

Netzbetreiber eines Landes. Optional in operator beim Kauf.

Parameter

NameBeschreibung
countryerforderlichLänder-ID.

Antwortfelder

FeldTypBeschreibung
countryintegerAbgefragtes Land.
operators[].idstringNetzbetreiber-ID. In operator verwenden.
operators[].namestringName.

Fehler

pais_invalido

Beispiel

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 .

Antwort

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

Testen

GET
/api/v1/offers

Angebote

Preisstufen und Bestand eines Dienstes in einem Land. Günstige Stufen haben wenig Bestand; teurere haben meist Nummern.

Parameter

NameBeschreibung
countryerforderlichLänder-ID.
serviceerforderlichDienstcode.

Antwortfelder

FeldTypBeschreibung
offers[].price_brlnumberPreis der Stufe.
offers[].availableintegerBestand der Stufe.

Fehler

pais_invalidoservico_invalidosem_numeros_disponiveis

Beispiel

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 .

Antwort

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

Testen

Nummern

GETPOST
/api/v1/number/get

Nummer kaufen

Kauft eine Nummer oder mehrere mit quantity. Wird sofort abgebucht. Wird die Nummer storniert oder läuft ohne Code ab, geht der Betrag zurück aufs Guthaben.

Stapel und sicheres Wiederholen: siehe Stapelkauf und Idempotenz unter Anleitungen.

Parameter

NameBeschreibung
countryerforderlichLänder-ID.
serviceerforderlichDienstcode.
max_price_brloptionalPreisobergrenze. Es wird die teuerste Stufe genutzt, die passt. Ohne Angabe die günstigste.
operatoroptionalNetzbetreiber. Standard: beliebig. Schränkt den Bestand ein.
quantityoptionalMenge, von 1 bis 50. Ohne Angabe wird 1 gekauft und die Antwort kommt im einfachen Format.
request_idoptionalSchlüssel gegen Doppelkäufe, 8 bis 80 Zeichen. Der Header Idempotency-Key funktioniert ebenfalls. Empfohlen.

Antwortfelder

FeldTypBeschreibung
idstringAktivierungs-ID. Wird in /number/status, /number/cancel und /number/finish verwendet.
servicestringDienstcode.
service_namestringDienstname. Stammt vom Anbieter und wird nicht übersetzt.
countryintegerLänder-ID.
country_namestringLändername.
phonestringNummer mit Landesvorwahl, nur Ziffern (5511999999999).
statestringAktivierungsstatus (siehe Status). Fester englischer Wert; verwenden Sie diesen in der Logik.
state_labelstringStatus als Text in der Kontosprache. Nur zur Anzeige.
codestring | nullZuletzt empfangener Code. null, solange keiner eingetroffen ist.
codesarrayAlle Codes, [{ code, received_at }], vom ältesten zum neuesten.
price_brlnumberBerechneter Betrag in Real.
seconds_leftintegerSekunden bis zum Ablauf der Aktivierung.
cancel_in_secondsintegerSekunden bis zur Stornierungsmöglichkeit. 0 = bereits möglich.
balance_brlnumberGuthaben nach dem Kauf.
mit quantity
requestedintegerAngeforderte Menge.
purchasedintegerGekaufte Menge.
failedintegerNicht gekaufte Menge (wird nicht berechnet).
numbersarrayAktivierungen mit denselben Feldern wie oben.
errorsarrayFehlercodes der fehlgeschlagenen Käufe (Teilkauf).

Fehler

pais_invalidoservico_invalidoquantidade_invalidapreco_invalidooperador_invalidorequest_id_invalidorequest_id_reutilizadarequisicao_em_andamentosaldo_insuficientesem_numeros_disponiveispreco_abaixo_do_minimolimite_de_numerosfalha_temporaria

Beispiel

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 .

Antwort

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

Antwort mit 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
}

Testen

GET
/api/v1/number/status

Status und Code

Aktivierungsstatus und empfangene Codes.

Parameter

NameBeschreibung
iderforderlichAktivierungs-ID, stammt aus dem Kauf.

Antwortfelder

FeldTypBeschreibung
idstringAktivierungs-ID. Wird in /number/status, /number/cancel und /number/finish verwendet.
servicestringDienstcode.
service_namestringDienstname. Stammt vom Anbieter und wird nicht übersetzt.
countryintegerLänder-ID.
country_namestringLändername.
phonestringNummer mit Landesvorwahl, nur Ziffern (5511999999999).
statestringAktivierungsstatus (siehe Status). Fester englischer Wert; verwenden Sie diesen in der Logik.
state_labelstringStatus als Text in der Kontosprache. Nur zur Anzeige.
codestring | nullZuletzt empfangener Code. null, solange keiner eingetroffen ist.
codesarrayAlle Codes, [{ code, received_at }], vom ältesten zum neuesten.
price_brlnumberBerechneter Betrag in Real.
seconds_leftintegerSekunden bis zum Ablauf der Aktivierung.
cancel_in_secondsintegerSekunden bis zur Stornierungsmöglichkeit. 0 = bereits möglich.

Fehler

id_invalidoativacao_nao_encontrada

Beispiel

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 .

Antwort

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

Testen

GETPOST
/api/v1/number/cancel

Stornieren

Storniert und erstattet den Betrag. Nur ohne Code und 2 Min. nach dem Kauf; davor antwortet die API mit cancelamento_muito_cedo und retry_in_seconds. Über die API gibt es keine Strafe für aufeinanderfolgende Stornierungen.

Parameter

NameBeschreibung
iderforderlichAktivierungs-ID.

Antwortfelder

FeldTypBeschreibung
idstringAktivierungs-ID.
statestringImmer "cancelled".
refunded_brlnumberErstatteter Betrag.
balance_brlnumberGuthaben nach der Erstattung.

Fehler

id_invalidoativacao_nao_encontradaativacao_nao_cancelavelcancelamento_muito_cedofalha_temporaria

Beispiel

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 .

Antwort

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

Testen

GETPOST
/api/v1/number/finish

Abschließen

Beendet die Aktivierung nach dem Code. Wartet nicht mehr auf weitere Codes. Keine Erstattung.

Parameter

NameBeschreibung
iderforderlichAktivierungs-ID.

Antwortfelder

FeldTypBeschreibung
idstringAktivierungs-ID.
statestringImmer "completed".

Fehler

id_invalidoativacao_nao_encontradaativacao_nao_finalizavel

Beispiel

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 .

Antwort

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

Testen

Verlauf

GET
/api/v1/activations

Aktivierungen auflisten

Ihre Aktivierungen, auch die von der Website, von der neuesten zur ältesten.

Parameter

NameBeschreibung
stateoptional"active" listet nur laufende auf.
limitoptionalMaximale Anzahl. Standard 50, max. 100.

Antwortfelder

FeldTypBeschreibung
activations[]arrayAktivierungen mit denselben Feldern wie /number/status.

Beispiel

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 .

Antwort

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

Testen

GET
/api/v1/transactions

Kontoauszug

Aufladungen, Käufe und Erstattungen.

Parameter

NameBeschreibung
limitoptionalMaximale Anzahl. Standard 50, max. 200.

Antwortfelder

FeldTypBeschreibung
transactions[].typestringTyp (PURCHASE, REFUND...).
transactions[].amount_brlnumberBetrag.
transactions[].balance_after_brlnumberGuthaben danach.
transactions[].descriptionstringBeschreibung.
transactions[].created_atstringDatum (ISO 8601).

Beispiel

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 .

Antwort

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

Testen

Fehler

Format: { "status": "error", "error": "saldo_insuficiente", "message": "..." }. Entscheiden Sie anhand des Felds error.

HTTPerrorWannWas zu tun ist
401token_nao_informado token_invalido Token fehlt, ist ungültig oder widerrufen.Token korrigieren. Nicht wiederholen.
403conta_bloqueada token_suspenso Konto gesperrt oder API vom Admin ausgesetzt.Wenden Sie sich an den Support.
400pais_invalido servico_invalido id_invalido quantidade_invalida preco_invalido operador_invalido request_id_invalido Parameter fehlt oder ist ungültig.Aufruf korrigieren.
402saldo_insuficiente Guthaben niedriger als der Preis.Laden Sie auf der Website auf.
404sem_numeros_disponiveis oferta_indisponivel Aktuell kein Bestand in dieser Stufe.max_price_brl erhöhen, Land wechseln oder später erneut versuchen.
404ativacao_nao_encontrada ID existiert nicht oder gehört zu einem anderen Konto.Prüfen Sie die id.
409requisicao_em_andamento Die request_id wird noch verarbeitet.Warten und denselben Aufruf wiederholen.
409cancelamento_muito_cedo Weniger als 2 Min. seit dem Kauf.retry_in_seconds abwarten.
409ativacao_nao_cancelavel ativacao_nao_finalizavel Der aktuelle Status erlaubt die Aktion nicht.Prüfen Sie /number/status.
422request_id_reutilizada Dieselbe request_id mit anderen Parametern.Verwenden Sie eine neue request_id.
422preco_abaixo_do_minimo max_price_brl liegt unter dem günstigsten Angebot.Auf min_price_brl oder mehr erhöhen.
429limite_de_requisicoes limite_de_numeros Limit überschritten.retry_in_seconds abwarten.
502falha_temporaria Vorübergehende Instabilität. Ihnen wird nichts berechnet.Mit zunehmender Wartezeit wiederholen, gleiche request_id.
Hilfe

Häufige Fragen

Wie lange dauert der Code?

In der Regel Sekunden, hängt aber vom Dienst ab. Die Aktivierung wartet bis zu 20 Min. Ohne Code in dieser Zeit läuft sie ab und der Betrag geht zurück aufs Guthaben.

Mein Kauf lief in ein Timeout. Und jetzt?

Wiederholen Sie denselben Aufruf mit derselben request_id: Die ursprüngliche Antwort kommt zurück und es wird nichts erneut berechnet. Haben Sie keine request_id verwendet, listen Sie /activations?state=active auf, bevor Sie erneut kaufen.

Kann ich direkt nach dem Kauf stornieren?

Nein. Die Stornierung ist erst 2 Min. nach dem Kauf möglich. cancel_in_seconds zeigt die Restzeit.

sem_numeros_disponiveis trotz Guthaben. Warum?

Die Preisstufe hat aktuell keinen Bestand. Erhöhen Sie max_price_brl, wechseln Sie das Land oder sehen Sie in /offers, wo Bestand ist.

Kann sich der Preis zwischen Abfrage und Kauf ändern?

Das ist möglich. Maßgeblich ist price_brl in der Kaufantwort, und max_price_brl verhindert, dass Ihre Obergrenze überschritten wird.

Brauche ich request_id?

Sie ist nicht Pflicht, aber nutzen Sie sie in jeder Automatisierung. Ohne sie kauft ein versehentlich wiederholter Aufruf doppelt.

Kann ich mehr als 50 Nummern kaufen?

Nicht in einer Anfrage, und die Obergrenze liegt bei 50 pro Minute pro Konto. Darüber antwortet die API mit limite_de_numeros.

Warum kommt die Antwort auf Portugiesisch?

message und state_label folgen der Kontosprache. Erzwingen Sie sie mit ?lang=pt oder ?lang=en. JSON-Schlüssel, state und Fehlercodes sind immer dieselben.

Wie lade ich mein Guthaben auf?

Über die Website mit PIX. Das API-Guthaben ist dasselbe wie auf der Website.

Mein Token ist durchgesickert.

Erzeugen Sie unter API auf der Website einen neuen. Der alte funktioniert sofort nicht mehr. Bei ungewöhnlicher Nutzung wenden Sie sich an den Support.

Nutzungsregeln

  • Jede Aktivierung wartet bis zu 20 Min. auf den Code. Ohne Code läuft sie ab und der Betrag geht zurück aufs Guthaben.
  • Nach dem ersten Code gibt es keine Erstattung.
  • Sie sehen und bedienen nur Ihre eigenen Aktivierungen.
  • Guthaben wird über die Website aufgeladen (PIX).
  • Jede Anfrage wird im Konto protokolliert. Der Admin kann die Token-Nutzung einsehen.
  • Missbrauch oder Betrug kann zur Sperrung des Kontos führen.