> ## 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.
# Consultar lotes
> Lista y filtra los lotes del marcador de Inagent.
Devuelve los lotes del marcador que coinciden con los filtros enviados.
## Autenticación
API key obtenida desde la interfaz de Inagent, dentro del marcador.
## Parámetros de consulta
Página que se desea consultar. El ejemplo comienza en `0`.
Cantidad de lotes por página.
Campo utilizado para ordenar los resultados. En el ejemplo se usa `createdAt`.
Orden de los resultados. En el ejemplo se usa `desc`.
Estado por el que se filtran los lotes. En el ejemplo se usa `archived`.
Inicio del periodo en formato ISO 8601.
Fin del periodo en formato ISO 8601.
## Ejemplo
```bash cURL theme={null}
curl --request GET \
--url 'https://api.backend.inconcertcc.com/autocontact/api/v1/batches?page=0&size=10&sortField=createdAt&sortOrder=desc&status=archived&startDate=2026-08-31T22%3A00%3A00.000Z&endDate=2026-09-16T21%3A59%3A59.999Z' \
--header 'apikey: TU_API_KEY'
```
```json Response theme={null}
{
"data": [
{
"id": "e8b63614-f5db-4fd4-84ab-258b7070262e",
"name": "lote_ventas",
"channelName": "Marcador_ventas",
"channelType": "Livekit_SipCall",
"channelId": "55210458-1957-4023-b7cc-82bbb5124aaa",
"status": "archived",
"displayStatus": "archived",
"statusReason": "manual",
"statusChangedAt": "2026-09-07T11:28:37.000Z",
"statusChangedBy": "Usuario de ejemplo",
"totalContacts": 6,
"contactedCount": 0,
"processedCount": 2,
"finishedCount": 2,
"uploadStatus": "completed",
"uploadProgress": 1,
"channelPriority": 1,
"queueSyncStatus": "completed",
"isFavorite": false,
"enabled": true,
"deleted": false,
"createdAt": "2026-09-07T10:53:45.000Z",
"updatedAt": "2026-09-07T11:28:37.000Z",
"createdBy": "Usuario de ejemplo",
"updatedBy": "Usuario de ejemplo",
"crewId": "3de07003-adc0-4b7a-b1d4-333220d51fb4.equipo-ventas.latest"
}
],
"pagination": {
"total": 1,
"page": 0,
"limit": 10
}
}
```
La respuesta de cada lote también puede incluir su mapeo, reglas, estrategia de duplicados y datos del canal. Para ver un ejemplo más detallado, consulta Obtener un lote.
## OpenAPI
````yaml api-reference/dialer/openapi.yaml GET /batches
openapi: 3.1.0
info:
title: AutoContact API
version: final
summary: Gestión de lotes de marcación automática y carga de contactos.
description: >
API de AutoContact: gestión de lotes de marcación automática y de los
contactos que los integran.
Todos los recursos se publican bajo `/autocontact/api/v1/`.
## Autenticación
Las peticiones se autentican con el header `apikey`. La misma credencial
permite operar los lotes
de la cuenta a los que tenga acceso. El servicio deriva la cuenta de esa
credencial y verifica que
el recurso solicitado le pertenezca.
Un lote que no pertenece a la cuenta responde `404`, igual que un lote
inexistente.
## Operaciones asíncronas
Algunas operaciones responden `202` en lugar de `200`: la petición se acepta
y el trabajo continúa
en segundo plano. Es el caso de la carga de contactos, el arranque y la
eliminación de un lote.
Esas respuestas incluyen un `operationId` que se consulta en
`GET /batches/operations/{operationId}` para conocer el resultado.
`POST /batches` no genera una operación: devuelve directamente el `batchId`,
el estado `created` y
el origen del lote, sin `operationId`.
Tiempo de retención de las operaciones:
| Tipo de operación | Disponible durante |
|---|---|
| Carga de contactos | 6 horas |
| Ciclo de vida del lote (arranque, archivado, eliminación) | 1 hora, y 10
minutos desde que finaliza |
## Reintentos seguros con `Idempotency-Key`
Las operaciones de escritura aceptan el header opcional `Idempotency-Key`.
Resuelve el caso en que
se produce un error de red después de que la petición llegó al servicio: sin
este header no es
posible determinar si el trabajo se procesó, y reintentar podría duplicar
llamadas telefónicas.
Con el header, un reintento que use la misma clave y el mismo cuerpo
devuelve la respuesta original
sin procesar nada de nuevo. Las claves se conservan 24 horas.
Recomendación de uso: generar un identificador único (por ejemplo un UUID)
antes del primer intento
y reutilizarlo solo en los reintentos de esa misma operación.
Requisitos de la clave: entre 1 y 255 caracteres, solo ASCII imprimible. Una
clave que no cumpla
estos requisitos se rechaza con `400 INVALID_IDEMPOTENCY_KEY` en lugar de
ignorarse, para evitar
procesar la petición sin la protección que el cliente espera tener.
### Headers de respuesta
| Header | Cuándo aparece | Significado |
|---|---|---|
| `Idempotency-Replayed: true` | En un reintento | La respuesta corresponde
a la petición original; no se procesó de nuevo |
| `Retry-After` | Junto a `409 IDEMPOTENCY_KEY_IN_FLIGHT` | Segundos a
esperar antes de reintentar |
| `Idempotency-Status: bypassed` | Excepcionalmente | La petición se procesó
**sin** protección de idempotencia |
El header `Idempotency-Status: bypassed` indica que el servicio de
idempotencia no estaba
disponible y la petición se procesó igualmente, para no interrumpir la
operación. La respuesta es
válida, pero esa petición concreta no quedó protegida: si no se recibe
respuesta, se recomienda
verificar el estado antes de reintentar.
Las respuestas con error `5xx` no se almacenan, de modo que un reintento con
la misma clave vuelve a
procesar la petición.
servers:
- url: https://api.backend.inconcertcc.com/autocontact/api/v1
description: API de Inagent
security:
- ApiKeyAuth: []
tags:
- name: Lotes
description: |
Creación, consulta y control de lotes de marcación.
- name: Contactos
description: |
Carga de contactos en un lote, reagendamiento y anulación.
- name: Direcciones bloqueadas
description: |
Direcciones excluidas de la marcación en toda la cuenta.
- name: Operaciones
description: |
Seguimiento de las operaciones asíncronas que devuelven `202`.
paths:
/batches:
get:
tags:
- Lotes
summary: Lista los lotes de la cuenta
description: >
Devuelve los lotes de la cuenta, paginados. Incluye los lotes archivados
salvo que se filtre por
`status`.
## Paginación
El parámetro `page` comienza en 0. El tamaño de página predeterminado es
20.
La respuesta incluye `pagination.total` con el número total de
resultados que cumplen el filtro,
a partir del cual se obtiene el número de páginas.
## Contadores de progreso
Para los lotes en curso, los campos `processedCount`, `contactedCount` y
`finishedCount`
reflejan el estado actual de la marcación. Si esa información no está
disponible
momentáneamente, se devuelven los últimos valores registrados, que
pueden presentar un ligero
retraso.
## `status` y `displayStatus`
`status` es el estado registrado del lote. `displayStatus` es el estado
efectivo en el momento de
la consulta y es el recomendado para mostrar o evaluar la situación del
lote.
Los dos pueden diferir: un lote con `status: running` fuera de su
ventana horaria devuelve
`displayStatus: scheduled`, porque no realizará llamadas hasta que la
ventana se abra.
operationId: listBatches
parameters:
- name: page
in: query
description: Número de página, comenzando en 0.
schema:
type: integer
minimum: 0
default: 0
- name: size
in: query
description: Número de lotes por página.
schema:
type: integer
minimum: 1
default: 20
- name: sortField
in: query
description: Campo de ordenamiento.
schema:
type: string
default: createdAt
- name: sortOrder
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
- name: status
in: query
description: >
Filtra por estado del lote. Si se omite, se devuelven todos los
lotes, incluidos los
archivados.
schema:
type: string
enum:
- running
- stopped
- completed
- archived
- name: search
in: query
description: Filtra por nombre del lote.
schema:
type: string
- name: startDate
in: query
description: Fecha de creación mínima.
schema:
type: string
format: date-time
- name: endDate
in: query
description: Fecha de creación máxima.
schema:
type: string
format: date-time
- name: crewId
in: query
description: Filtra por equipo asociado al canal del lote.
schema:
type: string
- name: channelType
in: query
description: >
Tipo de canal, según el catálogo de canales de la cuenta. Por
ejemplo `Livekit_SipCall`.
schema:
type: string
responses:
'200':
description: Página de lotes.
content:
application/json:
schema:
type: object
required:
- data
- pagination
properties:
data:
type: array
items:
$ref: '#/components/schemas/Batch'
pagination:
type: object
required:
- total
- page
- limit
properties:
total:
type: integer
description: Número total de lotes que cumplen el filtro.
example: 137
page:
type: integer
description: Número de página devuelta.
example: 0
limit:
type: integer
example: 20
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
Batch:
type: object
description: >
Lote de marcación. Es la estructura que devuelven tanto la consulta de
un lote como cada elemento
del listado.
properties:
id:
type: string
format: uuid
name:
type: string
channelId:
type: string
format: uuid
channelName:
type: string
channelType:
type: string
description: >
Tipo de canal, tal como lo expone el catálogo de canales. Por
ejemplo `Livekit_SipCall`.
example: Livekit_SipCall
channelPriority:
type: integer
minimum: 1
maximum: 10
description: >
Peso al repartir la capacidad del canal entre lotes que corren a la
vez.
crewId:
type:
- string
- 'null'
status:
type: string
enum:
- stopped
- running
- completed
- archived
- deleting
- archiving
description: >
Estado **persistido**.
`deleting` y `archiving` son transitorios: el lote **no admite
ninguna acción** mientras
está en uno de ellos, y cualquier intento responde `409`.
displayStatus:
type: string
description: >
Estado efectivo del lote en el momento de la consulta. Es el valor
recomendado para mostrar o
evaluar la situación del lote.
Puede no coincidir con `status`: un lote con `status: running` fuera
de su ventana horaria
devuelve `scheduled`, ya que no realizará llamadas hasta que la
ventana se abra.
example: scheduled
statusReason:
type: string
enum:
- created
- manual
- scheduled
- no more contacts
- system
description: >
Por qué está en ese estado. `manual` y `scheduled` son los que puede
declarar un cliente al
arrancar o detener; el resto los escribe el servicio.
statusChangedAt:
type:
- string
- 'null'
format: date-time
statusChangedBy:
type:
- string
- 'null'
statusDetail:
type:
- string
- 'null'
nextActivationAt:
type:
- string
- 'null'
format: date-time
description: >
Fecha y hora en que un lote en espera reanudará la marcación. `null`
si no procede.
En el listado puede venir vacío aunque el lote tenga una ventana
horaria configurada, ya que
allí solo se calcula para los lotes en curso. Para obtener el valor
en cualquier estado,
consulte el lote por su identificador.
totalContacts:
type: integer
description: Contactos del lote.
fileRowCount:
type: integer
description: >
Filas del CSV original. Puede ser mayor que `totalContacts`: las
filas sin dirección
utilizable, o descartadas por filtros o duplicados, no llegan a ser
contactos.
processedCount:
type: integer
description: >
Número de contactos ya procesados. En un lote en curso refleja el
estado actual de la
marcación; si esa información no está disponible momentáneamente, se
devuelve el último valor
registrado.
contactedCount:
type: integer
description: Contactos efectivamente contactados.
finishedCount:
type: integer
description: >
Contactos cerrados sin haber sido contactados: se agotaron sus
intentos o sus direcciones.
uploadStatus:
type: string
description: Estado de la importación del CSV.
uploadProgress:
type: integer
minimum: 0
maximum: 100
queueSyncStatus:
type: string
enum:
- pending
- syncing
- completed
- failed
description: >
Estado de la carga de los contactos en el motor de marcación.
Es necesario para distinguir un lote que está arrancando de uno que
ya está marcando: el lote
pasa a `running` antes de que la carga finalice.
mapping:
type: object
description: Qué columna del CSV es cada cosa.
filters:
type:
- object
- 'null'
schedule:
oneOf:
- $ref: '#/components/schemas/BatchSchedule'
- type: 'null'
description: Ventana horaria propia. `null` si hereda la de la cuenta.
rules:
type:
- object
- 'null'
description: >
Reglas de marcación del lote. `null` si usa las reglas globales de
la cuenta.
duplicateStrategy:
type:
- object
- 'null'
isFavorite:
type: boolean
s3CsvKey:
type: string
description: Ubicación interna del CSV importado.
s3SnapshotKey:
type:
- string
- 'null'
description: Ubicación interna del snapshot, en lotes archivados.
channel:
type:
- object
- 'null'
description: Datos del canal resuelto.
enabled:
type: boolean
deleted:
type: boolean
TenantId:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
createdBy:
type: string
updatedBy:
type: string
BatchSchedule:
type: object
required:
- startTime
- endTime
description: |
Ventana horaria en la que el lote puede realizar llamadas.
properties:
startTime:
type: string
pattern: ^([01]\d|2[0-3]):([0-5]\d)$
description: Hora de inicio, formato `HH:mm` de 24 horas.
example: '09:00'
endTime:
type: string
pattern: ^([01]\d|2[0-3]):([0-5]\d)$
description: >
Hora de fin, formato `HH:mm`. **Puede ser menor que `startTime`**:
eso significa una
ventana que cruza la medianoche. Lo que no puede es ser igual.
example: '20:00'
timezone:
type: string
description: >
Zona horaria IANA con la que se interpretan las horas. Si se omite,
se utiliza la configurada
en la cuenta.
example: America/Argentina/Buenos_Aires
daysOfWeek:
type: array
minItems: 1
items:
type: integer
minimum: 0
maximum: 6
description: |
Días habilitados, `0` domingo a `6` sábado. Omitido, todos los días.
example:
- 1
- 2
- 3
- 4
- 5
SimpleError:
type: object
required:
- message
description: >
Error con mensaje descriptivo.
Algunos traen `code` estable (los más nuevos); otros solo `message`.
Los mensajes pueden aparecer en español o en inglés según el caso, y
algunos errores todavía no
incluyen `code`. Cuando esté presente, utilice `code` para tratar el
error de forma programática.
properties:
code:
type: string
description: >
Presente en los errores ya normalizados (`MISSING_PARAMETER`,
`OPERATION_NOT_FOUND`,
`VALIDATION_FAILED`, `INVALID_IDEMPOTENCY_KEY`, y los de
idempotencia).
message:
type: string
responses:
InternalError:
description: Error interno.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: apikey
description: API key obtenida desde la interfaz de Inagent, dentro del marcador.
````