Documentação da API

A kartesim oferece aos parceiros números de telefone reais por meio de dois serviços: aluguéis de números de longo prazo e sessões OTP por uso. Ambos estão disponíveis pelo protocolo HANDLER_API e pela Native REST API.

Sessões OTPpor uso

Solicite um número temporário, aguarde um SMS e receba o código OTP, tudo em um único ciclo de chamadas à API. Cobrança por sessão, com reembolso se você cancelar antes de o código chegar.

Aluguel de númerosCartões SIM

Alugue um número de telefone dedicado por períodos diários, semanais ou mensais. Todos os SMS recebidos nesse número são encaminhados para a sua conta em tempo real.

Os aluguéis são configurados pelo seu gerente de conta. Entre em contato para configurar o seu aluguel. Depois de ativo, o seu número de telefone aparece no portal de parceiros e pode ser consultado pela API. As sessões OTP são de autoatendimento pela API, sem necessidade de configuração.

Autenticação

Todas as requisições à API exigem a sua chave de API de parceiro. A forma de enviá-la depende do seu protocolo.

Handler API: parâmetro de consulta

GET /api/stubs/handler_api.php
  ?api_key=YOUR_KEY
  &action=getBalance

Native REST API: cabeçalho HTTP

curl https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram"}'

Mantenha a sua chave de API em segredo. A sua chave fica visível no portal de parceiros, em API. Use o botão Gerar nova chave ali para trocá-la na hora.

Referência da Handler API

URL base: /api/stubs/handler_api.php. Todas as requisições usam GET. Todas as respostas são em texto puro.

GET/api/stubs/handler_api.php?action=getBalance

Retorna o seu saldo pré-pago atual em USD.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
api_key	string	obrigatório	A sua chave de API
action	string	obrigatório	Deve ser "getBalance"

Respostas

45.00O seu saldo em USD

999999Valor sentinela fixo retornado para contas com saldo ilimitado. Não é um saldo real e não muda com o uso

BAD_KEYChave de API inválida ou revogada

Exemplo de requisição

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getBalance'

Exemplo de resposta

45.00

GET/api/stubs/handler_api.php?action=getCountries

Lista os países suportados com os respectivos códigos numéricos.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
api_key	string	obrigatório	A sua chave de API
action	string	obrigatório	Deve ser "getCountries"

Respostas

JSON array[{ "id": 7, "name": "Russia" }, ...]

Exemplo de requisição

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getCountries'

Exemplo de resposta

[
  { "id": 7,   "name": "Russia" },
  { "id": 212, "name": "Morocco" }
]

GET/api/stubs/handler_api.php?action=getPrices

Obtém os preços atuais e o estoque ativo disponível por país e serviço.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
api_key	string	obrigatório	A sua chave de API
action	string	obrigatório	Deve ser "getPrices"
country	number	opcional	Filtra pelo ID numérico do país
hide_empty	integer	opcional	Defina como 1 para excluir da resposta os países com estoque zero

Respostas

JSON object{ "countryId": { "serviceId": { "cost": 0.1, "count": 10 } } }

Exemplo de requisição

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getPrices&hide_empty=1'

Exemplo de resposta

{
  "212": {
    "wa": { "cost": 0.15, "count": 12 },
    "tg": { "cost": 0.15, "count": 12 }
  }
}

GET/api/stubs/handler_api.php?action=getNumber

Solicita um número de telefone temporário para verificação por OTP. Retorna um ID de sessão e o número atribuído. A sessão expira após 10 minutos se nenhum SMS chegar.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
api_key	string	obrigatório	A sua chave de API
action	string	obrigatório	Deve ser "getNumber"
service	string	opcional	Nome do serviço (ex.: "telegram", "whatsapp"), apenas informativo
country	integer	opcional	Código de discagem do país (ex.: 212 para o Marrocos). Omita ou use 0 para qualquer país.

Respostas

ACCESS_NUMBER:id:numberSessão criada: id é usado em getStatus/setStatus, number é o número de telefone atribuído

NO_NUMBERSNenhuma porta online disponível que atenda à sua solicitação

NO_BALANCESaldo insuficiente para cobrir a taxa de OTP

Exemplo de requisição

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getNumber&service=telegram&country=212'

Exemplo de resposta

ACCESS_NUMBER:cma4x9k3b0000abc123:212661234567

GET/api/stubs/handler_api.php?action=getStatus

Consulta o código OTP de uma sessão ativa. Consulte a cada 5–10 segundos até receber STATUS_OK ou STATUS_CANCEL.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
api_key	string	obrigatório	A sua chave de API
action	string	obrigatório	Deve ser "getStatus"
id	string	obrigatório	ID da sessão vindo da resposta ACCESS_NUMBER

Respostas

STATUS_WAIT_CODEA sessão está ativa e o SMS ainda não foi recebido. Continue consultando.

STATUS_OK:84729OTP recebido: o código vem depois dos dois-pontos

STATUS_CANCELA sessão expirou ou foi cancelada

Exemplo de requisição

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getStatus&id=cma4x9k3b0000abc123'

Exemplo de resposta

STATUS_OK:84729

GET/api/stubs/handler_api.php?action=setStatus

Confirma o recebimento do OTP (status=1) ou cancela a sessão com reembolso integral (status=8). Somente sessões PENDING podem ser canceladas.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
api_key	string	obrigatório	A sua chave de API
action	string	obrigatório	Deve ser "setStatus"
id	string	obrigatório	ID da sessão sobre a qual agir
status	integer	obrigatório	1 = confirmar recebimento, 8 = cancelar e reembolsar

Respostas

ACCESS_READYConfirmado: sessão reconhecida

ACCESS_CANCELCancelado: saldo reembolsado

BAD_ACTIONSessão não encontrada ou já concluída

Exemplo de requisição

# Cancel and refund
curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=setStatus&id=cma4x9k3b0000abc123&status=8'

Exemplo de resposta

ACCESS_CANCEL

Native REST API

Para integrações modernas, use a nossa Native REST API em vez da Handler API legada. Envie a sua chave de API no cabeçalho HTTP x-api-key.

Sessões OTP

por uso

As sessões OTP permitem solicitar um número de telefone temporário, receber um código de uso único e liberar o número, tudo pela API. Cada sessão é cobrada uma única vez, na criação. Se você cancelar antes de o código chegar, a taxa integral é reembolsada.

POST/api/v1/otp/request

Solicita um número de telefone temporário para verificação por OTP. Retorna um sessionId e o número atribuído. Cobra a taxa OTP_PER_USE imediatamente.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
country	integer	opcional	Código de discagem do país para filtrar (ex.: 212). Omita para qualquer país.
service	string	opcional	Nome do serviço, ex.: "telegram", armazenado na sessão para sua referência
webhookUrl	string	opcional	URL HTTPS que receberá um POST quando o OTP chegar (em vez de polling)
expiresIn	integer	opcional	TTL da sessão em segundos (60–1800, padrão 600)

Respostas

200 OKSessão criada: o corpo contém sessionId, number e expiresAt

402 Payment RequiredSaldo insuficiente

503 Service UnavailableNenhum número online disponível

Exemplo de requisição

curl -X POST https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram", "country": 212}'

Exemplo de resposta

{ "sessionId": "cma4x9k3b0000abc123", "number": "212661234567", "status": "PENDING", "expiresAt": "2026-06-01T00:20:00.000Z" }

GET/api/v1/otp/:sessionId

Consulta o status e o código da sessão OTP. Retorna o código OTP extraído assim que o SMS chega. Consulte a cada 5–10 segundos.

Respostas

200 OK — PENDINGstatus: "PENDING", otp: null — ainda aguardando

200 OK — RECEIVEDstatus: "RECEIVED", otp: "84729" — código pronto

200 OK — EXPIREDstatus: "EXPIRED" — nenhum SMS dentro do tempo limite

200 OK — CANCELLEDstatus: "CANCELLED" — você cancelou a sessão

Exemplo de requisição

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123

Exemplo de resposta

{ "sessionId": "cma4x9k3b0000abc123", "status": "RECEIVED", "number": "212661234567", "otp": "84729", "smsBody": "Your code is 84729" }

POST/api/v1/otp/:sessionId/cancel

Cancela uma sessão PENDING. Emite o reembolso integral da taxa de OTP. Sessões que já receberam um OTP não podem ser canceladas.

Respostas

200 OKstatus: "CANCELLED", refunded: 0.10 — saldo creditado

409 ConflictA sessão não está no estado PENDING e não pode ser cancelada

404 Not FoundSessão não encontrada ou pertencente a outra conta

Exemplo de requisição

curl -X POST -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123/cancel

Exemplo de resposta

{ "sessionId": "cma4x9k3b0000abc123", "status": "CANCELLED", "refunded": "0.1000" }

POSTSua URL de webhook (push do servidor)

Quando um OTP chega, enviamos um POST para a webhookUrl que você informou na criação da sessão. É uma alternativa ao polling: o seu servidor recebe o OTP automaticamente, sem precisar chamar getStatus.

Payload

POST para a sua webhookUrl

{
  "event":      "otp.received",
  "sessionId":  "cma4x9k3b0000abc123",
  "status":     "RECEIVED",
  "number":     "212661234567",
  "otp":        "84729",
  "smsBody":    "Your Telegram code is 84729",
  "receivedAt": "2026-06-21T12:00:00.000Z"
}

Segurança

A sua URL de webhook deve ser HTTPS em produção. URLs HTTP são rejeitadas.
Enviamos um cabeçalho X-Webhook-Signature: sha256=... (HMAC-SHA256). Verifique-o para confirmar que a requisição é legítima.
Tentamos novamente uma vez em caso de 5xx, após 2 segundos. O seu endpoint deve retornar 200 rapidamente.
O seu endpoint deve ser idempotente: a entrega duplicada é possível na nova tentativa.

GET/api/partner/rentals

Busca todos os aluguéis de números ativos da sua conta.

Respostas

200 OKArray JSON dos aluguéis de números ativos

401 UnauthorizedChave de API inválida ou ausente

Exemplo de requisição

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

Exemplo de resposta

[
  {
    "id": "cuid...",
    "phoneNumber": "1234567890",
    "countryCode": 1,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

GET/api/partner/sms?simNumber=1234567890

Busca as mensagens SMS mais recentes recebidas pelos seus números alugados. Opcionalmente, filtre por um simNumber específico.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
simNumber	string	opcional	Filtra os SMS de um número alugado específico

Respostas

200 OKArray JSON das mensagens SMS recentes

401 UnauthorizedChave de API inválida ou ausente

Exemplo de requisição

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/sms

Exemplo de resposta

[
  {
    "id": "cuid...",
    "simNumber": "1234567890",
    "fromNumber": "Twilio",
    "body": "Your verification code is 49201",
    "receivedAt": "2026-05-29T15:30:00.000Z"
  }
]

Aluguel de números

O aluguel de números dá a você o uso exclusivo de um cartão SIM real por um período fixo de aluguel. Todo SMS recebido nesse número é entregue na sua conta em tempo real. Você pode alugar números diretamente pela API ou pelo portal de parceiros.

Período	Duração	Descrição
Diário	24 horas	Ideal para campanhas de verificação de curto prazo
Semanal	7 dias	Ideal para acesso contínuo a um número estável
Mensal	30 dias	Ideal para acesso de longo prazo a um número dedicado

Como funciona

Chame GET /api/v1/numbers/available para ver os números disponíveis (mascarados).
Escolha um número e um ciclo de cobrança e depois chame POST /api/v1/numbers/rent para alugá-lo na hora.
O seu saldo é debitado imediatamente. O número de telefone completo, sem máscara, é retornado na resposta.
Todos os SMS recebidos no seu número alugado aparecem em Logs de SMS em tempo real.
No vencimento, o número é liberado automaticamente. Não há reembolso pelo tempo não utilizado.

GET/api/v1/numbers/available

Veja os números disponíveis para aluguel. Os números são mascarados (ex.: +212 6** *** **7) para que você veja o país e a operadora antes de se comprometer. Opcionalmente, filtre pelo código do país.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
country	number	opcional	Código de país da ITU (ex.: 212). Omita ou use 0 para qualquer país.

Respostas

200 OKJSON com a lista de números disponíveis e a contagem total

401 UnauthorizedChave de API inválida ou ausente

429 Too Many RequestsLimite de requisições excedido (30 req/min)

Exemplo de requisição

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/numbers/available?country=212

Exemplo de resposta

{
  "available": [
    {
      "phoneId":      "clx...",
      "maskedNumber": "+212 6** *** **7",
      "countryCode":  212,
      "country":      "Morocco",
      "carrier":      "Orange",
      "pricing": { "daily": null, "weekly": 2.50, "monthly": 8.00 }
    }
  ],
  "total": 1
}

POST/api/v1/numbers/rent

Aluga um número por conta própria. Desconta o seu saldo de forma atômica e cria um aluguel exclusivo. Em caso de sucesso, retorna o número de telefone completo (sem máscara).

Parâmetros

Nome	Tipo	Obrigatório	Descrição
phoneId	string	obrigatório	ID da porta vindo de /api/v1/numbers/available
billingCycle	string	obrigatório	DAILY \| WEEKLY \| MONTHLY
cycles	number	opcional	Número de ciclos de cobrança a pagar antecipadamente (1–12, padrão 1)
autoRenew	boolean	opcional	Renovar automaticamente no vencimento (padrão false)

Respostas

200 OKAluguel criado: número de telefone completo na resposta

402 Payment RequiredSaldo insuficiente ou nenhum preço configurado para esse ciclo

409 ConflictO número acabou de ser alugado por outro parceiro. Tente novamente com um número diferente

401 UnauthorizedChave de API inválida ou ausente

Exemplo de requisição

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"phoneId":"clx...","billingCycle":"MONTHLY","cycles":1}' \
  https://www.kartesim.com/api/v1/numbers/rent

Exemplo de resposta

{
  "rentalId":     "cly...",
  "phoneNumber":  "+212661234567",
  "countryCode":  212,
  "carrier":      "Orange",
  "billingCycle": "MONTHLY",
  "pricePerCycle": 8.00,
  "cycles":        1,
  "totalCharged":  8.00,
  "autoRenew":     false,
  "startedAt":    "2026-06-21T20:00:00.000Z",
  "expiresAt":    "2026-07-21T20:00:00.000Z"
}

GET/api/partner/rentals

Busca todos os aluguéis de números ativos da sua conta.

Respostas

200 OKArray JSON dos aluguéis de números ativos

401 UnauthorizedChave de API inválida ou ausente

Exemplo de requisição

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

Exemplo de resposta

[
  {
    "id": "cuid...",
    "phoneNumber": "+212661234567",
    "maskedNumber": "+212 6** *** **7",
    "countryCode": 212,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

Os números são dedicados à sua conta. O número nunca é compartilhado nem reatribuído durante o seu período de aluguel. O saldo necessário para o período completo é cobrado no momento do aluguel. Se um número que você solicitou for ocupado entre a consulta e o aluguel, você receberá um 409. Tente novamente com outro número.

Países suportados

Use getCountries para obter a lista atual. Códigos de país mais comuns:

Código	País	Código	País
0	Qualquer (atribuição automática)	7	Rússia
212	Marrocos	33	França
1	Estados Unidos	44	Reino Unido
49	Alemanha	34	Espanha
966	Arábia Saudita	971	Emirados Árabes Unidos
20	Egito	216	Tunísia

Referência de erros

Resposta	Significado
BAD_KEY	Chave de API inválida, revogada ou ausente
BAD_ACTION	Ação desconhecida ou parâmetros obrigatórios ausentes
TOO_MANY_REQUESTS	Limite de requisições excedido: 120 requisições por minuto
NO_NUMBERS	Nenhuma porta online disponível que atenda à sua solicitação de OTP
NO_BALANCE	Saldo insuficiente para criar uma sessão OTP
STATUS_WAIT_CODE	OTP ainda não recebido. Continue consultando
STATUS_OK:code	OTP recebido: o código em dígitos vem depois dos dois-pontos
STATUS_CANCEL	A sessão expirou ou foi cancelada
ACCESS_NUMBER:id:num	Sessão OTP criada: o ID da sessão e o número de telefone vêm em seguida
ACCESS_CANCEL	Sessão cancelada, saldo reembolsado
ACCESS_READY	Sessão reconhecida / confirmada

Documentação de parceiros da kartesim. Para solicitar chaves de API ou tirar dúvidas sobre aluguéis, fale com o seu gerente de conta.