> ## 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.
# Obtener un lote
> Consulta el estado y la configuración de un lote del marcador.
Devuelve la información de un lote concreto, incluidos su estado, métricas, configuración y canal asociado.
## Autenticación
API key obtenida desde la interfaz de Inagent, dentro del marcador.
## Parámetros de ruta
Identificador único del lote.
## Ejemplo
```bash cURL theme={null}
curl --request GET \
--url 'https://api.backend.inconcertcc.com/autocontact/api/v1/batches/e8b63614-f5db-4fd4-84ab-258b7070262e' \
--header 'apikey: TU_API_KEY'
```
```json Response theme={null}
{
"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": "b5860478-5927-4362-8b59-c8f42149d045",
"totalContacts": 6,
"fileRowCount": 1,
"contactedCount": 0,
"processedCount": 2,
"finishedCount": 2,
"uploadStatus": "completed",
"uploadProgress": 1,
"mapping": {
"name": "nombre",
"priority": "",
"addresses": [
{
"column": "telefono",
"priority": 1
}
],
"identifier": "id",
"customFields": [],
"identifierLooksConstant": false
},
"filters": null,
"schedule": null,
"rules": {
"amd": {
"amdAction": "HANGUP",
"amdEnabled": true
},
"strategy": {
"timezone": "Europe/Madrid",
"daysOfWeek": [1, 2, 3, 4, 5],
"scheduleEnd": "19:00",
"scheduleStart": "08:00",
"timeBetweenAttempts": 3,
"maxAttemptsPerAddress": 2,
"maxAttemptsPerContact": 4,
"processAllContactsFirst": false
},
"channelType": "livekit_sipcall",
"resultRules": {
"busy": { "maxRetries": 2, "retryDelay": 15 },
"failed": { "maxRetries": 2, "retryDelay": 15 },
"noAnswer": { "maxRetries": 2, "retryDelay": 15 },
"voicemail": { "maxRetries": 2, "retryDelay": 15 }
},
"addressPriority": {
"tryAllBeforeRetry": true
}
},
"duplicateStrategy": {
"action": "update_always",
"enabled": true,
"detectionCriteria": "phone"
},
"channelPriority": 1,
"statusDetail": null,
"queueSyncStatus": "completed",
"isFavorite": false,
"enabled": true,
"deleted": false,
"createdAt": "2026-09-07T10:53:45.000Z",
"updatedAt": "2026-09-07T11:28:37.000Z",
"channel": {
"id": "55210458-1957-4023-b7cc-82bbb5124aaa",
"crewId": "3de07003-adc0-4b7a-b1d4-333220d51fb4.equipo-ventas.latest"
},
"crewId": "3de07003-adc0-4b7a-b1d4-333220d51fb4.equipo-ventas.latest"
}
```
## OpenAPI
````yaml api-reference/dialer/openapi.yaml GET /batches/{batchId}
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/{batchId}:
parameters:
- $ref: '#/components/parameters/BatchId'
get:
tags:
- Lotes
summary: Consulta un lote
description: >
Devuelve los datos completos de un lote: configuración, mapeo de
columnas, reglas de marcación,
ventana horaria y progreso.
La estructura es la misma que la de los elementos del listado.
## Diferencia con el listado
El campo `nextActivationAt` se calcula en esta operación para el lote en
cualquier estado,
mientras que en el listado solo se resuelve para los lotes en curso.
Para conocer cuándo un lote detenido reanudará la marcación, utilice
esta operación: en el
listado ese campo puede venir vacío aunque el lote tenga una ventana
horaria configurada.
## `status` y `displayStatus`
Igual que en el listado, `status` es el estado registrado y
`displayStatus` el estado efectivo en
el momento de la consulta. Un lote con `status: running` fuera de su
ventana horaria devuelve
`displayStatus: scheduled`.
operationId: getBatch
responses:
'200':
description: El lote.
content:
application/json:
schema:
$ref: '#/components/schemas/Batch'
'500':
description: >
Error interno, o lote inexistente.
Actualmente un lote que no existe o que no pertenece a la cuenta se
devuelve con este código
y el mensaje `Batch not found`, en lugar de `404`. Conviene
comprobar el campo `message`
antes de interpretar la respuesta como un fallo del servicio.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
examples:
noExiste:
summary: Lote inexistente o de otra cuenta
value:
message: Batch not found
fallo:
summary: Error del servicio
value:
message: Internal server error
components:
parameters:
BatchId:
name: batchId
in: path
required: true
schema:
type: string
format: uuid
description: Id del lote.
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
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
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
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: apikey
description: API key obtenida desde la interfaz de Inagent, dentro del marcador.
````