Começar

Provisionamento

Você cria os seus clientes, os operadores deles e os números — e leva um número até o QR de pareamento — em quatro chamadas, sem nenhuma etapa manual do nosso lado.

O fluxo completo

POST /v1/customers                  → cus_4471   cliente
POST /v1/customers/cus_4471/operators → op_991    operador do cliente
POST /v1/operators/op_991/numbers     → num_4711  número do operador
POST /v1/numbers/num_4711/pairing     → QR        o operador escaneia

Cada recurso nasce sob o anterior: o pai vem no caminho, e não no corpo. Assim não existe recurso órfão nem recurso pendurado no pai errado por um campo esquecido. O modelo inteiro é esse encaixe.

1. Criar um cliente

POST /v1/customers

curl -X POST https://api.nuntis.com.br/v1/customers \
  -H "x-api-key: $NUNTIS_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "name": "Clínica Sorriso", "externalRef": "clinica-4471" }'

{
  "id": "cus_4471",
  "name": "Clínica Sorriso",
  "externalRef": "clinica-4471",
  "active": true,
  "createdAt": "2026-08-13T18:12:03.000Z"
}

Campo desconhecido no corpo é recusado, não ignorado: a resposta é 400 VALIDATION_FAILED. Isso é de propósito — um campo ignorado em silêncio faz você achar que configurou algo que nunca chegou.

2. Criar um operador

POST /v1/customers/{id}/operators

curl -X POST https://api.nuntis.com.br/v1/customers/cus_4471/operators \
  -H "x-api-key: $NUNTIS_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "name": "Ana — comercial", "externalRef": "user-991" }'

{
  "id": "op_991",
  "name": "Ana — comercial",
  "externalRef": "user-991",
  "active": true,
  "createdAt": "2026-08-13T18:12:03.000Z"
}

As regras de name e externalRef são as mesmas do cliente. O recurso não publica o cliente ao qual pertence: o vínculo você obtém por GET /v1/customers/{id}/operators. Dois caminhos para a mesma verdade divergem no primeiro que for esquecido.

3. Cadastrar um número

POST /v1/operators/{id}/numbers

Esta chamada cria o número e prepara o canal na mesma requisição.

curl -X POST https://api.nuntis.com.br/v1/operators/op_991/numbers \
  -H "x-api-key: $NUNTIS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
        "channel": "whatsapp-unofficial",
        "phoneE164": "+5511999990000",
        "label": "Comercial — Ana"
      }'

{
  "id": "num_4711",
  "channel": "whatsapp-unofficial",
  "label": "Comercial — Ana",
  "phoneE164": "+5511999990000",
  "active": true,
  "status": "disconnected",
  "since": "2026-08-13T18:12:03.000Z",
  "sinceUnix": 1786731123,
  "lastCheckedAt": "2026-08-13T18:12:03.000Z",
  "lastCheckedAtUnix": 1786731123
}

O corpo do 201 é exatamente o item que GET /v1/numbers devolve no instante seguinte — mesmo shape, mesmos campos. Você não precisa de dois tratamentos.

Espaços, hifens e parênteses no telefone são aceitos e normalizados. O que não é aceito é número que não existe no plano de numeração do país.

Quais canais aceitam cadastro

Cada canal declara isso em GET /v1/channels, no campo provisioning:

O conjunto é aditivo: trate um valor que você não conhece como managed — ou seja, como “não tente cadastrar sozinho” — em vez de quebrar.

O telefone é único na plataforma inteira

Desativar o número que ocupa um telefone libera o valor para um cadastro novo.

4. Parear

POST /v1/numbers/{id}/pairing

curl -X POST -H "x-api-key: $NUNTIS_API_KEY" \
  https://api.nuntis.com.br/v1/numbers/num_4711/pairing

{
  "status": "qr_required",
  "qr": {
    "code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "format": "png-data-uri",
    "obtainedAt": "2026-08-13T18:13:10.000Z",
    "obtainedAtUnix": 1786731190
  },
  "hint": { "refreshAfterSeconds": 20 }
}

O qr.code vai direto num <img src="…">. Mostre a imagem, renove a cada ~20 s enquanto ninguém escanear, e pare quando chegar connection.updated com state: "connected". O passo a passo completo, com os erros possíveis, está em Números e pareamento.

O telefone que pareou tem que ser o que você declarou

Quando a sessão conecta, o Nuntis compara o telefone real do aparelho com o phoneE164 que você cadastrou. Se eles não forem o mesmo, a sessão é encerrada e o número volta para disconnected — o cadastro nunca é sobrescrito pelo que apareceu do outro lado.

O motivo chega no campo reason, presente nas duas superfícies: GET /v1/numbers/{id}/status e o evento connection.updated.

{
  "status": "disconnected",
  "since": "2026-08-13T18:20:00.000Z",
  "sinceUnix": 1786731600,
  "lastCheckedAt": "2026-08-13T18:20:00.000Z",
  "lastCheckedAtUnix": 1786731600,
  "reason": "phone_mismatch"
}

Correlacionar com os seus IDs: externalRef

Todo identificador do Nuntis é opaco (cus_4471, op_991, num_4711). Para amarrar cada recurso ao seu próprio registro, cliente e operador aceitam um externalRef.

• 1 a 50 caracteres, apenas A-Z a-z 0-9 . _ -.
• Único por tipo, dentro do seu produto, entre os recursos ativos. Um cliente e um operador podem ter o mesmo valor sem conflito — o id de uma pessoa e o id de uma empresa vivem em tabelas diferentes do seu lado e não têm por que competir aqui.
• Repetir um valor em uso devolve 409 RESOURCE_ALREADY_EXISTS. A resposta não revela o recurso existente: só você sabe se foi um retry ou uma colisão de verdade.
• Desativar libera o valor para reuso.

Número não tem externalRef: o correlacionador natural dele é o próprio phoneE164, que já é único entre os ativos.

Consultar o que existe

{
  "data": [
    {
      "id": "cus_4471",
      "name": "Clínica Sorriso",
      "externalRef": "clinica-4471",
      "active": true,
      "createdAt": "2026-08-13T18:12:03.000Z"
    }
  ]
}

As listagens devolvem sempre um objeto com data, nunca um array na raiz — é o que permite acrescentar campos depois sem quebrar você. Coleção vazia responde 200 com data: [], nunca 404.

Desativar

{ "id": "num_4711", "active": false }

Os três respondem o mesmo corpo e são idempotentes: repetir devolve exatamente isso de novo.

Não há cascata — desative de baixo para cima

Desativar um pai que ainda tem filho ativo responde 409 RESOURCE_NOT_EMPTY:

1. DELETE /v1/numbers/num_4711     ← primeiro os números
2. DELETE /v1/operators/op_991     ← depois o operador
3. DELETE /v1/customers/cus_4471   ← por último o cliente

É deliberado. Um DELETE de cliente que derrubasse em silêncio todas as sessões pareadas embaixo dele é exatamente a catástrofe que este contrato recusa cometer — você desativa passo a passo e vê o que está derrubando a cada um.

O que um número desativado faz

Número com active: false fica visível e inerte, nunca invisível:

• continua em GET /v1/numbers, com active: false;
• continua respondendo em GET /v1/numbers/{id}/status;
• recusa agir — pareamento, presença e envio respondem 422 NUMBER_DEACTIVATED.

Não confunda DELETE /v1/numbers/{id} com DELETE /v1/numbers/{id}/session: o segundo encerra a sessão e mantém o número ativo, para novo pareamento.

Escopos necessários

As rotas desta página exigem escopo explícito na sua API key — uma key sem ele responde 401 UNAUTHORIZED, mesmo sendo válida para o resto do contrato.

A tabela completa, com os escopos de envio, leitura e sessão, está em Autenticação.

Erros desta superfície

A forma do corpo de erro e o catálogo inteiro estão em Erros.

Checklist de integração

1. Leia GET /v1/channels e guarde quais canais são self-service.
2. Crie o cliente com um externalRef seu, sempre.
3. Crie o operador sob o cliente, também com externalRef.
4. Cadastre o número com channel e, quando o canal exigir, phoneE164.
5. Guarde os três ids opacos como texto, sem parsear.
6. Chame o pareamento e mostre o QR; renove a cada ~20 s.
7. Espere connection.updated. Se vier disconnected com reason, mostre o motivo ao operador em vez de tentar de novo em laço.
8. Para remover, desative de baixo para cima: número, operador, cliente.

Nuntis — serviço de mensageria multicanal da Devari.