Consulta de Movimientos Masiva

Este servicio permite generar reportes de movimientos de cuentas en formato CSV para un rango de fechas específico. La generación del archivo se procesa de forma asíncrona y el cliente será notificado mediante webhook cuando esté listo para descargar.

Características principales

• Generación asíncrona: Las solicitudes se procesan en background
• Notificaciones por Webhook: Se notifica al cliente cuando el archivo está listo
• Descarga segura: URLs prefirmadas para descargar los archivos
• Contingencia: API de consulta de estado en caso de fallos en webhook

Formato del archivo CSV

El archivo generado tiene el siguiente formato:

Cabecera:

FECHA;FECHA CARGA;DESCRIPCION;DESCRIPCION AMPLIADA 1;DESCRIPCION AMPLIADA 2;DESCRIPCION AMPLIADA 3;COMPROBANTE;IMPORTE;IDMU

Ejemplo de fila:

13/01/2026;13/01/2026;Transferencia enviada;030644184419;PRUEBA CARGA CUIT;SOC DE BOLSA CENTAURUS SA;40;-40,00;20251113144457000012

Solicitar generación de archivo

Endpoint: POST /v1/accounts/movements/file

Descripción: Solicita la generación de un archivo formato CSV con los movimientos de una cuenta en un rango de fechas específico.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
User-Agent	Header	string	Sí	Identificador del cliente
Trace-ID	Header	string	Sí	UUID para rastreo de la solicitud
Authorization	Header	string	Sí	Token bearer para autenticación

Body de la solicitud

{
  "reference_id": "550e8400-e29b-41d4-a716-446655440000",
  "dates": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "client": {
    "document": {
      "type": "CUIT",
      "number": "30123456789"
    },
    "account_id": "567890"
  }
}

Campos:

• reference_id (string, UUID): Identificador único de la solicitud. El cliente debe asegurar que sea único.
• dates.from (string, date): Fecha de inicio del rango (formato YYYY-MM-DD)
• dates.to (string, date): Fecha de fin del rango (formato YYYY-MM-DD)
• client.document.type (string): Tipo de documento (CUIT, CUIL, CDI)
• client.document.number (string): Número de documento
• client.account_id (string): ID de la cuenta

Respuestas

202 Accepted - Solicitud creada exitosamente

{
  "message": "The request has been created successfully"
}

400 Bad Request - Errores de validación

Código de error	Descripción
MISSING_TRACE_ID	El header Trace-ID no fue proporcionado
INVALID_TRACE_ID	El formato del Trace-ID es inválido
MISSING_REFERENCE_ID	El reference_id no fue proporcionado
INVALID_REFERENCE_ID_BODY	El formato del reference_id es inválido
BODY_REQUIRE_FIELDS	Faltan campos obligatorios en el body
DATES_REQUIRE_FIELDS	Faltan campos en la sección dates
INVALID_DATE_RANGE	El rango de fechas es superior al permitido
INVALID_FUTURE_DATE	La fecha es posterior a hoy
INVALID_DATE_ORDER	La fecha inicio es posterior a la fecha fin
CLIENT_DOCUMENT_MISSING	El documento del cliente no fue proporcionado
INVALID_CLIENT_DOCUMENT_NOT_OBJECT	El documento no es un objeto válido
CLIENT_DOCUMENT_REQUIRE_FIELDS	Faltan campos en el documento
INVALID_CLIENT_DOCUMENT_TYPE	El tipo de documento no es válido
INVALID_CLIENT_FIELDS_LENGTH	La longitud de los campos es inválida

401 Unauthorized - Token inválido o expirado

403 Forbidden - Autenticación fallida

404 Not Found - Cuenta no encontrada

412 Precondition Failed - Reference ID ya existe

{
  "error": "REFERENCE_ID_ALREADY_EXISTS",
  "message": "The reference_id provided already exists"
}

500 Internal Server Error - Error interno del servidor

---

Webhook de notificación

URL: Proporcionada por el cliente durante la configuración

Método: POST

Content-Type: application/json

Descripción: Webhook que notifica al cliente sobre el estado de la solicitud de generación de archivo.

Payload - Solicitud completada exitosamente (FINISH)

{
  "reference_id": "550e8400-e29b-41d4-a716-446655440000",
  "dates": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "account_id": "567890",
  "status": "FINISH",
  "download_url": "https://api.banking.com/downloads/movements_550e8400-e29b-41d4-a716-446655440000.csv"
}

Payload - Solicitud con error (ERROR)

{
  "reference_id": "550e8400-e29b-41d4-a716-446655440000",
  "dates": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "account_id": "567890",
  "status": "ERROR"
}

Respuesta esperada

{
  "message": "Notification received successfully"
}

Código esperado: 200 OK

---

Consultar estado de solicitud

Endpoint: GET /v1/accounts/movements/file

Descripción: Consulta el estado de una solicitud de generación de archivo. Esta API es de contingencia en caso de que falle la notificación por webhook.

Parámetros

Parámetro	Ubicación	Tipo	Requerido	Descripción
User-Agent	Header	string	Sí	Identificador del cliente
Trace-ID	Header	string	Sí	UUID para rastreo de la solicitud
Authorization	Header	string	Sí	Token bearer para autenticación
reference_id	Query	string	Sí	UUID de la solicitud a consultar

Respuestas

200 OK - Estado PENDING (en proceso)

{
  "reference_id": "550e8400-e29b-41d4-a716-446655440000",
  "dates": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "account_id": "567890",
  "status": "PENDING"
}

200 OK - Estado FINISH (completado exitosamente)

{
  "reference_id": "550e8400-e29b-41d4-a716-446655440000",
  "dates": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "account_id": "567890",
  "status": "FINISH",
  "download_url": "https://api.banking.com/downloads/movements_550e8400-e29b-41d4-a716-446655440000.csv"
}

200 OK - Estado ERROR (error en la generación)

{
  "reference_id": "550e8400-e29b-41d4-a716-446655440000",
  "dates": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "account_id": "567890",
  "status": "ERROR"
}

400 Bad Request - Errores de validación

Código de error	Descripción
MISSING_TRACE_ID	El header Trace-ID no fue proporcionado
INVALID_TRACE_ID	El formato del Trace-ID es inválido
MISSING_REFERENCE_ID_QUERY	El parámetro reference_id no fue proporcionado
INVALID_REFERENCE_ID	El formato del reference_id es inválido

401 Unauthorized - Token inválido o expirado

403 Forbidden - Autenticación fallida

404 Not Found - Solicitud no encontrada

{
  "error": "REFERENCE_ID_NOT_FOUND",
  "message": "The reference_id provided was not found"
}

500 Internal Server Error - Error interno del servidor

---

Estados de la solicitud

Estado	Descripción
PENDING	La solicitud está siendo procesada
FINISH	El archivo fue generado exitosamente y está listo para descargar
ERROR	Ocurrió un error durante la generación del archivo

---

Buenas prácticas

1. Generar reference_id único: Asegúrese de usar UUIDs únicos para cada solicitud para evitar conflictos.
2. Rango de fechas razonable: No solicite rangos excesivamente amplios para evitar timeouts.
3. Implementar webhook: Configure un endpoint webhook para recibir notificaciones automáticas de finalización.
4. Usar contingencia: En caso de no recibir webhook, implemente consultas periódicas del estado.
5. Descarga inmediata: Las URLs prefirmadas tienen validez limitada, descargue el archivo prontamente.