Fund control (control de fondos) endpoints

Fund control (control de fondos) is an intermediate step between collecting funds (TCOL) and disbursing loans (TPROD). An operator pre-allocates a specific amount from a bank’s available TCOL balance and assigns it to one or more executives. Those executives can then draw from the allocation when creating TPROD loans, ensuring funds are not over-committed and that each executive’s spending stays within the approved limit. The full flow is: TCOL received → control de fondos created (pre-allocation) → executive registers usage → TPROD loan issued against the used amount.

Create fund control

Creates a new fund control allocation, assigning a portion of a bank’s available TCOL balance to a set of executives. Method: POST
Path: /api/negocios/control-fondos
Authentication: Bearer JWT required
Content-Type: application/json

Body parameters

operador_id

string

required

UUID of the operator (supervisor) responsible for this allocation.

ejecutivos_ids

array

required

Array of UUIDs of the executives authorized to use these funds.

id_compania

string

required

UUID of the company whose TCOL balance backs this allocation.

id_banco

string

required

UUID of the bank account from which funds are pre-allocated.

fecha_inicio

string

required

Start date of the allocation period in YYYY-MM-DD format.

fecha_fin

string

required

End date of the allocation period in YYYY-MM-DD format.

tasa_bcv

number

required

BCV exchange rate at the time of allocation. Accepts the field as either tasa_bcv or tasaBCV.

monto_asignado

number

required

Total amount pre-allocated from the bank’s available TCOL balance.

moneda

string

Currency of the allocation. One of VES, USD, or EUR. Optional; inherits from the bank when omitted.

observacion

string

Notes or context about why this allocation was created.

estatus

string

Initial status. One of activo, suspendido, finalizado, or cancelado. Defaults to activo.

Response fields

string

Unique UUID for the fund control record.

operador_id

string

UUID of the supervising operator.

ejecutivos_ids

array

Array of executive UUIDs authorized to use the allocation.

id_compania

string

UUID of the backing company.

id_banco

string

UUID of the bank account.

fecha_inicio

string

Allocation start date.

fecha_fin

string

Allocation end date.

moneda

string

Currency code (VES, USD, EUR).

tasa_bcv

number

BCV exchange rate applied.

monto_asignado

number

Total amount pre-allocated.

monto_usado

number

Amount already consumed via usage registrations.

monto_disponible

number

Remaining usable amount (monto_asignado - monto_usado).

estatus

string

Current status: activo, suspendido, finalizado, or cancelado.

observacion

string | null

Notes on the allocation.

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.

created_at

string

ISO 8601 timestamp of record creation.

Examples

curl --request POST \
  --url https://api.example.com/api/negocios/control-fondos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "operador_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ejecutivos_ids": [
      "b2c3d4e5-f6a7-8901-bcde-f01234567891",
      "c3d4e5f6-a7b8-9012-cdef-012345678912"
    ],
    "id_compania": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
    "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
    "fecha_inicio": "2025-03-01",
    "fecha_fin": "2025-03-31",
    "tasa_bcv": 36.50,
    "monto_asignado": 80000,
    "moneda": "USD",
    "observacion": "Asignación mensual para equipo Caracas"
  }'

Success response

201

{
  "id": "cf112233-4455-6677-8899-aabbccddeeff",
  "operador_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ejecutivos_ids": [
    "b2c3d4e5-f6a7-8901-bcde-f01234567891",
    "c3d4e5f6-a7b8-9012-cdef-012345678912"
  ],
  "id_compania": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
  "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
  "fecha_inicio": "2025-03-01",
  "fecha_fin": "2025-03-31",
  "moneda": "USD",
  "tasa_bcv": 36.50,
  "monto_asignado": 80000,
  "monto_usado": 0,
  "monto_disponible": 80000,
  "estatus": "activo",
  "observacion": "Asignación mensual para equipo Caracas",
  "responsable": "Ana López",
  "update_by": null,
  "updated_at": "2025-03-01T08:00:00.000Z",
  "fecha_registro": "2025-03-01",
  "created_at": "2025-03-01T08:00:00.000Z"
}

Error responses

400

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

401

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

Register fund usage

Records a draw against an existing fund control allocation by an authorized executive. Each usage registration decrements monto_disponible and increments monto_usado. Method: POST
Path: /api/negocios/control-fondos/:id/uso
Authentication: Bearer JWT required
Content-Type: application/json

Path parameters

string

required

UUID of the fund control record to draw from.

Body parameters

id_ejecutivo

string

required

UUID of the executive consuming the funds. Must be one of the ejecutivos_ids on the control record.

monto_uso

number

required

Amount being drawn from the allocation. Must not exceed monto_disponible.

observacion

string

Optional note about what these funds are being used for.

Examples

curl --request POST \
  --url https://api.example.com/api/negocios/control-fondos/cf112233-4455-6677-8899-aabbccddeeff/uso \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id_ejecutivo": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
    "monto_uso": 25000,
    "observacion": "Préstamo TPROD cliente Sofía Mendoza"
  }'

Success response

200

{
  "success": true,
  "control": {
    "id": "cf112233-4455-6677-8899-aabbccddeeff",
    "monto_asignado": 80000,
    "monto_usado": 25000,
    "monto_disponible": 55000,
    "estatus": "activo"
  }
}

Error responses

400

{
  "success": false,
  "message": "El monto de uso excede el disponible"
}

400

{
  "success": false,
  "message": "El ejecutivo no está autorizado en este control de fondos"
}

Update fund control

Updates one or more fields on an existing fund control record. All fields are optional; only the fields you include are changed. Method: PUT
Path: /api/negocios/control-fondos/:id
Authentication: Bearer JWT required
Content-Type: application/json

Path parameters

string

required

UUID of the fund control record to update.

Body parameters

operador_id

string

UUID of the new supervising operator.

ejecutivos_ids

array

Replacement array of authorized executive UUIDs.

id_compania

string

UUID of the new backing company.

id_banco

string

UUID of the new bank account.

fecha_inicio

string

New allocation start date in YYYY-MM-DD format.

fecha_fin

string

New allocation end date in YYYY-MM-DD format.

moneda

string

Currency override. One of VES, USD, or EUR.

tasa_bcv

number

Updated BCV exchange rate. Also accepts tasaBCV.

monto_asignado

number

New total allocation amount. Must be at least as large as monto_usado.

estatus

string

New status. One of activo, suspendido, finalizado, or cancelado.

observacion

string | null

Updated notes. Pass null to clear.

Examples

curl --request PUT \
  --url https://api.example.com/api/negocios/control-fondos/cf112233-4455-6677-8899-aabbccddeeff \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "estatus": "suspendido",
    "observacion": "Suspendido temporalmente por auditoría interna"
  }'

Success response

200

{
  "success": true,
  "control": {
    "id": "cf112233-4455-6677-8899-aabbccddeeff",
    "estatus": "suspendido",
    "observacion": "Suspendido temporalmente por auditoría interna",
    "updated_at": "2025-03-15T10:00:00.000Z"
  }
}

Error responses

400

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

401

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

List fund controls

Returns fund control records, with optional query filters to narrow results. Method: GET
Path: /api/negocios/control-fondos
Authentication: Bearer JWT required

Query parameters

estatus

string

Filter by status. One of activo, suspendido, finalizado, or cancelado.

id_operador

string

Filter by operator UUID.

id_banco

string

Filter by bank UUID.

id_compania

string

Filter by company UUID.

id_ejecutivo

string

Filter to controls where this executive UUID appears in ejecutivos_ids.

solo_vigentes

string

Pass true to return only controls where the current date falls between fecha_inicio and fecha_fin.

Examples

curl --request GET \
  --url 'https://api.example.com/api/negocios/control-fondos?estatus=activo&solo_vigentes=true' \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "data": [
    {
      "id": "cf112233-4455-6677-8899-aabbccddeeff",
      "operador_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ejecutivos_ids": [
        "b2c3d4e5-f6a7-8901-bcde-f01234567891",
        "c3d4e5f6-a7b8-9012-cdef-012345678912"
      ],
      "id_compania": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
      "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
      "fecha_inicio": "2025-03-01",
      "fecha_fin": "2025-03-31",
      "moneda": "USD",
      "tasa_bcv": 36.50,
      "monto_asignado": 80000,
      "monto_usado": 25000,
      "monto_disponible": 55000,
      "estatus": "activo",
      "observacion": "Asignación mensual para equipo Caracas",
      "responsable": "Ana López",
      "update_by": null,
      "updated_at": "2025-03-01T08:00:00.000Z",
      "fecha_registro": "2025-03-01",
      "created_at": "2025-03-01T08:00:00.000Z"
    }
  ]
}

Error responses

500

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

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Fund control (control de fondos) endpoints

Create fund control

Body parameters

Response fields

Examples

Success response

Error responses

Register fund usage

Path parameters

Body parameters

Examples

Success response

Error responses

Update fund control

Path parameters

Body parameters

Examples

Success response

Error responses

List fund controls

Query parameters

Examples

Success response

Error responses

Build docs developers (and LLMs) love

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Documentation Index

​Create fund control

​Body parameters

​Response fields

​Examples

​Success response

​Error responses

​Register fund usage

​Path parameters

​Body parameters

​Examples

​Success response

​Error responses

​Update fund control

​Path parameters

​Body parameters

​Examples

​Success response

​Error responses

​List fund controls

​Query parameters

​Examples

​Success response

​Error responses

Build docs developers (and LLMs) love

Create fund control

Body parameters

Response fields

Examples

Success response

Error responses

Register fund usage

Path parameters

Body parameters

Examples

Success response

Error responses

Update fund control

Path parameters

Body parameters

Examples

Success response

Error responses

List fund controls

Query parameters

Examples

Success response

Error responses