{ "openapi": "3.1.0", "info": { "title": "NovoDID Public API", "version": "1.5.0", "description": "API pública v1 para integrações de clientes NovoDID com automações, n8n e agentes. Acesso automático para clientes PF e PJ, sem solicitação manual. Contas removidas e bloqueios administrativos permanecem impedidos. Limites compartilhados por conta: leitura 60/min, escrita 10/min, SMS 5/min e 100/dia UTC. Criar ou rotacionar tokens não reinicia limites. Corpo JSON até 16384 bytes; SMS até 1600 caracteres. Histórico limitado à posse atual confirmada; sem marco confiável, SMS permanece indisponível. Tokens permitem restrição por posse do número, validade e cotas individuais adicionais à conta.\n\nMCP: https://mcp.novodid.com/mcp (Streamable HTTP, Bearer token). All public REST operations are also available as MCP tools with the same scopes and account restrictions. Guide: https://novodid.com/desenvolvedores/mcp" }, "servers": [ { "url": "https://novodid.com" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Forwarding": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "enum": [ "phone", "sip", "ip", null ] }, "destination": { "type": [ "string", "null" ] } }, "required": [ "type", "destination" ] }, "Did": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "type": { "type": "string", "enum": [ "fixo", "movel", "unknown" ] }, "status": { "type": "string" }, "active": { "type": "boolean" }, "cycle": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "autoRenew": { "type": [ "boolean", "null" ] }, "payment": { "type": [ "object", "null" ], "properties": { "status": { "type": "string" }, "label": { "type": "string" }, "paidUntil": { "type": [ "string", "null" ], "format": "date-time" }, "method": { "type": [ "string", "null" ], "enum": [ "pix", "card", null ] } }, "required": [ "status", "label", "paidUntil", "method" ] }, "sms": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "canSend": { "type": "boolean" }, "accessStartedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "canSend", "accessStartedAt" ] }, "forwarding": { "anyOf": [ { "$ref": "#/components/schemas/Forwarding" }, { "type": "null" } ], "description": "Null sem forwarding:read." } }, "required": [ "id", "number", "type", "status", "active", "cycle", "expiresAt", "autoRenew", "payment", "sms", "forwarding" ] }, "SmsMessage": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "receivedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "direction", "from", "to", "text", "status", "receivedAt" ] }, "SipCredentials": { "type": "object", "description": "Segredo sensível: não registrar nem armazenar em cache.", "properties": { "username": { "type": "string" }, "password": { "type": "string", "maxLength": 255 }, "server": { "type": "string" }, "port": { "type": "integer" }, "transport": { "const": "udp" }, "uri": { "type": "string" } }, "required": [ "username", "password", "server", "port", "transport", "uri" ] }, "DidPurchaseInput": { "type": "object", "additionalProperties": false, "required": [ "didId", "cycle", "paymentMethod" ], "properties": { "didId": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "quantity": { "type": "integer", "const": 1, "default": 1 }, "cycle": { "type": "string", "enum": [ "monthly", "semiannually", "yearly" ] }, "paymentMethod": { "type": "string", "enum": [ "pix", "card" ] }, "couponCode": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,80}$" }, "fixedDidSmsAcknowledged": { "type": "boolean" }, "mobileMonthlySmsAcknowledged": { "type": "boolean", "description": "Aceite explícito quando acknowledgements.mobileMonthlySms.required=true na cotação, inclusive para ciclos móveis semestrais ou anuais sem SMS. Não presumir consentimento." } } }, "PurchaseOrder": { "type": "object", "required": [ "id", "didId", "quantity", "status", "paymentMethod", "currency", "amount", "createdAt", "expiresAt", "checkoutUrl", "pix" ], "properties": { "id": { "type": "string", "format": "uuid" }, "didId": { "type": "integer" }, "quantity": { "type": "integer", "const": 1 }, "status": { "type": "string", "enum": [ "creating", "awaiting_payment", "paid", "active", "expired", "cancelled", "refunded", "review_required", "rejected" ] }, "paymentMethod": { "type": "string", "enum": [ "pix", "card" ] }, "currency": { "type": "string" }, "amount": { "type": [ "integer", "null" ], "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "checkoutUrl": { "type": [ "string", "null" ], "format": "uri" }, "pix": { "type": [ "object", "null" ], "required": [ "copyPaste", "qrCodeDataUrl" ], "properties": { "copyPaste": { "type": "string" }, "qrCodeDataUrl": { "type": "string" } } } } }, "PurchaseOrderResponse": { "type": "object", "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/PurchaseOrder" } } }, "PurchaseOrderList": { "type": "object", "required": [ "orders", "page", "limit" ], "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseOrder" } }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "DidCatalog": { "type": "object", "required": [ "dids", "page", "limit", "total" ], "properties": { "dids": { "type": "array", "items": { "type": "object", "required": [ "id", "number", "ddd", "kind", "city", "state", "currency", "baseMonthlyAmount" ], "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "ddd": { "type": "string" }, "kind": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "currency": { "type": "string" }, "baseMonthlyAmount": { "type": "integer" } } } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" } } }, "DidPurchaseQuote": { "type": "object", "required": [ "did", "quantity", "paymentMethod", "pricing", "recurring", "reserved", "acknowledgements" ], "properties": { "did": { "type": "object", "required": [ "id", "number", "kind", "smsEnabled" ], "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "kind": { "type": "string" }, "smsEnabled": { "type": "boolean" } } }, "quantity": { "type": "integer" }, "paymentMethod": { "type": "string" }, "pricing": { "type": "object", "required": [ "currency", "baseMonthlyAmount", "cycle", "cycleMonths", "subtotalAmount", "totalDiscountPercent", "discountedAmount", "cardFeeAmount", "totalAmount" ], "properties": { "currency": { "type": "string" }, "baseMonthlyAmount": { "type": "integer" }, "cycle": { "type": "string" }, "cycleMonths": { "type": "integer" }, "subtotalAmount": { "type": "integer" }, "totalDiscountPercent": { "type": "integer" }, "discountedAmount": { "type": "integer" }, "cardFeeAmount": { "type": "integer" }, "totalAmount": { "type": "integer" } } }, "recurring": { "type": "boolean" }, "reserved": { "type": "boolean" }, "acknowledgements": { "type": "object", "required": [ "fixedDidSms", "mobileMonthlySms" ], "properties": { "fixedDidSms": { "type": "object", "required": [ "required", "message" ], "properties": { "required": { "type": "boolean" }, "message": { "type": "string" } } }, "mobileMonthlySms": { "type": "object", "required": [ "required", "message" ], "properties": { "required": { "type": "boolean" }, "message": { "type": [ "string", "null" ] } } } } } } } }, "responses": { "Error401": { "description": "Token ausente, inválido, expirado ou revogado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error400": { "description": "Entrada inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error403": { "description": "Permissão, acesso da conta ou SMS não liberado. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "securityReview": { "summary": "Conta em análise de segurança", "value": { "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." } } } } } } }, "Error404": { "description": "Recurso fora da posse ativa da conta ou inexistente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error409": { "description": "Estado do recurso mudou ou saldo necessário", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error429": { "description": "Limite excedido; respeite Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error502": { "description": "Falha temporária ao executar a operação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error503": { "description": "Serviço temporariamente indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error413": { "description": "Corpo maior que 16384 bytes" }, "Error408": { "description": "Tempo de leitura excedido" } } }, "paths": { "/api/v1/me": { "get": { "summary": "Consulta a conta autenticada", "responses": { "200": { "description": "Conta autenticada" }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scopes": [], "description": "Qualquer token válido. Nome e e-mail somente com account:read; sem o escopo, os campos são omitidos." } }, "/api/v1/dids": { "get": { "summary": "Lista DIDs da conta", "responses": { "200": { "description": "Lista de DIDs", "content": { "application/json": { "schema": { "type": "object", "properties": { "dids": { "type": "array", "items": { "$ref": "#/components/schemas/Did" } } }, "required": [ "dids" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scopes": [ "dids:read" ], "description": "Respeita seleção de números por posse. Sem billing:read, payment/cycle/expiresAt/autoRenew são null; sem forwarding:read, forwarding é null. 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." } }, "/api/v1/dids/{didId}": { "get": { "summary": "Consulta detalhes de um DID", "parameters": [ { "name": "didId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "Detalhes do DID", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "$ref": "#/components/schemas/Did" } }, "required": [ "did" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scopes": [ "dids:read" ], "description": "Respeita seleção de números por posse. Sem billing:read, payment/cycle/expiresAt/autoRenew são null; sem forwarding:read, forwarding é null. 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." } }, "/api/v1/forwardings": { "get": { "summary": "Lista encaminhamentos", "responses": { "200": { "description": "Lista de encaminhamentos" }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scopes": [ "forwarding:read" ] } }, "/api/v1/dids/{didId}/forwarding": { "get": { "summary": "Consulta encaminhamento de um DID", "parameters": [ { "name": "didId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "Encaminhamento atual" }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scopes": [ "forwarding:read" ] }, "patch": { "summary": "Altera encaminhamento de um DID", "parameters": [ { "name": "didId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "phone" }, "destination": { "type": "string", "description": "Número no formato 55 + DDD + número", "maxLength": 32 }, "destinationNumber": { "type": "string", "description": "Número no formato 55 + DDD + número", "maxLength": 32 } }, "required": [ "type" ], "anyOf": [ { "required": [ "destination" ] }, { "required": [ "destinationNumber" ] } ] }, { "type": "object", "properties": { "type": { "const": "sip" }, "sipAccountId": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "required": [ "type", "sipAccountId" ] }, { "type": "object", "properties": { "type": { "const": "ip" }, "clientIp": { "type": "string", "maxLength": 45, "description": "Endereço IPv4 ou IPv6 público literal; redes privadas e reservadas não são aceitas" }, "clientPort": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "type", "clientIp", "clientPort" ] }, { "type": "object", "properties": { "type": { "const": "sip" } }, "required": [ "type" ], "not": { "required": [ "sipAccountId" ] }, "description": "Cria/reutiliza o ramal próprio, configura encaminhamento e devolve sipCredentials. Exige forwarding:write + sip:create + sip:credentials:read." } ] } } } }, "responses": { "200": { "description": "Encaminhamento atualizado; sipCredentials somente no modo SIP automático. Cache-Control: no-store." }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "408": { "$ref": "#/components/responses/Error408" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scopes": [], "x-required-scopes-by-type": { "phone": [ "forwarding:phone" ], "sip": [ "forwarding:write" ], "ip": [ "forwarding:write" ] }, "description": "Telefone exige forwarding:phone; SIP/IP exige forwarding:write (alternativas conforme o tipo). Sem forwarding:read, forwarding na resposta é null. Sem sipAccountId, type=sip cria/reutiliza o ramal próprio e retorna sipCredentials; exige também sip:create e sip:credentials:read. Senhas nunca são herdadas automaticamente por tokens legados.", "x-required-scopes-sip-automatic": [ "forwarding:write", "sip:create", "sip:credentials:read" ] }, "delete": { "summary": "Remove encaminhamento de um DID", "parameters": [ { "name": "didId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "Encaminhamento removido" }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scopes": [ "forwarding:delete" ], "description": "Exige forwarding:delete. Sem forwarding:read, forwarding na resposta é null." } }, "/api/v1/calls": { "get": { "summary": "Lista chamadas recebidas", "parameters": [ { "name": "didId", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, { "name": "did", "in": "query", "schema": { "type": "string", "maxLength": 16, "pattern": "^\\+?\\d{10,15}$" } }, { "name": "startDate", "in": "query", "schema": { "type": "string", "maxLength": 40 } }, { "name": "endDate", "in": "query", "schema": { "type": "string", "maxLength": 40 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } } ], "responses": { "200": { "description": "Lista de chamadas" }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scopes": [ "calls:read" ] } }, "/api/v1/sms/messages": { "get": { "summary": "Lista mensagens SMS", "parameters": [ { "name": "didId", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, { "name": "did", "in": "query", "schema": { "type": "string", "maxLength": 16, "pattern": "^\\+?\\d{10,15}$" } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Lista de SMS" }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scopes": [ "sms:read" ] }, "post": { "summary": "Envia SMS", "description": "Aceita somente resposta a um SMS de entrada desse destino para o DID desde o início do acesso SMS da posse atual. Saída anterior, outro contato, posse anterior e falha de consulta não autorizam. Não há exceção por conta. newConversation em sucesso é false.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "maxLength": 16, "pattern": "^\\+?\\d{10,15}$" }, "to": { "type": "string", "maxLength": 16, "pattern": "^\\+?\\d{10,15}$" }, "text": { "type": "string", "minLength": 1, "maxLength": 1600 }, "didId": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "required": [ "from", "to", "text" ] } } } }, "responses": { "201": { "description": "SMS enviado" }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "408": { "$ref": "#/components/responses/Error408" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-required-scopes": [ "sms:send" ] } }, "/api/v1/dids/{didId}/sip-credentials": { "get": { "summary": "Consulta credenciais do ramal próprio com encaminhamento ativo", "x-required-scopes": [ "sip:credentials:read" ], "parameters": [ { "name": "didId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "Credenciais sensíveis; Cache-Control: no-store", "content": { "application/json": { "schema": { "type": "object", "properties": { "didId": { "type": "integer" }, "sipCredentials": { "$ref": "#/components/schemas/SipCredentials" } }, "required": [ "didId", "sipCredentials" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/catalog/dids": { "get": { "summary": "Consultar números à venda", "description": "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.\n\nddd: 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.\nbaseMonthlyAmount é o preço mensal de referência. O valor final do ciclo, descontos e taxa do cartão aparecem na cotação.", "tags": [ "Purchases" ], "x-required-scopes": [ "catalog:read" ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "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 }, "schema": { "$ref": "#/components/schemas/DidCatalog" } } } }, "400": { "description": "Dados inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Token inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Permissão ou conta indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pedido não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflito, requisito não atendido ou pedido em processamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Corpo acima do limite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Serviço temporariamente indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 9999, "default": 1 } }, { "name": "ddd", "in": "query", "schema": { "type": "string", "pattern": "^[1-9][1-9]$" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "fixed", "mobile" ] } } ] } }, "/api/v1/orders/quote": { "post": { "summary": "Cotar a compra de um número", "description": "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.\n\ncycle: monthly, semiannually ou yearly. paymentMethod: pix ou card. quantity, quando informado, deve ser 1.\ncouponCode é opcional, com até 80 letras, números, hífen ou sublinhado.\nAs 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.\n\nEm 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.", "tags": [ "Purchases" ], "x-required-scopes": [ "catalog:read" ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "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 } } }, "schema": { "$ref": "#/components/schemas/DidPurchaseQuote" } } } }, "400": { "description": "Dados inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Token inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Permissão ou conta indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pedido não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflito, requisito não atendido ou pedido em processamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Corpo acima do limite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Serviço temporariamente indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DidPurchaseInput" }, "example": { "didId": 1234, "quantity": 1, "cycle": "monthly", "paymentMethod": "pix", "fixedDidSmsAcknowledged": true } } } } } }, "/api/v1/orders": { "post": { "summary": "Criar pagamento de um número", "description": "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.\n\nIdempotency-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.\nA 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.\nFixos 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.\nPara 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.\nA 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.\n\nEm 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.\n\n409 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.\n\n409 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. 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.", "tags": [ "Purchases" ], "x-required-scopes": [ "orders:create" ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "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" } } }, "schema": { "$ref": "#/components/schemas/PurchaseOrderResponse" } } } }, "400": { "description": "Dados inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Token inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Permissão ou conta indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pedido não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Estado incompatível com a compra, incluindo idempotency_conflict, checkout_in_progress e did_number_unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "checkout_initializing": { "summary": "Outra compra ainda está sendo criada", "value": { "error": { "code": "checkout_initializing", "message": "Outra compra está sendo preparada. Tente novamente em instantes." } } }, "order_expired": { "summary": "Criação concluída após o prazo do pedido", "value": { "error": { "code": "order_expired", "message": "O prazo deste pedido terminou. Consulte o pedido antes de tentar novamente.", "details": { "orderId": "11111111-1111-4111-8111-111111111111" } } } }, "numberUnavailable": { "value": { "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" } } } } } } } }, "413": { "description": "Corpo acima do limite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Serviço temporariamente indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DidPurchaseInput" }, "example": { "didId": 1234, "quantity": 1, "cycle": "monthly", "paymentMethod": "pix", "fixedDidSmsAcknowledged": true } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ] }, "get": { "summary": "Listar pedidos da conta", "description": "Lista os pedidos da conta por data, do mais recente ao mais antigo. Aceita apenas paginação.\n\nlimit: 1–100, padrão 20; page: 1–9999, padrão 1. Uma página vazia indica o fim da lista.", "tags": [ "Purchases" ], "x-required-scopes": [ "orders:read" ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "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 }, "schema": { "$ref": "#/components/schemas/PurchaseOrderList" } } } }, "400": { "description": "Dados inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Token inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Permissão ou conta indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pedido não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflito, requisito não atendido ou pedido em processamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Corpo acima do limite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Serviço temporariamente indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 9999, "default": 1 } } ] } }, "/api/v1/orders/{orderId}": { "get": { "summary": "Consultar um pedido", "description": "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.\n\nEstados: creating (criando), awaiting_payment (aguardando pagamento), paid (pago, aguardando ativação), active (ativação realizada), expired, cancelled, refunded, rejected ou review_required.\npaid 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.\n\nA 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.", "tags": [ "Purchases" ], "x-required-scopes": [ "orders:read" ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "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" } } }, "schema": { "$ref": "#/components/schemas/PurchaseOrderResponse" } } } }, "400": { "description": "Dados inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Token inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Permissão ou conta indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pedido não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflito, requisito não atendido ou pedido em processamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Corpo acima do limite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Serviço temporariamente indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } } }, "x-mcp": { "url": "https://mcp.novodid.com/mcp", "transport": "streamable-http", "authentication": "Bearer", "tools": [ "get_account", "list_dids", "get_did", "list_forwardings", "get_did_forwarding", "set_did_phone_forwarding", "set_did_ip_forwarding", "set_did_sip_forwarding", "create_did_sip_forwarding", "delete_did_forwarding", "get_did_sip_credentials", "list_calls", "list_sms_messages", "send_sms", "search_available_dids", "quote_did_purchase", "create_did_checkout", "get_did_order", "list_did_orders" ] }, "externalDocs": { "description": "Documentação pública NovoDID", "url": "https://docs.novodid.com/" } }