> ## 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. # Iniciar un lote > Arranca la marcación de un lote. Solicita el arranque asíncrono de la marcación del lote. ```bash cURL theme={null} curl --request POST \ --url 'https://api.backend.inconcertcc.com/autocontact/api/v1/batches/5b591fcb-6beb-4157-b932-e8e707eeb6d7/start' \ --header 'apikey: TU_API_KEY' \ --data '' ``` ## OpenAPI ````yaml api-reference/dialer/openapi.yaml POST /batches/{batchId}/start 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}/start: parameters: - $ref: '#/components/parameters/BatchId' post: tags: - Lotes summary: Arranca la marcación de un lote description: > Inicia la marcación de un lote. Responde `202`: el arranque se procesa en segundo plano. ## Seguimiento El arranque implica preparar los contactos y cargarlos en el motor de marcación, lo que en lotes grandes requiere varios minutos. El `operationId` devuelto permite seguir el avance en `GET /batches/operations/{operationId}`, que lo devuelve con `kind: batch.lifecycle`. Esa operación se compone de dos etapas y su campo `progress` refleja el avance conjunto de ambas en una escala de 0 a 100. La operación está disponible durante 1 hora y solo 10 minutos desde que finaliza. Para comprobar el estado del arranque más allá de ese plazo, consulte el lote: `queueSyncStatus` indica si la carga de contactos ha finalizado. ## Cuándo comienza realmente la marcación La respuesta `202` confirma que el arranque se ha aceptado, no que el lote esté ya marcando. Para determinarlo, consulte el campo `queueSyncStatus` del lote: | `queueSyncStatus` | Situación | |---|---| | `syncing` | El arranque está en curso; el lote aún no marca | | `completed` | Los contactos están cargados y el lote puede marcar | Un lote puede presentar `status: running` con `queueSyncStatus: syncing`, lo que significa que está arrancando. ## Ventana horaria Si el lote se arranca fuera de su ventana horaria, el arranque se completa correctamente pero la marcación no comienza hasta que la ventana se abre. En ese caso el lote devuelve `displayStatus: scheduled` y `nextActivationAt` con la fecha prevista. operationId: startBatch requestBody: required: false content: application/json: schema: type: object properties: reason: type: string enum: - manual - scheduled default: manual description: > Motivo del arranque. Queda registrado en el historial de cambios de estado del lote. Solo se admiten estos dos valores. El resto de los motivos que pueden aparecer en el historial los registra el propio servicio. example: reason: manual responses: '202': description: | Arranque aceptado. El lote todavía no está marcando. content: application/json: schema: type: object required: - operationId - status properties: operationId: type: string format: uuid description: | Identificador de la operación de arranque, consultable en `GET /batches/operations/{operationId}`. status: type: string enum: - starting example: operationId: 5c2e8a14-7b09-4f3d-a1e6-8d4b2c9f0e71 status: starting '400': description: El `reason` no es uno de los aceptados. content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: code: VALIDATION_FAILED message: Validación fallida en el cuerpo del request details: - field: reason code: INVALID_TYPE reason: 'must be one of: manual, scheduled' meta: received: porque_quise allowed: - manual - scheduled '500': description: > Error interno, o una condición del lote que impide arrancarlo. Actualmente el lote inexistente y las condiciones de estado (lote ya en curso, importación sin finalizar, lote archivado) se devuelven con este código en lugar de `404` y `409`. El campo `message` identifica el caso concreto. content: application/json: schema: $ref: '#/components/schemas/SimpleError' examples: noExiste: summary: El lote no existe value: message: Batch not found yaCorriendo: summary: El lote ya está en curso value: message: Batch is already running importando: summary: La importación de contactos no ha finalizado value: message: La importación de contactos del lote aún está en curso archivado: summary: El lote está archivado value: message: Cannot modify an archived batch components: parameters: BatchId: name: batchId in: path required: true schema: type: string format: uuid description: Id del lote. schemas: ValidationError: type: object required: - message properties: code: type: string enum: - VALIDATION_FAILED description: > Presente cuando el rechazo corresponde a la validación de contactos. No aparece en los rechazos por límites de la petición, como un cuerpo vacío o más de 1000 contactos. message: type: string details: description: > Detalle del rechazo. La estructura varía según el caso: una lista de textos para los límites de la petición, o una lista de `FieldRejection` cuando el rechazo es de validación de contactos. oneOf: - type: array items: type: string - type: array items: $ref: '#/components/schemas/FieldRejection' 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 FieldRejection: type: object required: - index - field - code - reason description: > Campo rechazado de un contacto concreto. Se incluyen todos los rechazos, no solo el primero de cada contacto: un contacto con tres campos incorrectos genera tres entradas. Utilice `code`, que es estable, para tratar el error de forma programática. El campo `reason` es un texto descriptivo de apoyo y puede cambiar sin aviso. properties: index: type: integer description: Posición del contacto en el array enviado, base 0. example: 3 field: type: string description: > Ruta del campo rechazado, precedida por la posición del contacto. Permite localizarlo en la petición enviada. example: contacts[3].addresses[0].address code: type: string enum: - REQUIRED - INVALID_TYPE - INVALID_PHONE_FORMAT - INVALID_EMAIL_FORMAT - INVALID_ADDRESS_TYPE - INVALID_PRIORITY - EMPTY_ARRAY - INVALID_DATE - DATE_NOT_FUTURE - DATE_OUT_OF_RANGE - DUPLICATED_IN_REQUEST description: > Código estable del motivo del rechazo. Es el valor recomendado para tratar el error de forma programática y para traducir el mensaje al idioma del usuario final. reason: type: string description: > Descripción del rechazo, en español. Informativa: puede cambiar sin aviso. meta: type: object additionalProperties: true description: > Datos del rechazo: el valor recibido, el esperado o el límite aplicado. Permiten construir un mensaje propio sin necesidad de interpretar el texto de `reason`. example: received: '123' expected: digits only, 7-15 characters error: type: string deprecated: true description: > Contiene el mismo valor que `reason`. Se mantiene por compatibilidad con versiones anteriores; utilice `reason`. securitySchemes: ApiKeyAuth: type: apiKey in: header name: apikey description: API key obtenida desde la interfaz de Inagent, dentro del marcador. ````