Guia da API e webhooks

Documentação pública navegável: https://docs.novodid.com. Guia MCP: https://docs.novodid.com/mcp/.

Base: https://novodid.com. Versão das rotas: /api/v1.

Acesso e tokensCopiar link

1. Entre no painel e abra Desenvolvedores → Tokens. A API é liberada por padrão para PF e PJ, sem solicitação ou aprovação manual. Bloqueios administrativos e contas removidas continuam impedindo o uso.
2. Crie um token com nome de 3 a 80 caracteres e apenas as permissões necessárias. Há limite de 10 tokens ativos e não expirados por conta. Uma expiração, quando informada, deve ser futura.
3. Guarde o token exibido na criação em um gerenciador de segredos. O valor completo não poderá ser recuperado pela lista. Nunca coloque tokens em URLs, aplicativos distribuídos, repositórios ou código de navegador.
4. Envie Authorization: Bearer <seu-token> nas requisições. Use Content-Type: application/json em POST e PATCH.
5. Para substituir uma credencial, use a ação de rotação no painel. Quando a rotação é concluída, o token anterior é revogado. Atualize sua integração com o novo valor. Criar, revogar e rotacionar compartilham o limite de 10 operações/minuto da conta.

Permissões: dids:read, forwarding:read, forwarding:write, forwarding:phone, forwarding:delete, account:read, billing:read, calls:read, sms:read, sms:send, sip:create, sip:credentials:read. /me aceita qualquer token válido de conta liberada. Revogação, expiração ou bloqueio da conta impedem novas autenticações.

Limites e formatoCopiar link

Todos os tokens da conta compartilham esses limites. Criar ou rotacionar um token não reinicia a cota. Tentativas podem consumir cota mesmo quando a operação é recusada. Proteções adicionais podem limitar tentativas de autenticação. Em 429, aguarde Retry-After; não repita em laço imediato.

As respostas incluem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (Unix timestamp em segundos). Envios incluem também X-RateLimit-Sms-Day-Limit, X-RateLimit-Sms-Day-Remaining e X-RateLimit-Sms-Day-Reset. Os limites podem ser ajustados operacionalmente; consulte os cabeçalhos.

Corpo JSON: objeto com até 16384 bytes e 16 campos. Query string: até 2048 caracteres, sem parâmetros repetidos. IDs: inteiros positivos até 2147483647. Não use notação exponencial, IDs fracionários nem filtros inválidos: eles são recusados, não ignorados. Telefones de SMS: 10 a 15 dígitos, com + inicial opcional; prefira DDI + DDD + número. Texto: 1 a 1600 caracteres. O limite de caracteres não garante um único segmento SMS: a codificação e o tamanho da mensagem influenciam a entrega.

RotasCopiar link

A listagem de DIDs traz número, tipo, status, cobrança, disponibilidade de SMS e encaminhamento. Ela representa a posse ativa confirmada, não o histórico de compras. Não envie identificadores de conta para escolher o titular: a conta é determinada pelo token. Um DID inexistente ou fora da posse ativa retorna 404 did_not_found.

Consultar DIDs e SMSCopiar link

curl --fail-with-body \
  -H "Authorization: Bearer $NOVODID_API_TOKEN" \
  'https://novodid.com/api/v1/dids'

curl --fail-with-body \
  -H "Authorization: Bearer $NOVODID_API_TOKEN" \
  'https://novodid.com/api/v1/sms/messages?didId=1234&direction=inbound&limit=50'

SMS aceita didId, did, direction (inbound ou outbound) e limit (1–200; padrão 50). Sem direção, inclui ambas. Use o ID retornado pela listagem de DIDs. Quando informar ID e número, eles devem corresponder ao mesmo DID.

{"messages":[{"id":"exemplo","direction":"inbound","from":"5511888888888","to":"5511999999999","text":"Mensagem de exemplo","status":"received","receivedAt":"2026-09-23T12:00:00.000Z"}]}

Somente mensagens posteriores ao início confirmado da posse atual ficam disponíveis. Comprar novamente um número não recupera mensagens de posses anteriores. Sem confirmação desse marco, o histórico fica indisponível; contate o suporte. Número fixo não recebe SMS. Ter um número móvel também exige a elegibilidade de SMS da sua contratação. Consulte sms.enabled e sms.accessStartedAt no DID.

A consulta de SMS retorna as mensagens mais recentes, até o limite, e não oferece cursor/paginação de histórico nesta versão. Para novos eventos, use webhooks. Lista vazia significa que não há mensagens acessíveis para os filtros informados; 403 sms_not_enabled indica falta de habilitação para o DID solicitado.

ChamadasCopiar link

GET /api/v1/calls aceita didId, did, startDate, endDate, page (1–10000) e limit (1–200; padrão 50). Datas aceitam AAAA-MM-DD ou ISO 8601 com fuso. Use startDate anterior ou igual a endDate. A consulta filtra chamadas recebidas pelos números e período de acesso da conta. O retorno pode conter menos itens que o limite após a filtragem de acesso. Não há garantia de total global de registros.

Enviar SMSCopiar link

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $NOVODID_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"didId":1234,"from":"5511999999999","to":"5511888888888","text":"Mensagem de exemplo"}' \
  'https://novodid.com/api/v1/sms/messages'

from, to e text são obrigatórios. didId é opcional, mas, quando fornecido, deve corresponder ao remetente. O envio exige posse ativa, SMS habilitado e escopo sms:send. Ele só é aceito como resposta a um SMS de entrada desse destino para o DID, com data igual ou posterior ao início do acesso SMS da posse atual. Uma mensagem só de saída, o histórico de outro contato ou de outra posse, e a falha ou indisponibilidade da consulta não autorizam o envio. Não há liberação de conta para iniciar conversa. newConversation na resposta de sucesso é false.

{"message":{"id":"exemplo","smscMessageId":"referencia","didId":1234,"from":"5511999999999","to":"5511888888888","textLength":19,"newConversation":false}}

Os identificadores são opacos e podem ser nulos quando indisponíveis. HTTP 201 confirma o aceite da operação, não o recebimento pelo aparelho de destino. O envio não oferece chave de idempotência nesta versão: após timeout, confira o histórico antes de repetir, para evitar duplicidade.

EncaminhamentoCopiar link

Envie PATCH para /api/v1/dids/{didId}/forwarding com um destes objetos:

{"type":"phone","destinationNumber":"5511999999999"}

{"type":"sip","sipAccountId":123}

{"type":"ip","clientIp":"203.0.113.10","clientPort":5060}

Os valores são exemplos: use seu destino real. destination é um alias de destinationNumber. Siga-me exige saldo e cobra integralmente R$ 0,20/minuto, sem minutos gratuitos; destinos 0800 não são aceitos. O ramal precisa pertencer à conta. IP deve ser endereço IPv4/IPv6 público literal; endereços privados, locais e reservados não são aceitos; a porta deve ser inteira entre 1 e 65535. DELETE no mesmo caminho remove o encaminhamento. Se a posse mudar durante a operação, a requisição poderá ser recusada; consulte o DID novamente antes de repetir.

Exemplo em JavaScriptCopiar link

const response = await fetch('https://novodid.com/api/v1/dids', {
  headers: { Authorization: `Bearer ${process.env.NOVODID_API_TOKEN}` }
});
if (!response.ok) throw new Error(`Falha na consulta: HTTP ${response.status}`);
const { dids } = await response.json();
console.log(dids.map(({ id, number }) => ({ id, number })));

Execute no servidor. A referência interativa em Desenvolvedores → Referência também oferece exemplos por linguagem. Baixe o OpenAPI.

WebhooksCopiar link

1. Abra Desenvolvedores → Webhooks e crie um endpoint.
2. Informe nome de 3–80 caracteres, URL HTTPS de até 2048 caracteres e eventos. A URL precisa ser pública, sem espaços, credenciais ou redirecionamentos. Endereços locais, privados e reservados são recusados.
3. Opcionalmente selecione até 50 DIDs da sua posse ativa. Filtro vazio corresponde a todos os DIDs elegíveis da conta.
4. Guarde o segredo de assinatura exibido na criação. Use a ação de teste e consulte o histórico de entregas e tentativas.
5. Para interromper entregas, pause o endpoint. Para substituir o segredo, use a ação de rotação e atualize imediatamente seu recebedor.

Eventos: sms.received, sms.sent, call.received, call.missed, payment.approved, did.expiring. Cada payload contém id, type, version: "v1", createdAt e data. Os dados variam por evento, com objetos did, sms, call ou payment. Eventos de teste contêm data.test: true.

{"id":"evt_exemplo","type":"sms.received","version":"v1","createdAt":"2026-09-23T12:00:00.000Z","data":{"did":{"id":1234,"number":"5511999999999","type":"movel"},"sms":{"direction":"inbound","from":"5511888888888","to":"5511999999999","text":"Exemplo","status":"received","receivedAt":"2026-09-23T12:00:00.000Z"}}}

Receba o corpo bruto antes de fazer o parse. Verifique X-Novodid-Signature: sha256= seguido do HMAC-SHA256 hexadecimal de timestamp + "." + corpoBruto, usando seu segredo. O timestamp vem de X-Novodid-Timestamp. Rejeite timestamps inválidos ou distantes do horário atual e compare assinaturas em tempo constante. Outros cabeçalhos: X-Novodid-Event e X-Novodid-Delivery.

import { createHmac, timingSafeEqual } from 'node:crypto';
function assinaturaValida(rawBody, timestamp, signature, secret) {
  const time = Date.parse(timestamp);
  if (!Number.isFinite(time) || Math.abs(Date.now() - time) > 5 * 60 * 1000) return false;
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(signature || '');
  return a.length === b.length && timingSafeEqual(a, b);
}

Após validar e persistir o evento, responda 2xx rapidamente, preferencialmente sem corpo, e processe em segundo plano. O prazo de entrega é de 8 segundos, incluindo conexão e leitura da resposta; somente os primeiros 2000 bytes da resposta são lidos para diagnóstico. Redirects não são seguidos. Falhas têm até cinco tentativas, com intervalos progressivos; falhas consecutivas podem pausar o endpoint. Não suponha ordem nem entrega única: deduplique por id do evento. Eventos de números são revalidados antes da entrega e podem ser descartados se a posse ou o acesso mudar. Webhooks não oferecem recuperação de histórico anterior à integração.

Erros e diagnósticoCopiar link

Formato da API: {"error":{"code":"codigo","message":"Descrição segura."}}. Algumas respostas incluem detalhes públicos de validação, como a permissão exigida.

Não envie tokens, segredos de webhook ou mensagens SMS completas ao abrir um chamado. Informe rota, horário, código HTTP e identificador do recurso. Não interprete uma resposta de erro como confirmação de que um envio não ocorreu.

Permissões e restrições de tokensCopiar link

Em Desenvolvedores → Tokens, informe um nome de 3 a 80 caracteres e marque apenas as permissões necessárias. Nenhuma vem selecionada. Os modelos “Ler SMS”, “Consultar números” e “Gerenciar SIP e IP” são atalhos; você pode ajustar as caixas antes de criar.

billing:read não substitui dids:read; autoriza campos adicionais. Sem billing:read, payment, cycle, expiresAt e autoRenew são null. Sem forwarding:read, forwarding é null, inclusive após PATCH/DELETE. Sem account:read, /me continua disponível para conferir o token, mas omite nome e e-mail. Uma permissão de escrita não concede automaticamente leitura nem remoção.

Escolha “Somente os números selecionados” (1 a 100) ou explicitamente “Todos os números atuais e futuros da conta”. A seleção é vinculada à posse vigente. Devolver um número encerra o acesso; recomprá-lo não reativa a autorização antiga. Crie outro token para autorizar a nova posse. Recursos fora da seleção são omitidos das listagens; consultas por ID retornam 404. As mesmas restrições valem para DIDs, encaminhamentos, chamadas e SMS. Nenhuma seleção permite acessar números de outro cliente.

Escolha validade de 7, 30, 90 ou 365 dias, ou sem expiração. O formulário sugere 90 dias. Depois de expirado, o token não autentica: crie outro. Para revogar imediatamente, use “Revogar”. A rotação substitui o segredo e revoga o anterior; mantém permissões, validade, seleção de números, limites e consumo. Ela não renova a data de expiração.

Você também pode limitar consultas/minuto (1–60), alterações/minuto (1–10), envios SMS/minuto (1–5) e envios SMS/dia UTC (1–100). Campos vazios usam apenas os limites compartilhados da conta. Os limites individuais são adicionais: nunca ampliam os da conta, e aplica-se sempre o mais restritivo. Tentativas autenticadas podem consumir o limite individual mesmo quando a operação é recusada depois. HTTP 429 informa Retry-After; não crie tokens para tentar contornar limites. Os cabeçalhos de sucesso descrevem a cota compartilhada, e os de 429 descrevem a cota que bloqueou a requisição.

Tokens antigos aparecem como “Token legado”: continuam abrangendo a conta inteira e preservam perfil/pagamento e as ações de encaminhamento que já tinham. Suas permissões efetivas ficam visíveis na lista. A correção de leitura de encaminhamento vale para todos: inclua explicitamente forwarding:read se sua integração usa esse campo. Para reduzir permissões de um token antigo, crie um novo restrito, atualize a integração e revogue o antigo. Não existe escopo curinga nem permissão para gerenciar outros tokens pela API pública.

Exemplo de integração mínima: token com apenas sms:read, um número selecionado, validade de 30 dias e 10 consultas/minuto. Ele consegue consultar os SMS autorizados, mas não lista outros números, não envia mensagens, não altera encaminhamento e não obtém nome/e-mail ou dados financeiros.

Se um número não aparecer na seleção, confira se a posse está ativa; se a lista não carregar, atualize a página. Para 403, confira a permissão específica da ação. Para 404 após devolução/recompra, crie um token com a nova seleção. Nunca cole o token em chamados, URLs ou código publicado.

Acesso automático e operações disponíveisCopiar link

Clientes PF e PJ podem criar seus tokens diretamente, sem abrir chamado de liberação. Bloqueios administrativos explícitos impedem o acesso. Os tokens continuam exigindo autenticação, permissões, posse atual, validade e limites. A liberação não habilita SMS para números fixos, não muda a elegibilidade comercial dos números e não autoriza iniciar conversa SMS.

• Listar seus números: GET /api/v1/dids, com dids:read; não lista estoque para compra.
• Ler SMS: GET /api/v1/sms/messages, com sms:read e número elegível autorizado.
• Responder SMS: POST /api/v1/sms/messages, com sms:send; use seu número em from, o remetente que escreveu para esse número em to e a resposta em text. Não existe rota específica de resposta nem permissão para iniciar conversa. Destinos que não aceitam mensagens (por exemplo, certos remetentes alfanuméricos) não podem receber resposta por esta rota.
• Configurar siga-me: PATCH /api/v1/dids/{didId}/forwarding, tipo phone, com forwarding:phone, saldo e cobrança integral de R$ 0,20/min.
• Consultar credenciais SIP: GET /api/v1/dids/{didId}/sip-credentials, com sip:credentials:read. Criar o ramal ao encaminhar: PATCH /api/v1/dids/{didId}/forwarding com {"type":"sip"} e as três permissões descritas abaixo.

Se houver bloqueio administrativo, a tela informa a restrição; entre em contato com o suporte para revisão. Webhooks também usam a liberação automática da conta, mantendo as próprias verificações e configuração.

Criar encaminhamento para ramal e consultar credenciais SIPCopiar link

Na criação do token, marque explicitamente “Alterar SIP e IP” (forwarding:write), “Criar ramal do número” (sip:create) e “Consultar usuário e senha SIP” (sip:credentials:read). Essas duas novas permissões não são adicionadas a tokens legados nem a modelos automaticamente. Escolha também quais números o token pode acessar. Para um token antigo, crie outro com as permissões necessárias, atualize a integração e revogue o anterior quando deixar de usá-lo.

Para criar ou reutilizar o ramal próprio do número e já encaminhar as chamadas para ele:

curl -X PATCH 'https://novodid.com/api/v1/dids/1234/forwarding' \
  -H "Authorization: Bearer $NOVODID_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"type":"sip"}'

Não envie usuário nem senha: são gerados pelo servidor. Se o ramal próprio já existe, é reutilizado, sem trocar sua senha. Uma repetição bem-sucedida não cria outro ramal. O resultado inclui:

{
  "didId": 1234,
  "number": "5511999999999",
  "forwarding": null,
  "sipCredentials": {
    "username": "5511999999999",
    "password": "EXEMPLO_NAO_UTILIZAR",
    "server": "ramal.novodid.com",
    "port": 5060,
    "transport": "udp",
    "uri": "sip:[email protected]"
  }
}

Os valores acima são fictícios. forwarding depende de forwarding:read; as credenciais dependem da permissão específica, não desse campo. Configure seu aplicativo com username como usuário/login, password como senha, server como servidor/domínio, porta 5060 e transporte UDP. uri é um endereço SIP, não uma URL HTTP e não contém a senha. Não presuma suporte a WebSocket/TLS por esse contrato.

Para consultar novamente, sem alterar o encaminhamento:

curl 'https://novodid.com/api/v1/dids/1234/sip-credentials' \
  -H "Authorization: Bearer $NOVODID_TOKEN"

Essa consulta exige somente sip:credentials:read, além das restrições do token e posse atual. Retorna didId e sipCredentials. Só atende ao ramal próprio do número com encaminhamento SIP ativo; não consulta senhas de ramais arbitrários, compartilhados com outros números ou vinculados a filas. Encaminhamento por telefone/IP não autoriza recuperar credenciais SIP.

Com {"type":"sip","sipAccountId":123}, o PATCH anterior continua configurando um ramal existente autorizado com forwarding:write; não cria ramal nem devolve senha nesse modo.

Tratamento de erros:

• 403 insufficient_scope: falta uma das permissões exigidas; nenhuma criação automática ocorre sem as três.
• 404 did_not_found: número indisponível, fora da seleção ou sem posse atual.
• 409 sip_forwarding_required: não há encaminhamento ativo para o ramal próprio elegível.
• 503 sip_persistence_failed: criação/vínculo ainda incompleto; repetir a configuração tenta concluir usando o mesmo ramal, sem excluir o existente.
• 502 sip_unavailable: serviço não confirmou a operação; consulte o estado antes de repetir. Conflitos de ramal residual ou compartilhado podem exigir suporte, sem assumir ou apagar um ramal de outra posse.

Se a criação foi concluída mas o encaminhamento falhou, o ramal pode permanecer criado para recuperação por retry. O retorno de erro não confirma que nada mudou. Respeitam-se limites de ramais da conta e cotas de escrita/leitura da API. Essa operação não inclui crédito nem autoriza chamadas gratuitas.

Respostas usam Cache-Control: no-store. A revogação do token impede novas consultas, mas não invalida uma senha SIP já copiada; eventual troca de senha do ramal é uma operação separada.

Usar a API no PostmanCopiar link

Na visão geral de Desenvolvedores ou em Referência, clique em Abrir no Postman. O workspace público reúne coleções em inglês americano, português brasileiro e espanhol colombiano. Abra a coleção do idioma desejado e use uma cópia no seu workspace para configurar as variáveis.

Defina novodid_token apenas como valor local/privado com um token criado em Desenvolvedores → Tokens. Confira baseUrl, consulte seus números e preencha didId com o ID autorizado retornado. Não publique seu token nem respostas com dados pessoais ou credenciais SIP. Execute apenas a requisição desejada: envio de SMS e alteração de encaminhamento produzem efeitos reais.

Documentação pública NovoDID no Postman.

A referência interativa em /desenvolvedores/referencia contém exemplos separados para siga-me, SIP existente, criação/reuso automático de ramal e IP público, com escopos cumulativos e respostas HTTP. O IP 203.0.113.10 nos exemplos é reservado para documentação e deve ser substituído pelo IP público do seu serviço SIP.

Compra de DIDs e MCPCopiar link

Permissões: catalog:read consulta estoque e cotação; orders:create cria pedidos; orders:read consulta e lista pedidos da conta. Tokens existentes não recebem essas permissões automaticamente. Para comprar, o token deve permitir todos os números, sem restrição a posses existentes. A conta precisa estar ativa, autorizada a comprar, com verificação exigida concluída e capacidade disponível. Valem as mesmas regras de móveis, ciclos e SMS do painel.

Cada pedido contém exatamente um DID. quantity pode ser omitido ou informado como o inteiro 1; listas e compras em lote são recusadas. A reserva pendente vale somente para o DID escolhido e dura no máximo 15 minutos desde a criação do pedido. Outros DIDs podem ser comprados durante esse período, respeitando os limites da conta. Ciclos: mensal, semestral e anual. Valores em centavos de BRL, calculados pelo servidor. O catálogo informa o preço mensal de referência; a cotação inclui ciclo, descontos e taxa do cartão. Cotar não reserva o número.

Apresente número, ciclo, valor recorrente e condições de SMS ao cliente. Somente após o aceite envie fixedDidSmsAcknowledged=true para fixos, ou mobileMonthlySmsAcknowledged=true quando exigido na cotação. O agente não deve presumir o consentimento do cliente.

Em ofertas temporárias de números móveis, os ciclos disponíveis e a inclusão de SMS podem variar. Consulte sempre a cotação: did.smsEnabled informa se o plano inclui SMS, e acknowledgements.mobileMonthlySms.required indica se é necessário enviar mobileMonthlySmsAcknowledged=true após o aceite do cliente. Apesar do nome, esses campos se aplicam a qualquer ciclo móvel sem SMS. A cotação não garante a oferta; as condições são conferidas novamente ao criar o pagamento. Pagamentos emitidos durante a oferta preservam suas condições até a validade do próprio pagamento. Após o encerramento, novas compras seguem as condições vigentes, e contratações concluídas mantêm seu ciclo e a condição de SMS nas renovações enquanto permanecerem vigentes. Isso não representa garantia de preço. Conta apta, verificação, limites, estoque disponível e um número por pedido continuam obrigatórios.

POST /api/v1/orders exige o cabeçalho Idempotency-Key: 16–128 letras, números, hífen ou sublinhado. Gere uma chave para cada nova intenção de compra e mantenha chave/corpo nas repetições. Alterar os dados com a mesma chave retorna 409 idempotency_conflict. Após timeout, consulte o pedido ou repita a mesma chave; não gere outra para contornar a falha. O erro pode informar details.orderId.

Pix Automático retorna pix.copyPaste e pix.qrCodeDataUrl. Confira no aplicativo bancário o pagamento e a autorização recorrente. Cartão retorna checkoutUrl para o cliente concluir o pagamento. Criar o pedido não paga nem ativa o DID. O retorno do navegador não confirma o pagamento.

Estados do pedido: creating, awaiting_payment, paid (pago, aguardando ativação), active (ativação concluída), expired, cancelled, refunded, rejected e review_required. Consulte o pedido para acompanhar e /api/v1/dids para conferir a posse ativa atual. As instruções de pagamento aparecem apenas em awaiting_payment. A reserva pendente expira em até 15 minutos, inclusive se a criação falhar ou o pedido precisar de análise. Isso não confirma cancelamento externo instantâneo nem reembolso. Não pague instruções vencidas; um pagamento confirmado após a expiração será analisado sem substituir outra reserva ou posse. Pagamentos já confirmados e números ativos continuam protegidos. Em review_required, contate o suporte com o ID do pedido.

MCP remoto: https://mcp.novodid.com/mcp, transporte Streamable HTTP e o mesmo token Bearer da API NovoDID. Ferramentas de compra: search_available_dids, quote_did_purchase, create_did_checkout, get_did_order e list_did_orders. As demais ferramentas estão descritas em “MCP: operações da conta e permissões”. A listagem respeita as permissões do token. create_did_checkout recebe idempotencyKey nos argumentos. Pix retorna copia e cola, imagem PNG e terminalQr para fonte monoespaçada. Se o cliente não exibir imagens, use o texto exato de copia e cola. O cliente MCP precisa permitir configurar o token Bearer.

Sequência de compraCopiar link

1. Consulte o catálogo e escolha um único ID.
2. Consulte a cotação para esse ID, ciclo e forma de pagamento.
3. Apresente o valor recorrente e as condições ao cliente.
4. Após a confirmação, crie o pedido com uma chave de idempotência nova para essa compra.
5. Mostre o Pix ou abra o link de cartão. O pagamento é concluído pelo cliente.
6. Consulte o pedido até confirmar pagamento e ativação. Use /api/v1/dids para consultar os números atualmente ativos.

GET /api/v1/catalog/didsCopiar link

Consultar números à venda — permissão catalog:read.

Consulta o estoque disponível, excluindo números vinculados e reservados. Não reserva estoque. Consulte a cotação para validar perfil, limites e condições da conta. Valores em centavos de BRL.

• ddd: dois dígitos; kind: fixed ou mobile; limit: 1–100 (padrão 20); page: 1–9999 (padrão 1). Filtros duplicados e desconhecidos são recusados.
• baseMonthlyAmount é o preço mensal de referência. O valor final do ciclo, descontos e taxa do cartão aparecem na cotação.

curl --fail-with-body --max-time 30 -X GET \
  'https://novodid.com/api/v1/catalog/dids?ddd=11&kind=fixed&limit=20&page=1' \
  -H "Authorization: Bearer $NOVODID_API_TOKEN"

Resposta HTTP 200 (exemplo fictício; o Pix de exemplo não é pagável):

{
  "dids": [
    {
      "id": 1234,
      "number": "551130001234",
      "ddd": "11",
      "kind": "fixed",
      "city": "São Paulo",
      "state": "SP",
      "currency": "BRL",
      "baseMonthlyAmount": 1499
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}

POST /api/v1/orders/quoteCopiar link

Cotar a compra de um número — permissão catalog:read.

Valida os requisitos da conta e calcula uma assinatura de um DID. Não cria cobrança nem reserva o número. Apresente preço, recorrência e condições de SMS ao cliente antes de criar o pedido.

• cycle: monthly, semiannually ou yearly. paymentMethod: pix ou card. quantity, quando informado, deve ser 1.
• couponCode é opcional, com até 80 letras, números, hífen ou sublinhado.
• As confirmações de SMS não são necessárias para consultar a cotação. Na criação, confirme somente após o aceite real do cliente.

curl --fail-with-body --max-time 30 -X POST \
  'https://novodid.com/api/v1/orders/quote' \
  -H "Authorization: Bearer $NOVODID_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"didId":1234,"quantity":1,"cycle":"monthly","paymentMethod":"pix","fixedDidSmsAcknowledged":true}'

Resposta HTTP 200 (exemplo fictício; o Pix de exemplo não é pagável):

{
  "did": {
    "id": 1234,
    "number": "551130001234",
    "kind": "fixed",
    "smsEnabled": false
  },
  "quantity": 1,
  "paymentMethod": "pix",
  "pricing": {
    "currency": "BRL",
    "baseMonthlyAmount": 1499,
    "cycle": "monthly",
    "cycleMonths": 1,
    "subtotalAmount": 1499,
    "totalDiscountPercent": 0,
    "discountedAmount": 1499,
    "cardFeeAmount": 0,
    "totalAmount": 1499
  },
  "recurring": true,
  "reserved": false,
  "acknowledgements": {
    "fixedDidSms": {
      "required": true,
      "message": "Confirme que está ciente de que este número fixo não recebe SMS antes de assinar."
    },
    "mobileMonthlySms": {
      "required": false,
      "message": null
    }
  }
}

POST /api/v1/ordersCopiar link

Criar pagamento de um número — permissão orders:create.

Cria um pedido de exatamente um DID. Pix retorna copia e cola e imagem QR; cartão retorna checkoutUrl para o cliente concluir a assinatura. Exige Idempotency-Key no cabeçalho. Criar o pedido não significa pagamento confirmado ou número ativado.

• Idempotency-Key: 16–128 letras, números, hífen ou sublinhado. Gere uma chave para cada nova intenção de compra e reutilize a mesma chave e o mesmo corpo nas repetições. Outra compra precisa de outra chave.
• A reserva pendente vale somente para o DID escolhido e dura no máximo 15 minutos desde a criação do pedido. Outros DIDs podem ser comprados durante esse período, respeitando os limites da conta. A mesma chave com dados diferentes retorna 409 idempotency_conflict. Em timeout, consulte o pedido ou repita a mesma chave; não gere outra cobrança.
• Fixos exigem fixedDidSmsAcknowledged=true. Planos móveis sem SMS exigem mobileMonthlySmsAcknowledged=true quando indicado na cotação. Não aceite essas condições automaticamente em nome do cliente.
• Para comprar, use um token sem restrição a posses de números existentes. O escopo não permite usar cartão salvo nem efetuar pagamento sem ação do cliente.
• A reserva pendente expira em até 15 minutos, inclusive se a criação falhar ou o pedido precisar de análise. Isso não confirma cancelamento externo instantâneo nem reembolso. Não pague instruções vencidas; um pagamento confirmado após a expiração será analisado sem substituir outra reserva ou posse. Pagamentos já confirmados e números ativos continuam protegidos. Em review_required, contate o suporte com o ID do pedido.

curl --fail-with-body --max-time 30 -X POST \
  'https://novodid.com/api/v1/orders' \
  -H "Authorization: Bearer $NOVODID_API_TOKEN" \
  -H "Idempotency-Key: $NOVODID_ORDER_KEY" \
  -H "Content-Type: application/json" \
  --data '{"didId":1234,"quantity":1,"cycle":"monthly","paymentMethod":"pix","fixedDidSmsAcknowledged":true}'

Resposta HTTP 201 (exemplo fictício; o Pix de exemplo não é pagável):

{
  "order": {
    "id": "11111111-1111-4111-8111-111111111111",
    "didId": 1234,
    "quantity": 1,
    "status": "awaiting_payment",
    "paymentMethod": "pix",
    "currency": "BRL",
    "amount": 1499,
    "createdAt": "2026-09-23T15:00:00.000Z",
    "expiresAt": "2026-09-23T15:15:00.000Z",
    "checkoutUrl": null,
    "pix": {
      "copyPaste": "PIX_COPY_AND_PASTE_EXAMPLE",
      "qrCodeDataUrl": "data:image/png;base64,EXAMPLE"
    }
  }
}

GET /api/v1/orders/{orderId}Copiar link

Consultar um pedido — permissão orders:read.

Consulta apenas pedidos da conta autenticada. Substitua {orderId} pelo UUID retornado na criação. Retorna as instruções de pagamento enquanto o pedido aguarda pagamento. Pedido de outra conta retorna 404.

• Estados: creating (criando), awaiting_payment (aguardando pagamento), paid (pago, aguardando ativação), active (ativação realizada), expired, cancelled, refunded, rejected ou review_required.
• paid e active são estados diferentes. Consulte também /api/v1/dids para confirmar a posse ativa atual. O pedido mantém o histórico da compra.

curl --fail-with-body --max-time 30 -X GET \
  'https://novodid.com/api/v1/orders/{orderId}' \
  -H "Authorization: Bearer $NOVODID_API_TOKEN"

Resposta HTTP 200 (exemplo fictício; o Pix de exemplo não é pagável):

{
  "order": {
    "id": "11111111-1111-4111-8111-111111111111",
    "didId": 1234,
    "quantity": 1,
    "status": "awaiting_payment",
    "paymentMethod": "pix",
    "currency": "BRL",
    "amount": 1499,
    "createdAt": "2026-09-23T15:00:00.000Z",
    "expiresAt": "2026-09-23T15:15:00.000Z",
    "checkoutUrl": null,
    "pix": {
      "copyPaste": "PIX_COPY_AND_PASTE_EXAMPLE",
      "qrCodeDataUrl": "data:image/png;base64,EXAMPLE"
    }
  }
}

GET /api/v1/ordersCopiar link

Listar pedidos da conta — permissão orders:read.

Lista os pedidos da conta por data, do mais recente ao mais antigo. Aceita apenas paginação.

• limit: 1–100, padrão 20; page: 1–9999, padrão 1. Uma página vazia indica o fim da lista.

curl --fail-with-body --max-time 30 -X GET \
  'https://novodid.com/api/v1/orders?limit=20&page=1' \
  -H "Authorization: Bearer $NOVODID_API_TOKEN"

Resposta HTTP 200 (exemplo fictício; o Pix de exemplo não é pagável):

{
  "orders": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "didId": 1234,
      "quantity": 1,
      "status": "awaiting_payment",
      "paymentMethod": "pix",
      "currency": "BRL",
      "amount": 1499,
      "createdAt": "2026-09-23T15:00:00.000Z",
      "expiresAt": "2026-09-23T15:15:00.000Z",
      "checkoutUrl": null,
      "pix": {
        "copyPaste": "PIX_COPY_AND_PASTE_EXAMPLE",
        "qrCodeDataUrl": "data:image/png;base64,EXAMPLE"
      }
    }
  ],
  "page": 1,
  "limit": 20
}

Conectar um agente ao MCPCopiar link

Configure o transporte Streamable HTTP com URL https://mcp.novodid.com/mcp e cabeçalho Authorization: Bearer <seu token>. Crie o token em Desenvolvedores → Tokens com apenas as permissões necessárias. Para o fluxo completo de compra, selecione catalog:read, orders:create e orders:read.

Exemplo de cliente Node.js com o SDK MCP:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'minha-integracao', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
  new URL('https://mcp.novodid.com/mcp'),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.NOVODID_API_TOKEN}` } } }
);
await client.connect(transport);
const result = await client.callTool({
  name: 'search_available_dids',
  arguments: { ddd: '11', kind: 'fixed', limit: 20, page: 1 }
});
console.log(result.structuredContent);
await client.close();

O MCP retorna os mesmos dados e aplica as mesmas permissões da API. No Pix, structuredContent.order.pix.terminalQr contém o QR em texto; copyPaste contém a sequência completa para o aplicativo bancário e qrCodeDataUrl contém uma imagem PNG. O resultado também inclui blocos MCP de imagem e texto. A apresentação depende do cliente MCP.

Problemas comuns na compraCopiar link

• 400 single_did_required: envie um único didId; quantity deve ser o inteiro 1.
• 400 idempotency_key_required: configure o cabeçalho Idempotency-Key na API ou o argumento idempotencyKey no MCP.
• 400 fixed_did_sms_ack_required / mobile_monthly_sms_ack_required: obtenha a confirmação do cliente sobre a condição indicada na cotação.
• 403 insufficient_scope: revise as permissões do token.
• 403 restricted_token: crie um token com permissão de compra e sem seleção restrita a números já contratados.
• 409 checkout_in_progress: o DID escolhido já está reservado por um pedido pendente por até 15 minutos; consulte esse pedido. Outros DIDs não são bloqueados por essa reserva.
• 409 idempotency_conflict: preserve os dados da tentativa original; uma compra diferente exige outra chave.
• 409 checkout_initializing: indica que outra compra da conta ainda está sendo preparada. Aguarde alguns instantes e repita com a mesma Idempotency-Key e o mesmo corpo. Essa espera ocorre somente na criação, não durante os 15 minutos para pagamento.
• 409 order_expired: indica que a resposta de criação chegou após o prazo do pedido. Nenhum QR Code ou link vencido é entregue. Consulte details.orderId antes de iniciar outra compra e não pague instruções antigas.
• 409 order_processing: acompanhe details.orderId; a tentativa original continua em processamento.
• 404 order_not_found: confira o ID e a conta vinculada ao token.
• 503 checkout_unavailable: o resultado não foi confirmado; consulte o pedido informado antes de repetir.
• QR não aparece: use o copia e cola completo ou um cliente que suporte imagens PNG; mantenha fonte monoespaçada no QR de terminal.
• Pedido pago, número ausente: paid indica pagamento confirmado, enquanto a ativação ainda é processada. Acompanhe o mesmo pedido; não crie outra compra.

As rotas de compra não enviam SMS, não configuram encaminhamento e não permitem recuperar histórico de titulares anteriores. Essas funções mantêm seus escopos e critérios próprios.

Guia MCP no painelCopiar link

Acesse Desenvolvedores → MCP para configurar a conexão Streamable HTTP, escolher as permissões do token e seguir o fluxo de pesquisa, cotação, confirmação e pagamento de um número por vez. O guia inclui exemplo Node.js, instruções para Pix e cartão e solução de problemas de conexão, permissões, reservas e exibição do QR Code. A visão geral de Desenvolvedores também oferece um atalho para o guia.

MCP: operações da conta e permissõesCopiar link

O MCP remoto em https://mcp.novodid.com/mcp usa Streamable HTTP e o mesmo token Bearer da API. Oferece 19 ferramentas, incluindo as cinco de compra. A descoberta considera as permissões do token; a execução mantém titularidade, restrição a números, validade, bloqueios, limites e projeção de campos da API.

Os encaminhamentos retornam os destinos somente com forwarding:read. Criação automática de ramal exige as três permissões indicadas; a consulta de credenciais entrega senha ao cliente MCP autorizado. Permissões existentes não são ampliadas por conectar via MCP. Dados de antigos titulares não são acessíveis.

Exemplo de chamada somente de leitura com o cliente do exemplo anterior:

const result = await client.callTool({
  name: 'get_did',
  arguments: { didId: 123 }
});
console.log(result.structuredContent);

Troque 123 por um ID retornado por list_dids. Com dids:read + billing:read a resposta inclui vencimento e situação de pagamento; sem billing:read esses campos ficam nulos. Erros de ferramentas retornam isError=true e um bloco de texto JSON com error.code e error.message. Limites podem incluir error.retryAfterSeconds; respeite o intervalo. Envio de SMS não é idempotente: não repita automaticamente quando não souber se o envio ocorreu.

Antes de alterar encaminhamentos, criar ramal, enviar SMS ou gerar pagamento, confirme a ação e os dados com o cliente. A criação de checkout continua limitada a um DID por compra. As ferramentas não incluem administração de tokens, webhooks, cancelamento de assinatura ou devolução de números, operações que não existem na API pública.

Confirmação do pagamento do pedidoCopiar link

A confirmação vale somente para o pagamento associado ao pedido consultado. Gerar o QR Code ou autorizar a recorrência não significa que o pagamento foi concluído. Se o banco mostrar pagamento concluído e o pedido continuar aguardando, consulte o mesmo pedido e contate o suporte com seu ID; não pague novamente.

Conta em análise de segurançaCopiar link

Quando a conta estiver em análise de segurança, consultas e operações são bloqueadas com HTTP 403 e código account_security_review, inclusive com tokens já emitidos. Não tente contornar a restrição ou repetir automaticamente. O acesso retorna após liberação administrativa; outros limites e restrições continuam aplicáveis. Webhooks pendentes e eventos do período são suprimidos sem reenvio automático. Cobranças, vencimentos e expiração seguem as regras existentes. Acompanhe a análise em https://novodid.com/seguranca/atendimento. Durante o bloqueio, somente o chamado de segurança vinculado à análise permite leitura, respostas e anexos pelo site autenticado; outros chamados e a API pública continuam indisponíveis. O cliente aguarda o primeiro contato da equipe e pode enviar uma única resposta a cada nova mensagem do suporte, incluindo os anexos solicitados.

{"error":{"code":"account_security_review","message":"Estamos realizando verificações de segurança relacionadas à sua conta, às compras e à documentação cadastrada. Durante essa análise, o acesso às funcionalidades e a realização e o recebimento de novas chamadas ficam temporariamente suspensos. Acompanhe a análise e converse com nossa equipe pelo chamado de segurança. Se precisarmos de informações adicionais, faremos a solicitação por lá e avisaremos pelo e-mail cadastrado."}}

Confirmação do telefone e disponibilidadeCopiar link

O campo number contém somente um telefone confirmado para a posse atual. Se essa confirmação estiver indisponível ou inconsistente, o item não aparece na listagem e a consulta por ID retorna 404 did_not_found. Tente consultar novamente mais tarde; se persistir, contate o suporte. O início de acesso ao histórico permanece o da posse atual. A confirmação também é exigida nas operações de encaminhamento, credenciais SIP, chamadas e SMS. Uma indisponibilidade de leitura não altera o contrato financeiro.

HTTP 409 did_number_unavailable: não foi possível confirmar o telefone selecionado antes de criar o pagamento. Consulte o pedido indicado em error.details.orderId e atualize o catálogo antes de uma nova tentativa; não repita uma cobrança sem conferir o pedido anterior.

{
  "error": {
    "code": "did_number_unavailable",
    "message": "Não foi possível confirmar o número selecionado. Atualize a lista e tente novamente.",
    "details": {
      "orderId": "11111111-1111-4111-8111-111111111111"
    }
  }
}