Documentação da API

Automatize fluxos de verificação SMS com a API do SimNoKYC. Compre números de telefone virtuais, receba códigos SMS, alugue números dedicados e gerencie pedidos — tudo programaticamente.

Autenticação

A API usa autenticação de sessão baseada em cookies. Para autenticar programaticamente:

Envie uma requisição POST para /auth-api.php com sua frase seed
Armazene o cookie de sessão da resposta
Inclua o cookie em todas as requisições API subsequentes

POST /auth-api.php

Autentique-se com sua frase seed e estabeleça uma sessão.

Parâmetro	Tipo	Obrigatório	Descrição
action	string	obrigatório	Deve ser `"login"`
seed	string	obrigatório	Sua seed de acesso de 16 caracteres (ex. `AbC3-dEf4-gHj5-kLm6`)

cURL
Python
JavaScript
# Login and save session cookie
curl -X POST https://simnokyc.com/auth-api.php \
  -d "action=login&seed=AbC3-dEf4-gHj5-kLm6" \
  -c cookies.txt
import requests

session = requests.Session()
resp = session.post("https://simnokyc.com/auth-api.php", data={
    "action": "login",
    "seed": "AbC3-dEf4-gHj5-kLm6"
})
data = resp.json()
print(data)  # {"success": true, "user": {...}}

# session object now holds the cookie for all future requests
const resp = await fetch("https://simnokyc.com/auth-api.php", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: "action=login&seed=AbC3-dEf4-gHj5-kLm6"
});
const data = await resp.json();
console.log(data); // {success: true, user: {...}}

Resposta de sucesso

{ "success": true, "user": { "id": 42, "prefix": "AbC3", "balance": "74.50" } }

Resposta de erro

{ "success": false, "error": "Invalid seed." }

URL Base

Todos os endpoints da API são relativos a:

https://simnokyc.com/api.php?action={action}

Todas as respostas são em JSON. Os endpoints POST aceitam corpos de requisição application/json e application/x-www-form-urlencoded.

Limites de requisições

A API aplica os seguintes limites de taxa:

Endpoint	Limite	Janela
Autenticação	5 tentativas	15 minutos
Todos os outros endpoints	Sem limite rígido	—

Limite de taxa: A autenticação é limitada a 5 tentativas por 15 minutos. Outros endpoints não são atualmente limitados, mas o uso excessivo pode ser restringido. Use intervalos de requisição razoáveis.

Tratamento de erros

Todos os erros retornam um objeto JSON com um campo <code>error</code>:

{ "error": "Description of what went wrong" }

Código HTTP	Significado
200	Sucesso (verifique o corpo da resposta para erros de nível de aplicação)
403	Token CSRF inválido
405	Método HTTP incorreto (ex. GET em um endpoint somente POST)
429	Limite de taxa excedido

Erros comuns a nível de aplicação:

Erro	Causa
`"Login required"`	Sessão expirada ou não autenticado
`"Insufficient balance"`	Fundos insuficientes — inclui os campos `need` e `have`
`"Service not available for this country"`	Sem estoque ou serviço inativo para o país selecionado
`"Missing country or service"`	Os parâmetros obrigatórios não foram fornecidos

Listar Países

GET /api.php?action=countries

Retorna todos os países ativos com números virtuais disponíveis. Nenhuma autenticação necessária.

cURL
Python
JavaScript
curl https://simnokyc.com/api.php?action=countries
resp = session.get("https://simnokyc.com/api.php", params={"action": "countries"})
countries = resp.json()
for c in countries:
    print(c["code"], c["name"])
const resp = await fetch("https://simnokyc.com/api.php?action=countries");
const countries = await resp.json();

Resposta

[ { "id": 1, "code": "us", "name": "USA" }, { "id": 2, "code": "gb", "name": "UK" }, { "id": 3, "code": "de", "name": "Germany" } ]

Listar Serviços

GET /api.php?action=services&country={code}

Retorna os serviços disponíveis para um país específico, incluindo preços e estoque. Sem código de país, retorna todos os serviços sem preços.

Parâmetro	Tipo	Obrigatório	Descrição
country	string	opcional	Código de país ISO 3166-1 alpha-2 (ex. `us`, `gb`, `de`)

Resposta (com país)

[ { "id": 12, "name": "WhatsApp", "slug": "whatsapp", "icon_code": "WA", "icon_color": "#25d366", "category": "social", "price": "0.35", "stock": 847 } ]

Listar Operadoras

GET /api.php?action=operators&country={code}

Retorna as operadoras disponíveis para um país específico. Cada operadora tem um tipo e um multiplicador de preço aplicado ao preço base do serviço.

Parâmetro	Tipo	Obrigatório	Descrição
country	string	obrigatório	Código de país ISO 3166-1 alpha-2

Resposta

[ { "id": 5, "name": "T-Mobile", "type": "physical", "price_multiplier": "1.50", "icon_slug": "tmobile", "icon_domain": "t-mobile.com" } ]

Tipos de operadoras: virtual — números VoIP, mais baratos, podem ser bloqueados por alguns serviços. physical — cartões SIM reais, maior taxa de sucesso. premium — entrega mais rápida (~10s), maior taxa de sucesso.

Comprar número (Ativação SMS)

POST /api.php?action=buy

Compre um número virtual para verificação SMS única. O número fica ativo por 20 minutos. Se nenhum SMS for recebido, seu saldo é reembolsado automaticamente.

Parâmetro	Tipo	Obrigatório	Descrição
country	string	obrigatório	Código do país (ex. `us`)
service_id	integer	obrigatório	ID do serviço de Lista de Serviços
operator_id	integer	opcional	ID da operadora de Lista de Operadoras. Omita para a operadora padrão.

cURL
Python
JavaScript
curl -X POST https://simnokyc.com/api.php?action=buy \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"country":"us","service_id":12,"operator_id":5}'
resp = session.post("https://simnokyc.com/api.php?action=buy", json={
    "country": "us",
    "service_id": 12,
    "operator_id": 5
})
order = resp.json()
print(f"Order #{order['order_id']} — ${order['price']}")
const resp = await fetch("https://simnokyc.com/api.php?action=buy", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ country: "us", service_id: 12, operator_id: 5 })
});
const order = await resp.json();

Resposta de sucesso

{ "success": true, "order_id": 1847, "price": 0.53, "balance": "73.97" }

Erro: Saldo insuficiente

{ "error": "Insufficient balance", "need": 0.53, "have": "0.10" }

Listar pedidos

GET /api.php?action=orders

Retorna seus 50 pedidos mais recentes, incluindo números de telefone e códigos SMS. Consulte este endpoint para verificar códigos SMS recebidos em pedidos ativos.

Resposta

[ { "id": 1847, "price": "0.53", "status": "completed", "phone_number": "+12025551234", "sms_code": "847293", "created_at": "2026-04-09 14:32:00", "country_code": "us", "country_name": "USA", "service_name": "WhatsApp", "operator_name": "T-Mobile" } ]

Status dos pedidos: active — aguardando SMS. completed — SMS recebido. cancelled — cancelado pelo usuário. refunded — reembolsado automaticamente (nenhum SMS recebido antes do tempo limite). expired — expirado.

Obter preço de aluguel

GET /api.php?action=rental_price&country={code}&operator_id={id}&duration={days}

Obtenha o preço de aluguel de um número dedicado de uma operadora específica por uma duração determinada.

Parâmetro	Tipo	Obrigatório	Descrição
country	string	obrigatório	Código do país
operator_id	integer	obrigatório	ID da operadora
duration	integer	obrigatório	Duração do aluguel em dias: `7`, `14`, `30` ou `90`

Resposta

{ "price": "12.50", "duration": 30, "operator": "T-Mobile", "type": "physical", "country": "USA" }

Alugar Número

POST /api.php?action=rental_buy

Alugue um ou mais números de telefone dedicados. O número é exclusivamente seu durante todo o período de aluguel e recebe SMS ilimitados.

Parâmetro	Tipo	Obrigatório	Descrição
country	string	obrigatório	Código do país
operator_id	integer	obrigatório	ID da operadora
duration	integer	obrigatório	`7`, `14`, `30` ou `90` dias
qty	integer	opcional	Quantidade de números para alugar (1–10, padrão: 1)

Resposta de sucesso

{ "success": true, "order_ids": [1848, 1849], "total": 25.00, "qty": 2, "unit_price": 12.50, "duration": 30, "balance": "49.50" }

Obter informações do usuário

GET /api.php?action=user

Retorna as informações da conta e o saldo do usuário atual. Use para verificar o status de autenticação e os fundos disponíveis.

Autenticado

{ "logged_in": true, "id": 42, "prefix": "AbC3", "balance": "74.50" }

Não autenticado

{ "logged_in": false }

Exemplo de fluxo de trabalho completo

Aqui está um exemplo completo em Python que autentica, encontra um serviço, compra um número e consulta o código SMS:

Python
import requests, time

BASE = "https://simnokyc.com"
SEED = "AbC3-dEf4-gHj5-kLm6"

s = requests.Session()

# 1. Authenticate
s.post(f"{BASE}/auth-api.php", data={"action": "login", "seed": SEED})

# 2. Check balance
user = s.get(f"{BASE}/api.php?action=user").json()
print(f"Balance: ${user['balance']}")

# 3. Get services for USA
services = s.get(f"{BASE}/api.php?action=services&country=us").json()
whatsapp = next(svc for svc in services if svc["name"] == "WhatsApp")
print(f"WhatsApp: ${whatsapp['price']} ({whatsapp['stock']} in stock)")

# 4. Buy a number
order = s.post(f"{BASE}/api.php?action=buy", json={
    "country": "us",
    "service_id": whatsapp["id"]
}).json()
print(f"Order #{order['order_id']} created")

# 5. Poll for SMS code
for _ in range(60):
    orders = s.get(f"{BASE}/api.php?action=orders").json()
    my_order = next(o for o in orders if o["id"] == order["order_id"])

    if my_order["sms_code"]:
        print(f"SMS code: {my_order['sms_code']}")
        print(f"Phone:    {my_order['phone_number']}")
        break

    print("Waiting for SMS...")
    time.sleep(5)
else:
    print("Timeout — balance will be refunded automatically")