Desarrolladores
Todo lo que hace la consola, la API también lo hace.
Una API pública versionada, eventos en tiempo real y webhooks firmados. No es una capa de marketing por encima de un producto cerrado: la consola de administración de Konvoice consume exactamente estos mismos puntos de acceso.
Principios
Cuatro compromisos que cuentan más que la lista de puntos de acceso.
Versionada
/api/v1/ es estable. Una ruptura da lugar a una versión mayor nueva, nunca a una modificación silenciosa. La versión anterior se sigue sirviendo doce meses como mínimo.
Trazable
Cada petición lleva un identificador de correlación que usted vuelve a encontrar en nuestros registros y en su registro de auditoría. Un ticket de soporte empieza por ese número.
Idempotente
Toda escritura acepta una clave de idempotencia. Reintentar una petición tras un retraso de red no crea un segundo usuario ni una segunda llamada.
Compartimentada
Un token pertenece a una empresa y lleva alcances explícitos. No puede leer nada más allá, y un alcance de lectura no se convierte nunca en escritura.
REST
Crear un usuario con su extensión.
Una sola petición crea la persona, su extensión, sus credenciales de equipo y dispara el aprovisionamiento de su teléfono.
POST /api/v1/users HTTP/1.1
Host: api.konvoice.io
Authorization: Bearer kv_live_…
Idempotency-Key: 4f1c-9a02-b7
{
"display_name": "Amadou Diallo",
"email": "[email protected]",
"site_id": "site_lyon",
"extension": "203",
"role": "agent",
"devices": [
{ "type": "deskphone", "mac": "805e0c1a2b3c" },
{ "type": "mobile" },
{ "type": "web" }
],
"teams": ["support"]
}
Antes de la producción
Números que responden mal, a propósito.
El peor entorno de pruebas de una integración telefónica es un compañero al que se llama veinte veces. El entorno de pruebas ofrece números cuyo comportamiento es predecible — descolgado, sin respuesta, ocupado, buzón, fallo del operador — y sus pruebas dejan de depender de nadie.
- Escenarios deterministas — un número por resultado, siempre el mismo.
- Webhooks de verdad — firmados, reintentables, con el mismo formato que en producción.
- Un identificador de correlación en cada petición, que el soporte encuentra en nuestros registros.
- Ninguna llamada facturada — el entorno de pruebas no consume nada.
Eventos
Lo que pasa, en el momento en que pasa.
Los eventos se difunden por webhook firmado y por flujo en tiempo real. Ambos transportan la misma carga útil, con la misma garantía de entrega al menos una vez.
| Evento | Cuándo | Uso habitual |
|---|---|---|
call.ringing | Una llamada empieza a sonar | Mostrar la ficha del cliente antes de descolgar |
call.answered | Alguien ha descolgado | Arrancar un cronómetro, abrir un ticket |
call.ended | La llamada ha terminado | Escribir la actividad en el CRM |
call.missed | Nadie ha respondido | Crear una tarea de devolución |
recording.ready | La grabación está disponible | Archivar en su propio almacenamiento |
transcript.ready | La transcripción y el resumen están producidos | Alimentar su herramienta de análisis |
voicemail.received | Se ha dejado un mensaje de voz | Avisar a un equipo |
device.registered | Un teléfono se registra | Supervisar el parque |
site.link_lost | Una sede pasa a autonomía local | Alertar a su supervisión de red |
site.link_restored | El enlace de una sede se restablece | Cerrar la alerta, comprobar la cola de sincronización |
fraud.route_blocked | El motor antifraude ha cortado una ruta | Despertar a alguien |
Webhooks
Firmados, con marca de tiempo, reintentados.
Verifique la firma antes de tratar la carga útil. La marca de tiempo protege del reenvío, la clave de idempotencia protege de los duplicados cuando reintentamos.
- Firma HMAC-SHA256 sobre el cuerpo en bruto, con un secreto por punto de entrega.
- Reintentos con espera creciente durante 24 horas, y luego una cola de fallos consultable.
- Rechace una marca de tiempo de más de cinco minutos: es un reenvío.
- Responda 2xx rápido y trate en segundo plano; cortamos a los 10 segundos.
POST /su-endpoint HTTP/1.1
Konvoice-Signature: t=1743158400,
v1=8c1f…d40a
Konvoice-Event-Id: evt_01HZ…
Konvoice-Delivery: 1
{
"type": "call.ended",
"created_at": "2026-03-28T09:20:00Z",
"tenant_id": "ten_8f3c",
"data": {
"call_id": "call_01HZ…",
"direction": "inbound",
"from": "+34917XXXXXX",
"to": "+34912XXXXXX",
"extension": "203",
"duration_s": 214,
"disposition": "answered",
"site_id": "site_lyon",
"handled_locally": true
}
}Nuestras propias pantallas sólo consumen esta API. Es la única garantía seria de que seguirá siendo completa.
El día que le falte algo, nuestra aplicación se para también
Entorno de pruebas
Desarrolle sin llamar a clientes de verdad.
Un entorno separado, con sus propios tokens, sus números de prueba y un juego de llamadas simulables bajo demanda.
Números de prueba
Números que responden con un escenario predecible: descolgado, sin respuesta, ocupado, mensaje de voz, fallo del operador. Sus pruebas automatizadas dejan de depender de un compañero.
Eventos disparables
Emita cualquier evento de la lista desde la consola, incluida la pérdida de enlace de una sede, para comprobar que su integración reacciona correctamente.
Registro de entregas
Cada webhook enviado, su respuesta, su latencia y sus reintentos. Reintentar manualmente una entrega se hace con un botón.
Preguntas de desarrollo
¿Hay límites de tasa?
¿Facilitan una especificación OpenAPI?
¿Se pueden controlar las llamadas en tiempo real?
¿Está disponible la API en una sede sin conexión?
Un acceso de pruebas, gratis.
Díganos qué quiere construir. Abrimos un entorno con números de prueba y seguimos localizables durante su integración.
Sin compromiso. No pedimos ningún número de tarjeta.