Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/RoyGeova07/Credith/llms.txt

Use this file to discover all available pages before exploring further.

The Clients API provides full lifecycle management for the credit customers registered in Credith. A client is a person (or entity) who may purchase goods on installment credit. Clients are identified system-wide by a unique national identity number (dni), which is also used as the key to look up their active payment plan. Client records are not required for CASH bills, but are mandatory when creating an INSTALLMENT bill — the clientId must be present in the customer object and the client must not already have an open plan. None of the Clients endpoints require authentication.

​
GET /api/clients

Returns a paginated list of all clients, ordered by name ascending. Supports optional filtering by DNI. Query parameters
​
limit
integer
default:"10"
Maximum number of client records to return.
​
offset
integer
default:"0"
Number of records to skip (for pagination).
​
dni
string
Optional exact-match filter on dni. Useful for quick client lookups at point-of-sale.
Response 
{
  "total": 42,
  "data": [
    {
      "clientId": "f22222e5-9ae8-4597-b95e-9889028f5555",
      "name": "Ana García",
      "dni": "0801-1985-54321",
      "phone": "9777-6655",
      "address": "Comayagüela, FM",
      "isActive": true
    }
  ]
}

​
GET /api/clients/:id

Returns a single client record by its UUID. Path parameter
​
id
string (UUID)
required
UUID of the client to retrieve.
Error responses
StatusCause
404Client not found

​
POST /api/clients

Creates a new client. The name field is the only required field. If a dni is provided it must be unique across all clients in the system.
DNI uniqueness is enforced at the application layer before the database insert. Submitting a DNI that belongs to another client returns HTTP 400. To avoid conflicts, always search by ?dni= before registering a new client.
The dni is the lookup key used by GET /api/payment-plan/:dni to retrieve a client’s active installment plan. Register an accurate DNI to ensure seamless credit tracking.
Request body
​
name
string
required
Full name of the client. Cannot be blank.
​
dni
string
National identity number (up to 25 characters). Must be globally unique if provided. Example: "0801-1990-12345".
​
phone
string
Client phone number (up to 25 characters). Example: "9999-9999".
​
address
string
Client’s physical address. Example: "Tegucigalpa, Honduras".
Example 
curl -X POST https://your-domain.com/api/clients \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Pérez",
    "dni": "0801-1990-12345",
    "phone": "9999-9999",
    "address": "Tegucigalpa, Honduras"
  }'
Error responses
StatusCause
400name is missing/blank, or a client with the same dni already exists

​
PUT /api/clients/:id

Updates one or more fields on an existing client. Only fields included in the request body are modified. To clear a field, explicitly pass null or an empty string as appropriate. When dni is provided and differs from the client’s current value, uniqueness is re-validated against all other clients. Path parameter
​
id
string (UUID)
required
UUID of the client to update.
Request body
​
name
string
Updated full name. Cannot be set to an empty string.
​
dni
string
Updated DNI. Must be unique if changed and non-empty.
​
phone
string
Updated phone number.
​
address
string
Updated address.
Response 
{
  "message": "Cliente actualizado correctamente",
  "client": {
    "clientId": "f22222e5-9ae8-4597-b95e-9889028f5555",
    "name": "Juan Pérez Actualizado",
    "dni": "0801-1990-12345",
    "phone": "8888-8888",
    "address": "San Pedro Sula, Cortés",
    "isActive": true
  }
}
Error responses
StatusCause
400name set to empty string, or updated dni conflicts with another client
404Client not found

​
DELETE /api/clients/:id

Permanently (hard) deletes a client record. This operation does not cascade to payment plans — associated installment plans remain in the database for historical reporting. Path parameter
​
id
string (UUID)
required
UUID of the client to delete.
Response 
{ "message": "Cliente eliminado correctamente" }
Error responses
StatusCause
404Client not found

​
Client data model

​
clientId
string (UUID)
Auto-generated UUIDv4 primary key.
​
name
string
Full name of the client. Required and non-null.
​
dni
string | null
National identity number. Maximum 25 characters. Unique index enforced (idx_client_dni_unique). Used as the path parameter for GET /api/payment-plan/:dni.
​
phone
string | null
Client contact phone number. Maximum 25 characters.
​
address
string | null
Client physical address.
​
isActive
boolean
Whether the client account is considered active. Defaults to true. This field is managed internally and is not accepted as an input by any write endpoint — there is no API route to activate or deactivate a client.
​
createdAt
string (date-time)
Timestamp when the record was created.
​
updatedAt
string (date-time)
Timestamp of the last update.
​
deletedAt
string (date-time) | null
Soft-delete timestamp. Set by DELETE /api/clients/:id — records with a non-null value here are excluded from all normal queries.

Build docs developers (and LLMs) love

Get started for freeTalk to us