> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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`.

```bash theme={null}
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.

```bash theme={null}
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": "+34612345678",
    "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:

```json theme={null}
{
  "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.