> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inagent.inconcertcx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API del marcador

> Crea, configura y opera lotes de marcación automática mediante la API de Inagent.

La API del **marcador de Inagent** permite administrar el ciclo de vida completo de los lotes, cargar y gestionar contactos, mantener una lista de direcciones bloqueadas y consultar operaciones asíncronas.

## URL base

```text theme={null}
https://api.backend.inconcertcc.com/autocontact/api/v1
```

## Autenticación

Todas las peticiones requieren una API key en el header `apikey`. La misma credencial permite operar los lotes de la cuenta a los que tenga acceso.

```http theme={null}
apikey: TU_API_KEY
```

El servicio obtiene la cuenta a partir de esa credencial. Si un lote no pertenece a la cuenta, responde `404`, igual que si no existiera.

<Warning>
  Trata la API key como una credencial. No la incluyas en repositorios, código cliente, logs ni ejemplos compartidos.
</Warning>

## Operaciones asíncronas

La carga de contactos, el arranque y la eliminación de lotes responden `202 Accepted`. La respuesta confirma que el trabajo fue aceptado, pero no que haya terminado.

Estas respuestas incluyen un `operationId` y un header `Location`. Consulta el resultado mediante `GET /batches/operations/{operationId}`.

<Note>
  `POST /batches` es una excepción: devuelve directamente `batchId`, `status: "created"` y `source`, sin `operationId` ni header `Location`.
</Note>

| Tipo de operación      | Tiempo de retención                      |
| ---------------------- | ---------------------------------------- |
| Carga de contactos     | 6 horas                                  |
| Ciclo de vida del lote | 1 hora y, una vez finalizada, 10 minutos |

<Info>
  Si una operación ya expiró, el endpoint de consulta devuelve `404`. Para una importación de lote también puedes revisar los campos permanentes `uploadStatus` y `totalContacts` del propio lote.
</Info>

## Reintentos seguros

Las operaciones de escritura aceptan el header opcional `Idempotency-Key`. Genera un valor único —por ejemplo, un UUID— antes del primer intento y reutilízalo únicamente al repetir esa misma petición con el mismo body.

```http theme={null}
Idempotency-Key: 6e789e2c-5ce7-4f15-982a-92a2bdfbe293
```

La clave debe contener entre 1 y 255 caracteres ASCII imprimibles y se conserva durante 24 horas.

| Header de respuesta            | Significado                                                                                    |
| ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `Idempotency-Replayed: true`   | Se devolvió la respuesta original sin volver a procesar la petición.                           |
| `Retry-After`                  | Segundos que debes esperar ante `409 IDEMPOTENCY_KEY_IN_FLIGHT`.                               |
| `Idempotency-Status: bypassed` | La petición se procesó sin protección porque el servicio de idempotencia no estaba disponible. |

Las respuestas `5xx` no se almacenan. Si recibes `Idempotency-Status: bypassed` y pierdes la respuesta, verifica el estado del recurso antes de reintentar.

## Crear un lote desde la API

Envía `POST /batches` con `source: "api"`, el nombre, el canal y `duplicateStrategy`. Este último campo es obligatorio, no admite `null` y define cómo se tratan los contactos repetidos. Puedes incluir `rules` para dejar configurados los intentos, la ventana horaria, las prioridades y el comportamiento ante cada resultado desde la creación.

El lote se crea sin contactos. Añádelos después mediante `POST /batches/{batchId}/contacts`; la respuesta de esa carga contiene el `operationId` que permite seguir su procesamiento.

## Crear un lote desde un CSV

<Steps>
  <Step title="Solicita una URL de carga">
    Llama a `POST /batches/upload-url` con el nombre del archivo y `fileType: text/csv`. La URL firmada caduca en una hora.
  </Step>

  <Step title="Sube el CSV">
    Envía el contenido mediante `PUT` a `uploadUrl` con `Content-Type: text/csv`. Esta petición va al almacenamiento y no requiere la API key.
  </Step>

  <Step title="Crea el lote">
    Llama a `POST /batches` con el `tempCsvKey`, la configuración del lote, `duplicateStrategy` y el mapeo de columnas.
  </Step>

  <Step title="Consulta la importación">
    Utiliza el `batchId` de la respuesta en `GET /batches/{batchId}` y revisa `uploadStatus`, `uploadProgress` y `totalContacts`.
  </Step>
</Steps>

## Áreas de la API

<CardGroup cols={2}>
  <Card title="Lotes" icon="layer-group" href="./list-batches">
    Consulta, crea, configura, inicia, detiene y elimina lotes de marcación.
  </Card>

  <Card title="Contactos" icon="address-book" href="./add-contacts">
    Carga contactos, reagenda intentos y anula contactos de un lote.
  </Card>

  <Card title="Direcciones bloqueadas" icon="ban" href="./list-blocked-addresses">
    Gestiona las direcciones excluidas de la marcación en toda la cuenta.
  </Card>

  <Card title="Operaciones asíncronas" icon="rotate" href="./get-operation">
    Consulta el avance y el resultado de los trabajos aceptados con `202`.
  </Card>

  <Card title="Historial y auditoría" icon="clock-rotate-left" href="./batch-logs">
    Revisa cambios del lote e intentos de llamada del lote o de un contacto.
  </Card>
</CardGroup>

<Info>
  `identifier` es el identificador externo definido por el cliente. `contactId` es el identificador interno que genera el servicio al importar cada contacto.
</Info>