Clientes API — Company Client Management Endpoints

All clientes endpoints require a valid JWT token in the Authorization header (Bearer <token>). Clients (empresas) are the legal entities on behalf of which tax consolidations are created. The RTN (Registro Tributario Nacional) is Honduras’s tax registration number and must contain only digits and hyphens — it uniquely identifies a company in the SAR (Servicio de Administración de Rentas) system. Every write operation is automatically logged to the system audit trail.

GET /api/clientes

List all client records. By default returns only active clients (activo = 1). Supports optional filtering by status and a full-text search across company name, RTN, representative, and sector. Auth: Bearer token required.

Query Parameters

activo

boolean

Filter by active status. Pass true (default) for active clients only, false to retrieve deactivated clients. Omit to receive all clients regardless of status.

string

Free-text search term. Matched against nombre_empresa, rtn, representante, and rubro fields.

Response

success

boolean

true on a successful query.

clientes

array

Array of client objects matching the filter criteria.

Show client object fields

integer

Auto-generated primary key.

nombre_empresa

string

Legal name of the company.

rtn

string

Registro Tributario Nacional — stored in uppercase. Contains only digits and hyphens.

rubro

string

Business sector / industry (e.g. "Farmacia", "Hotelería", "Comercio General").

representante

string

Full name of the legal representative.

telefono

string

Contact phone number.

string

Contact email address (stored lowercase).

direccion

string

Physical address.

logo_url

string

Relative URL to the uploaded company logo, e.g. /uploads/logos/logo_1714000000000_abc123.png. null if no logo has been uploaded.

activo

boolean

true if the client is active; false if deactivated.

fecha_registro

string

ISO-8601 timestamp of when the client was created.

fecha_actualizacion

string

ISO-8601 timestamp of the last update.

total

integer

Count of client records returned.

Example

curl -X GET "https://api.example.com/api/clientes?activo=true&search=farmacia" \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "clientes": [
    {
      "id": 7,
      "nombre_empresa": "Farmacia Honduras S.A.",
      "rtn": "08019999123456",
      "rubro": "Farmacia",
      "representante": "Carlos Mejía López",
      "telefono": "2239-4455",
      "email": "contacto@farmaciahn.com",
      "direccion": "Col. Palmira, Tegucigalpa, Honduras",
      "logo_url": null,
      "activo": true,
      "fecha_registro": "2024-01-10T09:00:00.000Z",
      "fecha_actualizacion": "2024-01-10T09:00:00.000Z"
    }
  ],
  "total": 1
}

POST /api/clientes

Create a new client company record. All seven core fields are required. Optionally accepts a logo image file via multipart/form-data (max 5 MB; image formats only). Auth: Bearer token required.

This endpoint uses multipart/form-data when uploading a logo. Send text fields alongside the logo file part. If you are not uploading a logo, you may use application/json instead — the uploadLogo middleware will simply find no file.

Request Body

nombre_empresa

string

required

Legal name of the company. Length: 2–255 characters.

rtn

string

required

Registro Tributario Nacional. Length: 3–50 characters. Must match /^[0-9\-]+$/ — only digits and hyphens are accepted. The value is stored in uppercase. Duplicate RTNs are rejected with HTTP 409.

rubro

string

required

Business sector (e.g. "Hotelería", "Comercio", "Servicios"). Length: 2–100 characters.

representante

string

required

Full legal name of the company representative. Length: 2–255 characters.

telefono

string

required

Contact phone number. Length: 8–20 characters. Must match /^[\d\-\+\s]+$/ — digits, spaces, hyphens, parentheses, and + are allowed (e.g. "2239-4455" or "+504 9988-7766").

string

required

Contact email address. Must be a valid email format. Max 255 characters. Stored lowercase.

direccion

string

required

Physical address. Length: 5–500 characters.

logo

file

Company logo image. Sent as the logo field in a multipart/form-data request. Max 5 MB. Only image MIME types (image/*) are accepted. The server stores the file at uploads/logos/ and sets logo_url automatically.

force

boolean

Set to true to bypass the duplicate-RTN check and force-create the record. Use with caution.

Response

success

boolean

true on successful creation.

message

string

"Cliente creado exitosamente"

cliente

object

Full client record as persisted, including the server-assigned id, logo_url, activo, fecha_registro, and fecha_actualizacion.

Error Responses

HTTP Status	Scenario
`400`	Validation failure — `details` array lists each failing field and its message
`409`	A client with the same RTN already exists in the database
`500`	Unhandled server error

{
  "error": "Datos inválidos",
  "details": [
    {
      "type": "field",
      "msg": "El RTN debe contener solo números y guiones",
      "path": "rtn",
      "location": "body"
    }
  ]
}

Example

curl -X POST https://api.example.com/api/clientes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre_empresa": "Hotel Vista Honduras S.A.",
    "rtn": "08011234567890",
    "rubro": "Hotelería",
    "representante": "María Fernanda Reyes",
    "telefono": "2235-6677",
    "email": "info@vistahotel.hn",
    "direccion": "Blvd. Juan Pablo II, San Pedro Sula, Honduras"
  }'

{
  "success": true,
  "message": "Cliente creado exitosamente",
  "cliente": {
    "id": 15,
    "nombre_empresa": "Hotel Vista Honduras S.A.",
    "rtn": "08011234567890",
    "rubro": "Hotelería",
    "representante": "María Fernanda Reyes",
    "telefono": "2235-6677",
    "email": "info@vistahotel.hn",
    "direccion": "Blvd. Juan Pablo II, San Pedro Sula, Honduras",
    "logo_url": null,
    "activo": true,
    "fecha_registro": "2024-03-01T15:30:00.000Z",
    "fecha_actualizacion": "2024-03-01T15:30:00.000Z"
  }
}

GET /api/clientes/:id

Fetch a single client by its numeric ID. Returns 404 if the client does not exist; returns 400 if the id path segment is not a valid integer. Auth: Bearer token required.

Path Parameters

integer

required

Numeric primary key of the client.

Response

success

boolean

true on success.

cliente

object

Full client record. See the fields listed in GET /api/clientes.

PUT /api/clientes/:id

Update one or more fields on an existing client record. All fields are optional — only the fields included in the request body will be updated. Validation rules are identical to POST but no field is required. A logo file can be updated by sending a new multipart/form-data request with a logo field; the previous logo file will be deleted from disk automatically. Auth: Bearer token required.

Path Parameters

integer

required

Numeric ID of the client to update.

Request Body

nombre_empresa

string

Updated company name. Length: 2–255 characters.

rtn

string

Updated RTN. Length: 3–50 characters. Must match /^[0-9\-]+$/. Stored uppercase.

rubro

string

Updated business sector. Length: 2–100 characters.

representante

string

Updated representative name. Length: 2–255 characters.

telefono

string

Updated phone number. Length: 8–20 characters. Must match /^[\d\-\+\s]+$/.

string

Updated email address. Must be valid format. Max 255 characters.

direccion

string

Updated address. Length: 5–500 characters.

activo

boolean

Set to false to deactivate the client, true to reactivate. This field is available on PUT but not on POST (new clients are always active).

logo

file

New logo image (multipart/form-data). Replaces the existing logo. Max 5 MB, image formats only.

Response

success

boolean

true on successful update.

message

string

"Cliente actualizado exitosamente"

cliente

object

The updated client record as re-fetched from the database after the change.

DELETE /api/clientes/:id

Soft-delete (deactivate) a client. Sets activo = false in the database. The client record is preserved and can be reactivated via PUT /api/clientes/:id with "activo": true. Deactivated clients do not appear in the default GET /api/clientes response unless activo=false is passed. Auth: Bearer token required.

This is a soft delete — the client row is not removed from the database. All associated consolidation records remain intact. To permanently delete a client (admin only), use DELETE /api/clientes/:id/hard.

Path Parameters

integer

required

Numeric ID of the client to deactivate.

Response

success

boolean

true on successful deactivation.

message

string

Human-readable confirmation returned by the model, e.g. "Cliente desactivado exitosamente".

Additional Endpoints

The following endpoints are also available on the /api/clientes router but are supplementary to the core CRUD operations above.

GET /api/clientes/stats

Returns aggregate statistics for the client list. Auth: Bearer token required.

success

boolean

true on success.

estadisticas

object

Statistics object returned by Cliente.getStats(). Typically includes counts of active/inactive clients and breakdowns by rubro.

PATCH /api/clientes/:id/toggle-status

Toggle the activo flag of a client without specifying the new value — the server flips the current state. Useful for quick activate/deactivate actions in list views. Auth: Bearer token required.

integer

required

ID of the client whose status should be toggled.

success

boolean

true on success.

message

string

"Cliente activado exitosamente" or "Cliente desactivado exitosamente".

cliente

object

Updated client record reflecting the new activo state.

DELETE /api/clientes/:id/hard

Permanently delete a client and remove its logo from disk. Admin role required. Returns 403 Forbidden for non-admin users. This operation is irreversible. Auth: Bearer token required + role = "admin".

integer

required

ID of the client to permanently remove.

success

boolean

true on success.

message

string

Confirmation message from the model’s deleteHard() method.

POST /api/clientes/upload-csv

Bulk-import clients from a CSV file. Admin role required. The CSV must be semicolon-delimited with headers matching the client field names. Both UTF-8 and ISO-8859-1 (Windows Latin-1) encodings are accepted. RTNs must be exactly 14 digits; rows with invalid RTNs or missing required fields are skipped and reported in the errors array. Auth: Bearer token required + role = "admin". Content-Type: multipart/form-data

csv

file

required

The CSV file to import. Required columns: nombre_empresa, rtn, rubro, representante, telefono, email, direccion. Optional columns: logo_url, activo, fecha_registro, fecha_actualizacion.

success

boolean

true if the upload was processed (even if some rows had errors).

inserted

integer

Number of client records successfully created.

errors

array

Array of objects describing rows that could not be imported. Each item contains nombre, rtn, and error fields.

RTN Format Reference

The RTN (Registro Tributario Nacional) is a 14-digit number assigned by the SAR. It is typically formatted as XXXX-XXXX-XXXXXX (e.g. 0801-1234-567890) or provided as a plain 14-digit string (08011234567890). The API accepts either format as long as it matches /^[0-9\-]+$/.

Error Responses

All endpoints return a consistent error envelope on failure:

HTTP Status	Meaning
`400`	Validation error, missing required fields, or no update fields provided
`403`	Insufficient role (admin-only endpoint accessed by non-admin)
`404`	Client not found
`409`	RTN conflict — a client with this RTN already exists
`500`	Unhandled server error

{
  "error": "Ya existe un cliente con este RTN",
  "message": "Ya existe un cliente con este RTN"
}

Authentication — Obtain a JWT token
Consolidaciones API — Create consolidation records referencing a cliente_id
Reports API — Generate per-client tax reports
Features — Clients — Client management feature overview
Audit Logs API — View system events generated by client operations

Authentication

Resources

Clientes API — Company Client Management Endpoints

GET /api/clientes

Query Parameters

Response

Example

POST /api/clientes

Request Body

Response

Error Responses

Example

GET /api/clientes/:id

Path Parameters

Response

PUT /api/clientes/:id

Path Parameters

Request Body

Response

DELETE /api/clientes/:id

Path Parameters

Response

Additional Endpoints

GET /api/clientes/stats

PATCH /api/clientes/:id/toggle-status

DELETE /api/clientes/:id/hard

POST /api/clientes/upload-csv

RTN Format Reference

Error Responses

Build docs developers (and LLMs) love

Authentication

Resources

Documentation Index

​GET /api/clientes

​Query Parameters

​Response

​Example

​POST /api/clientes

​Request Body

​Response

​Error Responses

​Example

​GET /api/clientes/:id

​Path Parameters

​Response

​PUT /api/clientes/:id

​Path Parameters

​Request Body

​Response

​DELETE /api/clientes/:id

​Path Parameters

​Response

​Additional Endpoints

​GET /api/clientes/stats

​PATCH /api/clientes/:id/toggle-status

​DELETE /api/clientes/:id/hard

​POST /api/clientes/upload-csv

​RTN Format Reference

​Error Responses

​Related Pages

Build docs developers (and LLMs) love

GET /api/clientes

Query Parameters

Response

Example

POST /api/clientes

Request Body

Response

Error Responses

Example

GET /api/clientes/:id

Path Parameters

Response

PUT /api/clientes/:id

Path Parameters

Request Body

Response

DELETE /api/clientes/:id

Path Parameters

Response

Additional Endpoints

GET /api/clientes/stats

PATCH /api/clientes/:id/toggle-status

DELETE /api/clientes/:id/hard

POST /api/clientes/upload-csv

RTN Format Reference

Error Responses

Related Pages