Guía de API y webhooks

API pública de NovoDID · contrato 1.5.0. La edición principal es inglés de Estados Unidos; portugués de Brasil y español de Colombia cubren el mismo contrato. El idioma no cambia campos, permisos, enums ni respuestas; los mensajes de error pueden seguir en portugués.

Qué puede hacerCopiar enlace

Consultar sus números activos (DIDs), revisar y configurar desvíos a teléfono/extensión SIP/IP pública, crear o reutilizar una extensión al configurar el desvío, consultar sus credenciales, consultar llamadas entrantes y leer/enviar SMS habilitados. La liberación de números, los cambios de suscripción, la creación de tokens y la administración de webhooks se realizan desde el panel. Los tokens y webhooks se gestionan desde el panel autenticado.

Primeros pasosCopiar enlace

1. En el panel NovoDID, abra Desenvolvedores → Tokens y cree un token con los permisos y números necesarios. El acceso es automático para personas naturales y jurídicas; los bloqueos administrativos siguen vigentes.
2. Copie el token al crearlo (se muestra una sola vez) y guárdelo como valor local/privado de entorno en Postman, novodid_token. No lo guarde en valores compartidos, ejemplos, exportaciones ni Git.
3. Configure baseUrl para su entorno; el valor inicial es https://novodid.com. Ejecute GET /me y luego GET /dids con dids:read. Copie el id numérico autorizado en didId; el número telefónico no es el id.
4. Los filtros opcionales están desactivados inicialmente. Active los necesarios y diligencie los destinos antes de escribir. Revise los ejemplos de respuesta.
5. Ejecute las escrituras de forma individual: cambian desvíos reales o envían SMS reales. La colección no es un entorno de pruebas y no se debe ejecutar completa en producción. Los ejemplos son ficticios, sin datos de clientes.

Autenticación y acceso a númerosCopiar enlace

Todas las solicitudes heredan Authorization: Bearer {{novodid_token}}, mediante HTTPS. No existe permiso comodín. Un token puede incluir todos los números actuales/futuros o entre 1 y 100 asignaciones actuales seleccionadas. Siempre se valida la titularidad activa: una asignación anterior no da acceso a SMS o llamadas de otro cliente. Volver a adquirir un número no reactiva la selección anterior; cree un token con la asignación actual. Se rechazan tokens vencidos/revocados, cuentas bloqueadas y recursos fuera de la selección.

Nombre del token: 3–80 caracteres; máximo 10 tokens activos sin vencer. Vigencia: 7, 30, 90, 365 días o sin vencimiento; el panel sugiere 90 días. Rotar invalida el token anterior inmediatamente y conserva permisos, selección, vencimiento y consumo de cuotas. Los tokens antiguos pueden conservar acceso amplio; revíselos y aplique permisos mínimos. Revocar un token de API no invalida credenciales SIP ya consultadas.

PermisosCopiar enlace

Límites y erroresCopiar enlace

Cuotas predeterminadas por cuenta, compartidas por todos los tokens: consultas 60/min, escrituras de desvío 10/min, SMS 5/min y 100/día UTC. Las cuotas individuales más estrictas se aplican adicionalmente; no aumentan la capacidad de la cuenta. Crear/rotar tokens no reinicia el consumo. Los intentos rechazados pueden consumir cuota. Revise X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset y Retry-After; SMS también incluye X-RateLimit-Sms-Day-*. Ante 429, respete la espera y use reintentos limitados con espera progresiva y variación aleatoria.

Cuerpo JSON: máximo 16 KiB y 16 campos de primer nivel. Query string: máximo 2048 caracteres; se rechazan parámetros desconocidos o repetidos. IDs: enteros entre 1 y 2147483647, sin decimales ni notación exponencial. Las respuestas con datos del cliente usan Cache-Control: no-store.

Error: {"error":{"code":"...","message":"...","details":{}}}; details es opcional. 400 entrada inválida; 401 token ausente/inválido/vencido; 403 permiso, bloqueo o política SMS; 404 recurso no disponible para este token/titularidad; 408 timeout del cuerpo; 409 estado incompatible o saldo insuficiente; 413 cuerpo excesivo; 429 cuota; 502/503 indisponibilidad temporal. Corrija autenticación/validación antes de reintentar. Un 404 no demuestra que el número no exista globalmente. No repita un SMS automáticamente tras timeout: puede haberse enviado y no existe un contrato de llave de idempotencia.

Convenciones de respuestaCopiar enlace

Tipos DID: fixo, movel o unknown. Medio de pago: pix, card o null. Sin billing:read, cycle/expiresAt/autoRenew/payment son null; sin forwarding:read se oculta el destino. Null puede indicar falta de permiso o disponibilidad, no necesariamente desactivación. La capacidad SMS es independiente del permiso: los números fijos no admiten SMS y los móviles deben cumplir las condiciones comerciales. Use las fechas y zonas horarias ISO devueltas, sin asumir su hora local.

Recetas de integraciónCopiar enlace

Panel de consulta: dids:read, opcionalmente billing:read y forwarding:read, respetando cuotas compartidas. Bandeja SMS y respuesta: sms:read + sms:send; responda con from=su DID y to=remitente recibido. Softphone: forwarding:write + sip:create + sip:credentials:read; PATCH type=sip sin sipAccountId y configure servidor/usuario/contraseña/puerto/transporte devueltos. Agregue forwarding:read para consultar el destino. Desvío a teléfono: forwarding:phone y saldo suficiente; tarifa de BRL 0,20/min (reales brasileños, no pesos colombianos), desde el inicio del cobro y sin minutos gratuitos.

Webhooks (configuración en el panel)Copiar enlace

Abra Desenvolvedores → Webhooks y registre nombre (3–80 caracteres), URL HTTPS pública (hasta 2048), eventos y filtro opcional de hasta 50 DIDs propios. Filtro vacío incluye todos los números habilitados. No se aceptan credenciales en la URL, hosts privados/locales ni redirecciones. Eventos: sms.received, sms.sent, call.received, call.missed, payment.approved, did.expiring. No hay CRUD público v1 de webhooks en esta colección; su configuración no hereda permisos del token.

El sobre contiene id, type, version, createdAt y data, con did/sms/call/payment según el evento. Las pruebas tienen data.test=true. Conserve el cuerpo original exacto y valide X-Novodid-Signature: sha256= + HMAC-SHA256(secreto, X-Novodid-Timestamp + "." + cuerpoOriginal). Compare en tiempo constante, rechace timestamps antiguos (recomendado ±5 minutos) y elimine duplicados por id del evento. X-Novodid-Event y X-Novodid-Delivery identifican el contexto.

Guarde/encole el evento validado y responda 2xx rápidamente. Plazo total de 8 segundos, sin redirecciones, captura limitada de respuesta y hasta cinco intentos con espera progresiva. Fallas repetidas pueden pausar el endpoint. Revise registros de entrega y corrija conectividad, TLS, firma/cuerpo y latencia antes de reactivar. No asuma orden, entrega exactamente una vez ni reproducción del historial. Se revalida la titularidad antes de entregar; liberar un DID no transfiere su historial al siguiente cliente.

ReferenciasCopiar enlace

Panel · OpenAPI · Guía detallada.

Ejemplos de códigoCopiar enlace

Ejemplos de consulta. Configure NOVODID_API_TOKEN en su entorno local; no incluya el secreto en el código.

cURLCopiar enlace

curl --fail-with-body --max-time 15 \
  https://novodid.com/api/v1/dids \
  -H "Authorization: Bearer $NOVODID_API_TOKEN" \
  -H "Accept: application/json"

Node.js (fetch)Copiar enlace

const token = process.env.NOVODID_API_TOKEN;
if (!token) throw new Error("NOVODID_API_TOKEN is required");
const response = await fetch("https://novodid.com/api/v1/dids", {
  headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
  signal: AbortSignal.timeout(15000),
  redirect: "error"
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { dids } = await response.json();
console.log({ count: dids.length });

Python (requests)Copiar enlace

import os
import requests

response = requests.get(
    "https://novodid.com/api/v1/dids",
    headers={"Authorization": "Bearer " + os.environ["NOVODID_API_TOKEN"]},
    timeout=15,
    allow_redirects=False,
)
if response.status_code != 200:
    raise RuntimeError(f"HTTP {response.status_code}")
dids = response.json()["dids"]
print({"count": len(dids)})

Referencia interactivaCopiar enlace

La referencia NovoDID ofrece la misma cobertura de rutas, variantes de desvío separadas, permisos acumulativos y ejemplos en ocho lenguajes. HTTP 500 indica un error interno.

Compra de DIDs y MCPCopiar enlace

Permisos: catalog:read consulta el inventario y las cotizaciones; orders:create crea pedidos; orders:read consulta y lista los pedidos de su cuenta. Los tokens existentes no reciben estos permisos automáticamente. Para comprar, el token debe permitir todos los números, sin limitarse a asignaciones existentes. La cuenta debe estar activa, autorizada para comprar, con la verificación requerida completa y capacidad disponible. Se aplican las mismas reglas de móviles, ciclos y SMS del panel.

Cada pedido incluye exactamente un DID. quantity se puede omitir o enviar como el entero 1; no se aceptan listas ni compras por lote. La reserva pendiente se aplica solo al DID elegido y dura como máximo 15 minutos desde la creación del pedido. Durante ese período se pueden comprar otros DIDs, respetando los límites de la cuenta. Se admiten ciclos mensuales, semestrales y anuales. Los precios se calculan en el servidor, en centavos de BRL. El catálogo muestra el precio mensual de referencia; la cotización incluye el ciclo, los descuentos y el cargo por tarjeta. Cotizar no reserva el número.

Presente al cliente el número, ciclo, valor recurrente y condiciones de SMS. Solo después de su aceptación envíe fixedDidSmsAcknowledged=true para números fijos o mobileMonthlySmsAcknowledged=true cuando lo exija la cotización. El agente no debe asumir el consentimiento.

POST /api/v1/orders exige el encabezado Idempotency-Key, de 16–128 letras, números, guiones o guiones bajos. Genere una clave por nueva intención de compra y reutilice la misma clave y cuerpo al repetir. Cambiar los datos con la misma clave devuelve 409 idempotency_conflict. Después de un timeout, consulte el pedido o repita la misma clave; no genere otra para evadir el error. La respuesta puede incluir details.orderId.

Pix Automático devuelve pix.copyPaste y pix.qrCodeDataUrl. Revise el pago y la autorización recurrente en la aplicación bancaria. Con tarjeta se devuelve checkoutUrl para que el cliente complete el pago. Crear el pedido no paga ni activa el DID. El regreso del navegador no confirma el pago.

Estados: creating, awaiting_payment, paid (pagado, pendiente de activación), active (activación realizada), expired, cancelled, refunded, rejected y review_required. Consulte el pedido y /api/v1/dids para comprobar la posesión activa actual. Las instrucciones de pago solo aparecen en awaiting_payment. La reserva pendiente vence en un máximo de 15 minutos, incluso si falla la creación o el pedido requiere revisión. Esto no confirma una cancelación externa inmediata ni un reembolso. No pague instrucciones vencidas; un pago confirmado después del vencimiento se revisa sin sustituir otra reserva o asignación. Los pagos ya confirmados y los números activos siguen protegidos. En review_required, contacte a soporte con el ID.

MCP remoto: https://mcp.novodid.com/mcp, transporte Streamable HTTP y el mismo token Bearer de NovoDID. Herramientas: search_available_dids, quote_did_purchase, create_did_checkout, get_did_order y list_did_orders. Solo se enumeran herramientas autorizadas. create_did_checkout recibe idempotencyKey como argumento. Pix incluye texto para copiar y pegar, imagen PNG y terminalQr para fuente monoespaciada. Si el cliente no muestra imágenes, use el texto exacto de copia y pega. El cliente MCP debe admitir la configuración del token Bearer.

Herramientas MCP de tu cuentaCopiar enlace

El MCP remoto ofrece todas las operaciones de la API pública mediante 19 herramientas, incluidas las cinco de compra. Conéctate a https://mcp.novodid.com/mcp con Streamable HTTP y el mismo token Bearer. El descubrimiento respeta los permisos; la ejecución conserva la titularidad actual, las restricciones del token, las cuotas y los permisos de campos. billing:read permite consultar pagos y vencimientos; account:read muestra nombre/correo; forwarding:read muestra destinos. Crear una extensión requiere los tres permisos indicados. El desvío a teléfono requiere saldo y cuesta BRL 0,20/minuto, sin minutos gratuitos. El envío de SMS no es idempotente: no repitas automáticamente un envío con resultado incierto. Confirma las modificaciones con el cliente. Esta conexión no usa OAuth. Guía: https://novodid.com/desenvolvedores/mcp

Durante las ofertas temporales de números móviles, los ciclos disponibles y la inclusión de SMS pueden variar. Consulta siempre una cotización: did.smsEnabled indica si el plan incluye SMS, y acknowledgements.mobileMonthlySms.required indica si debes enviar mobileMonthlySmsAcknowledged=true después del consentimiento del cliente. A pesar del nombre, estos campos se aplican a cualquier ciclo móvil sin SMS. La cotización no garantiza la oferta; las condiciones se validan de nuevo al crear el pago. Los pagos emitidos durante la oferta conservan sus condiciones hasta el vencimiento del propio pago. Al finalizar la oferta, las nuevas compras siguen las condiciones vigentes; las suscripciones completadas conservan su ciclo y la condición de SMS en las renovaciones mientras sigan vigentes. Esto no garantiza el precio. Se mantienen los requisitos de cuenta, verificación, límites, disponibilidad y un número por pedido.

409 checkout_initializing indica que otra compra de la cuenta todavía se está preparando. Espere unos instantes y repita con la misma Idempotency-Key y el mismo cuerpo. Esta espera solo aplica a la creación, no al plazo de 15 minutos para pagar.

409 order_expired indica que la respuesta de creación llegó después del plazo del pedido. No se devuelve un código QR ni un enlace vencido. Consulte details.orderId antes de iniciar otra compra y no pague instrucciones anteriores.

Cuenta en revisión de seguridadCopiar enlace

Cuando una cuenta está en revisión de seguridad, las consultas y operaciones se bloquean con HTTP 403 y código account_security_review, incluso con tokens emitidos previamente. No intente eludir la restricción ni repetir automáticamente. El acceso se restablece después de la liberación administrativa; se mantienen los demás límites y restricciones. Los webhooks pendientes y los eventos del período se suprimen sin reenvío automático. La facturación y los vencimientos siguen las reglas existentes. Siga la revisión en https://novodid.com/seguranca/atendimento. Solo el ticket vinculado a la revisión permite lectura, respuestas y archivos adjuntos en el sitio autenticado. Los demás tickets y la API pública continúan bloqueados. El cliente debe esperar el primer mensaje del equipo y puede enviar una sola respuesta por cada nuevo mensaje del soporte, incluidos los archivos solicitados.

La confirmación del teléfono y la posesión actual también son obligatorias para desvíos, credenciales SIP, llamadas y SMS. La indisponibilidad de lectura no modifica el contrato de facturación.

Documentación pública: https://docs.novodid.com/ MCP: https://docs.novodid.com/mcp/