Começar

Autenticação

Toda requisição ao contrato /v1 leva a sua API key no header x-api-key. Não há login, não há token de sessão, não há refresh.

x-api-key: <sua-api-key>

Exemplo

curl https://api.nuntis.com.br/v1/channels \
  -H "x-api-key: $NUNTIS_API_KEY"

Credencial em query string é recusada

Enviar a key como parâmetro de URL (?api_key=…) não funciona, e a recusa é por desenho. Query string vaza em três lugares que ninguém controla:

• log de proxy e de servidor, onde a URL completa costuma ser gravada em texto puro;
• histórico do navegador, se a URL passar por um;
• o header Referer, que carrega a URL de origem para terceiros.

Header não vai para nenhum dos três por padrão. É a única forma aceita aqui.

O que a key delimita

A key é o limite. Ela identifica o seu produto, e tudo que você lê ou escreve pertence a ele — clientes, operadores, números, conversas, mensagens, subscriptions de webhook.

Orçamento de requisições

Cada API key tem um orçamento em dois horizontes: por minuto e por hora. Toda resposta autenticada — inclusive as de erro — traz o estado corrente dos dois, para que você não precise adivinhar o ritmo.

curl -sD - -o /dev/null \
  -H "x-api-key: $NUNTIS_API_KEY" \
  https://api.nuntis.com.br/v1/channels

# x-ratelimit-limit-minute: 60
# x-ratelimit-remaining-minute: 59
# x-ratelimit-reset-minute: 2026-09-02T16:21:00.000Z
# x-ratelimit-limit-hour: 1000
# x-ratelimit-remaining-hour: 999
# x-ratelimit-reset-hour: 2026-09-02T17:00:00.000Z

A janela é de calendário, não deslizante

Reset é um instante, não um número de segundos. As janelas viram no relógio: a de minuto no segundo :00, a de hora no minuto :00. Consequência prática: o orçamento não se recompõe aos poucos — ele volta inteiro na virada.

Quem supõe janela deslizante programa um backoff que vai devolvendo cota aos poucos, continua batendo no limite e conclui que “o rate limit está errado”. O comportamento correto é esperar até o Reset.

Quando estoura

A resposta é 429 RATE_LIMITED, e ela traz o trio sem sufixo — referente à janela que estourou, que pode ser a de minuto ou a de hora — mais Retry-After em segundos:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-09-02T16:21:00.000Z
Retry-After: 42

RATE_LIMITED é retryable: true. Respeite Retry-After — retentar antes só gasta orçamento da janela seguinte.

Escopos

Além do produto, a key carrega escopos: o conjunto de coisas que ela pode fazer. Eles são definidos na emissão — peça os que você precisa, e só eles.

Uma key por produto, por ambiente

Não emita uma key por cliente final nem por operador. A separação entre os seus clientes é feita pelo modelo de recursos, não por credenciais — multiplicar keys só multiplica o que você precisa rotacionar quando uma vazar.

Guarde a key como segredo

• Só no servidor. Nunca em aplicativo móvel, front-end web, repositório ou build de cliente — qualquer coisa que rode na máquina do usuário final é pública, mesmo compilada.
• Em variável de ambiente (ou no cofre que você já usa), lida em tempo de execução. A key precisa ser trocável sem recompilar nada.
• Fora dos logs. Se o seu cliente HTTP registra headers ao depurar, filtre x-api-key explicitamente.

// A key é lida do ambiente, nunca escrita no código.
const NUNTIS_URL = process.env.NUNTIS_URL;      // https://api.nuntis.com.br
const NUNTIS_API_KEY = process.env.NUNTIS_API_KEY;

async function nuntis(caminho, opcoes = {}) {
  const resposta = await fetch(`${NUNTIS_URL}/v1${caminho}`, {
    ...opcoes,
    headers: {
      'x-api-key': NUNTIS_API_KEY,
      'content-type': 'application/json',
      ...(opcoes.headers || {}),
    },
  });

  if (!resposta.ok) {
    // O corpo de erro é sempre { code, message, retryable, source }.
    const erro = await resposta.json();
    throw Object.assign(new Error(erro.message), erro);
  }

  return resposta.status === 204 ? null : resposta.json();
}

Rotação

Trocar a key é uma mudança de variável de ambiente, não de código. Se você suspeitar de vazamento, peça uma key nova e descarte a antiga — como toda chamada é autenticada por header, não há sessão pendurada para expirar.

Erros de autenticação

A forma completa do corpo de erro e a lista inteira de códigos estão em Erros.

Nuntis — serviço de mensageria multicanal da Devari.