API y MCP de Delega

Autenticación

Cada solicitud lleva una llave de API de tu cuenta. Las llaves se crean en el panel, en Mi cuenta → Llaves de API; solo se muestran completas una vez, así que guárdala en un lugar seguro (por ejemplo, una variable de entorno o un gestor de secretos). Si una llave se expone, revócala desde el mismo lugar y crea otra.

Authorization: Bearer <tu llave>
Accept: application/json

Formato de respuesta

Todas las respuestas JSON tienen la misma forma. Si salió bien, data trae el resultado y error es null:

{
  "data": { "id": "01JAB3QK6Z8W4N2P7R5T9V1X3C", "estado": "listo" },
  "error": null
}

Si algo falló, data es null y error trae message (en español, listo para mostrar), code (estable, para tu lógica) y, en errores de validación, campos con el detalle por campo:

{
  "data": null,
  "error": {
    "message": "Falta el nombre de la empresa a la que se llama.",
    "code": "validacion",
    "campos": {
      "empresa": ["Falta el nombre de la empresa a la que se llama."]
    }
  }
}

Límites

Además, cada cuenta tiene un máximo de llamadas simultáneas y puede tener un límite de minutos al mes. Si pasas un límite de solicitudes recibes un 429; si llegas al de llamadas o minutos, llamar responde 422 con el motivo.

Flujo recomendado

1. 1

   GET /tipos

   Consulta los tipos de trámite y qué datos pide cada uno.

2. 2

   POST /tramites

   Crea el trámite con los datos que tienes.

3. 3

   PATCH /tramites/{id}/datos

   Si faltan no está vacío, pide esos datos al usuario y complétalos. Nunca los inventes.

4. 4

   POST /tramites/{id}/llamar

   Lanza la llamada.

5. 5

   GET /tramites/{id}

   Consulta cada pocos segundos el estado y la pregunta_pendiente.

6. 6

   POST /tramites/{id}/responder

   Si el estado es esperando_respuesta, contesta la pregunta cuanto antes.

7. 7

   GET /tramites/{id}/transcripcion · /grabacion

   Al terminar, lee resumen, folio y siguiente_paso, y descarga la transcripción y la grabación.

Tipos de trámite

Devuelve los tipos de trámite disponibles con los datos que pide cada uno (campos, con requerido), las voces disponibles para tu cuenta, la voz por defecto (voz_default) y el nombre que se usa por defecto en a_nombre_de (a_nombre_de_default). Úsalo antes de crear un trámite para saber qué pedirle al usuario.

{
  "data": {
    "tipos": [
      {
        "tipo": "generico",
        "nombre": "Trámite general",
        "descripcion": "Cualquier trámite por teléfono: aclaraciones, cambios, cancelaciones, citas.",
        "empresa": null,
        "telefono": null,
        "objetivo": null,
        "campos": [
          { "clave": "titular_nombre", "etiqueta": "Nombre completo del titular", "tipo": "texto", "requerido": true }
        ],
        "requiere_alguno": []
      }
    ],
    "voces": [
      { "id": "a1B2c3D4e5F6g7H8", "nombre": "Voz natural" }
    ],
    "voz_default": "a1B2c3D4e5F6g7H8",
    "a_nombre_de_default": "Ana López"
  },
  "error": null
}

Indicadores

Conteos de los trámites de tu cuenta: en curso, esperando tu respuesta, con datos faltantes, completados, creados hoy y total, más la actividad de los últimos 7 días.

{
  "data": {
    "en_curso": 1,
    "esperando_respuesta": 0,
    "faltan_datos": 2,
    "completados": 14,
    "hoy": 3,
    "total": 19,
    "semana": [
      { "dia": "2026-10-12", "total": 2, "completados": 2 },
      { "dia": "2026-10-13", "total": 4, "completados": 3 }
    ]
  },
  "error": null
}

Listar trámites

Trámites de tu cuenta, del más reciente al más antiguo, paginados.

{
  "data": {
    "tramites": [
      {
        "id": "01JAB3QK6Z8W4N2P7R5T9V1X3C",
        "tipo": "generico",
        "empresa": "Telefonía Ejemplo",
        "estado": "completado",
        "folio": "PR5582",
        "resumen": "Se actualizó el correo de contacto de la línea.",
        "faltan": [],
        "creado": "2026-10-18T10:15:02-06:00"
      }
    ],
    "pagina": 1,
    "paginas": 1,
    "total": 1
  },
  "error": null
}

Crear un trámite

Crea un trámite. Lo que no mandes se toma del tipo (empresa, teléfono y objetivo). Los datos que no correspondan a un campo del tipo se guardan como datos libres. La respuesta trae faltan: si no está vacío, el estado es faltan_datos y hay que completarlo antes de llamar. Delega nunca completa un dato del titular por su cuenta. Responde 201.

{
  "tipo": "generico",
  "empresa": "Telefonía Ejemplo",
  "telefono": "8001234567",
  "objetivo": "Actualizar el correo de contacto de la línea y obtener el folio del cambio.",
  "a_nombre_de": "Ana López",
  "datos": {
    "titular_nombre": "Ana López",
    "linea": "5512345678",
    "correo_nuevo": "ana@ejemplo.com"
  }
}

{
  "data": {
    "id": "01JAB3QK6Z8W4N2P7R5T9V1X3C",
    "tipo": "generico",
    "tipo_nombre": "Trámite general",
    "empresa": "Telefonía Ejemplo",
    "telefono_destino": "8001234567",
    "objetivo": "Actualizar el correo de contacto de la línea y obtener el folio del cambio.",
    "a_nombre_de": "Ana López",
    "estado": "listo",
    "pregunta_pendiente": null,
    "resumen": null,
    "folio": null,
    "siguiente_paso": null,
    "faltan": [],
    "origen": "mcp",
    "creado": "2026-10-18T10:15:02-06:00",
    "finalizado": null,
    "datos": {
      "titular_nombre": "Ana López",
      "linea": "5512345678",
      "correo_nuevo": "ana@ejemplo.com"
    },
    "notas": null,
    "voz": "a1B2c3D4e5F6g7H8",
    "hallazgos": [],
    "campos": [
      { "clave": "titular_nombre", "etiqueta": "Nombre completo del titular", "tipo": "texto", "requerido": true }
    ],
    "llamada": null,
    "intentos": 0
  },
  "error": null
}

Consultar un trámite

Detalle completo: estado, pregunta_pendiente (lo que el asistente te está preguntando en vivo), resumen, folio, siguiente_paso, los datos (los sensibles se muestran enmascarados) y la última llamada con su transcripción en llamada.turnos. Consúltalo cada pocos segundos mientras la llamada esté en curso.

{
  "data": {
    "id": "01JAB3QK6Z8W4N2P7R5T9V1X3C",
    "empresa": "Telefonía Ejemplo",
    "estado": "completado",
    "pregunta_pendiente": null,
    "resumen": "Se actualizó el correo de contacto de la línea a ana@ejemplo.com.",
    "folio": "PR5582",
    "siguiente_paso": "Ninguno: el cambio quedó registrado.",
    "faltan": [],
    "llamada": {
      "id": 812,
      "estado": "completed",
      "duracion_seg": 214,
      "motivo_falla": null,
      "tiene_grabacion": true,
      "turnos": [
        { "role": "dtmf", "text": "2", "at": "10:16:11" },
        { "role": "human", "text": "Buenas tardes, ¿en qué le puedo ayudar?", "at": "10:18:40" },
        { "role": "ai", "text": "Buenas tardes. Soy el asistente de Ana López y llamo de su parte…", "at": "10:18:44" }
      ]
    },
    "intentos": 1
  },
  "error": null
}

Completar o corregir datos

Agrega o corrige datos. Un valor vacío borra ese dato. Devuelve el trámite con lo que todavía falta. No se puede mientras haya una llamada en curso; si el trámite ya había terminado, se reabre para otro intento.

{
  "datos": {
    "linea": "5512345678",
    "rfc_titular": ""
  }
}

{
  "data": {
    "id": "01JAB3QK6Z8W4N2P7R5T9V1X3C",
    "estado": "faltan_datos",
    "faltan": [
      { "clave": "titular_nombre", "etiqueta": "Nombre completo del titular", "ayuda": null }
    ]
  },
  "error": null
}

Llamar

Marca a la empresa y el asistente hace el trámite: navega el menú, espera en línea y habla con el agente. Solo funciona si no faltan datos. Antes de marcar se revisa que tu cuenta esté activa, que te queden minutos en el mes y que no hayas llegado al máximo de llamadas simultáneas. Límite: 10 solicitudes por minuto.

{
  "data": {
    "id": "01JAB3QK6Z8W4N2P7R5T9V1X3C",
    "estado": "llamando",
    "pregunta_pendiente": null,
    "intentos": 1
  },
  "error": null
}

Responder al asistente

Contesta la pregunta que el asistente hizo en vivo (estado esperando_respuesta) o dale una indicación durante la llamada. Hazlo rápido: el agente está esperando. Si no tienes el dato, dilo, por ejemplo «no lo tenemos, pide que lo envíen por correo».

{
  "respuesta": "Los últimos 4 dígitos de la tarjeta son 4321."
}

{
  "data": { "enviada": true },
  "error": null
}

Marcar teclas

Presiona teclas en la llamada en curso, por si hace falta ayudar al asistente en un menú. Solo se aceptan 0-9, * y #.

{
  "digitos": "2"
}

{
  "data": { "marcado": true },
  "error": null
}

Colgar

Cuelga la llamada en curso. Responde 409 sin_llamada_activa si no hay llamada.

{
  "data": { "colgada": true },
  "error": null
}

Cancelar

Cancela el trámite; si hay una llamada en curso, la cuelga. Devuelve el trámite con estado cancelado.

{
  "data": {
    "id": "01JAB3QK6Z8W4N2P7R5T9V1X3C",
    "estado": "cancelado",
    "finalizado": "2026-10-18T10:20:31-06:00"
  },
  "error": null
}

Transcripción

Transcripción completa de todas las llamadas del trámite. En cada turno, role es ai (el asistente), human (la empresa) o dtmf (teclas marcadas).

{
  "data": {
    "tramite_id": "01JAB3QK6Z8W4N2P7R5T9V1X3C",
    "llamadas": [
      {
        "id": 812,
        "inicio": "2026-10-18T10:16:02-06:00",
        "duracion_seg": 214,
        "estado": "completed",
        "turnos": [
          { "role": "dtmf", "text": "2", "at": "10:16:11" },
          { "role": "human", "text": "¿Me dicta el correo nuevo?", "at": "10:19:02" },
          { "role": "ai", "text": "Es ana@ejemplo.com. Se lo deletreo…", "at": "10:19:05" }
        ]
      }
    ]
  },
  "error": null
}

Grabación

Audio de la última llamada con grabación, como audio/mpeg (mp3). Solo se entrega con tu llave o tu sesión; nunca hay un enlace público. Responde 404 sin_grabacion si todavía no hay grabación.

Respuesta: el archivo de audio (Content-Type: audio/mpeg). Guárdalo directo a un archivo, por ejemplo con curl -o tramite.mp3.

Tu cuenta

Datos de tu cuenta y el consumo del mes en minutos: minutos usados, límite mensual, minutos restantes, llamadas en curso e historial de los últimos meses. Un límite null significa sin límite.

{
  "data": {
    "cuenta": {
      "id": 3,
      "nombre": "Despacho Ejemplo",
      "activa": true,
      "limite_minutos_mes": 600,
      "limite_llamadas_simultaneas": 2,
      "voz_default": "a1B2c3D4e5F6g7H8",
      "a_nombre_de_default": "Ana López"
    },
    "consumo": {
      "periodo": "2026-10",
      "minutos": 48,
      "llamadas": 11,
      "limite_minutos": 600,
      "minutos_restantes": 552,
      "llamadas_activas": 0,
      "historial": [
        { "periodo": "2026-10", "minutos": 48, "llamadas": 11 }
      ]
    },
    "voces": [
      { "id": "a1B2c3D4e5F6g7H8", "nombre": "Voz natural" }
    ]
  },
  "error": null
}

Consumo por llamada

Minutos por llamada en un mes (hasta 500 llamadas, de la más reciente a la más antigua).

{
  "data": {
    "periodo": "2026-10",
    "minutos": 48,
    "llamadas": 11,
    "detalle": [
      {
        "fecha": "2026-10-18T10:19:36-06:00",
        "tramite_id": "01JAB3QK6Z8W4N2P7R5T9V1X3C",
        "empresa": "Telefonía Ejemplo",
        "folio": "PR5582",
        "segundos": 214,
        "minutos": 4
      }
    ]
  },
  "error": null
}

Errores

Usa siempre el código HTTP para decidir qué hacer. Todos los errores vienen como {"data": null, "error": {"message": "…", "code": "…"}}.

Consumo

El consumo se mide por llamada, en minutos, redondeando cada llamada hacia arriba: una llamada de 61 segundos cuenta como 2 minutos. Solo cuenta el tiempo de llamadas conectadas; si no contestan, no cuenta tiempo.

Consulta los minutos del mes y tu límite con GET /cuenta y el detalle por llamada con GET /cuenta/consumo.

Herramientas

Configuración

El servidor lee estas variables de entorno:

DELEGA_URL

URL de la plataforma. Por defecto https://delega.overcloud.us.

DELEGA_TOKEN_FILE

Ruta a un archivo con tu llave, con permisos 600. Es la opción recomendada. Por defecto ~/.config/delega/token.

DELEGA_TOKEN

La llave directamente. Si está definida, tiene prioridad sobre el archivo.

Primero guarda la llave en su archivo:

# Guarda tu llave en un archivo que solo tú puedas leer
mkdir -p ~/.config/delega
printf '%s' '<tu llave>' > ~/.config/delega/token
chmod 600 ~/.config/delega/token

Después agrega el servidor a la configuración de tu cliente MCP. El formato más común es este (cambia la ruta por la del paquete que te entregamos):

{
  "mcpServers": {
    "delega": {
      "command": "node",
      "args": ["/ruta/a/delega-mcp/index.js"],
      "env": {
        "DELEGA_URL": "https://delega.overcloud.us",
        "DELEGA_TOKEN_FILE": "/Users/tu-usuario/.config/delega/token"
      }
    }
  }
}

Reinicia tu cliente para que cargue las herramientas. Pídele, por ejemplo: «Llama a mi compañía de teléfono para actualizar el correo de contacto de mi línea».