> ## 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 una URL de carga > Genera una URL prefirmada para subir el CSV de contactos. Solicita la URL temporal que se utiliza para subir el archivo CSV antes de crear un lote. ## OpenAPI ````yaml api-reference/dialer/openapi.yaml POST /batches/upload-url 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/upload-url: post: tags: - Lotes summary: Pide una URL para subir el CSV de contactos description: > Primer paso para crear un lote. Devuelve una URL firmada para subir el archivo CSV directamente al almacenamiento, junto con la clave que identifica ese archivo al crear el lote. ## Proceso completo 1. `POST /batches/upload-url`: devuelve `uploadUrl` y `tempCsvKey`. 2. `PUT` del contenido del CSV a `uploadUrl`, con el header `Content-Type: text/csv`. Esta petición se dirige al almacenamiento, no a la API, y no requiere credenciales. 3. `POST /batches` indicando ese `tempCsvKey`. ## Requisitos de la subida * La URL caduca en 1 hora. Es el plazo para completar la subida; una vez creada la clave, el lote puede crearse después. * El `Content-Type` debe ser `text/csv`. La URL se firma para ese tipo concreto, por lo que cualquier otro valor hace que el almacenamiento rechace la subida. ## Validez de la clave La clave se consume al crear el lote y no puede reutilizarse para un segundo lote. Si la creación del lote se rechaza por límite de contactos o por canal deshabilitado, el archivo se descarta y es necesario subirlo de nuevo. En cambio, un rechazo por validación del cuerpo (`VALIDATION_FAILED`) conserva el archivo, de modo que se puede corregir la petición y volver a intentarlo con la misma clave. operationId: getCsvUploadUrl requestBody: required: true content: application/json: schema: type: object required: - fileName - fileType properties: fileName: type: string description: > Nombre del archivo. Forma parte de la clave generada y facilita su identificación posterior. No necesita ser único. example: contactos-agosto.csv fileType: type: string enum: - text/csv description: > Tipo de contenido con el que se firma la URL. Debe coincidir con el `Content-Type` de la subida. example: fileName: contactos-agosto.csv fileType: text/csv responses: '200': description: URL de subida emitida. content: application/json: schema: type: object required: - uploadUrl - tempCsvKey properties: uploadUrl: type: string description: > URL firmada para subir el archivo. Caduca en 1 hora. Debe utilizarse sin modificar sus parámetros, ya que la firma forma parte de la propia URL. tempCsvKey: type: string description: > Referencia al archivo subido. Es el valor que se indica en el campo `tempCsvKey` al crear el lote. example: >- csv-uploads/acme/3f8a1b2c-5d6e-4f70-8a9b-1c2d3e4f5a6b-contactos-agosto.csv example: uploadUrl: >- https://storage.example.com/csv-uploads/acme/3f8a1b2c-contactos-agosto.csv?X-Amz-Signature=... tempCsvKey: >- csv-uploads/acme/3f8a1b2c-5d6e-4f70-8a9b-1c2d3e4f5a6b-contactos-agosto.csv '500': $ref: '#/components/responses/InternalError' components: responses: InternalError: description: Error interno. content: application/json: schema: $ref: '#/components/schemas/SimpleError' schemas: 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: apikey description: API key obtenida desde la interfaz de Inagent, dentro del marcador. ````