Bank account statements and balances

The accounting endpoints cover the full lifecycle of bank statement data in Marbes: uploading a raw bank Excel file and transforming it into a double-entry accounting format, persisting movements to the database, querying balances over a date range, and revaluing all fund positions at the current BCV rate. Every request must include a valid Authorization: Bearer <token> header.

Generate account statement from database

Method: GET
Path: /api/conta/estadoscuenta
Authentication: Bearer JWT required Queries bank movements stored in the database for a given date range, applies correlative numbering, and returns a ready-to-download .xlsx file formatted for double-entry bookkeeping. The file is streamed directly in the response body and deleted from the server once the download is complete.

Query parameters

fechaDesde

string

required

Start date for the report in YYYY-MM-DD format. Example: 2025-05-01.

fechaHasta

string

required

End date for the report in YYYY-MM-DD format. Example: 2025-05-31.

numero

number

required

Starting correlative number for the generated voucher entries. Each movement increments this number by one.

Response

On success the server responds with an Excel file attachment:

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="estado_cuenta_<timestamp>.xlsx"

The generated sheet contains these columns: Fecha, Nº Comp., Cod. Cuenta, Cuenta, Descripción de la Cuenta, Debe, Haber. Each movement produces two rows (a complete double-entry voucher).

Examples

curl --request GET \
  --url 'https://api.example.com/api/conta/estadoscuenta?fechaDesde=2025-05-01&fechaHasta=2025-05-31&numero=6452' \
  --header 'Authorization: Bearer <token>' \
  --output estado_cuenta.xlsx

Error responses

400

{
  "success": false,
  "message": "El parámetro \"fechaDesde\" es requerido (formato: YYYY-MM-DD)"
}

401

{
  "success": false,
  "message": "Usuario no autenticado"
}

Process bank Excel statement

Method: POST
Path: /api/conta/estadoscuenta
Authentication: Bearer JWT required
Content-Type: multipart/form-data Accepts a raw bank-exported Excel file, parses it according to the specified bank’s column layout, and transforms each movement into a double-entry accounting entry. The processed file is returned as a downloadable .xlsx attachment and then automatically deleted from the server.

Only Banco de Venezuela is fully implemented. Uploading a file for any other bank returns a 400 response with an informational message. Support for Banco Mercantil, Banesco, Banco Provincial, and others is planned.

Body parameters (multipart/form-data)

archivo

file

required

Excel file (.xls or .xlsx) exported from the bank. The field name can be archivo, file, or excel — the middleware accepts any name. Maximum size: 15 MB. The file must contain a sheet named data with the columns expected for the specified bank.

banco

string

required

Name of the bank that generated the statement. Must match exactly. Example: Banco de Venezuela.

numero

number

required

Starting correlative number for voucher entries. Must be a non-negative integer. Example: 6452.

Input file format (Banco de Venezuela)

The sheet named data must contain the following columns:

Column	Description	Example
`fecha`	Transaction date	`01/05/2025`
`referencia`	Reference number	`0120200000653`
`concepto`	Transaction description	`COM MANTENIMIENTO DE CUENTA`
`saldo`	Running balance	`97,45`
`monto`	Amount (positive = credit, negative = debit)	`-0,50`
`tipoMovimiento`	Movement type	`Nota de Débito`
`rif`	Company tax ID	`J404358226`
`numeroCuenta`	Account number	`01020135750000115296`

Rows with tipoMovimiento = Saldo Inicial and rows with monto = 0 are excluded automatically.

Output file format

Each movement produces two rows following double-entry rules:

Credit movement (monto > 0): Row 1 — bank account in Debe (code 111210, name BANCO DE VENEZUELA); Row 2 — counterpart in Haber (empty account).
Debit movement (monto < 0): Row 1 — counterpart in Debe (empty account); Row 2 — bank account in Haber (code 111210).

All amounts are shown as absolute values. Thousands separator is . (period); decimal separator is , (comma).

Response

On success the server responds with:

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="estado_cuenta_procesado.xlsx"

Examples

curl --request POST \
  --url https://api.example.com/api/conta/estadoscuenta \
  --header 'Authorization: Bearer <token>' \
  --form 'archivo=@estado_cuenta.xlsx' \
  --form 'banco=Banco de Venezuela' \
  --form 'numero=6452' \
  --output estado_cuenta_procesado.xlsx

Error responses

400 — banco not implemented

{
  "success": false,
  "message": "El banco \"Banco X\" no está implementado aún. Por el momento solo está disponible el procesamiento para \"Banco de Venezuela\"."
}

400 — missing file

{
  "success": false,
  "message": "No se ha proporcionado ningún archivo"
}

400 — missing banco field

{
  "success": false,
  "message": "El campo \"banco\" es requerido"
}

400 — invalid numero

{
  "success": false,
  "message": "El campo \"numero\" debe ser un número entero válido"
}

401

{
  "success": false,
  "message": "Usuario no autenticado"
}

Save bank movements to database

Method: POST
Path: /api/conta/movimientos-banco
Authentication: Bearer JWT required
Content-Type: multipart/form-data Parses the uploaded bank Excel file and persists the movements to the database without generating an output file. Existing movements for the same bank and date range are replaced. Returns counts of inserted and deleted records.

Body parameters (multipart/form-data)

archivo

file

required

Excel file (.xls or .xlsx) from the bank. Maximum size: 15 MB.

banco

string

required

Bank name. Example: Banco de Venezuela.

saldoInicial

number

Optional opening balance to associate with the imported movements.

Response fields

success

boolean

required

true when movements were saved successfully.

message

string

required

Human-readable result summary.

cantidadMovimientos

number

required

Number of movements inserted into the database.

cantidadEliminados

number

required

Number of existing movements deleted before the insert (replaced records).

Examples

curl --request POST \
  --url https://api.example.com/api/conta/movimientos-banco \
  --header 'Authorization: Bearer <token>' \
  --form 'archivo=@estado_cuenta.xlsx' \
  --form 'banco=Banco de Venezuela'

Success response

200

{
  "success": true,
  "message": "Movimientos guardados correctamente",
  "cantidadMovimientos": 24,
  "cantidadEliminados": 3
}

Get bank movements by date

Method: GET
Path: /api/conta/movimientos-banco
Authentication: Bearer JWT required Returns all bank movements stored in the database for a specific date.

Query parameters

fecha

string

required

Target date in YYYY-MM-DD format. Example: 2025-05-14.

Response fields

success

boolean

required

true on success.

fecha

string

required

The queried date, echoed back.

total

number

required

Total number of movements returned.

movimientos

object[]

required

Array of movement records for the date.

Examples

curl --request GET \
  --url 'https://api.example.com/api/conta/movimientos-banco?fecha=2025-05-14' \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "fecha": "2025-05-14",
  "total": 8,
  "movimientos": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "banco": "Banco de Venezuela",
      "fecha": "2025-05-14",
      "referencia": "672851791341",
      "concepto": "TRANSF RECIBIDA BDV V18588526",
      "monto": 104000.00,
      "saldo": 104097.45
    }
  ]
}

Get balances by date range

Method: GET
Path: /api/conta/saldos
Authentication: Bearer JWT required Returns the balance for each bank calculated over a date range, based on movements stored in the database.

Query parameters

fechaDesde

string

required

Start date in YYYY-MM-DD format.

fechaHasta

string

required

End date in YYYY-MM-DD format.

Response fields

success

boolean

required

true on success.

fechaDesde

string

required

Start date echoed back.

fechaHasta

string

required

End date echoed back.

totalBancos

number

required

Number of banks with movements in the queried range.

saldos

object[]

required

Array of balance summaries, one entry per bank.

Examples

curl --request GET \
  --url 'https://api.example.com/api/conta/saldos?fechaDesde=2025-05-01&fechaHasta=2025-05-31' \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "fechaDesde": "2025-05-01",
  "fechaHasta": "2025-05-31",
  "totalBancos": 2,
  "saldos": [
    {
      "banco": "Banco de Venezuela",
      "saldo_inicial": 97.95,
      "total_creditos": 104000.00,
      "total_debitos": 103900.50,
      "saldo_final": 197.45
    }
  ]
}

Revalue funds at current BCV rate

Method: GET
Path: /api/conta/revaluar-fondos
Authentication: Bearer JWT required Fetches the current official BCV (Banco Central de Venezuela) exchange rate and recalculates the USD/VES equivalent for all fund positions (TCOLs, bank movements, and TPRODs). The update applies different revaluation logic depending on the fund’s origin.

The revaluation logic differs by fund type: for Bóveda, the USD amount is fixed and VES is recalculated as USD × tasa_actual; for all other banks, the VES amount is fixed (calculated at the original rate) and USD is recalculated as VES / tasa_actual. This preserves the nominal currency in each context.

Response fields

success

boolean

required

true on success.

tasa_bcv

number

required

The BCV exchange rate (VES per USD) that was applied in this revaluation.

tcol_actualizados

number

required

Number of TCOL records updated.

movimientos_actualizados

number

required

Number of fund movement records updated.

tprod_actualizados

number

required

Number of TPROD records updated.

total_actualizados

number

required

Sum of all updated records across all types.

errores

string[]

required

List of error messages for individual records that could not be revalued. Empty array when all updates succeed.

tiene_errores

boolean

required

true if at least one record produced an error during revaluation.

Examples

curl --request GET \
  --url https://api.example.com/api/conta/revaluar-fondos \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "message": "Revaluación de fondos completada exitosamente",
  "tasa_bcv": 58.43,
  "tcol_actualizados": 12,
  "movimientos_actualizados": 8,
  "tprod_actualizados": 5,
  "total_actualizados": 25,
  "errores": [],
  "tiene_errores": false
}

500

{
  "success": false,
  "message": "Error interno del servidor",
  "error": "Error desconocido"
}

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Bank account statements and balances

Generate account statement from database

Query parameters

Response

Examples

Error responses

Process bank Excel statement

Body parameters (multipart/form-data)

Input file format (Banco de Venezuela)

Output file format

Response

Examples

Error responses

Save bank movements to database

Body parameters (multipart/form-data)

Response fields

Examples

Success response

Get bank movements by date

Query parameters

Response fields

Examples

Success response

Get balances by date range

Query parameters

Response fields

Examples

Success response

Revalue funds at current BCV rate

Response fields

Examples

Success response

Build docs developers (and LLMs) love

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Documentation Index

​Generate account statement from database

​Query parameters

​Response

​Examples

​Error responses

​Process bank Excel statement

​Body parameters (multipart/form-data)

​Input file format (Banco de Venezuela)

​Output file format

​Response

​Examples

​Error responses

​Save bank movements to database

​Body parameters (multipart/form-data)

​Response fields

​Examples

​Success response

​Get bank movements by date

​Query parameters

​Response fields

​Examples

​Success response

​Get balances by date range

​Query parameters

​Response fields

​Examples

​Success response

​Revalue funds at current BCV rate

​Response fields

​Examples

​Success response

Build docs developers (and LLMs) love

Generate account statement from database

Query parameters

Response

Examples

Error responses

Process bank Excel statement

Body parameters (multipart/form-data)

Input file format (Banco de Venezuela)

Output file format

Response

Examples

Error responses

Save bank movements to database

Body parameters (multipart/form-data)

Response fields

Examples

Success response

Get bank movements by date

Query parameters

Response fields

Examples

Success response

Get balances by date range

Query parameters

Response fields

Examples

Success response

Revalue funds at current BCV rate

Response fields

Examples

Success response