Credit clients (clientes) registration and lookup endpoints

Credit clients (clientes) are the borrowers who receive funds through TPROD loan operations. Each client has a credit limit (credito) that caps how much can be lent to them across all active loans. These endpoints cover creating clients, listing them with optional bank details, retrieving loan history, and accessing supporting catalogs such as economic activities, countries, and companies.

Create client

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

Body parameters

nombre

string

required

Client’s first name.

apellido

string

required

Client’s last name.

cedula_rif

string

required

National identity number or tax ID (RIF). Must be unique.

string

required

Contact email address. Must be unique.

tipo

string

required

Client type. Typical values: natural (individual), juridico (company).

credito

number

required

Maximum credit limit for this client. Must be a positive number greater than 0.

referido

string

required

Name or identifier of the person who referred this client.

telefono

string

required

Contact phone number.

fecha_registro

string

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

Response fields

string

Unique UUID for the client.

nombre

string

First name.

apellido

string

Last name.

cedula_rif

string

Identity or tax ID number.

string

Email address.

telefono

string

Phone number.

tipo

string

Client type (natural or juridico).

credito

string

Total credit limit assigned to the client.

disponible

string

Remaining credit available for new loans.

prestado

string

Amount currently lent out to this client.

referido

string

Referral source or referrer name.

responsable

string

ID of the authenticated user who created this record.

estatus

string

Account status. Typically activo after creation.

fecha_registro

string

ISO 8601 date when the client was registered.

created_at

string

ISO 8601 timestamp of record creation.

updated_at

string

ISO 8601 timestamp of the last update.

bancos

array

List of bank accounts linked to this client. Each entry contains:

Show banco object fields

string

Bank account record UUID.

id_banco

string

UUID of the bank institution.

banco_nombre

string

Bank name.

banco_codigo

string

Bank routing or SWIFT code.

cuenta

string

Account number.

telefono

string | null

Phone number associated with the account, if any.

estatus

string

Account status (activo, inactivo).

created_at

string

ISO 8601 timestamp of account creation.

updated_at

string

ISO 8601 timestamp of the last update.

Examples

curl --request POST \
  --url https://api.example.com/api/negocios/cliente \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "nombre": "Sofía",
    "apellido": "Mendoza",
    "cedula_rif": "V-20123456",
    "email": "[email protected]",
    "tipo": "natural",
    "credito": 100000,
    "referido": "Carlos Ramírez",
    "telefono": "+58 424 555 0300",
    "fecha_registro": "2025-03-01"
  }'

Success response

201

{
  "id": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
  "nombre": "Sofía",
  "apellido": "Mendoza",
  "cedula_rif": "V-20123456",
  "email": "[email protected]",
  "telefono": "+58 424 555 0300",
  "tipo": "natural",
  "credito": "100000.00",
  "disponible": "100000.00",
  "prestado": "0.00",
  "referido": "Carlos Ramírez",
  "responsable": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "estatus": "activo",
  "fecha_registro": "2025-03-01T00:00:00.000Z",
  "created_at": "2025-03-01T09:00:00.000Z",
  "updated_at": "2025-03-01T09:00:00.000Z",
  "bancos": []
}

Error responses

400

{
  "success": false,
  "message": "Los campos nombre, apellido, cedula_rif, email, tipo, telefono y credito son requeridos"
}

400

{
  "success": false,
  "message": "El crédito debe ser un número mayor a 0"
}

401

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

500

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

List all clients

Returns all credit clients. Optionally filter by client ID and bank ID via query parameters. Method: GET
Path: /api/negocios/clientes
Authentication: Bearer JWT required

Query parameters

id_cliente

string

Filter results to a specific client UUID.

id_banco

string

Filter results to clients associated with a specific bank UUID.

Examples

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

Success response

200

{
  "success": true,
  "clientes": [
    {
      "id": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
      "nombre": "Sofía",
      "apellido": "Mendoza",
      "cedula_rif": "V-20123456",
      "email": "[email protected]",
      "telefono": "+58 424 555 0300",
      "tipo": "natural",
      "credito": "100000.00",
      "disponible": "75000.00",
      "prestado": "25000.00",
      "referido": "Carlos Ramírez",
      "responsable": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "estatus": "activo",
      "fecha_registro": "2025-03-01T00:00:00.000Z",
      "created_at": "2025-03-01T09:00:00.000Z",
      "updated_at": "2025-03-15T11:00:00.000Z",
      "bancos": [
        {
          "id": "b1c2d3e4-f5a6-7890-bcde-f01234567890",
          "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
          "banco_nombre": "Banco de Venezuela",
          "banco_codigo": "0102",
          "cuenta": "0102-0123-45-6789012345",
          "telefono": "+58 424 555 0300",
          "estatus": "activo",
          "created_at": "2025-03-01T09:05:00.000Z",
          "updated_at": "2025-03-01T09:05:00.000Z"
        }
      ]
    }
  ]
}

Get client with bank details

Returns a single client record along with their associated bank accounts, filtered by client ID and bank ID. Method: GET
Path: /api/negocios/clientes/:id_cliente/:id_banco
Authentication: Bearer JWT required

Path parameters

id_cliente

string

required

UUID of the client to retrieve.

id_banco

string

required

UUID of the bank to filter the client’s accounts by.

Examples

curl --request GET \
  --url https://api.example.com/api/negocios/clientes/e5f6a7b8-c9d0-1234-ef01-234567890abc/f0e1d2c3-b4a5-6789-0abc-def012345678 \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "clientes": [
    {
      "id": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
      "nombre": "Sofía",
      "apellido": "Mendoza",
      "bancos": [
        {
          "id": "b1c2d3e4-f5a6-7890-bcde-f01234567890",
          "id_banco": "f0e1d2c3-b4a5-6789-0abc-def012345678",
          "banco_nombre": "Banco de Venezuela",
          "banco_codigo": "0102",
          "cuenta": "0102-0123-45-6789012345",
          "telefono": null,
          "estatus": "activo",
          "created_at": "2025-03-01T09:05:00.000Z",
          "updated_at": "2025-03-01T09:05:00.000Z"
        }
      ]
    }
  ]
}

Get all contracts by client

Returns all loan contracts grouped by client across the entire system. Method: GET
Path: /api/negocios/clientes/contratos
Authentication: Bearer JWT required

Examples

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

Success response

200

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

Get contracts for a specific client

Returns all loan contracts for the specified client. Method: GET
Path: /api/negocios/cliente/:idCliente/contratos
Authentication: Bearer JWT required

Path parameters

idCliente

string

required

UUID of the client whose contracts you want to retrieve.

Examples

curl --request GET \
  --url https://api.example.com/api/negocios/cliente/e5f6a7b8-c9d0-1234-ef01-234567890abc/contratos \
  --header 'Authorization: Bearer <token>'

Success response

200

{
  "success": true,
  "data": [
    {
      "id": "c1d2e3f4-a5b6-7890-cdef-012345678901",
      "id_cliente": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
      "monto_prestado": 25000,
      "moneda": "USD",
      "estatus": "aceptado"
    }
  ]
}

Get economic activities catalog

Returns the list of economic activity categories used when classifying clients. Accepts either a standard Bearer JWT or a solicitud link token. Method: GET
Path: /api/negocios/actividad_economica
Authentication: Bearer JWT or solicitud link token

Examples

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

Success response

200

{
  "success": true,
  "actividad_economica": [
    { "id": "1", "nombre": "Agricultura, ganadería y silvicultura" },
    { "id": "2", "nombre": "Pesca y acuicultura" }
  ]
}

Get countries catalog

Returns the list of countries for use in client and solicitud forms. Accepts either a standard Bearer JWT or a solicitud link token. Method: GET
Path: /api/negocios/paises
Authentication: Bearer JWT or solicitud link token

Examples

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

Success response

200

{
  "success": true,
  "paises": [
    { "id": "1", "nombre": "Venezuela" },
    { "id": "2", "nombre": "Colombia" }
  ]
}

List companies

Returns all company records in the system. Method: GET
Path: /api/negocios/companias
Authentication: Bearer JWT required

Examples

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

Success response

200

{
  "success": true,
  "companias": [
    {
      "id": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
      "nombre": "Inversiones Marbes C.A.",
      "rif": "J-12345678-9",
      "descripcion": "Empresa de inversión y préstamos",
      "estatus": "activo",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

Create company

Creates a new company record. Method: POST
Path: /api/negocios/companias
Authentication: Bearer JWT required
Content-Type: application/json

Body parameters

nombre

string

required

Company name. Cannot be empty.

rif

string

Company tax ID (RIF). Optional.

descripcion

string

Short description of the company. Optional.

estatus

string

Initial status. One of activo, desactivo, or suspendido. Defaults to activo.

Examples

curl --request POST \
  --url https://api.example.com/api/negocios/companias \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "nombre": "Inversiones Marbes C.A.",
    "rif": "J-12345678-9",
    "descripcion": "Empresa de inversión y préstamos",
    "estatus": "activo"
  }'

Success response

201

{
  "id": "a9b8c7d6-e5f4-3210-abcd-ef9876543210",
  "nombre": "Inversiones Marbes C.A.",
  "rif": "J-12345678-9",
  "descripcion": "Empresa de inversión y préstamos",
  "estatus": "activo",
  "created_at": "2025-04-01T10:00:00.000Z",
  "updated_at": "2025-04-01T10:00:00.000Z"
}

Error responses

400

{
  "success": false,
  "message": "El nombre de la compañía es requerido"
}

401

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

500

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

Authentication

HR & Users

Business Operations

Banking

Accounting & Reports

Documentation Index

​Create client

​Body parameters

​Response fields

​Examples

​Success response

​Error responses

​List all clients

​Query parameters

​Examples

​Success response

​Get client with bank details

​Path parameters

​Examples

​Success response

​Get all contracts by client

​Examples

​Success response

​Get contracts for a specific client

​Path parameters

​Examples

​Success response

​Get economic activities catalog

​Examples

​Success response

​Get countries catalog

​Examples

​Success response

​List companies

​Examples

​Success response

​Create company

​Body parameters

​Examples

​Success response

​Error responses

Build docs developers (and LLMs) love

Create client

Body parameters

Response fields

Examples

Success response

Error responses

List all clients

Query parameters

Examples

Success response

Get client with bank details

Path parameters

Examples

Success response

Get all contracts by client

Examples

Success response

Get contracts for a specific client

Path parameters

Examples

Success response

Get economic activities catalog

Examples

Success response

Get countries catalog

Examples

Success response

List companies

Examples

Success response

Create company

Body parameters

Examples

Success response

Error responses