Investment contract create, update, and close endpoints

Investment contracts (contratos) represent a formal agreement with an investor (aportante) to deploy capital over a fixed term. Each contract tracks the currency, term length, and optional collateral guarantee. Once capital starts flowing through a contract, individual TCOL collection records are linked to it. You can also close a contract formally via the contrato-cerrado operation, which locks in the agreed rate and commission.

Create contract

Method: POST
Path: /api/negocios/contrato
Authentication: Bearer JWT required
Content-Type: application/json

Body parameters

id_aportante

string

required

UUID of the investor who is party to this contract.

moneda

string

required

Currency code for the contract. One of VES, USD, or EUR.

plazo

number

required

Numeric duration of the contract term. Must be greater than 0.

plazo_opcion

string

required

Unit for the term duration. One of dias, mes, or ano.

fecha_inicio

string

required

Contract start date in YYYY-MM-DD format.

fecha_fin

string

Contract end date in YYYY-MM-DD format. When omitted, the system calculates it from fecha_inicio and the plazo values.

garantia

string

Collateral description or JSON reference to guarantee file paths. Optional at creation; files can be attached later via the update endpoint.

fecha_registro

string

Registration date in YYYY-MM-DD format. Defaults to the current timestamp when omitted.

Response fields

string

Unique UUID for the contract.

id_aportante

string

UUID of the linked investor.

aportante

string

Full name of the investor.

cedula_rif

string

Identity or tax ID of the investor.

monto

number

Total amount collected into this contract via TCOL records.

moneda

string

Currency code (VES, USD, EUR).

plazo_cantidad

number

Numeric term length.

plazo_opcion

string

Term unit (dias, mes, ano).

fecha_inicio

string

Contract start date.

fecha_fin

string

Contract end date.

garantia

string

Collateral reference or JSON string of file paths.

contrato_estatus

string

Current status of the contract (e.g., activo, finalizado).

actualizado_por

string

ID of the user who last updated this record.

ultima_actualizacion

string

ISO 8601 timestamp of the last update.

fecha_registro

string

ISO 8601 date of original registration.

responsable_id

string

UUID of the user who created the contract.

responsable

string

Full name of the responsible user.

Examples

curl --request POST \
  --url https://api.example.com/api/negocios/contrato \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id_aportante": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
    "moneda": "USD",
    "plazo": 6,
    "plazo_opcion": "mes",
    "fecha_inicio": "2025-02-01"
  }'

Success response

201

{
  "id": "c1d2e3f4-a5b6-7890-cdef-012345678901",
  "id_aportante": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
  "aportante": "Carlos Ramírez",
  "cedula_rif": "V-18765432",
  "monto": 0,
  "moneda": "USD",
  "plazo_cantidad": 6,
  "plazo_opcion": "mes",
  "fecha_inicio": "2025-02-01",
  "fecha_fin": "2025-08-01",
  "garantia": null,
  "contrato_estatus": "activo",
  "actualizado_por": null,
  "ultima_actualizacion": null,
  "fecha_registro": "2025-02-01T00:00:00.000Z",
  "responsable_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "responsable": "Ana López"
}

Error responses

400

{
  "success": false,
  "message": "Fecha de inicio es requerida"
}

400

{
  "success": false,
  "message": "Tipo de plazo debe ser: dias, mes o ano"
}

500

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

List all contracts

Returns all investment contracts in the system. Method: GET
Path: /api/negocios/contratos
Authentication: Bearer JWT required

Examples

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

Success response

200

{
  "success": true,
  "contratos": [
    {
      "id": "c1d2e3f4-a5b6-7890-cdef-012345678901",
      "id_aportante": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
      "aportante": "Carlos Ramírez",
      "monto": 50000,
      "moneda": "USD",
      "plazo_cantidad": 6,
      "plazo_opcion": "mes",
      "fecha_inicio": "2025-02-01",
      "fecha_fin": "2025-08-01",
      "contrato_estatus": "activo"
    }
  ]
}

List finalized contracts

Returns only contracts that have been closed or finalized. Method: GET
Path: /api/negocios/contratos/finalizados
Authentication: Bearer JWT required

Examples

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

Success response

200

{
  "success": true,
  "contratos": []
}

Get TCOL records for a contract

Returns all TCOL (fund collection) entries linked to the specified contract. Method: GET
Path: /api/negocios/contratos/:idContrato/tcol
Authentication: Bearer JWT required

Path parameters

idContrato

string

required

UUID of the contract whose TCOL records you want to retrieve.

Examples

curl --request GET \
  --url https://api.example.com/api/negocios/contratos/c1d2e3f4-a5b6-7890-cdef-012345678901/tcol \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "tcol": [
    {
      "id": "t1c2o3l4-5678-9012-abcd-ef3456789012",
      "id_contrato": "c1d2e3f4-a5b6-7890-cdef-012345678901",
      "monto": 50000,
      "moneda": "USD",
      "estatus": "aceptado",
      "fecha_recibido": "2025-02-05"
    }
  ]
}

Error responses

400

{
  "success": false,
  "message": "El id del contrato es requerido"
}

Update contract

Updates term, start date, or guarantee files for an existing contract. At least one field or at least one file must be provided. Method: POST
Path: /api/negocios/contratos/actualizar/:id
Authentication: Bearer JWT required
Content-Type: multipart/form-data

Path parameters

string

required

UUID of the contract to update.

Body parameters

plazo_cantidad

number

New term length. Must be greater than 0 if provided.

plazo_opcion

string

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

fecha_inicio

string

New start date in YYYY-MM-DD format. When changed, the system recalculates fecha_fin.

garantia

file

One or more guarantee files (e.g., PDF, image). Attach as multipart file fields. Existing guarantee files are preserved and the new files are appended.

Examples

curl --request POST \
  --url https://api.example.com/api/negocios/contratos/actualizar/c1d2e3f4-a5b6-7890-cdef-012345678901 \
  --header 'Authorization: Bearer <token>' \
  --form 'plazo_cantidad=9' \
  --form 'plazo_opcion=mes' \
  --form 'garantia=@/path/to/guarantee.pdf'

Success response

200

{
  "success": true,
  "contrato": {
    "id": "c1d2e3f4-a5b6-7890-cdef-012345678901",
    "plazo_cantidad": 9,
    "plazo_opcion": "mes",
    "fecha_inicio": "2025-02-01",
    "fecha_fin": "2025-11-01",
    "garantia": "{\"archivos\":[\"uploads/contratos/c1d2e3f4/guarantee.pdf\"]}"
  }
}

Error responses

400

{
  "success": false,
  "message": "Debe proporcionar al menos un campo para actualizar (plazo_cantidad, plazo_opcion, fecha_inicio) o archivos de garantía"
}

Get guarantee files for a contract

Returns the list of guarantee files attached to the specified contract. Method: GET
Path: /api/negocios/contratos/:id/garantias
Authentication: Bearer JWT required

Path parameters

string

required

UUID of the contract whose guarantee files you want to retrieve.

Examples

curl --request GET \
  --url https://api.example.com/api/negocios/contratos/c1d2e3f4-a5b6-7890-cdef-012345678901/garantias \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "id_contrato": "c1d2e3f4-a5b6-7890-cdef-012345678901",
  "archivos": [
    "uploads/contratos/c1d2e3f4/guarantee.pdf"
  ]
}

Error responses

404

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

Close contract

Formally closes a contract by recording the agreed interest rate and commission. This creates a contrato-cerrado record and updates the contract status to finalized. Method: POST
Path: /api/negocios/contrato-cerrado
Authentication: Bearer JWT required
Content-Type: application/json

Body parameters

id_contrato

string

required

UUID of the contract to close.

tasa

number

required

Agreed interest rate as a percentage (0–100).

comision

number

required

Commission percentage charged on the contract (0–100).

nota

string

Optional note or observations about the contract closure.

fecha_registro

string

Closure date in YYYY-MM-DD format. Defaults to the current timestamp when omitted.

Examples

curl --request POST \
  --url https://api.example.com/api/negocios/contrato-cerrado \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id_contrato": "c1d2e3f4-a5b6-7890-cdef-012345678901",
    "tasa": 12.5,
    "comision": 2.0,
    "nota": "Contrato cerrado por vencimiento de plazo"
  }'

Success response

201

{
  "id": "cc112233-4455-6677-8899-aabbccddeeff",
  "id_contrato": "c1d2e3f4-a5b6-7890-cdef-012345678901",
  "tasa": 12.5,
  "comision": 2.0,
  "nota": "Contrato cerrado por vencimiento de plazo",
  "responsable": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "update_by": null,
  "updated_at": null,
  "fecha_registro": "2025-08-01T00:00:00.000Z",
  "created_at": "2025-08-01T14:00:00.000Z"
}

Error responses

400

{
  "success": false,
  "message": "Los campos id_contrato, tasa y comision son requeridos"
}

400

{
  "success": false,
  "message": "La tasa debe estar entre 0 y 100"
}

401

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

Get available funds per bank

Returns the available (unallocated) fund balance for a given bank, optionally filtered by client and company. Method: GET
Path: /api/negocios/bancos/:idBanco/disponible
Authentication: Bearer JWT required

Path parameters

idBanco

string

required

UUID of the bank institution to query.

Query parameters

id_cliente

string

Optionally filter results for a specific client UUID.

id_compania

string

Optionally filter results for a specific company UUID.

moneda

string

Optionally filter results by currency (VES, USD, or EUR).

Examples

curl --request GET \
  --url 'https://api.example.com/api/negocios/bancos/f0e1d2c3-b4a5-6789-0abc-def012345678/disponible?moneda=USD' \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "data": {
    "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
    "banco": "Banco de Venezuela",
    "moneda": "USD",
    "disponible": 125000.00
  }
}

Get available control funds per bank

Returns the fund balance available through control-de-fondos allocations for a given bank. Only funds pre-allocated via control records are counted here. Method: GET
Path: /api/negocios/bancos/:idBanco/disponible-control
Authentication: Bearer JWT required

Path parameters

idBanco

string

required

UUID of the bank institution to query.

Query parameters

id_compania

string

Optionally filter results by company UUID.

Examples

curl --request GET \
  --url 'https://api.example.com/api/negocios/bancos/f0e1d2c3-b4a5-6789-0abc-def012345678/disponible-control?id_compania=a9b8c7d6-e5f4-3210-abcd-ef9876543210' \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "data": {
    "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
    "banco": "Banco de Venezuela",
    "monto_disponible_control": 80000.00
  }
}

Error responses

400

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

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Documentation Index

​Create contract

​Body parameters

​Response fields

​Examples

​Success response

​Error responses

​List all contracts

​Examples

​Success response

​List finalized contracts

​Examples

​Success response

​Get TCOL records for a contract

​Path parameters

​Examples

​Success response

​Error responses

​Update contract

​Path parameters

​Body parameters

​Examples

​Success response

​Error responses

​Get guarantee files for a contract

​Path parameters

​Examples

​Success response

​Error responses

​Close contract

​Body parameters

​Examples

​Success response

​Error responses

​Get available funds per bank

​Path parameters

​Query parameters

​Examples

​Success response

​Get available control funds per bank

​Path parameters

​Query parameters

​Examples

​Success response

​Error responses

Build docs developers (and LLMs) love

Create contract

Body parameters

Response fields

Examples

Success response

Error responses

List all contracts

Examples

Success response

List finalized contracts

Examples

Success response

Get TCOL records for a contract

Path parameters

Examples

Success response

Error responses

Update contract

Path parameters

Body parameters

Examples

Success response

Error responses

Get guarantee files for a contract

Path parameters

Examples

Success response

Error responses

Close contract

Body parameters

Examples

Success response

Error responses

Get available funds per bank

Path parameters

Query parameters

Examples

Success response

Get available control funds per bank

Path parameters

Query parameters

Examples

Success response

Error responses