API para desenvolvedores

Compre números e receba códigos de verificação direto do seu sistema, com os mesmos serviços, países e preços do site. Consulte o catálogo sem chave e teste agora no sandbox, sem cadastro. Para operar, crie a conta, abra API no painel e gere as suas chaves na hora.

Chave pública de testes: d2g_test_publico_demo (só sandbox, sem cobrança).

Baixar especificação OpenAPI Criar conta e gerar chaves Criar conta e gerar chaves

Começo

Introdução e primeiros passos

A API do D2G SMS permite comprar números virtuais e receber códigos de verificação por SMS direto do seu sistema, com os mesmos serviços, países e preços do site. É aberta: leia, consulte preços e teste no sandbox sem cadastro; para operar, use a sua conta, as suas chaves e o seu saldo.

Operações

GET/api/v1/balanceConsultar saldo
GET/api/v1/countriesListar países
GET/api/v1/categoriesListar categorias
GET/api/v1/servicesListar serviços
GET/api/v1/pricesConsultar preços
GET/api/v1/ordersListar pedidos
POST/api/v1/ordersComprar um número
GET/api/v1/orders/{id}Consultar pedido e SMS
POST/api/v1/orders/{id}/cancelCancelar pedido

É uma API REST com JSON, servida só por HTTPS. Todas as rotas ficam sob o mesmo endereço base, e o ambiente (sandbox ou produção) é definido pela chave usada.

Convenções
Item	Como funciona
Endereço base	`https://d2gsms.top/api/v1`, o mesmo para sandbox e produção.
Formato	JSON em UTF-8. Sucesso: `{ "data": ... }`. Erro: `{ "error": { "code", "message" } }`.
Valores	Em centavos de real, nos campos `*_cents` (ex.: `450` = R$ 4,50), com `currency: "BRL"`.
Datas	ISO 8601 com fuso (UTC).
Ambiente	Vem do prefixo da chave: `d2g_test_` (sandbox) ou `d2g_live_` (produção). Toda resposta de sucesso com chave traz `X-D2G-Environment`.
Rotas públicas	`/countries`, `/categories`, `/services` e `/prices` respondem sem chave (60 requisições por minuto por IP).
Teste sem conta	Chave pública `d2g_test_publico_demo`: sandbox simulado, sem cadastro (veja Sandbox e Produção).
Especificação	OpenAPI 3.1 em `https://d2gsms.top/api/v1/openapi.json` (pública, sem chave), para gerar clientes ou importar em ferramentas como o Postman.
Exemplos	Os JSON de resposta desta página são exemplos ilustrativos: os campos são os reais, os valores não.

Primeiros passos

Sem cadastro: consulte países, serviços e preços sem chave e teste o fluxo completo com a chave pública d2g_test_publico_demo. Use o botão Testar de cada rota para chamar a API daqui mesmo.
Crie sua conta no D2G SMS e, no painel, abra API. O painel da API já está pronto: sem formulário, sem análise e sem espera.
Em Credenciais, gere a sua chave de sandbox (d2g_test_..., grátis; na primeira chave, aceite as regras de uso). Ela aparece uma única vez: guarde em local seguro. No sandbox nada é cobrado e o SMS de teste chega sozinho.
Quando estiver pronto, recarregue o saldo do site por Pix, use Adicionar saldo à API na Carteira da API, gere uma chave de produção (d2g_live_..., pede a sua senha) e troque a chave no seu sistema.

Fluxo completo de compra

Compra um número de Telegram no Brasil, consulta o pedido a cada 5 segundos, mostra o código quando o SMS chega e cancela se nada chegar em 3 minutos (o valor volta para a carteira da API). No sandbox, o código 123456 chega em 20 segundos.

Fluxo completo

#!/usr/bin/env bash
# Fluxo completo com cURL e jq: compra, acompanha, lê o SMS e cancela se não chegar.
set -euo pipefail
API_URL="https://d2gsms.top/api/v1"
API_KEY="d2g_test_publico_demo"

# 1. Compra (a Idempotency-Key evita cobrança duplicada se você repetir a chamada)
ORDER=$(curl -sS -X POST "$API_URL/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-$(date +%s)-$RANDOM" \
  -d '{"service":"telegram","country":"BR"}')
ORDER_ID=$(echo "$ORDER" | jq -r '.data.id // empty')
if [ -z "$ORDER_ID" ]; then echo "$ORDER" | jq '.error'; exit 1; fi
echo "Pedido $ORDER_ID: use o número $(echo "$ORDER" | jq -r '.data.phone_number')"

# 2. Acompanha a cada 5 s por até 3 minutos
for _ in $(seq 1 36); do
  sleep 5
  ORDER=$(curl -sS "$API_URL/orders/$ORDER_ID" -H "Authorization: Bearer $API_KEY")
  # 3. SMS recebido: mostra o código
  if [ "$(echo "$ORDER" | jq -r '.data.sms != null')" = "true" ]; then
    echo "Código: $(echo "$ORDER" | jq -r '.data.sms.code')"
    exit 0
  fi
  STATUS=$(echo "$ORDER" | jq -r '.data.status')
  case "$STATUS" in completed|cancelled|expired|failed) echo "Pedido terminou: $STATUS"; exit 0 ;; esac
done

# 4. Sem SMS: cancela (o valor volta para a carteira da API)
curl -sS -X POST "$API_URL/orders/$ORDER_ID/cancel" -H "Authorization: Bearer $API_KEY" | jq '.data.status // .error'

Uso permitido

A API segue as mesmas regras do site: verificação de contas e testes autorizados. Bancos, fintechs, governo, apostas e cripto não fazem parte do catálogo.

Começo

Autenticação

As rotas do catálogo são públicas. Saldo e pedidos precisam de uma chave de API, enviada em um cabeçalho.

Envie Authorization: Bearer <chave>. Como alternativa, use X-API-Key: <chave>. Se os dois forem enviados, vale o Authorization.

Tipos de chave
Prefixo	Ambiente	Efeito
`d2g_test_publico_demo`	Sandbox público	Chave pública, sem conta. Pedidos simulados, separados por IP, apagados em 24 h.
`d2g_test_`	Sandbox	A sua chave de testes: pedidos simulados, sem cobrança e sem operadora.
`d2g_live_`	Produção	Compras reais, cobradas da carteira da API.

A chave tem o prefixo seguido de 32 letras e números. O D2G SMS guarda só um resumo dela: se perder, gere outra.
Uma chave revogada para de funcionar na hora (key_revoked). Se o acesso for suspenso por abuso ou fraude, todas as chaves param (partner_suspended).
As chaves são criadas por você no painel (área API), até 5 ativas por ambiente. A de produção pede a senha da sua conta.
Muitas recusas de chave seguidas do mesmo IP (chave ausente, inválida ou revogada, parceiro suspenso ou ambiente desligado) levam a 429 rate_limited por 60 segundos, em todas as rotas.
Respostas 401 trazem o cabeçalho WWW-Authenticate: Bearer realm="d2g-api".

Cabeçalhos das respostas
Cabeçalho	Quando aparece
`X-D2G-Environment`	Em toda resposta de sucesso de uma chamada com chave: `sandbox` ou `production`. Ausente nas rotas públicas chamadas sem chave.
`Cache-Control: no-store`	Em toda resposta (menos `/openapi.json`, que pode ficar em cache por 1 hora).
`Idempotent-Replayed: true`	Na compra repetida com a mesma Idempotency-Key.
`Retry-After`	Nas respostas 429: segundos até tentar de novo.
`WWW-Authenticate`	Nas respostas 401.

Autenticação

Bearer token no cabeçalho. Países, categorias, serviços e preços respondem sem chave.

Authorization: Bearer d2g_test_publico_demo

Alternativa: X-API-Key. Os exemplos de sandbox usam a chave pública de testes e rodam como estão. Para o seu próprio sandbox, troque pela sua chave d2g_test_ gerada no painel.

Sem conta? Chave pública de testes (só sandbox):

d2g_test_publico_demo

Chave ausente ou inválida (401)

{
  "error": {
    "code": "unauthorized",
    "message": "Chave de API ausente ou inválida. Envie Authorization: Bearer <chave>."
  }
}

Conta e catálogo

Conta e saldo

Saldo da carteira da API, separada do saldo da sua conta no site. Você abastece com o saldo do site e devolve quando quiser, no painel.

Operações

GET/api/v1/balanceConsultar saldo

Consultar saldo

GEThttps://d2gsms.top/api/v1/balance

Saldo da carteira da API. Em produção é o saldo real usado nas compras; no sandbox é um saldo simulado de R$ 1.000,00 que nunca diminui (simulated: true).

Cabeçalhos

Authorizationstringobrigatório
Bearer <chave>. Também aceito: cabeçalho X-API-Key: <chave>. Para testar sem conta: d2g_test_publico_demo.

balance_cents: saldo total. held_cents: valor reservado em pedidos que aguardam SMS. available_cents: o que pode ser usado agora.

Erros possíveis

Só os comuns a todas as rotas: unauthorized, key_revoked, partner_suspended, environment_disabled, rate_limited, service_unavailable, internal_error.

Requisição

curl "https://d2gsms.top/api/v1/balance" \
  -H "Authorization: Bearer d2g_test_publico_demo"

Resposta (exemplo ilustrativo)

200 · Saldo (exemplo, sandbox)

{
  "data": {
    "environment": "sandbox",
    "currency": "BRL",
    "balance_cents": 100000,
    "held_cents": 0,
    "available_cents": 100000,
    "simulated": true
  }
}

Conta e catálogo

Países

Países com ofertas publicadas.

Operações

GET/api/v1/countriesListar países

Listar países

GEThttps://d2gsms.top/api/v1/countries

Países com ofertas publicadas no catálogo. Use iso2 (ex.: BR) ou id nos filtros e na compra. Pública: a chave é opcional.

Cabeçalhos

Authorizationstringopcional
Opcional nesta rota pública. Com chave: Bearer <chave> (ou X-API-Key); sem chave, limite de 60 requisições por minuto por IP.

A lista é guardada por 30 segundos no servidor: não é preciso consultá-la a cada compra.

Erros possíveis

Só os comuns a todas as rotas: unauthorized, key_revoked, partner_suspended, environment_disabled, rate_limited, service_unavailable, internal_error.

Requisição

curl "https://d2gsms.top/api/v1/countries" \
  -H "Authorization: Bearer d2g_test_publico_demo"

Resposta (exemplo ilustrativo)

200 · Lista de países (exemplo)

{
  "data": [
    {
      "id": "8a3d5c1e-7b2f-4d90-a6e4-3f1c9b0d2e57",
      "iso2": "BR",
      "name": "Brasil",
      "dial_code": "+55",
      "services": 120,
      "available": true
    },
    {
      "id": "1c7e4b9a-0d3f-4a26-8e51-6b2d9f4a0c83",
      "iso2": "US",
      "name": "Estados Unidos",
      "dial_code": "+1",
      "services": 95,
      "available": true
    }
  ]
}

Conta e catálogo

Categorias

Categorias que agrupam os serviços.

Operações

GET/api/v1/categoriesListar categorias

Listar categorias

GEThttps://d2gsms.top/api/v1/categories

Categorias com serviços publicados. O slug serve de filtro em /services. Pública: a chave é opcional.

Cabeçalhos

Authorizationstringopcional
Opcional nesta rota pública. Com chave: Bearer <chave> (ou X-API-Key); sem chave, limite de 60 requisições por minuto por IP.

A lista é guardada por 30 segundos no servidor.

Erros possíveis

Só os comuns a todas as rotas: unauthorized, key_revoked, partner_suspended, environment_disabled, rate_limited, service_unavailable, internal_error.

Requisição

curl "https://d2gsms.top/api/v1/categories" \
  -H "Authorization: Bearer d2g_test_publico_demo"

Resposta (exemplo ilustrativo)

200 · Lista de categorias (exemplo)

{
  "data": [
    {
      "slug": "redes_sociais_mensageiros",
      "name": "Redes sociais e mensageiros",
      "services": 18,
      "available": true
    },
    {
      "slug": "compras_delivery",
      "name": "Compras e delivery",
      "services": 9,
      "available": true
    }
  ]
}

Conta e catálogo

Serviços

Serviços que enviam o SMS (Telegram, WhatsApp e outros).

Operações

GET/api/v1/servicesListar serviços

Listar serviços

GEThttps://d2gsms.top/api/v1/services

Serviços publicados, com o menor preço entre os países e a disponibilidade. Pública: a chave é opcional.

Cabeçalhos

Authorizationstringopcional
Opcional nesta rota pública. Com chave: Bearer <chave> (ou X-API-Key); sem chave, limite de 60 requisições por minuto por IP.

Parâmetros de consulta

categorystringopcional
Slug da categoria (ex.: redes_sociais_mensageiros), para listar só os serviços dela.

min_price_cents: menor preço do serviço entre todos os países. Para o preço de cada país, use /prices.

Erros possíveis

400invalid_request

E os comuns a todas as rotas: unauthorized, key_revoked, partner_suspended, environment_disabled, rate_limited, service_unavailable, internal_error.

Requisição

curl "https://d2gsms.top/api/v1/services" \
  -H "Authorization: Bearer d2g_test_publico_demo"

Resposta (exemplo ilustrativo)

200 · Lista de serviços (exemplo)

{
  "data": [
    {
      "id": "3e9b1f6d-4a2c-4c8e-b07a-5d1e8f2c6a94",
      "slug": "telegram",
      "name": "Telegram",
      "category": "redes_sociais_mensageiros",
      "min_price_cents": 290,
      "currency": "BRL",
      "countries": 64,
      "available": true
    }
  ]
}

Conta e catálogo

Catálogo e preços

As ofertas de cada serviço por país, com o preço final em reais.

Operações

GET/api/v1/pricesConsultar preços

Mesmo preço do site. A API não tem tabela própria nem desconto: o preço é o publicado no catálogo.
Conferido no servidor. O preço nunca é enviado pelo seu sistema. Na compra, o servidor lê o preço publicado naquele momento e o banco confere de novo.
Um serviço pode ter mais de uma oferta no mesmo país. Para comprar uma oferta exata, use o offer_id dela; com service + country, a compra usa a disponível mais barata.

Consultar preços

GEThttps://d2gsms.top/api/v1/prices

Ofertas publicadas com o preço final em reais, o mesmo do site. Informe ao menos um filtro: service, country ou os dois. Pública: a chave é opcional.

Cabeçalhos

Authorizationstringopcional
Opcional nesta rota pública. Com chave: Bearer <chave> (ou X-API-Key); sem chave, limite de 60 requisições por minuto por IP.

Parâmetros de consulta

servicestringopcional
Slug (ex.: telegram) ou id do serviço. Obrigatório se country não for enviado.
countrystringopcional
Código ISO de 2 letras (ex.: BR) ou id do país. Obrigatório se service não for enviado.

Um serviço pode ter mais de uma oferta no mesmo país. Para comprar uma oferta exata, use o offer_id dela em POST /orders.
O preço é lido na hora da consulta e pode mudar. Na compra, o servidor usa o preço publicado naquele momento.

Erros possíveis

400filter_required 400invalid_request 404not_found

E os comuns a todas as rotas: unauthorized, key_revoked, partner_suspended, environment_disabled, rate_limited, service_unavailable, internal_error.

Requisição

curl "https://d2gsms.top/api/v1/prices?service=telegram&country=BR" \
  -H "Authorization: Bearer d2g_test_publico_demo"

Resposta (exemplo ilustrativo)

200 · Ofertas e preços (exemplo)

{
  "data": [
    {
      "offer_id": "c2a9e0d4-6f1b-4a7e-8d35-91e2f4b6a7c8",
      "service": {
        "id": "3e9b1f6d-4a2c-4c8e-b07a-5d1e8f2c6a94",
        "slug": "telegram",
        "name": "Telegram"
      },
      "country": {
        "id": "8a3d5c1e-7b2f-4d90-a6e4-3f1c9b0d2e57",
        "iso2": "BR",
        "name": "Brasil"
      },
      "label": null,
      "price_cents": 450,
      "currency": "BRL",
      "available": true
    }
  ]
}

Ativações

Solicitação de números

A compra entrega um número reservado para receber o SMS do serviço escolhido.

Operações

POST/api/v1/ordersComprar um número

Comprar um número

POSThttps://d2gsms.top/api/v1/orders

Compra um número para receber o SMS de um serviço em um país. Envie offer_id ou o par service + country. O preço nunca é enviado: o servidor usa o preço publicado no catálogo e cobra da carteira da API.

Cabeçalhos

Authorizationstringobrigatório
Bearer <chave>. Também aceito: cabeçalho X-API-Key: <chave>. Para testar sem conta: d2g_test_publico_demo.
Content-Typestringobrigatório
application/json.
Idempotency-Keystringobrigatório
Chave única desta compra, de 8 a 128 caracteres (letras, números, -, _, : ou .). Um UUID serve. Repetir a mesma chave devolve o mesmo pedido, sem nova cobrança.

Corpo (JSON)

Envie offer_id ou o par service + country.

offer_idstring (uuid)opcional
Oferta exata, vinda de /prices. Obrigatório se service e country não forem enviados.
servicestringopcional
Slug ou id do serviço. Use junto com country.
countrystringopcional
ISO de 2 letras ou id do país. Use junto com service.

Com service + country, a compra usa a oferta disponível mais barata daquele serviço no país.
Qualquer outro campo do corpo (inclusive um preço) é ignorado.
Guarde o id do pedido e informe o phone_number no serviço que vai enviar o SMS.

Erros possíveis

400idempotency_key_required 400invalid_idempotency_key 400invalid_json 400invalid_request 404not_found 409idempotency_key_conflict 409price_changed 422offer_unavailable 422no_numbers_available 422insufficient_funds 422too_many_open_orders 403account_not_active 403account_on_hold 429daily_limit_reached 502provider_failed 503purchases_unavailable

E os comuns a todas as rotas: unauthorized, key_revoked, partner_suspended, environment_disabled, rate_limited, service_unavailable, internal_error.

Requisição

curl -X POST "https://d2gsms.top/api/v1/orders" \
  -H "Authorization: Bearer d2g_test_publico_demo" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-$(date +%s)-$RANDOM" \
  -d '{"service":"telegram","country":"BR"}'

Resposta (exemplo ilustrativo)

{
  "data": {
    "id": "5d1f7a4e-2c3b-4e8f-9a61-0b7c4d2e8f13",
    "environment": "sandbox",
    "status": "waiting_sms",
    "offer_id": "c2a9e0d4-6f1b-4a7e-8d35-91e2f4b6a7c8",
    "service": "Telegram",
    "country": "Brasil",
    "phone_number": "+99904718236",
    "price_cents": 450,
    "currency": "BRL",
    "sms": null,
    "can_cancel": true,
    "cancel_available_at": "2026-11-09T14:00:00.000000+00:00",
    "expires_at": "2026-11-09T14:20:00.000000+00:00",
    "created_at": "2026-11-09T14:00:00.000000+00:00",
    "completed_at": null,
    "cancelled_at": null
  }
}

Regras de cobrança

Preço do catálogo. O valor cobrado é o preço publicado da oferta no momento da compra, o mesmo de /prices e do site. Qualquer campo de preço enviado no corpo é ignorado.
Preço mudou. Se o preço mudar entre a leitura e a compra, ela é recusada com 409 price_changed e nada é cobrado.
Carteira da API. As compras usam a carteira da API, separada do saldo da sua conta no site. Você mesmo abastece: recarregue o site por Pix e use Adicionar saldo à API (de R$ 1,00 a R$ 5.000,00 por vez). Para tirar, use Devolver ao saldo do site. O saldo de indicações não vai para a API.
Reserva e devolução. Na compra, o valor fica reservado (held_cents em /balance). Com o SMS, a compra está concluída. Cancelado ou expirado sem SMS, o valor volta para a carteira.
Sem cobrança em falha. Se a operadora não concluir a compra (502 provider_failed), nada é cobrado.
Idempotência. A mesma Idempotency-Key nunca cobra duas vezes: a repetição devolve o mesmo pedido (200, com Idempotent-Replayed: true). A mesma chave com outros dados é recusada (409 idempotency_key_conflict).
Sandbox nunca cobra nada.

Repetir uma compra com segurança

Se a conexão cair ou vier um erro 5xx, repita a chamada com a mesma Idempotency-Key: se a compra já tinha sido feita, a API devolve o mesmo pedido e não cobra de novo. Para uma compra nova, use sempre uma chave nova.

Ativações

Consulta de ativações

Situação de um pedido (ativação): número, prazos, cancelamento e SMS.

Operações

GET/api/v1/orders/{id}Consultar pedido e SMS

Consultar pedido e SMS

GEThttps://d2gsms.top/api/v1/orders/{id}

Situação atual do pedido, o número e o SMS quando ele chega. Consulte a cada 5 segundos ou mais enquanto o pedido estiver em processing ou waiting_sms.

Cabeçalhos

Authorizationstringobrigatório
Bearer <chave>. Também aceito: cabeçalho X-API-Key: <chave>. Para testar sem conta: d2g_test_publico_demo.

Parâmetros de rota

idstring (uuid)obrigatório
Id devolvido na compra.

sms fica null até a mensagem chegar. Depois traz code (o código extraído), text (a mensagem inteira) e received_at.
can_cancel diz se o cancelamento é aceito agora; cancel_available_at diz a partir de quando.

Erros possíveis

404order_not_found

E os comuns a todas as rotas: unauthorized, key_revoked, partner_suspended, environment_disabled, rate_limited, service_unavailable, internal_error.

Requisição

curl "https://d2gsms.top/api/v1/orders/ID_DO_PEDIDO" \
  -H "Authorization: Bearer d2g_test_publico_demo"

Resposta (exemplo ilustrativo)

{
  "data": {
    "id": "5d1f7a4e-2c3b-4e8f-9a61-0b7c4d2e8f13",
    "environment": "sandbox",
    "status": "waiting_sms",
    "offer_id": "c2a9e0d4-6f1b-4a7e-8d35-91e2f4b6a7c8",
    "service": "Telegram",
    "country": "Brasil",
    "phone_number": "+99904718236",
    "price_cents": 450,
    "currency": "BRL",
    "sms": null,
    "can_cancel": true,
    "cancel_available_at": "2026-11-09T14:00:00.000000+00:00",
    "expires_at": "2026-11-09T14:20:00.000000+00:00",
    "created_at": "2026-11-09T14:00:00.000000+00:00",
    "completed_at": null,
    "cancelled_at": null
  }
}

Ativações

Recebimento de SMS

O SMS chega no pedido. Não há envio para o seu sistema: consulte o pedido até ele chegar.

Operações

GET/api/v1/orders/{id}Consultar pedido e SMS

Depois da compra, informe o phone_number no serviço que vai enviar o código.
Consulte GET /orders/{id} a cada 5 segundos ou mais, enquanto status for processing ou waiting_sms.
Quando sms deixar de ser null, o código está em sms.code e a mensagem inteira em sms.text. A situação passa a sms_received.
Se nada chegar, cancele quando can_cancel for true (veja Cancelamento). Se o prazo acabar, o pedido vira expired e o valor volta.

Situações do pedido

Situação	Significado	Final
`processing`	A compra está sendo confirmada com a operadora. Continue consultando.	Não
`waiting_sms`	Número entregue, aguardando o SMS. É a única situação em que o pedido pode ser cancelado.	Não
`sms_received`	O SMS chegou: o código está em sms.code e o texto em sms.text. A compra não pode mais ser cancelada.	Não
`completed`	Pedido concluído (com SMS).	Sim
`cancelled`	Cancelado sem SMS. O valor voltou para a carteira da API.	Sim
`expired`	O prazo acabou sem SMS. O valor voltou para a carteira da API.	Sim
`failed`	A compra não foi concluída.	Sim

Campos do SMS
Campo	Conteúdo
`sms.code`	Código de verificação extraído da mensagem. Pode ser `null` se a mensagem não tiver um código reconhecível.
`sms.text`	Texto completo da mensagem.
`sms.received_at`	Data e hora em que o SMS chegou.

Campo sms com a mensagem recebida

{
  "status": "sms_received",
  "sms": {
    "code": "123456",
    "text": "D2G SMS (sandbox): seu código de teste é 123456",
    "received_at": "2026-11-09T14:00:21.000000+00:00"
  }
}

Ativações

Cancelamento

Cancele pedidos sem SMS para receber o valor de volta na carteira da API.

Operações

POST/api/v1/orders/{id}/cancelCancelar pedido

Só pedidos em waiting_sms podem ser cancelados. Depois que o SMS chega, a compra está concluída.
Em produção, o cancelamento é liberado 2 minutos depois da compra; em alguns números, em até 5 minutos. Use can_cancel e cancel_available_at do pedido para saber quando.
No sandbox, o cancelamento é liberado na hora, enquanto o pedido aguarda o SMS.
Se o prazo do pedido acabar sem SMS, ele vira expired sozinho e o valor também volta.

Cancelar pedido

POSThttps://d2gsms.top/api/v1/orders/{id}/cancel

Cancela um pedido que ainda aguarda o SMS. O valor volta para a carteira da API. Não precisa de corpo.

Cabeçalhos

Authorizationstringobrigatório
Bearer <chave>. Também aceito: cabeçalho X-API-Key: <chave>. Para testar sem conta: d2g_test_publico_demo.

Parâmetros de rota

idstring (uuid)obrigatório
Id do pedido.

Erros possíveis

404order_not_found 409order_not_cancellable 409cancel_not_available_yet 503refund_under_review

E os comuns a todas as rotas: unauthorized, key_revoked, partner_suspended, environment_disabled, rate_limited, service_unavailable, internal_error.

Requisição

curl -X POST "https://d2gsms.top/api/v1/orders/ID_DO_PEDIDO/cancel" \
  -H "Authorization: Bearer d2g_test_publico_demo"

Resposta (exemplo ilustrativo)

200 · Pedido cancelado (exemplo)

{
  "data": {
    "id": "5d1f7a4e-2c3b-4e8f-9a61-0b7c4d2e8f13",
    "environment": "sandbox",
    "status": "cancelled",
    "offer_id": "c2a9e0d4-6f1b-4a7e-8d35-91e2f4b6a7c8",
    "service": "Telegram",
    "country": "Brasil",
    "phone_number": "+99904718236",
    "price_cents": 450,
    "currency": "BRL",
    "sms": null,
    "can_cancel": false,
    "cancel_available_at": null,
    "expires_at": "2026-11-09T14:20:00.000000+00:00",
    "created_at": "2026-11-09T14:00:00.000000+00:00",
    "completed_at": null,
    "cancelled_at": "2026-11-09T14:03:05.000000+00:00"
  }
}

Ativações

Histórico

Todos os pedidos do ambiente da chave, com filtro e paginação.

Operações

GET/api/v1/ordersListar pedidos

Listar pedidos

GEThttps://d2gsms.top/api/v1/orders

Pedidos do ambiente da chave, do mais novo para o mais antigo, com paginação.

Cabeçalhos

Authorizationstringobrigatório
Bearer <chave>. Também aceito: cabeçalho X-API-Key: <chave>. Para testar sem conta: d2g_test_publico_demo.

Parâmetros de consulta

limitintegeropcional
Itens por página, de 1 a 100. Padrão: 20.
offsetintegeropcional
Quantos itens pular, de 0 a 100000. Padrão: 0.
statusstringopcional
Filtra por situação: processing, waiting_sms, sms_received, completed, cancelled, expired ou failed.

pagination.total é o total com o filtro aplicado. Some limit ao offset para a próxima página.

Erros possíveis

400invalid_request

E os comuns a todas as rotas: unauthorized, key_revoked, partner_suspended, environment_disabled, rate_limited, service_unavailable, internal_error.

Requisição

curl "https://d2gsms.top/api/v1/orders?limit=20&offset=0" \
  -H "Authorization: Bearer d2g_test_publico_demo"

Resposta (exemplo ilustrativo)

200 · Página de pedidos (exemplo)

{
  "data": [
    {
      "id": "5d1f7a4e-2c3b-4e8f-9a61-0b7c4d2e8f13",
      "environment": "sandbox",
      "status": "sms_received",
      "offer_id": "c2a9e0d4-6f1b-4a7e-8d35-91e2f4b6a7c8",
      "service": "Telegram",
      "country": "Brasil",
      "phone_number": "+99904718236",
      "price_cents": 450,
      "currency": "BRL",
      "sms": {
        "code": "123456",
        "text": "D2G SMS (sandbox): seu código de teste é 123456",
        "received_at": "2026-11-09T14:00:21.000000+00:00"
      },
      "can_cancel": false,
      "cancel_available_at": null,
      "expires_at": "2026-11-09T14:20:00.000000+00:00",
      "created_at": "2026-11-09T14:00:00.000000+00:00",
      "completed_at": null,
      "cancelled_at": null
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1
  }
}

Referência

Códigos de erro

Todo erro tem o mesmo formato. Decida pelo code, que é estável; a message é para leitura humana e pode mudar.

4xx: corrija a chamada antes de repetir. Repetir igual dá o mesmo erro.
429: espere os segundos do cabeçalho Retry-After.
500, 502 e 503: tente de novo com espera crescente (ex.: 1 s, 2 s, 4 s). Na compra, repita com a mesma Idempotency-Key para não comprar duas vezes.
Fora das rotas documentadas, um caminho inexistente responde 404 e um método que a rota não aceita responde 405, os dois sem o corpo { "error": ... }.

Códigos HTTP
HTTP	Significado
`200`	Sucesso. Também na compra repetida com a mesma Idempotency-Key.
`201`	Pedido criado (POST /orders).
`400`	Parâmetros, corpo ou Idempotency-Key inválidos.
`401`	Chave ausente, inválida ou revogada.
`403`	Chave válida, mas sem permissão agora (parceiro suspenso, ambiente desligado, conta pausada).
`404`	Serviço, país ou pedido não encontrado (com o corpo de erro). Caminho inexistente: `404` sem o corpo JSON.
`405`	Método não aceito na rota (ex.: `GET` em `/orders/{id}/cancel`), sem o corpo JSON.
`409`	Conflito com o estado atual (Idempotency-Key reutilizada, preço mudou, cancelamento fora de hora).
`422`	Regra de negócio (sem saldo, sem números, oferta indisponível, limite de pedidos em aberto).
`429`	Limite de requisições ou de compras atingido. Veja `Retry-After`.
`500`	Erro interno.
`502`	A operadora não concluiu a compra. Nada foi cobrado.
`503`	Compras ou serviço temporariamente indisponíveis.

Todos os códigos

400invalid_request
Requisição inválida. Confira os parâmetros enviados.
Corrija o parâmetro indicado na mensagem (formato de service, country, category, limit, offset ou status, ou o corpo da compra). Não repita sem corrigir.
400invalid_json
O corpo da requisição precisa ser um JSON válido (até 4 KB).
Envie um objeto JSON válido com até 4 KB.
400idempotency_key_required
Envie o cabeçalho Idempotency-Key (8 a 128 caracteres: letras, números, '-', '_', ':' ou '.').
Gere uma chave única por compra (um UUID serve) e envie no cabeçalho Idempotency-Key.
400invalid_idempotency_key
Idempotency-Key inválida: use de 8 a 128 caracteres (letras, números, '-', '_', ':' ou '.').
Use de 8 a 128 caracteres: letras, números, '-', '_', ':' ou '.'.
400filter_required
Informe ao menos um filtro: service ou country.
Em /prices, envie service, country ou os dois.
401unauthorized
Chave de API ausente ou inválida. Envie Authorization: Bearer <chave>.
Confira se a chave foi copiada inteira e se está no cabeçalho Authorization: Bearer ou X-API-Key. Muitas recusas seguidas do mesmo IP levam a 429 por 60 s.
401key_revoked
Esta chave de API foi revogada.
Gere uma nova chave no painel e troque no seu sistema.
403partner_suspended
O acesso deste parceiro à API está suspenso. Fale com o suporte.
Fale com o suporte. Nenhuma chave do parceiro funciona enquanto durar a suspensão.
403environment_disabled
Este ambiente não está liberado para o parceiro.
O ambiente da chave (sandbox ou produção) está desligado para a sua conta. Fale com o suporte.
403account_not_active
A conta da API não pode fazer compras agora. Fale com o suporte.
Fale com o suporte.
403account_on_hold
As compras estão pausadas por uma análise financeira. Fale com o suporte.
Aguarde a análise ou fale com o suporte. Não repita a compra.
404not_found
Recurso não encontrado.
O serviço ou país informado não existe (a mensagem diz qual). Confira em /services e /countries.
404order_not_found
Pedido não encontrado.
Confira o id. Pedidos de outro parceiro ou de outro ambiente também respondem 404.
409idempotency_key_conflict
Esta Idempotency-Key já foi usada com outros dados.
Use uma chave nova para uma compra nova. Repita a mesma chave só com os mesmos dados.
409price_changed
O preço da oferta mudou. Consulte /prices e tente de novo.
Consulte /prices de novo e refaça a compra com uma nova Idempotency-Key.
409order_not_cancellable
Só é possível cancelar pedidos que ainda aguardam o SMS.
Consulte o pedido: o SMS pode ter chegado ou o pedido já terminou.
409cancel_not_available_yet
O cancelamento ainda não está liberado. Tente de novo em instantes.
Espere até cancel_available_at (veja o pedido) e tente de novo.
422offer_unavailable
Oferta indisponível no momento.
Escolha outra oferta ou outro país em /prices.
422no_numbers_available
Sem números disponíveis para esta oferta agora.
Tente outro país ou mais tarde.
422insufficient_funds
Saldo insuficiente na carteira da API.
No painel, em API → Carteira da API, use "Adicionar saldo à API" (sai do seu saldo do site) e confira em /balance.
422too_many_open_orders
Limite de pedidos aguardando SMS atingido. Conclua ou cancele um deles antes de comprar outro.
Espere o SMS ou cancele um dos pedidos em aberto.
429rate_limited
Limite de requisições por minuto atingido.
Espere o tempo do cabeçalho Retry-After (60 s) e reduza a frequência. Vale por chave, por parceiro e, sem chave ou com a chave pública, por IP.
429daily_limit_reached
Limite diário de compras atingido.
O limite conta as compras das últimas 24 horas. Tente mais tarde ou peça um limite maior ao suporte.
500internal_error
Erro interno. Tente de novo em instantes.
Tente de novo com espera crescente. Na compra, repita com a mesma Idempotency-Key.
502provider_failed
O fornecedor não concluiu a compra. Nada foi cobrado.
Nada foi cobrado. Tente de novo com uma nova Idempotency-Key ou outro país.
503purchases_unavailable
As compras estão temporariamente indisponíveis.
Tente mais tarde. As consultas continuam funcionando.
503service_unavailable
Serviço temporariamente indisponível. Tente de novo em instantes.
Tente de novo com espera crescente. Na compra, repita com a mesma Idempotency-Key.
503refund_under_review
O cancelamento foi registrado e o estorno será conferido pela equipe.
Não repita o cancelamento. A equipe confere o estorno; consulte o pedido e o saldo depois.

Referência

Limites e segurança

Os limites protegem a plataforma e a sua carteira. Os valores padrão podem ser ajustados para cada parceiro pelo suporte.

Limites
Limite	Padrão	Ao passar
Requisições por minuto, por chave	60	`429 rate_limited`, `Retry-After: 60`
Requisições por minuto, somando as chaves do parceiro	3 × o limite por chave	`429 rate_limited`, `Retry-After: 60`
Rotas públicas sem chave, por IP	60 por minuto	`429 rate_limited`, `Retry-After: 60`
Chave pública de testes, por IP	30 por minuto	`429 rate_limited`, `Retry-After: 60`
Recusas de chave (401, e 403 de parceiro suspenso ou ambiente desligado), por IP	20 por minuto	`429 rate_limited` por 60 s
Compras nas últimas 24 horas, por ambiente	500 (chave pública: 100 por IP e 20.000 somando todos os IPs)	`429 daily_limit_reached`, `Retry-After: 3600`
Pedidos em aberto ao mesmo tempo (`processing` ou `waiting_sms`), por ambiente	20 (chave pública: 5 por IP)	`422 too_many_open_orders`
Corpo da requisição	4 KB	`400 invalid_json`
Itens por página em /orders	100	`400 invalid_request`

As listas de países, categorias e serviços são atualizadas a cada 30 segundos: não é preciso consultá-las a cada compra. Para acompanhar um pedido, consulte a cada 5 segundos ou mais.

Segurança

Use a chave só no seu servidor, em uma variável de ambiente. Nunca coloque em aplicativo, página web ou repositório.
Se uma chave vazar, revogue no painel: ela para de funcionar na hora. Gere outra e troque no seu sistema.
Cada parceiro só enxerga os próprios pedidos: o pedido de outro parceiro responde 404 order_not_found.
As chamadas feitas com chave ficam registradas por 90 dias (rota, situação, duração e o IP só como resumo criptográfico com segredo do servidor), para suporte e segurança. Com a chave pública de testes, por 7 dias. Chamadas sem chave e com chave inválida não são registradas.
Uso fora das regras de uso, abuso ou fraude levam à suspensão da API na hora.
Webhooks para parceiros ainda não estão disponíveis: acompanhe os pedidos consultando GET /orders/{id}.

Referência

Sandbox e Produção

Os dois ambientes usam o mesmo endereço base, os mesmos países, serviços e preços. A chave decide qual é usado.

Sandbox (d2g_test_)

Testar sem conta

Use a chave pública d2g_test_publico_demo. Ela funciona como uma chave de sandbox, mas é compartilhada: os pedidos ficam separados por IP (cada IP só vê os seus), somem depois de 24 horas e os limites valem por IP (30 requisições por minuto, 5 pedidos aguardando SMS, 100 por dia), com um teto de 20.000 pedidos por dia somando todos os IPs. Os exemplos desta página no ambiente Sandbox já usam essa chave e rodam como estão. Não envie dados reais. Para ter a sua própria chave, crie a conta e gere a chave em API, no painel.

Linha do tempo de um pedido no sandbox
Momento	O que acontece
Compra	Pedido em `waiting_sms` com um número fictício que começa com `+999`. Pode ser cancelado na hora.
20 segundos depois	Chega o SMS de teste com o código `123456`. Situação: `sms_received`.
20 minutos depois da compra	O pedido com SMS fica `completed`.

O pedido avança quando você o consulta (GET /orders/{id} ou GET /orders).
O saldo é simulado: R$ 1.000,00 fixos, com simulated: true. Nada é cobrado e não há erro de saldo insuficiente.
Idempotency-Key, limite de pedidos aguardando SMS e limite diário funcionam como em produção.
Com ?status=, o filtro já considera a situação de agora (o SMS de teste conta mesmo sem consultar o pedido antes).
As situações processing e failed não acontecem no sandbox.
Pedidos do sandbox e da produção são separados: um não aparece no outro.

Produção (d2g_live_)

As compras são reais: o número vem da operadora e o valor sai da carteira da API (abastecida por você com o saldo do site).
O pedido dura até 20 minutos e pode passar por processing enquanto a compra é confirmada com a operadora.
O cancelamento é liberado 2 minutos depois da compra (em alguns números, em até 5 minutos).
Sem SMS, cancelado ou expirado, o valor volta para a carteira da API automaticamente.
Cada serviço decide quais números aceita. Se o serviço recusar o número antes de enviar o código, cancele o pedido.

Antes de ir para produção

Teste o fluxo completo no sandbox, inclusive cancelamento e erros.
Abasteça a carteira da API (Carteira da API → Adicionar saldo à API) e guarde a chave de produção em uma variável de ambiente do servidor.
Gere uma Idempotency-Key por compra e guarde junto com o seu pedido.
Confira o saldo em /balance antes de picos de uso.
Trate 429 respeitando Retry-After e os erros 5xx com novas tentativas.