APIs: Llamadas salientes

Contratos reales de MarIA Core para campañas outbound con cuestionarios

Esta página documenta los endpoints de MarIA Core usados para campañas de llamadas salientes con cuestionarios.

​

Autenticación

Todos los endpoints requieren X-Api-Key. En la referencia interactiva sustituye your-prod-endpoint por el host real antes de probar una petición.

curl -X GET "https://{your-prod-endpoint}/api/v1/questionnaires" \
  -H "accept: application/json" \
  -H "X-Api-Key: <tu-api-key>"

​

Cuestionarios

Método	Ruta	Uso
GET	/api/v1/questionnaires	Lista cuestionarios. Acepta `?status=draft	active	archived`.
POST	/api/v1/questionnaires	Crea un cuestionario.
GET	/api/v1/questionnaires/{id}	Obtiene un cuestionario por UUID.
PUT	/api/v1/questionnaires/{id}	Actualiza título, preguntas, webhooks, scheduling o metadata.
DELETE	/api/v1/questionnaires/{id}	Elimina el cuestionario. Devuelve 204 sin body.
GET	/api/v1/questionnaires/external/{externalId}	Obtiene un cuestionario por identificador externo.

Ejemplo de creación:

curl -X POST "https://{your-prod-endpoint}/api/v1/questionnaires" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <tu-api-key>" \
  -d '{
    "title": { "es": "Seguimiento postconsulta" },
    "defaultLanguage": "es",
    "externalId": "postconsulta-2026",
    "questions": [
      {
        "questionText": { "es": "¿Cómo se encuentra hoy?" },
        "questionType": "text",
        "isRequired": true,
        "displayOrder": 1,
        "metadata": {}
      }
    ]
  }'

Respuesta 201 abreviada:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "postconsulta-2026",
    "title": { "es": "Seguimiento postconsulta" },
    "defaultLanguage": "es",
    "status": "draft",
    "version": 1,
    "questions": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440000",
        "questionnaireId": "550e8400-e29b-41d4-a716-446655440000",
        "questionText": { "es": "¿Cómo se encuentra hoy?" },
        "questionType": "text",
        "isRequired": true,
        "displayOrder": 1,
        "metadata": {}
      }
    ]
  }
}

​

Webhooks

Método	Ruta	Uso
GET	/api/v1/webhooks	Lista webhooks configurados.
POST	/api/v1/webhooks	Crea un webhook.
PUT	/api/v1/webhooks/{webhookId}	Actualiza un webhook.
DELETE	/api/v1/webhooks/{webhookId}	Elimina un webhook. Devuelve 204 sin body.

Tipos válidos: generic, whatsapp_incoming, whatsapp_status, voice_incoming, voice_status, questionnaire_completion, voice_shutdown, voice_tool_call.

curl -X POST "https://{your-prod-endpoint}/api/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <tu-api-key>" \
  -d '{
    "name": "Resultados outbound",
    "url": "https://tu-backend.com/webhooks/maria",
    "webhookType": "questionnaire_completion",
    "auth": { "type": "bearer", "token": "<token>" },
    "params": { "timeout": 30 }
  }'

La respuesta devuelve success: true y el webhook en data; si hay auth.token, aparece enmascarado como ***.

​

Llamadas salientes

Para crear una llamada ligada a un cuestionario externo usa POST /api/v1/calls/external-questionnaire. Usa schedulingWindow si quieres acotar fecha u horario.

curl -X POST "https://{your-prod-endpoint}/api/v1/calls/external-questionnaire" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <tu-api-key>" \
  -d '{
    "name": "Ana",
    "surname1": "García",
    "phone": "[phone]",
    "questionnaireId": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "case-123",
    "schedulingWindow": {
      "date": "2026-05-12",
      "startTime": "10:00",
      "endTime": "12:00"
    },
    "metadata": { "source": "ehr" }
  }'

Respuesta 201 abreviada:

{
  "success": true,
  "data": {
    "callId": "660e8400-e29b-41d4-a716-446655440000",
    "call": {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "callDirection": "outbound",
      "status": "pending",
      "schedulingWindow": {
        "date": "2026-05-12",
        "startTime": "10:00",
        "endTime": "12:00"
      }
    }
  }
}

​

Consulta de llamadas

Para integraciones externas usa las rutas de lectura:

Método	Ruta	Uso
GET	/api/v1/calls?page=1&limit=100	Lista llamadas paginadas.
GET	/api/v1/calls/{id}	Obtiene una llamada por ID.

El listado devuelve success, data y pagination. El detalle devuelve success y data.call. La llamada incluye id, endUserId, questionnaireInstanceId, callDirection, status, timestamps, schedulingWindow, transcripción, eventos y resultado cuando existe.