Archivo de Posición Consolidada

En esta sección se describe el servicio para la generación del archivo JSON de Posición Consolidada a partir del endpoint POST /v1/clients/consolidated-position/file.

Proceso de generación

1. El cliente solicita la generación del archivo.
2. La API responde con estado PROCESSING y un file_id.
3. Cuando el archivo queda disponible, se notifica con una URL prefirmada para descargarlo.

Proceso de obtención de archivo de Posición Consolidada

1. Solicitud de generación

CURL de solicitud de generacion de archivo:

curl --location --request POST 'http://apibanking-url/v1/clients/consolidated-position/file' \
--header 'trace-id: 1d4c459f-8c61-43a2-9423-59bca8c973bd' \
--header 'Authorization: Bearer eyJhbGc...'

Respuesta esperada (202):

{
    "file": {
        "id": "20260624_26168190",
        "status": "PROCESSING"
    },
    "message": "Consolidated position file request received."
}

Se recomienda revisar definición de la API en el swagger.

2. Notificación del archivo generado

Una vez que el archivo haya sido generado con éxito, se enviará una notificación al cliente mediante el Webhook que debe exponer POST /v1/notifications/client/consolidated-position/file

En esta notificación se indican los datos de descarga del archivo generado en caso de haber sido exitoso, o de lo contrario se indica que la generación del archivo falló y que puede ser reintentada.

Se recomienda revisar definición de Webhook a exponer en el swagger.

Ejemplo de notificación:

{
  "notification": {
    "id": "019edb21-3446-7b52-a49c-3bd70f47413b",
    "date": "2026-06-16T20:35:46Z"
  },
  "file": {
    "id": "20260624_26168190",
    "status": "COMPLETED",
    "download_data": {
      "url": "https://bucket.s3.amazonaws.com/position-consolidated/123/salida/2026-04-15.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..",
      "method": "GET",
      "content_type": "application/json",
      "expiration": "2026-06-18T23:59:59Z",
      "expiration_in_minutes": 60
    }
  },
  "error": null
}

3. Descarga mediante URL prefirmada

Cuando el archivo este listo, la notificación incluirá la informacion de descarga en el objeto file.download_data.

Ejemplo de bloque de descarga en notificacion:

{
    "file": {
        "id": "20260624_26168190",
        "download_data": {
            "url": "https://storage.example.com/position-consolidated/20260624_26168190.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
            "method": "GET",
            "content_type": "application/json",
            "expiration": "2026-06-24T23:59:59Z",
            "expiration_in_minutes": 60
        }
    }
}

En el campo file.download_data.url se expondrá una URL Prefirmada de descarga del archivo la cual tiene un tiempo de vigencia de 1 hora para su uso.

El vencimiento de la URL prefirmada esta indicado por dos campos:

• expiration: fecha y hora exacta de expiracion (UTC).
• expiration_in_minutes: cantidad de minutos de validez desde su emision.

Recomendación: descargar el archivo inmediatamente al recibir la notificacion para evitar expiracion.

4. Ejemplo curl para descargar el archivo

Ejemplo usando la URL prefirmada recibida en la notificacion:

curl --request GET \
    --url "https://storage.example.com/position-consolidated/20260624_20354678988.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&..." \
    --output posición-consolidada-20260624_20354678988.json

Notas:

• No modificar la query string de la URL prefirmada.
• Usar exactamente el metodo HTTP informado en download_data.method.

5. Estructura de Archivo generado

El archivo de Posición Consolidada es un archivo de formato JSON. En dicho archivo se expondrá la información de Posicion Bancaria (cuentas y plazos fijos), Posición en Fondos Comunes de Inversión y Posición Bursátil (instrumentos y detalles de cuentas).

Recomendación: Validar los schemas del archivo a continuación

La estructura del archivo será la siguiente:

Ejemplo de contenido de archivo

{
    "metadata": {
        "client": {
            "document_type": "DNI",
            "document_number": "26168190"
        },
        "created_at": "2026-07-14 16:06:13",
        "file_id": "20260616_26168190"
    },
    "bank_position": {
        "bank_accounts": [
            {
                "balance": {
                    "available": 8.09,
                    "balance": 8.09,
                    "agreement": 0
                },
                "account_type": "AC",
                "account_number": "41141494",
                "cbu": "2990004800411414940015",
                "currency_code": "ARS"
            }
        ],
        "fixed_term_deposits": [
            {
                "certificate_number": "1156369",
                "currency_code": "USD",
                "capital": 3400,
                "interest": 136,
                "total": 3536,
                "term_in_days": 365,
                "rate": "4.0000000",
                "opening_date": "2025-04-28T03:00:00.000Z",
                "due_date": "2026-04-28T03:00:00.000Z"
            }
        ]
    },
    "fol_position": {
        "shareholder_accounts": [
            {
                "funds": [
                    {
                        "fund_name": "GALILEO - Galileo Pesos - Clase A",
                        "currency_code": "ARS",
                        "share_quantity": 1234.7867,
                        "last_quotation": 14.714755,
                        "holding_value": 18169.58,
                        "cafci": "2398"
                    }
                ],
                "shareholder_account": "71028"
            }
        ]
    },
    "stock_market_position": {
        "brokerage_accounts_holdings": [
            {
                "holdings": [
                    {
                        "instruments": [
                            {
                                "abbreviation": "AL30",
                                "description": "5921 / AL30 - BONO REP. ARGENTINA USD STEP UP 2030",
                                "quantity": 38446,
                                "valuation": 36077726.4
                            }
                        ],
                        "instrument_type": "Titulo Publicos"
                    }
                ],
                "brokerage_account": 500001
            }
        ]
    }
}

Schemas

ConsolidatedPositionFile

Campo	Tipo de dato	Descripcion
metadata	Metadata	Metadata del archivo
bank_position	BankPosition	Informacion de la posicion bancaria
fol_position	FolPosition	Informacion de la posicion en fondos comunes de inversion
stock_market_position	StockMarketPosition	Informacion de la posicion bursatil

Metadata

Campo	Tipo de dato	Descripcion
created_at	string	Fecha de creacion del archivo (formato YYYY-MM-DD HH:mm:ss)
file_id	string	Identificador del archivo
client	Client	Informacion del cliente al cual pertenece la informacion del archivo

Client

Campo	Tipo de dato	Descripcion
document_type	string	Tipo de documento del cliente
document_number	string	Numero de documento del cliente

BankPosition

Campo	Tipo de dato	Descripcion
bank_accounts	array<BankAccount>	Listado de cuentas bancarias del cliente
fixed_term_deposits	array<FixedTermDeposit>	Listado de plazos fijos del cliente

BankAccount

Campo	Tipo de dato	Descripcion	Valores posibles
account_type	string	Tipo de cuenta bancaria	"AC" (Caja de Ahorro) "CC" (Cuenta Corriente)
account_number	string	Numero de cuenta bancaria	-
cbu	string	CBU de la cuenta	-
currency_code	string	Moneda de la cuenta	"ARS" "USD"
balance	Balance	Saldo de la cuenta	-

Balance

Campo	Tipo de dato	Descripcion
available	number	Saldo disponible para operar
balance	number	Saldo actual
agreement	number	Saldo del acuerdo bancario

FixedTermDeposit

Campo	Tipo de dato	Descripcion	Valores posibles
certificate_number	string	Numero de certificado del plazo fijo	-
currency_code	string	Moneda del plazo fijo	"ARS" "USD"
capital	number	Capital del plazo fijo	-
interest	number	Interes del plazo fijo	-
total	number	Importe total del plazo fijo (capital + interes)	-
term_in_days	number	Plazo en dias	-
rate	string	Tasa del plazo fijo	-
opening_date	string	Fecha de alta	-
due_date	string	Fecha de vencimiento	-

FolPosition

Campo	Tipo de dato	Descripcion
shareholder_accounts	array<ShareholderAccount>	Listado de cuentas cuotapartistas

ShareholderAccount

Campo	Tipo de dato	Descripcion
shareholder_account	string	Numero de cuenta cuotapartista
funds	array<Fund>	Listado de fondos de la cuenta cuotapartista

Fund

Campo	Tipo de dato	Descripcion	Valores posibles
fund_name	string	Nombre del fondo	-
currency_code	string	Moneda del fondo	"ARS" "USD"
share_quantity	number	Cantidad de cuotapartes	-
last_quotation	number	Ultima cotizacion de la cuotaparte	-
holding_value	number	Tenencia valorizada	-
cafci	string	Numero del fondo en CAFCI	-

StockMarketPosition

Campo	Tipo de dato	Descripcion
brokerage_accounts_holdings	array<BrokerageAccountHoldings>	Listado de tenencias por cuenta comitente

BrokerageAccountHoldings

Campo	Tipo de dato	Descripcion
brokerage_account	number	Numero de cuenta comitente
holdings	array<HoldingByType>	Listado de tenencias agrupadas por tipo de instrumento

HoldingByType

Campo	Tipo de dato	Descripcion
instrument_type	string	Tipo de instrumento
instruments	array<Instrument>	Listado de instrumentos del tipo

Instrument

Campo	Tipo de dato	Descripcion
abbreviation	string	Abreviatura del instrumento
description	string	Descripcion del instrumento
quantity	number	Cantidad
valuation	number	Valuacion total de la tenencia

6. Consideraciones

1. Validar el campo created_at antes de procesar ya que indica la fecha de creación hasta la cual se tomaron en cuenta los datos de Posición Consolidada del cliente.
2. Los saldos y valuaciones son considerados en el momento de la generación del archivo. Se debe validar la fecha de creación del mismo en el objeto Metadata