novauth
PreciosDocumentaciónEmpieza gratis
Referencia

Referencia de API

Referencia completa de todos los endpoints de verificación de Novauth. Cada canal comparte el mismo modelo de autenticación y la misma URL base; solo difieren la ruta y el payload.

BASE URLhttps://api.novauth.com/api/v1/connect-hub

Autenticación

Cada solicitud debe incluir dos encabezados. Puedes encontrar tus credenciales en la sección Desarrollador → Claves de API del panel. Las credenciales se almacenan en caché del lado del servidor durante 5 minutos, por lo que las claves recién creadas estarán activas en segundos.

x-api-keyTu clave de API. Trátala como una contraseña: nunca la expongas en código del lado del cliente.
x-account-idTu identificador de cuenta. Se muestra en el panel junto a cada clave de API.
x-request-idID de correlación opcional. Pasa cualquier UUID; se devuelve en las respuestas de error para facilitar el rastreo.

Almacena las credenciales en variables de entorno (BETATEL_API_KEY, BETATEL_ACCOUNT_ID). Nunca las codifiques directamente en los archivos fuente.

Las claves con prefijo sk_test_ son claves de sandbox: nunca interactúan con operadores reales y no generan cargos. Úsalas durante el desarrollo y luego cámbialas por tu clave BTEL_ cuando pases a producción. Modo Sandbox →

Lista blanca de IP

Al crear una clave de API puedes asociar opcionalmente una o más direcciones IP o rangos CIDR. Si se configura una lista blanca de IP, cualquier solicitud proveniente de una IP que no figure en ella será rechazada con 401 Unauthorized, aunque la clave de API sea válida. Esto te permite restringir una clave a la IP de tu servidor para que no pueda usarse si se filtra.

Ejemplo de solicitud autenticada
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"callee": "+14155552671"}'

Verify Call

Inicia una llamada de corta duración que suena y se cuelga. El ID de llamada codifica el OTP; tu SDK móvil lee el número entrante sin que el usuario tenga que contestar.

Enviar un Verify Call
POST/api/v1/connect-hub/call/flash
Cuerpo de la solicitud
calleestringobligatorio
Teléfono del destinatario en formato E.164 (p. ej. +14155552671).
callerstring
ID de llamada en formato E.164. Por defecto se usa el número configurado en la cuenta.
max_ring_timenumber
Duración del tono en segundos antes de colgar automáticamente. Por defecto es un valor aleatorio entre los tiempos mínimo y máximo de tono configurados en la cuenta.
Respuesta — 200 OK
uuidstring (ULID)
Identificador único de la llamada. Guárdalo: es necesario para consultar el CDR y para los informes de webhook.
callerstring
ID de llamada utilizado realmente (puede diferir del solicitado si se usó el valor por defecto).
calleestring
Número del destinatario (eco).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "callee": "+14155552671",
    "caller": "+38761000001",
    "max_ring_time": 5
  }'

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "caller": "+38761000001",
#   "callee": "+14155552671"
# }
Obtener registro detallado de llamada
GET/api/v1/connect-hub/call/flash/:uuid/cdr
Respuesta — 200 OK
hangup_causestring
Motivo de colgado SIP (p. ej. NORMAL_CLEARING, NO_ANSWER, ORIGINATOR_CANCEL).
durationnumber
Duración total de la llamada en segundos (tono + conectado).
billsecnumber
Duración facturada en segundos (desde la respuesta hasta el colgado).
pddnumber
Retardo posterior a la marcación en segundos (tiempo hasta el primer tono).
destination_countrystring
Nombre del país de destino resuelto.
start_stampstring (ISO 8601)
Marca de tiempo UTC de inicio de la llamada.
bash
curl https://api.novauth.com/api/v1/connect-hub/call/flash/01KAK9KATW01A437PSXS5EVDCR/cdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "caller": "+38761000001",
#   "callee": "+14155552671",
#   "hangup_cause": "NORMAL_CLEARING",
#   "duration": 6,
#   "billsec": 0,
#   "pdd": 2,
#   "start_stamp": "2024-06-01T10:30:00.000Z",
#   "destination_country": "United States",
#   "destination_country_code": "US"
# }
Listar registros de llamadas
POST/api/v1/connect-hub/call/flash/cdr

Devuelve una lista paginada de todas las llamadas de tu cuenta. Usa filter para acotar los resultados por cualquier campo del CDR (p. ej. callee, hangup_cause).

Cuerpo de la solicitud
pagenumber
Número de página (mínimo: 1, por defecto: 1).
rows_per_pagenumber
Registros por página (1–100, por defecto: 20).
sort_bystring
Campo por el que ordenar (p. ej. start_stamp, callee).
sort_direction"ASC" | "DESC"
Dirección del ordenamiento.
filterobject
Filtros clave/valor opcionales aplicados a los campos del CDR.
Respuesta — 200 OK
totalnumber
Total de registros que coinciden con el filtro.
total_pagesnumber
Número total de páginas.
has_next_pageboolean
Indica si existe una página siguiente.
has_previous_pageboolean
Indica si existe una página anterior.
listCDR[]
Arreglo de registros detallados de llamada de la página actual.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash/cdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_by": "start_stamp",
    "sort_direction": "DESC"
  }'
Colgar una llamada
DELETE/api/v1/connect-hub/call/flash/:uuid

Finaliza una llamada activa antes de que termine de forma natural. Devuelve 204 No Content en caso de éxito.

bash
# Terminate an active call before it naturally ends
curl -X DELETE https://api.novauth.com/api/v1/connect-hub/call/flash/01KAK9KATW01A437PSXS5EVDCR \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Returns 204 No Content on success

SMS

Entrega un mensaje de texto vía SMPP. Se utiliza habitualmente para enviar un código OTP numérico que el usuario introduce en tu aplicación.

Enviar un SMS
POST/api/v1/connect-hub/sms
Cuerpo de la solicitud
tostringobligatorio
Teléfono del destinatario en formato E.164.
textstringobligatorio
Cuerpo del mensaje. Hasta 4096 caracteres; los mensajes más largos se dividen en partes concatenadas.
fromstring
ID del remitente (alfanumérico o número de teléfono). Por defecto se usa el remitente configurado en la cuenta.
Respuesta — 200 OK
messageIdstring (UUID)
Identificador único del mensaje. Guárdalo: es necesario para consultar el SDR y para los informes de webhook.
fromstring
ID del remitente utilizado.
tostring
Número del destinatario (eco).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/sms \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "text": "Your verification code is 482910. Valid for 5 minutes.",
    "from": "Novauth"
  }'

# Response:
# {
#   "messageId": "0a62face-6d15-11f0-962f-d89d6729654c",
#   "from": "Novauth",
#   "to": "14155552671"
# }
Obtener estado del mensaje
GET/api/v1/connect-hub/sms/:messageId/sdr

Recupera el estado de entrega de un mensaje enviado. El estado se actualiza de forma asíncrona a medida que llegan los informes de entrega del operador (DLR).

Respuesta — valores de estado
deliveredEntrega confirmada en el dispositivo.
sentEnviado al operador; en espera del DLR.
failedEntrega fallida (número inválido, bloqueado).
undeliveredEl operador lo aceptó pero la entrega no está confirmada.
bash
curl https://api.novauth.com/api/v1/connect-hub/sms/0a62face-6d15-11f0-962f-d89d6729654c/sdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "...",
#   "messageId": "0a62face-6d15-11f0-962f-d89d6729654c",
#   "from": "Novauth",
#   "to": "+14155552671",
#   "status": "delivered",
#   "timestamp": "2024-06-01T10:30:00.000Z"
# }
Listar mensajes
POST/api/v1/connect-hub/sms/sdr

Devuelve una lista paginada de todos los mensajes enviados. Acepta el mismo cuerpo de paginación que otros endpoints de listado (page, rows_per_page, sort_by, filter).

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/sms/sdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

OTP de Telegram

Envía un OTP numérico a través de la Gateway API oficial de Telegram. Admite comprobaciones de alcanzabilidad, validación de código del lado del servidor y revocación con reembolso automático.

Enviar OTP de Telegram
POST/api/v1/connect-hub/telegram
Cuerpo de la solicitud
tostringobligatorio
Teléfono del destinatario en formato E.164.
codestringobligatorio
Código OTP a entregar (4–8 dígitos).
ttlnumber
Validez del código en segundos (30–3600). Por defecto: 300.
sender_usernamestring
Nombre de usuario del canal de Telegram verificado. Omítelo para usar el valor por defecto de la cuenta.
callback_urlstring
Anulación de webhook por solicitud. Telegram Gateway enviará eventos de estado directamente a esta URL mediante POST.
Respuesta — 200 OK
uuidstring (ULID)
ID de correlación de Novauth. Úsalo para los informes de webhook.
request_idstring
ID de solicitud de Telegram Gateway. Úsalo para comprobaciones de estado y revocación.
statusstring
Estado de entrega normalizado (sent, delivered, …).
request_costnumber
Cargo por esta solicitud en EUR.
remaining_balancenumber
Saldo de la cuenta tras el cargo.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "code": "482910",
    "ttl": 300
  }'

# Response:
# {
#   "uuid": "01KNV9CWW9ZEYVDFBJ1N7M1DVR",
#   "request_id": "tg_req_abc123",
#   "to": "14155552671",
#   "status": "sent",
#   "request_cost": 0.05,
#   "remaining_balance": 49.95
# }
Comprobar alcanzabilidad
POST/api/v1/connect-hub/telegram/check-send-ability

Verifica si el número tiene una cuenta de Telegram antes de enviar. Si is_refunded es true, el usuario no tiene cuenta de Telegram; el costo de la comprobación se reembolsa y debes recurrir a SMS o Verify Call.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-send-ability \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155552671"}'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "phone_number": "14155552671",
#   "request_cost": 0.01,
#   "is_refunded": false,
#   "remaining_balance": 49.99,
#   "delivery_status": { "status": "sent", "updated_at": 1713350400 }
# }
Comprobar estado de verificación
POST/api/v1/connect-hub/telegram/check-verification-status

Consulta el resultado de la entrada del código para un request_id dado. Opcionalmente, pasa el code introducido por el usuario para la validación del lado del servidor.

Valores de verification_status
code_validEl usuario introdujo el código correcto.
code_invalidEl usuario introdujo un código incorrecto.
code_max_attempts_exceededDemasiados intentos fallidos.
expiredEl TTL del código expiró antes de que se introdujera.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-verification-status \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "tg_req_abc123",
    "code": "482910"
  }'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "verification_status": {
#     "status": "code_valid",
#     "updated_at": 1713350400
#   }
# }
Revocar verificación
POST/api/v1/connect-hub/telegram/revoke-verification

Cancela una solicitud OTP activa antes de que el usuario la complete. Si el mensaje aún no ha sido leído, is_refunded será true y el cargo se devuelve a tu saldo.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/revoke-verification \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "tg_req_abc123"}'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "is_refunded": true,
#   "remaining_balance": 50.0
# }
Obtener registro de entrega
GET/api/v1/connect-hub/telegram/:uuid/tdr

Obtiene el registro de entrega completo de Telegram (TDR) para un uuid dado (el ID de correlación de Novauth devuelto por el endpoint de envío). Incluye el estado de entrega, el estado de verificación, el costo y el país.

bash
curl https://api.novauth.com/api/v1/connect-hub/telegram/01KNV9CWW9ZEYVDFBJ1N7M1DVR/tdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response includes full TDR:
# {
#   "uuid": "01KNV9CWW9ZEYVDFBJ1N7M1DVR",
#   "to": "+14155552671",
#   "status": "DELIVERED",
#   "delivery_status": "delivered",
#   "verification_status": "code_valid",
#   "request_cost": 0.05,
#   "country": "United States",
#   "created_at": "2024-06-01T10:30:00.000Z"
# }
Listar registros de entrega
POST/api/v1/connect-hub/telegram/tdr

Devuelve una lista paginada de todos los registros de entrega de Telegram. Filtra por <code>verification_status</code>, <code>delivery_status</code> o cualquier otro campo del TDR.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/tdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

WhatsApp

Envía un mensaje OTP a través de la API de WhatsApp Business. El usuario lee el código en la conversación de WhatsApp y lo introduce en tu aplicación.

Enviar OTP de WhatsApp
POST/api/v1/connect-hub/whatsapp/otp
Cuerpo de la solicitud
tostringobligatorio
Teléfono del destinatario en formato E.164.
textstringobligatorio
Cuerpo del mensaje. Incluye el código OTP y una indicación de expiración.
Respuesta — 200 OK
uuidstring (ULID)
Identificador único del mensaje. Guárdalo: es necesario para los informes de webhook.
tostring
Número del destinatario (eco).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/otp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "text": "Your verification code is 482910. Valid for 5 minutes."
  }'

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "to": "+14155552671"
# }

Tras el envío, informa el resultado de verificación del usuario mediante POST /whatsapp/webhook. Consulta la referencia de Webhooks para más detalles.

Obtener registro de entrega
GET/api/v1/connect-hub/whatsapp/:uuid/wdr

Obtiene el registro de entrega de WhatsApp (WDR) para un uuid devuelto por el endpoint de envío.

bash
curl https://api.novauth.com/api/v1/connect-hub/whatsapp/01KAK9KATW01A437PSXS5EVDCR/wdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "to": "+14155552671",
#   "status": "DELIVERED",
#   "created_at": "2024-06-01T10:30:00.000Z"
# }
Listar registros de entrega
POST/api/v1/connect-hub/whatsapp/wdr

Devuelve una lista paginada de todos los registros de entrega de WhatsApp. Admite el mismo cuerpo <code>page</code>, <code>rows_per_page</code>, <code>filter</code> que todos los demás endpoints de listado.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/wdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

Códigos de error

Todas las respuestas de error siguen el mismo envelope JSON. El campo error contiene una cadena legible por máquina; proporciona tu x-request-id al soporte cuando reportes incidencias.

EstadoCódigoDescripción
400BAD_REQUESTCuerpo de solicitud inválido: campo obligatorio faltante, formato incorrecto o número de teléfono inválido.
401UNAUTHORIZEDEncabezados x-api-key / x-account-id faltantes o inválidos.
402PAYMENT_REQUIREDSaldo de cuenta insuficiente. Recarga tu cuenta para continuar.
403FORBIDDENLa clave de API existe pero no tiene permiso para esta operación.
404NOT_FOUNDEl UUID o recurso solicitado no existe.
409CONFLICTSolicitud duplicada o estado conflictivo (p. ej. revocar una solicitud ya expirada).
480TEMPORARY_UNAVAILABLEGateway temporalmente inaccesible. Reintenta con retroceso exponencial.
486BUSY_HERE(Verify Call) El destinatario está ocupado o la llamada fue rechazada por la red.
500INTERNAL_SERVER_ERRORError inesperado del servidor. Contacta a soporte con tu x-request-id.
503SERVICE_UNAVAILABLEGateway desconectado o servicio en mantenimiento. Consulta la página de estado.
603DECLINE(Verify Call) El destinatario rechazó explícitamente la llamada.

Para una lista completa de códigos de error con pasos de remediación sugeridos, consulta la guía de gestión de errores.