A API da Noir SMS para desenvolvedores: compre um número e leia o código SMS pelo seu próprio código

Autenticação e URL base

Entre na sua conta, abra a página API do painel e gere uma chave. As chaves começam com nsk_live_ e aparecem só uma vez, então guarde a sua num gerenciador de segredos ou numa variável de ambiente. Cada conta tem uma chave; gerar uma nova desativa a antiga na hora, e é assim que você troca uma chave vazada.

Envie a chave em toda requisição, no cabeçalho Authorization: Bearer nsk_live_SUA_CHAVE ou no cabeçalho X-API-Key. Corpos de requisição e resposta são JSON, os preços são em dólares americanos e os horários em ISO 8601 (UTC). Chame a API só a partir do seu servidor: uma chave dentro de uma página web ou de um app pode ser extraída e gastar o seu saldo.

O fluxo de compra, passo a passo

Primeiro, veja o que dá para comprar. GET /countries lista os países com números em estoque agora, e GET /services?country=us devolve o código de cada serviço (wa para WhatsApp, tg para Telegram, go para Google e assim por diante) com o preço que você paga e o estoque. Os preços podem mudar durante o dia, então leia em tempo de execução.

Depois, compre com POST /numbers, enviando service, country e, se quiser, max_price. Se o preço atual estiver acima de max_price, a compra é recusada com HTTP 409 e nada é cobrado. Uma compra bem-sucedida responde 201 com o objeto do número:

• waiting: o número fica reservado para você até expires_at, 20 minutos após a compra. Digite o phone no app.
• received: chegou pelo menos um SMS. O código está em sms[].code e o texto completo em sms[].text.
• canceled: você chamou POST /numbers/{id}/cancel depois de cancelable_at (2 minutos após a compra) e o valor voltou para o seu saldo.
• expired: nenhum SMS em 20 minutos; o valor foi reembolsado automaticamente.

curl -X POST https://noirsms.com/api/v1/numbers \
  -H "Authorization: Bearer nsk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"service": "wa", "country": "us", "max_price": 1.50}'

Polling ou webhook: qual usar

Polling é a opção mais simples: chame GET /numbers/{id} a cada 3 a 5 segundos até o status mudar. Respeite o limite de 120 requisições por minuto por chave: com uma requisição a cada 4 segundos, cada número aberto usa cerca de 15 requisições por minuto.

O webhook escala melhor. Configure uma URL HTTPS na página API do painel e a Noir SMS envia um POST com type sms.received assim que detecta um SMS num número comprado pela API. Toda entrega traz o cabeçalho X-NoirSMS-Signature com um timestamp t e uma assinatura v1, que é o HMAC-SHA256 em hexadecimal do timestamp, um ponto e o corpo bruto, usando o seu segredo de webhook. Valide a assinatura, rejeite timestamps com mais de 5 minutos e responda com qualquer status 2xx. Muitas integrações usam o webhook pela velocidade e um polling de vez em quando como garantia.

Erros que você deve tratar

Os erros vêm com um status HTTP e um corpo JSON como {"error": {"code": "...", "message": "..."}}. Decida pelo code, não pelo texto da mensagem.

• 401 invalid_api_key: chave ausente, errada ou revogada.
• 402 insufficient_balance: adicione saldo; needed traz o preço.
• 409 price_above_max: o preço atual está acima do seu max_price.
• 400 no_numbers: sem estoque para esse serviço e país agora; você não foi cobrado.
• 400 too_early ou already_closed: o cancelamento veio antes de cancelable_at, ou o número já está fechado.
• 429 rate_limited: mais de 120 requisições em um minuto; espere alguns segundos e tente de novo.
• 502 ou 503 provider_error ou restocking: problema temporário; você não foi cobrado.

Um exemplo mínimo completo em Node.js

Este script compra um número dos EUA para WhatsApp, mostra o número, consulta até o código chegar, marca o número como finalizado e devolve o código. Se o número expirar ou for cancelado, retorna null e o saldo já foi reembolsado. POST /numbers/{id}/finish é opcional, mas libera o número mais cedo. POST /numbers/{id}/resend pede um segundo código num número aberto, sem custo.

// Node.js 18+ (fetch nativo). Rode no seu servidor, nunca no navegador.
const BASE = 'https://noirsms.com/api/v1';
const headers = { Authorization: 'Bearer nsk_live_SUA_CHAVE', 'Content-Type': 'application/json' };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function getCode(service, country) {
  const res = await fetch(BASE + '/numbers', { method: 'POST', headers, body: JSON.stringify({ service, country }) });
  const num = await res.json();
  if (!res.ok) throw new Error(num.error.code); // ex.: insufficient_balance, no_numbers
  console.log('Digite este número no app:', num.phone);

  while (true) {
    await sleep(4000); // consulta a cada 3 a 5 segundos
    const n = await (await fetch(BASE + '/numbers/' + num.id, { headers })).json();
    if (n.status === 'received') {
      await fetch(BASE + '/numbers/' + num.id + '/finish', { method: 'POST', headers });
      return n.sms[0].code;
    }
    if (n.status === 'expired' || n.status === 'canceled') return null; // reembolsado
  }
}

getCode('wa', 'us').then((code) => console.log('Código:', code));

Passo a passo

1. Crie uma chaveAbra a página API do painel, gere uma chave de API, guarde no seu servidor e adicione saldo.
2. Compre e aguardeChame POST /numbers com um serviço e um país, depois consulte GET /numbers/{id} ou espere o webhook sms.received.
3. Use e fecheLeia sms[].code, digite no app e chame finish. Números sem SMS são reembolsados automaticamente.