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.

Credith organises its data around a three-level hierarchy: a company (empresa) owns one or more stores (tiendas/sucursales), and each store has users (staff) and checkout machines (cajas de facturación) assigned to it. A user belongs to exactly one store and one checkout machine, while the company record holds the legal identity — name and RTN (Registro Tributario Nacional) — that is stamped on every invoice at bill time. Getting this hierarchy right before processing sales is essential, as the bill controller validates each layer during invoice creation.

​
Setup Flow

1

Create a company

POST /api/companies creates the top-level legal entity. name and rtn are required; the RTN must be unique across the system.
curl -X POST http://localhost:3000/api/companies \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "name": "ServiCredit Honduras",
    "rtn": "08011999123456",
    "email": "contacto@servicredit.hn",
    "address": "Col. Palmira, Tegucigalpa"
  }'
A 201 response returns the new company record including the generated companyId UUID. If the RTN already exists the server returns 400 Ya existe una empresa con ese RTN.
{
  "message": "Empresa creada correctamente",
  "company": {
    "companyId": "a11111e5-9ae8-4597-b95e-9889028f0001",
    "name": "ServiCredit Honduras",
    "rtn": "08011999123456",
    "email": "contacto@servicredit.hn",
    "address": "Col. Palmira, Tegucigalpa"
  }
}
The companies endpoints require the OWNER role via roleMiddleware. Requests without a valid OWNER-role JWT cookie will be rejected.
2

Create a store under the company

POST /api/stores creates a branch linked to the company. storeNumber must be a positive integer and companyId must reference an existing company.
curl -X POST http://localhost:3000/api/stores \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "storeNumber": 1,
    "address": 101,
    "companyId": "a11111e5-9ae8-4597-b95e-9889028f0001"
  }'
A 201 response returns the created store:
{
  "message": "Tienda creada correctamente",
  "store": {
    "storeId": "b22222e5-9ae8-4597-b95e-9889028f0002",
    "storeNumber": 1,
    "address": 101,
    "isActive": true,
    "companyId": "a11111e5-9ae8-4597-b95e-9889028f0001"
  }
}
The address field on the cd.stores table is typed as INTEGER in the database schema — it represents a store number or location code rather than a free-text address string. Pass an integer value such as 101 or 2. Free-text branch addresses live on the cd.companies record.
POST /api/stores is protected by authMiddleware + roleMiddleware(ROLE.ADMIN, ROLE.OWNER), so a valid auth cookie with at least an ADMIN role is required.
3

Register users and assign them to a store

POST /api/users accepts a storeId field that links the new user to their branch. Every user must be assigned to a store at creation time — the storeId is validated server-side and the request is rejected if the store does not exist.
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Pedro",
    "second_name": "Luis",
    "first_last_name": "Martínez",
    "second_last_name": "Cruz",
    "email": "pedro.martinez@servicredit.hn",
    "password": "clave456",
    "storeId": "b22222e5-9ae8-4597-b95e-9889028f0002",
    "checkoutMachineId": "c33333e5-9ae8-4597-b95e-9889028f0003",
    "role": "EMPLOYEE"
  }'
4

Assign roles to users

Roles (Employee, Admin, Owner) are seeded in cd.roles. You can associate a role to a user after creation via the dedicated endpoint:
curl -X POST http://localhost:3000/api/roles/associate-user \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "d44444e5-9ae8-4597-b95e-9889028f0004",
    "roleId": "e55555e5-9ae8-4597-b95e-9889028f0005"
  }'
This inserts a row into the cd.users_roles junction table. A user can hold multiple roles; the login controller uses the first role returned (user.roles?.[0]?.name) to sign the JWT.
5

Create a checkout machine and associate it to a cashier

Every user who will process sales needs a checkout machine. First create the machine:
curl -X POST http://localhost:3000/api/checkout-machines \
  -H "Content-Type: application/json" \
  -d '{
    "machineNumber": 1,
    "name": "Caja Principal",
    "userId": "d44444e5-9ae8-4597-b95e-9889028f0004"
  }'
If the machine already exists but needs to be re-associated to a different cashier, use the associate endpoint:
curl -X PUT http://localhost:3000/api/checkout-machines/f66666e5-9ae8-4597-b95e-9889028f0006/associate-user \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "d44444e5-9ae8-4597-b95e-9889028f0004"
  }'
The machineNumber is stamped on each generated invoice as part of the billNumberFinal string and also stored in checkoutMachineNumber on the cd.bills row.

​
Activating and Deactivating Stores

Stores can be toggled active/inactive without deleting them. Deactivating a store prevents it from showing as a valid assignment target and excludes it from company-level revenue reports. 
curl -X PUT http://localhost:3000/api/stores/deactivate/b22222e5-9ae8-4597-b95e-9889028f0002 \
  -H "Content-Type: application/json" \
  -b cookies.txt
Both endpoints require a valid auth cookie with at least ADMIN or OWNER role. Error responses:
StatusMessage
400"La tienda ya esta desactivada" / "La tienda ya esta activa"
404"Tienda no encontrada"

​
Updating a Store

PUT /api/stores/:id allows any combination of storeNumber, address, and companyId to be updated. Only the fields you send are changed. 
curl -X PUT http://localhost:3000/api/stores/b22222e5-9ae8-4597-b95e-9889028f0002 \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "address": 202
  }'

​
Updating a Company

PUT /api/companies/:id accepts name, rtn, email, and address. RTN changes are validated for uniqueness. 
curl -X PUT http://localhost:3000/api/companies/a11111e5-9ae8-4597-b95e-9889028f0001 \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "email": "nuevo@servicredit.hn",
    "address": "Blvd. Morazán, Tegucigalpa"
  }'
If you need to view which store each admin is assigned to, use GET /api/admin-stores (OWNER role required) — it returns all admin users with their currently assigned store. To unassign a store from an admin, call DELETE /api/admin-stores/:userId/store, which sets the user’s storeId to null. Store assignment is set at user creation time via POST /api/users.

Build docs developers (and LLMs) love

Get started for freeTalk to us