Complete REST API Endpoint Reference for Corpointa

This page is a comprehensive reference for every REST endpoint consumed by the Corpointa frontend. Endpoints and their request/response shapes have been extracted directly from the frontend API modules in src/features/*/api/. All endpoints (except POST /auth/login and POST /auth/refresh-token) require a valid Authorization: Bearer <token> header — see the Authentication page for how to obtain a token.

Authentication

Authenticate a user and receive a JWT.

cedula

string

required

The user’s national ID number (e.g. "V-12345678").

contraseña

string

required

The user’s plaintext password.

token

string

Signed JWT to include as Authorization: Bearer <token> on subsequent requests.

user

object

Authenticated user object: id_usuario, cedula, nombre1, apellido1, correo, rol.

`POST /auth/refresh-token`

Exchange an existing (non-expired) token for a new one. No request body required — pass the current token in the Authorization header.

token

string

A freshly issued JWT with a new expiry.

Dashboard

`GET /dashboard/stats`

Returns a single aggregated statistics object used to populate the home dashboard. No query parameters or request body.

totalMateriales

number

Total number of distinct material records in the catalogue.

totalExistencias

number

Total number of stock records (one per material).

stockBajo

number

Count of materials whose current stock level is at or below their configured minimum (stock_minimo).

entradasMes

number

Number of control perceptivo (goods received) entries recorded in the current calendar month.

salidasMes

number

Number of dispatch (salida) records recorded in the current calendar month.

movimientosMensuales

array

Monthly movement summary for the chart. Each element contains:

Show movimientosMensuales item

mes

string

Localised month name (e.g. "Enero").

mes_num

string

Zero-padded month number (e.g. "01").

entradas

number

Total entries for that month.

salidas

number

Total dispatches for that month.

ultimasSalidas

array

The most recent dispatch records. Each element contains:

Show ultimasSalidas item

numero_salida

string

Human-readable dispatch number.

fecha

string

ISO 8601 date string.

recibe_nombre

string

Full name of the employee who received the materials.

total_materiales

number

Number of line items in the dispatch.

stockPorCategoria

array

Aggregated stock quantity broken down by category. Each element contains:

Show stockPorCategoria item

nombre

string

Category name.

cantidad

number

Total stock quantity across all materials in this category.

Materials

Materials are the core inventory items managed by Corpointa.

`GET /materiales`

Returns the full list of materials, including joined categoria_nombre and medida_nombre fields. Response: Material[]

`GET /materiales/:id`

Returns a single material record by its primary key. Response: Material

`POST /materiales`

Creates a new material record.

descripcion

string

required

Name or description of the material. Maximum 50 characters.

fk_id_categoria

number

required

Foreign key referencing the material’s category (id_categoria).

fk_id_medida

number

required

Foreign key referencing the unit of measure (id_medida).

ubicacion

string

Optional physical storage location. Maximum 30 characters.

Response: The created Material object, including its generated id_material.

`PUT /materiales/:id`

Updates an existing material. Accepts the same body fields as POST /materiales. Response: The updated Material object.

`DELETE /materiales/:id`

Deletes a material by its primary key. Response: 204 No Content

Control Perceptivo (Entries / Receipts)

Control perceptivo records represent goods-received notes — the formal record of materials arriving from a supplier.

`GET /controles-perceptivos`

Returns the list of all control perceptivo headers. Response: ControlPerceptivo[]

`GET /controles-perceptivos/:id`

Returns a single control perceptivo with its full detalles (line items) array. Response: ControlPerceptivo — includes:

id_control, numero_control, numero_nota_entrega, fecha_control
fk_id_proveedor, proveedor_nombre
numero_requerimiento, numero_orden_compra, observacion, foto
detalles[] — each item: id_detalle_control, fk_id_material, material_descripcion, cantidad

`POST /controles-perceptivos`

Creates a new goods-received note, including its line items in a single request.

numero_control

string

required

The unique control number for this receipt (e.g. "ACTA 001-2025").

fecha_control

string

required

ISO 8601 date string for the receipt date (e.g. "2024-11-15").

fk_id_proveedor

number

required

Foreign key referencing the supplier (id_proveedor).

numero_nota_entrega

string

The delivery note number from the supplier. Optional.

numero_requerimiento

string

Internal requisition number. Optional.

numero_orden_compra

string

Purchase order number. Optional.

observacion

string

Free-text observations or notes. Optional.

detalles

array

required

Array of line items. Each object must include:

fk_id_material (number, required) — primary key of the material received
cantidad (number, required) — quantity received
foto (string, optional) — Base64-encoded image of the product

Response: The created ControlPerceptivo object.

Dispatches (Salidas)

Dispatch records track outbound material movements — materials leaving the warehouse.

`GET /salidas`

Returns the list of all dispatch records. Response: Salida[] — each item includes id_salida, numero_salida, fecha_salida, existencia_validada, motivo_solicitud, fk_id_empleado_recibe, fk_id_gerente_finanzas, fk_id_presidente, observacion.

`POST /salidas`

Creates a new dispatch record, including its material line items in a single request.

numero_salida

string

required

The unique dispatch number (e.g. "SAL-001").

fecha_salida

string

required

ISO 8601 date of the dispatch.

fk_id_empleado_recibe

number

required

Foreign key of the employee receiving the materials (id_empleado).

detalles

array

required

Array of line items. Each object must include:

fk_id_existencia (number, required) — primary key of the stock record (id_existencia)
cantidad_solicitada (number, required) — quantity requested
cantidad_entregada (number, required) — quantity actually delivered
observacion (string, optional) — line-item note

existencia_validada

boolean

Whether stock levels were verified before dispatch. Defaults to false.

motivo_solicitud

string

Reason or justification for the dispatch. Optional.

observacion

string

Free-text observations. Optional.

Response: The created Salida object.

`GET /salidas/:id/pdf`

Generates and streams an official dispatch note (acta de salida) as a PDF binary.

You must set responseType: 'blob' on this request. The frontend uses window.URL.createObjectURL to trigger a file download named acta-salida-{id}.pdf. When calling this endpoint outside the browser (e.g. from a backend service), save the binary response body directly to a file.

curl http://localhost:4000/salidas/42/pdf \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --output acta-salida-42.pdf

Response: Binary PDF blob (Content-Type: application/pdf).

Stock (Existencias)

Existencias track current stock levels for every material, plus the configured minimum and maximum thresholds.

`GET /existencias`

Returns the complete stock list. Response: Existencia[] — each item includes id_existencia, fk_id_material, material_descripcion, cantidad_actual, stock_minimo, stock_maximo.

`PUT /existencias/:id`

Updates the minimum and maximum stock thresholds for a stock record. Current stock (cantidad_actual) is managed automatically by the backend when entries and dispatches are recorded.

stock_minimo

number

required

The minimum acceptable stock level. Triggers the low-stock alert when cantidad_actual falls to or below this value.

stock_maximo

number

required

The maximum stock level target.

Response: The updated Existencia object.

Catalogs

The following resources follow a standard CRUD pattern. All support GET /<resource> (list), POST /<resource> (create), PUT /<resource>/:id (update), and DELETE /<resource>/:id (delete), unless noted otherwise.

Categories — `/categorias`

Method	Path	Description
`GET`	`/categorias`	List all categories → `Categoria[]`
`GET`	`/categorias/:id`	Get single category → `Categoria`
`POST`	`/categorias`	Create category — body: `{ nombre: string }`
`PUT`	`/categorias/:id`	Update category — body: `{ nombre: string }`
`DELETE`	`/categorias/:id`	Delete category → `204`

nombre

string

required

Category name. Maximum 50 characters.

Units of Measure — `/unidades-medidas`

Method	Path	Description
`GET`	`/unidades-medidas`	List all units → `UnidadMedida[]`
`GET`	`/unidades-medidas/:id`	Get single unit → `UnidadMedida`
`POST`	`/unidades-medidas`	Create unit — body: `{ nombre: string }`
`PUT`	`/unidades-medidas/:id`	Update unit — body: `{ nombre: string }`
`DELETE`	`/unidades-medidas/:id`	Delete unit → `204`

nombre

string

required

Unit name (e.g. "Kilogramo", "Metro", "Unidad"). Maximum 50 characters.

Destinations — `/destinos`

Destinations represent internal departments or cost centres that receive dispatched materials.

Method	Path	Description
`GET`	`/destinos`	List all destinations → `Destino[]`
`GET`	`/destinos/:id`	Get single destination → `Destino`
`POST`	`/destinos`	Create destination — body: `{ nombre: string }`
`PUT`	`/destinos/:id`	Update destination — body: `{ nombre: string }`
`DELETE`	`/destinos/:id`	Delete destination → `204`

nombre

string

required

Destination name. Maximum 50 characters.

Suppliers — `/proveedores`

Method	Path	Description
`GET`	`/proveedores`	List all suppliers → `Proveedor[]`
`GET`	`/proveedores/:id`	Get single supplier → `Proveedor`
`POST`	`/proveedores`	Create supplier
`PUT`	`/proveedores/:id`	Update supplier

The suppliers API module does not include a DELETE endpoint.

nombre

string

required

Supplier company name. Maximum 100 characters.

rif_o_cedula

string

required

Tax ID (RIF) or national ID number of the supplier. Maximum 30 characters.

telefono

string

required

Contact telephone number. Maximum 30 characters.

Employees — `/empleados`

Method	Path	Description
`GET`	`/empleados`	List all employees → `Empleado[]`
`GET`	`/empleados/:id`	Get single employee → `Empleado`
`POST`	`/empleados`	Create employee
`PUT`	`/empleados/:id`	Update employee
`DELETE`	`/empleados/:id`	Delete employee → `204`

nombre_completo

string

required

Employee’s full name. Maximum 200 characters.

fk_id_destino

number

required

Foreign key referencing the employee’s assigned destination/department (id_destino).

cedula

string

National ID number. Optional. Maximum 30 characters.

telefono

string

Contact telephone number. Optional. Maximum 30 characters.

activo

boolean

Whether the employee is currently active. Included in PUT requests; defaults to true on creation.

Users

System user accounts that can log into Corpointa. The backend routes use /users (not /usuarios).

Method	Path	Description
`GET`	`/users`	List all users → `Usuario[]`
`GET`	`/users/:id`	Get single user → `Usuario`
`POST`	`/users`	Create user
`PUT`	`/users/:id`	Update user
`DELETE`	`/users/:id`	Delete user → `204`

cedula

string

required

National ID — used as the login identifier. Maximum 30 characters.

nombre1

string

required

First given name. Maximum 50 characters.

apellido1

string

required

First family name. Maximum 50 characters.

nombre2

string

Second given name. Optional. Maximum 50 characters.

apellido2

string

Second family name. Optional. Maximum 50 characters.

clave

string

Password. Minimum 6 characters. Required on POST; optional on PUT (omit to leave unchanged).

activo

boolean

Whether the user account is enabled. Defaults to true.

Audit Log

The audit log (bitacoras) is an append-only record of all state-changing actions performed in the system. It is read-only from the frontend — records are created server-side automatically.

`GET /bitacoras`

Returns all audit log entries. Response: Bitacora[]

Field	Type	Description
`id_bitacora`	`number`	Primary key.
`fk_id_usuario`	`number \| null`	ID of the user who performed the action.
`nombre1`	`string \| null`	First name of the acting user (denormalised).
`apellido1`	`string \| null`	First surname of the acting user (denormalised).
`cedula`	`string \| null`	National ID of the acting user (denormalised).
`fecha_hora`	`string`	ISO 8601 timestamp of the action.
`accion`	`string`	Action type, e.g. `"CREATE"`, `"UPDATE"`, `"DELETE"`.
`tabla_afectada`	`string`	Name of the database table that was modified.
`id_registro_afectado`	`string \| number \| null`	Primary key of the affected record.
`descripcion`	`string \| null`	Human-readable description of the change.

Use the tabla_afectada field to filter log entries by resource type when displaying activity history for a specific entity (e.g. all changes made to materiales).

API Integration

Customization

Deployment

Complete REST API Endpoint Reference for Corpointa

Authentication

`POST /auth/refresh-token`

Dashboard

`GET /dashboard/stats`

Materials

`GET /materiales`

`GET /materiales/:id`

`POST /materiales`

`PUT /materiales/:id`

`DELETE /materiales/:id`

Control Perceptivo (Entries / Receipts)

`GET /controles-perceptivos`

`GET /controles-perceptivos/:id`

`POST /controles-perceptivos`

Dispatches (Salidas)

`GET /salidas`

`POST /salidas`

`GET /salidas/:id/pdf`

Stock (Existencias)

`GET /existencias`

`PUT /existencias/:id`

Catalogs

Categories — `/categorias`

Units of Measure — `/unidades-medidas`

Destinations — `/destinos`

Suppliers — `/proveedores`

Employees — `/empleados`

Users

Audit Log

`GET /bitacoras`

Build docs developers (and LLMs) love

API Integration

Customization

Deployment

Documentation Index

​Authentication

​POST /auth/login

​POST /auth/refresh-token

​Dashboard

​GET /dashboard/stats

​Materials

​GET /materiales

​GET /materiales/:id

​POST /materiales

​PUT /materiales/:id

​DELETE /materiales/:id

​Control Perceptivo (Entries / Receipts)

​GET /controles-perceptivos

​GET /controles-perceptivos/:id

​POST /controles-perceptivos

​Dispatches (Salidas)

​GET /salidas

​POST /salidas

​GET /salidas/:id/pdf

​Stock (Existencias)

​GET /existencias

​PUT /existencias/:id

​Catalogs

​Categories — /categorias

​Units of Measure — /unidades-medidas

​Destinations — /destinos

​Suppliers — /proveedores

​Employees — /empleados

​Users

​Audit Log

​GET /bitacoras

Build docs developers (and LLMs) love

Authentication

`POST /auth/login`

`POST /auth/refresh-token`

Dashboard

`GET /dashboard/stats`

Materials

`GET /materiales`

`GET /materiales/:id`

`POST /materiales`

`PUT /materiales/:id`

`DELETE /materiales/:id`

Control Perceptivo (Entries / Receipts)

`GET /controles-perceptivos`

`GET /controles-perceptivos/:id`

`POST /controles-perceptivos`

Dispatches (Salidas)

`GET /salidas`

`POST /salidas`

`GET /salidas/:id/pdf`

Stock (Existencias)

`GET /existencias`

`PUT /existencias/:id`

Catalogs

Categories — `/categorias`

Units of Measure — `/unidades-medidas`

Destinations — `/destinos`

Suppliers — `/proveedores`

Employees — `/empleados`

Users

Audit Log

`GET /bitacoras`