TCOL collections and TPROD loans reference

Marbes operates a two-sided ledger for every bank account. TCOL (colocación) records money flowing in — funds received from an investor under an active contract. TPROD (préstamo de producción) records money flowing out — capital lent to a credit client. A third record type, TCON (contrato cerrado), closes the loop when a contract is settled. The typical lifecycle is: investor signs contract → TCOL records each deposit → TPROD issues loans to clients → TCON closes the contract at maturity.

TCOL endpoints

Create TCOL

Records a new inbound fund collection tied to an investment contract. Method: POST
Path: /api/negocios/tcol
Authentication: Bearer JWT required
Content-Type: application/json

Body parameters

id_contrato

string

required

UUID of the investment contract this deposit belongs to.

id_compania

string

required

UUID of the company receiving or intermediating the funds.

monto

number

required

Base amount received. Must be greater than 0.

moneda

string

required

Currency of the deposit. One of VES, USD, or EUR.

tasa_bcv

number

required

BCV (Central Bank) exchange rate at the time of collection. Must be greater than 0.

id_banco

string

required

UUID of the bank account where the funds were received.

fecha_recibido

string

required

Date the funds were received, in YYYY-MM-DD format.

referencia

string

Bank transaction reference number. Optional; can be updated later.

estatus

string

Initial status of the TCOL record. One of aceptado, pendiente, devuelto, or rechazado. Defaults to pendiente.

costo_banco

number

Bank processing fee as a percentage (e.g., 0.25 for 0.25%). Defaults to 0 when omitted.

monto vs costo_banco: monto is the gross amount received before any fees. costo_banco is a separate percentage charged by the bank for processing the transfer. The net amount credited to the contract is monto - (monto * costo_banco / 100).

Response fields

string

Unique UUID for the TCOL record.

id_contrato

string

UUID of the linked investment contract.

id_compania

string | null

UUID of the linked company.

compania

string | null

Company name.

monto

number

Gross amount received.

moneda

string

Currency code (VES, USD, EUR).

costo_banco

number

Bank fee percentage applied.

tasa_bcv

number

BCV exchange rate at time of collection.

id_banco

string

UUID of the receiving bank.

banco

string

Bank name.

referencia

string | null

Transaction reference number.

fecha_recibido

string

Date funds were received.

estatus

string

Status: aceptado, pendiente, devuelto, or rechazado.

responsable

string | null

Name of the user who created the record.

update_by

string | null

ID of the user who last updated this record.

updated_at

string

ISO 8601 timestamp of the last update.

fecha_registro

string

ISO 8601 date of original registration.

Examples

curl --request POST \
  --url https://api.example.com/api/negocios/tcol \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id_contrato": "c1d2e3f4-a5b6-7890-cdef-012345678901",
    "id_compania": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
    "monto": 50000,
    "moneda": "USD",
    "tasa_bcv": 36.50,
    "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
    "fecha_recibido": "2025-02-05",
    "referencia": "TRF-20250205-001",
    "costo_banco": 0.25
  }'

Success response

201

{
  "id": "t1c2o3l4-5678-9012-abcd-ef3456789012",
  "id_contrato": "c1d2e3f4-a5b6-7890-cdef-012345678901",
  "id_compania": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
  "compania": "Inversiones Marbes C.A.",
  "monto": 50000,
  "moneda": "USD",
  "costo_banco": 0.25,
  "tasa_bcv": 36.50,
  "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
  "banco": "Banco de Venezuela",
  "referencia": "TRF-20250205-001",
  "fecha_recibido": "2025-02-05",
  "estatus": "pendiente",
  "responsable": "Ana López",
  "update_by": null,
  "updated_at": "2025-02-05T10:00:00.000Z",
  "fecha_registro": "2025-02-05"
}

Error responses

400

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

400

{
  "success": false,
  "message": "Formato de fecha_recibido inválido. Use YYYY-MM-DD"
}

401

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

Update TCOL

Updates the status or observations on an existing TCOL record. This route is under the /api/bancos prefix. Method: PUT
Path: /api/bancos/tcol/:id
Authentication: Bearer JWT required
Content-Type: application/json

Path parameters

string

required

UUID of the TCOL record to update.

Body parameters

estatus

string

New status. One of aceptado, pendiente, devuelto, or rechazado.

observaciones

string

Notes or observations about the status change.

Examples

curl --request PUT \
  --url https://api.example.com/api/bancos/tcol/t1c2o3l4-5678-9012-abcd-ef3456789012 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "estatus": "aceptado",
    "observaciones": "Transferencia verificada por el área contable"
  }'

Success response

200

{
  "success": true,
  "tcol": {
    "id": "t1c2o3l4-5678-9012-abcd-ef3456789012",
    "estatus": "aceptado",
    "observaciones": "Transferencia verificada por el área contable",
    "updated_at": "2025-02-06T08:30:00.000Z"
  }
}

Bulk accept TPROD with guarantee files

Accepts a batch of TPROD records, optionally attaching guarantee files to each entry. This route is under the /api/bancos prefix. Method: POST
Path: /api/bancos/tprod/aceptar-lote
Authentication: Bearer JWT required
Content-Type: multipart/form-data

Body parameters

ids

array

Array of TPROD UUIDs to accept in bulk.

garantia

file

One or more guarantee files to attach to all records in the batch.

Examples

curl --request POST \
  --url https://api.example.com/api/bancos/tprod/aceptar-lote \
  --header 'Authorization: Bearer <token>' \
  --form 'ids=["p1r2o3d4-5678-9012-abcd-ef0123456789","p9r8o7d6-5432-1098-fedc-ba9876543210"]' \
  --form 'garantia=@/path/to/batch-guarantee.pdf'

TPROD endpoints

Create TPROD

Records a new outbound loan disbursement to a credit client. Requires that the client has sufficient available credit and the bank has sufficient TCOL-backed funds. Method: POST
Path: /api/negocios/tprod
Authentication: Bearer JWT required
Content-Type: multipart/form-data

Body parameters

id_banco

string

required

UUID of the bank account from which the funds are disbursed.

id_cliente

string

required

UUID of the credit client receiving the loan.

monto

number

required

Base loan amount disbursed to the client. Must be greater than 0.

monto_comision

number

required

Commission charged on the loan, expressed as a percentage (e.g., 15 for 15%).

moneda

string

required

Currency of the loan. One of VES, USD, or EUR.

tasa_bcv

number

required

BCV exchange rate at the time of disbursement.

plazo_cantidad

number

required

Numeric loan term duration.

plazo_opcion

string

required

Loan term unit. One of dias, mes, or ano.

fecha_inicio

string

required

Loan disbursement date in YYYY-MM-DD format.

costo_banco

number

Bank processing fee as a percentage. Defaults to 0 when omitted.

cliente

string

Client display name. Optional override if different from the stored client name.

referencia

string

Bank transaction reference. Optional; can be updated later.

estatus

string

Initial loan status. One of pendiente, aceptado, devuelto, or rechazado. Defaults to pendiente.

garantia

file

One or more guarantee files for this loan (e.g., signed contract PDF). Attached as multipart file fields.

responsable_id

string

UUID of the user responsible for this loan. If omitted, defaults to the authenticated user’s ID.

monto vs monto_comision: monto is the principal amount disbursed to the client — the base amount on which the loan is calculated. monto_comision is a percentage applied on top of monto as a service commission. The total amount owed by the client is monto + (monto * monto_comision / 100), stored as monto_total in the TPROD record.

Response fields

string

Unique UUID for the TPROD record.

id_tcol

string

UUID of the TCOL record that backs this loan.

id_cliente

string

UUID of the borrowing client.

monto_total

number

Total amount owed (principal + commission).

monto_prestado

number

Principal amount disbursed.

monto_comision

number

Commission percentage applied.

monto_pagado

number

Amount already repaid by the client.

costo_banco

number

Bank fee percentage applied.

moneda

string

Currency code (VES, USD, EUR).

plazo_cantidad

number

Loan term duration.

plazo_opcion

string

Loan term unit (dias, mes, ano).

id_banco

string

UUID of the disbursing bank.

banco

string

Bank name.

referencia

string | null

Transaction reference number.

fecha_inicio

string

Loan start date.

fecha_fin

string

Calculated loan end date.

observacion

string

Observations or notes on the loan.

responsable

string | null

Name of the responsible user.

garantia

string

JSON string with paths to guarantee files.

estatus

string

Loan status: aceptado, pendiente, devuelto, rechazado, or mora.

update_by

string | null

ID of the user who last updated this record.

updated_at

string

ISO 8601 timestamp of the last update.

fecha_registro

string

ISO 8601 date of original registration.

Examples

curl --request POST \
  --url https://api.example.com/api/negocios/tprod \
  --header 'Authorization: Bearer <token>' \
  --form 'id_banco=f0e1d2c3-b4a5-6789-0abc-def012345678' \
  --form 'id_cliente=e5f6a7b8-c9d0-1234-ef01-234567890abc' \
  --form 'monto=25000' \
  --form 'monto_comision=15' \
  --form 'moneda=USD' \
  --form 'tasa_bcv=36.50' \
  --form 'plazo_cantidad=3' \
  --form 'plazo_opcion=mes' \
  --form 'fecha_inicio=2025-02-10' \
  --form 'garantia=@/path/to/loan-contract.pdf'

Success response

201

{
  "id": "p1r2o3d4-5678-9012-abcd-ef0123456789",
  "id_tcol": "t1c2o3l4-5678-9012-abcd-ef3456789012",
  "id_cliente": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
  "monto_total": 28750,
  "monto_prestado": 25000,
  "monto_comision": 15,
  "monto_pagado": 0,
  "costo_banco": 0,
  "moneda": "USD",
  "plazo_cantidad": 3,
  "plazo_opcion": "mes",
  "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
  "banco": "Banco de Venezuela",
  "referencia": null,
  "fecha_inicio": "2025-02-10",
  "fecha_fin": "2025-05-10",
  "observacion": "",
  "responsable": "Ana López",
  "garantia": "[\"uploads/clientes/e5f6a7b8/loan-contract.pdf\"]",
  "estatus": "pendiente",
  "update_by": null,
  "updated_at": "2025-02-10T09:00:00.000Z",
  "fecha_registro": "2025-02-10"
}

Error responses

400

{
  "success": false,
  "message": "El cliente no tiene crédito disponible suficiente"
}

401

{
  "success": false,
  "message": "Usuario no autenticado o responsable_id no proporcionado"
}

List all TPROD

Returns all TPROD loan records in the system. Method: GET
Path: /api/negocios/tprod
Authentication: Bearer JWT required

Examples

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

Success response

200

{
  "success": true,
  "contratos": [
    {
      "id": "p1r2o3d4-5678-9012-abcd-ef0123456789",
      "id_cliente": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
      "monto_total": 28750,
      "monto_prestado": 25000,
      "moneda": "USD",
      "estatus": "aceptado",
      "fecha_inicio": "2025-02-10",
      "fecha_fin": "2025-05-10"
    }
  ]
}

Get TPROD by ID

Returns the full details of a single TPROD loan record. Method: GET
Path: /api/negocios/tprod/:id
Authentication: Bearer JWT required

Path parameters

string

required

UUID of the TPROD record to retrieve.

Examples

curl --request GET \
  --url https://api.example.com/api/negocios/tprod/p1r2o3d4-5678-9012-abcd-ef0123456789 \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "contratos": {
    "id": "p1r2o3d4-5678-9012-abcd-ef0123456789",
    "id_tcol": "t1c2o3l4-5678-9012-abcd-ef3456789012",
    "id_cliente": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
    "monto_total": 28750,
    "monto_prestado": 25000,
    "monto_comision": 15,
    "monto_pagado": 0,
    "costo_banco": 0,
    "moneda": "USD",
    "plazo_cantidad": 3,
    "plazo_opcion": "mes",
    "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
    "banco": "Banco de Venezuela",
    "referencia": null,
    "fecha_inicio": "2025-02-10",
    "fecha_fin": "2025-05-10",
    "observacion": "",
    "responsable": "Ana López",
    "garantia": "[\"uploads/clientes/e5f6a7b8/loan-contract.pdf\"]",
    "estatus": "aceptado",
    "update_by": null,
    "updated_at": "2025-02-10T09:00:00.000Z",
    "fecha_registro": "2025-02-10"
  }
}

Error responses

404

{
  "success": false,
  "message": "TPROD no encontrado"
}

Update TPROD

Updates a TPROD record’s status, observations, or guarantee files. This route is under the /api/bancos prefix. Method: POST
Path: /api/bancos/tprod/:id
Authentication: Bearer JWT required
Content-Type: multipart/form-data

Path parameters

string

required

UUID of the TPROD record to update.

Body parameters

estatus

string

New loan status. One of pendiente, aceptado, devuelto, rechazado, or mora.

observacion

string

Notes or observations about this update.

referencia

string

Bank transaction reference number for this disbursement.

garantia

file

Additional guarantee files to attach. New files are appended to existing ones.

Examples

curl --request POST \
  --url https://api.example.com/api/bancos/tprod/p1r2o3d4-5678-9012-abcd-ef0123456789 \
  --header 'Authorization: Bearer <token>' \
  --form 'estatus=aceptado' \
  --form 'referencia=TRF-20250210-005' \
  --form 'garantia=@/path/to/signed-receipt.pdf'

Success response

200

{
  "success": true,
  "tprod": {
    "id": "p1r2o3d4-5678-9012-abcd-ef0123456789",
    "estatus": "aceptado",
    "referencia": "TRF-20250210-005",
    "updated_at": "2025-02-10T11:00:00.000Z"
  }
}

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Documentation Index

​TCOL endpoints

​Create TCOL

​Body parameters

​Response fields

​Examples

​Success response

​Error responses

​Update TCOL

​Path parameters

​Body parameters

​Examples

​Success response

​Bulk accept TPROD with guarantee files

​Body parameters

​Examples

​TPROD endpoints

​Create TPROD

​Body parameters

​Response fields

​Examples

​Success response

​Error responses

​List all TPROD

​Examples

​Success response

​Get TPROD by ID

​Path parameters

​Examples

​Success response

​Error responses

​Update TPROD

​Path parameters

​Body parameters

​Examples

​Success response

Build docs developers (and LLMs) love

TCOL endpoints

Create TCOL

Body parameters

Response fields

Examples

Success response

Error responses

Update TCOL

Path parameters

Body parameters

Examples

Success response

Bulk accept TPROD with guarantee files

Body parameters

Examples

TPROD endpoints

Create TPROD

Body parameters

Response fields

Examples

Success response

Error responses

List all TPROD

Examples

Success response

Get TPROD by ID

Path parameters

Examples

Success response

Error responses

Update TPROD

Path parameters

Body parameters

Examples

Success response