Claves de API y permisos

La API REST de Ringhum permite que tus propios sistemas trabajen con tu espacio de trabajo: listar llamadas y transcripciones, crear asistentes, reservar citas, gestionar contactos, realizar llamadas salientes y mucho más. Cada solicitud se autentica con una clave de API que pertenece a un espacio de trabajo. Este artículo explica cómo crear claves y las convenciones que comparten todos los endpoints. La referencia completa de endpoints está en /docs.

Quién puede gestionar las claves

La API está disponible en todos los planes. Lo que una clave puede hacer sigue estando limitado por tu plan: por ejemplo, crear un asistente por encima del límite de tu plan devuelve un error.

Crear una clave de API

1. Abre Desarrolladores en el menú lateral.
2. En la tarjeta Claves de API, haz clic en Crear clave.
3. Introduce un Nombre de la clave que indique dónde se usa, por ejemplo "Servidor de producción".
4. En Permisos, marca lectura, escritura o ambas.
5. Haz clic en Crear clave.
6. Copia la clave del recuadro verde y guárdala en un lugar seguro, como el almacén de secretos de tu servidor. Haz clic en Listo.

Importante: La clave se muestra solo una vez. Ringhum guarda únicamente una huella de ella, así que no puede volver a mostrarse. Si la pierdes, crea una clave nueva y revoca la antigua.

Las claves empiezan por ck_live_. La tabla Claves de API muestra el nombre de cada clave, sus primeros caracteres, sus permisos, cuándo se usó por última vez y si está Activa o Revocada.

Permisos

Toda clave puede llamar a los endpoints que solo leen. Los endpoints que crean, cambian o eliminan algo necesitan el permiso de escritura. Algunos ejemplos son realizar una llamada, enviar un mensaje, reservar una cita o actualizar un asistente. La referencia en /docs marca estos endpoints. Una clave sin escritura recibe un error 403 en ellos.

Da a cada sistema el mínimo acceso que necesite. Un panel de informes solo necesita lectura.

Revocar una clave

1. En Desarrolladores, busca la clave en la tabla Claves de API.
2. Haz clic en Revocar y confirma.

Las solicitudes que usen esa clave fallarán de inmediato con 401. Las claves revocadas permanecen en la lista, marcadas como Revocada, para que puedas ver su historial. Una clave no se puede editar: para cambiar sus permisos, crea una clave nueva y revoca la antigua.

Hacer solicitudes

• URL base: https://ringhum.com/api/v1
• Autenticación: envía la clave como token Bearer: Authorization: Bearer ck_live_…
• Formato: JSON de entrada y salida. Envía Content-Type: application/json con el cuerpo.
• Las horas son ISO 8601 en UTC. Los números de teléfono son E.164, por ejemplo +14155550132. Los ids son enteros.
• Las actualizaciones usan PATCH solo con los campos que quieras cambiar.
• Cada respuesta lleva una cabecera X-Request-Id. Inclúyela cuando contactes con soporte.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

Para comprobar a qué espacio de trabajo pertenece una clave, llama a GET /me.

Respuestas y paginación

Un solo objeto se devuelve como {"data": {…}}. Las listas paginadas se devuelven con un objeto meta:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Usa page y per_page para recorrer los resultados. per_page es 25 por defecto y puede ser como máximo 100.

Errores

Todo fallo tiene la misma forma, con un type estable que puedes comprobar en tu código:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Límites de peticiones

Puedes hacer 120 solicitudes por minuto. Las respuestas incluyen las cabeceras X-RateLimit-Limit y X-RateLimit-Remaining. Cuando superas el límite recibes un 429 con una cabecera Retry-After que indica los segundos que debes esperar.

Consejo: No hagas polling para consultar los resultados de las llamadas. Añade un webhook para call.ended y Ringhum te enviará el resumen y la transcripción cuando termine la llamada. Consulta Webhooks.

Preguntas frecuentes

¿Hay una especificación legible por máquina? Sí. La descripción OpenAPI 3.1 está en /api/v1/openapi.json y no necesita clave. Puedes generar un cliente a partir de ella.

¿Deja de funcionar una clave si la persona que la creó se va? No. Las claves pertenecen al espacio de trabajo y siguen funcionando hasta que se revocan. Revoca las claves en las que ya no confíes, sobre todo cuando alguien con acceso se marcha.

¿Puedo usar la API desde una página web? No. Cualquiera que abra la página podría leer la clave. Llama a la API desde tu servidor.