TCOL fund movement and tracing endpoints

The fund movement layer in Marbes operates across three interconnected entities. A TPROD is a guarantee or loan product record that holds funds on behalf of a client. A TCOL (colateral account) is a bank-level fund container associated with a loan contract; funds flow in and out of TCOLs during the life of a contract. A TCON is a payment transaction tied to a specific TPROD — it records money received from a client against their credit obligation. Together these three entities form the complete audit trail for every bolivar that enters or leaves the system.

TCOL, TPROD, and TCON are tightly coupled. A TPROD sources funds that populate a TCOL. A TCON records client payments against the same TPROD. Moving funds between TCOLs creates a traceable entry that you can later inspect with GET /api/bancos/tcol/:idTcol/traza. Always record the id_tprod on a TCON so that the TPROD balance updates correctly.

POST /api/bancos/tcol/mover-fondos

Moves a specified amount from one TCOL bank account to another. The operation is atomic: the source TCOL balance is debited and the destination TCOL balance is credited in the same database transaction. A movement trace record is written automatically so the transfer can be audited later. Authentication: Required

Request body

id_banco_origen

string

required

UUID of the source bank (TCOL account to debit).

id_banco_destino

string

required

UUID of the destination bank (TCOL account to credit).

monto_a_mover

number

required

Amount to transfer. Must be a positive value in the specified currency.

moneda

string

required

Currency of the transfer. Allowed values: VES, USD, EUR.

observacion

string

Optional note describing the reason for the fund movement.

Response

success

boolean

required

true when the movement completes without errors.

message

string

required

Human-readable confirmation message.

monto_movido

number

required

The exact amount transferred.

tcol_actualizados

object[]

required

TCOL records whose available balance was reduced (source side).

Show tcol_actualizado properties

string

TCOL record ID.

id_contrato

string

Associated loan contract ID.

monto_tomado

number

Amount taken from this TCOL record.

nuevo_disponible

number

Remaining available balance after the debit.

tcol_creados

object[]

required

New TCOL records created on the destination bank to hold the received funds.

Show tcol_creado properties

string

New TCOL record ID.

id_contrato

string

Associated loan contract ID.

monto

number

Amount assigned to this new TCOL record.

id_banco

string

Destination bank ID.

curl --request POST \
  --url https://api.marbes.org/api/bancos/tcol/mover-fondos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id_banco_origen": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "id_banco_destino": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "monto_a_mover": 5000.00,
    "moneda": "USD",
    "observacion": "Rebalanceo mensual de fondos"
  }'

200 Success

{
  "success": true,
  "message": "Fondos movidos exitosamente",
  "monto_movido": 5000.00,
  "tcol_actualizados": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "id_contrato": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "monto_tomado": 5000.00,
      "nuevo_disponible": 12500.00
    }
  ],
  "tcol_creados": [
    {
      "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "id_contrato": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "monto": 5000.00,
      "id_banco": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    }
  ]
}

400 Bad Request

{
  "success": false,
  "message": "Los campos id_banco_origen, id_banco_destino, monto_a_mover y moneda son requeridos"
}

401 Unauthorized

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

POST /api/bancos/tcol/:id/fondos

Adds funds to an existing TCOL record by sourcing them from a TPROD (guarantee). This is the primary mechanism for capitalizing a TCOL with funds that were originally held in a loan product guarantee. Authentication: Required

Path parameters

string

required

UUID of the TCOL record to receive the funds.

Request body

monto

number

required

Amount to add to the TCOL. Must be positive.

moneda

string

required

Currency of the amount. Allowed values: VES, USD, EUR.

id_tprod

string

required

UUID of the TPROD that is the source of these funds.

id_banco

string

required

UUID of the bank where the TCOL account is held.

id_cliente

string

required

UUID of the client associated with the TPROD and TCOL.

tasa_bcv

number

required

BCV exchange rate (VES/USD) used to convert the amount if currencies differ.

curl --request POST \
  --url https://api.marbes.org/api/bancos/tcol/c3d4e5f6-a7b8-9012-cdef-123456789012/fondos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "monto": 2500.00,
    "moneda": "USD",
    "id_tprod": "f7a8b9c0-d1e2-3456-fabc-456789012345",
    "id_banco": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "id_cliente": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "tasa_bcv": 36.45
  }'

201 Created

{
  "success": true,
  "data": {
    "id_tcol": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "monto_agregado": 2500.00,
    "moneda": "USD",
    "id_tprod": "f7a8b9c0-d1e2-3456-fabc-456789012345",
    "nuevo_disponible": 7500.00
  }
}

400 Bad Request

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

GET /api/bancos/tcol/:idTcol/traza

Returns the full movement trace for a TCOL record — an ordered history of every fund addition, deduction, and transfer that has touched the account. Use this endpoint to audit where funds originated and where they were sent. Authentication: Required

Path parameters

idTcol

string

required

UUID of the TCOL record whose movement history you want to retrieve.

Response

success

boolean

required

true when the trace is retrieved successfully.

data

object

required

Tracing result containing movement history for the specified TCOL.

Show data properties

id_tcol

string

The queried TCOL record ID.

movimientos

object[]

Ordered list of movement events.

Show movimiento properties

string

Movement record ID.

tipo

string

Movement direction: entrada (funds added) or salida (funds removed).

monto

number

Amount involved in the movement.

moneda

string

Currency of the movement.

origen

string

Source description (bank name or TPROD reference).

destino

string

Destination description.

fecha

string

ISO 8601 timestamp of the movement.

responsable

string

UUID of the user who triggered the movement.

curl --request GET \
  --url https://api.marbes.org/api/bancos/tcol/c3d4e5f6-a7b8-9012-cdef-123456789012/traza \
  --header 'Authorization: Bearer <token>'

200 Success

{
  "success": true,
  "data": {
    "id_tcol": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "movimientos": [
      {
        "id": "g8h9i0j1-k2l3-4567-mnop-789012345678",
        "tipo": "entrada",
        "monto": 2500.00,
        "moneda": "USD",
        "origen": "TPROD f7a8b9c0",
        "destino": "TCOL c3d4e5f6",
        "fecha": "2024-06-01T09:00:00.000Z",
        "responsable": "user-uuid"
      },
      {
        "id": "h9i0j1k2-l3m4-5678-nopq-890123456789",
        "tipo": "salida",
        "monto": 1000.00,
        "moneda": "USD",
        "origen": "TCOL c3d4e5f6",
        "destino": "Banco Mercantil TCOL",
        "fecha": "2024-06-15T14:30:00.000Z",
        "responsable": "user-uuid"
      }
    ]
  }
}

400 Bad Request

{
  "success": false,
  "message": "El id_tcol es requerido"
}

GET /api/bancos/tcon

Returns all TCON payment records in the system. Authentication: Required

Response

success

boolean

required

true when the request succeeds.

tcon

object[]

required

Array of TCON records.

Show TCON properties

string

Unique TCON identifier (UUID).

id_tprod

string

UUID of the linked TPROD loan record.

monto

number

Payment amount.

moneda

string

Currency: VES, USD, or EUR.

id_banco

string

UUID of the bank through which the payment was received.

banco

string

Display name of the bank.

referencia

string

Optional payment reference number. May be null.

fecha_recibido

string

Date the payment was received (YYYY-MM-DD).

estatus

string

One of aceptado, pendiente, devuelto, rechazado.

responsable

string

UUID of the user who created the record. May be null.

update_by

string

UUID of the user who last updated the record. May be null.

fecha_registro

string

ISO 8601 timestamp of when the record was created.

updated_at

string

ISO 8601 last-updated timestamp.

curl --request GET \
  --url https://api.marbes.org/api/bancos/tcon \
  --header 'Authorization: Bearer <token>'

200 Success

{
  "success": true,
  "tcon": [
    {
      "id": "i0j1k2l3-m4n5-6789-opqr-901234567890",
      "id_tprod": "f7a8b9c0-d1e2-3456-fabc-456789012345",
      "monto": 1500.00,
      "moneda": "USD",
      "id_banco": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "banco": "Banco de Venezuela",
      "referencia": "REF-20240601-001",
      "fecha_recibido": "2024-06-01",
      "estatus": "aceptado",
      "responsable": "user-uuid",
      "update_by": null,
      "fecha_registro": "2024-06-01T10:00:00.000Z",
      "updated_at": "2024-06-01T10:00:00.000Z"
    }
  ]
}

POST /api/bancos/tcon

Creates a new TCON payment record linked to a TPROD loan. Creating a TCON signals that a client payment has been received and is pending approval. The associated TPROD balance is updated once the TCON is approved via PUT /api/bancos/tcon/:id. Authentication: Required

Request body

id_tprod

string

required

UUID of the TPROD loan record this payment applies to.

monto

number

required

Payment amount received.

moneda

string

required

Currency of the payment. Allowed values: VES, USD, EUR.

id_banco

string

required

UUID of the bank through which the payment was received.

fecha_recibido

string

required

Date the payment was received. Format: YYYY-MM-DD.

tasa_bcv

number

required

BCV exchange rate (VES/USD) at the time of the payment. Used for cross-currency reconciliation.

cliente

string

Display name of the client making the payment. Used for notifications.

referencia

string

Bank reference number for the payment transaction.

estatus

string

Initial status. Defaults to pendiente. Allowed values: aceptado, pendiente, devuelto, rechazado.

fecha_registro

string

Optional manual registration timestamp. Defaults to the server’s current time when omitted.

curl --request POST \
  --url https://api.marbes.org/api/bancos/tcon \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id_tprod": "f7a8b9c0-d1e2-3456-fabc-456789012345",
    "monto": 1500.00,
    "moneda": "USD",
    "id_banco": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "fecha_recibido": "2024-06-01",
    "tasa_bcv": 36.45,
    "cliente": "Juan Pérez",
    "referencia": "REF-20240601-001"
  }'

201 Created

{
  "success": true,
  "data": {
    "id": "i0j1k2l3-m4n5-6789-opqr-901234567890",
    "id_tprod": "f7a8b9c0-d1e2-3456-fabc-456789012345",
    "monto": 1500.00,
    "moneda": "USD",
    "id_banco": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "referencia": "REF-20240601-001",
    "fecha_recibido": "2024-06-01",
    "estatus": "pendiente",
    "fecha_registro": "2024-06-01T10:00:00.000Z"
  }
}

400 Bad Request

{
  "success": false,
  "message": "Los campos id_tprod, monto, moneda, id_banco y fecha_recibido son requeridos"
}

GET /api/bancos/tcon/tprod/:idTprod

Returns all TCON payment records associated with a specific TPROD loan. Authentication: Required

Path parameters

idTprod

string

required

UUID of the TPROD whose payment records you want to retrieve.

Response

success

boolean

required

true when the request succeeds.

tcon

object[]

required

Array of TCON records for the specified TPROD. See GET /api/bancos/tcon for the record shape.

curl --request GET \
  --url https://api.marbes.org/api/bancos/tcon/tprod/f7a8b9c0-d1e2-3456-fabc-456789012345 \
  --header 'Authorization: Bearer <token>'

200 Success

{
  "success": true,
  "tcon": [
    {
      "id": "i0j1k2l3-m4n5-6789-opqr-901234567890",
      "id_tprod": "f7a8b9c0-d1e2-3456-fabc-456789012345",
      "monto": 1500.00,
      "moneda": "USD",
      "banco": "Banco de Venezuela",
      "referencia": "REF-20240601-001",
      "fecha_recibido": "2024-06-01",
      "estatus": "aceptado"
    }
  ]
}

PUT /api/bancos/tcon/:id

Updates the status and optional metadata of a TCON payment record. Approving a TCON (estatus: "aceptado") triggers a balance update on the linked TPROD and notifies the relevant Slack channel via the n8n webhook integration. Authentication: Required

Path parameters

string

required

UUID of the TCON record to update.

Request body

estatus

string

required

New status for the TCON. Allowed values: aceptado, pendiente, devuelto, rechazado.

observacion

string

Explanation for the status change. Required when estatus is anything other than aceptado.

monto_comision

number

Optional commission percentage (e.g., 18 for 18%). When provided, the linked TPROD’s monto_total is recalculated as monto_prestado + (monto_prestado × monto_comision / 100) before applying the payment.

Response

success

boolean

required

true when the update is applied.

data

object

required

Updated TCON record with recalculated TPROD balance fields.

Show data properties

string

TCON record ID.

estatus

string

Updated status.

banco_nombre

string

Name of the bank associated with this TCON.

fondos_disponible_contrato

number

Remaining available balance on the loan contract (USD).

fondos_disponible_ves

number

Remaining available balance on the loan contract (VES).

curl --request PUT \
  --url https://api.marbes.org/api/bancos/tcon/i0j1k2l3-m4n5-6789-opqr-901234567890 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "estatus": "aceptado"
  }'

200 Success

{
  "success": true,
  "data": {
    "id": "i0j1k2l3-m4n5-6789-opqr-901234567890",
    "estatus": "aceptado",
    "banco_nombre": "Banco de Venezuela",
    "fondos_disponible_contrato": 8500.00,
    "fondos_disponible_ves": 309825.00
  }
}

400 Bad Request — missing observacion

{
  "success": false,
  "message": "La observación es requerida cuando el estatus es diferente de \"aceptado\""
}

400 Bad Request — invalid estatus

{
  "success": false,
  "message": "Estatus inválido. Valores permitidos: aceptado, pendiente, devuelto, rechazado"
}

401 Unauthorized

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

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

TCOL fund movement and tracing endpoints

POST /api/bancos/tcol/mover-fondos

Request body

Response

POST /api/bancos/tcol/:id/fondos

Path parameters

Request body

GET /api/bancos/tcol/:idTcol/traza

Path parameters

Response

GET /api/bancos/tcon

Response

POST /api/bancos/tcon

Request body

GET /api/bancos/tcon/tprod/:idTprod

Path parameters

Response

PUT /api/bancos/tcon/:id

Path parameters

Request body

Response

Build docs developers (and LLMs) love

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Documentation Index

​POST /api/bancos/tcol/mover-fondos

​Request body

​Response

​POST /api/bancos/tcol/:id/fondos

​Path parameters

​Request body

​GET /api/bancos/tcol/:idTcol/traza

​Path parameters

​Response

​GET /api/bancos/tcon

​Response

​POST /api/bancos/tcon

​Request body

​GET /api/bancos/tcon/tprod/:idTprod

​Path parameters

​Response

​PUT /api/bancos/tcon/:id

​Path parameters

​Request body

​Response

Build docs developers (and LLMs) love

POST /api/bancos/tcol/mover-fondos

Request body

Response

POST /api/bancos/tcol/:id/fondos

Path parameters

Request body

GET /api/bancos/tcol/:idTcol/traza

Path parameters

Response

GET /api/bancos/tcon

Response

POST /api/bancos/tcon

Request body

GET /api/bancos/tcon/tprod/:idTprod

Path parameters

Response

PUT /api/bancos/tcon/:id

Path parameters

Request body

Response