Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GianlucaBessone/HDB-Service/llms.txt

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

The Inventory API manages all stock-related operations in HDB Service. Stock entries are scoped to a specific plant and track both bulk consumables (e.g., filters, cartridges counted by quantity) and serialized consumables that require a unique tracking ID per unit. When stock is shared between plants in an emergency, the system automatically records an inter-plant debt that must later be resolved either manually or via a follow-up transfer. All endpoints require an authenticated session with a valid Supabase Auth cookie. Permissions are enforced through the RBAC matrix — see the permission column on each endpoint below.

​
GET /api/stock

Returns a list of stock entries visible to the authenticated user. Results are automatically scoped by role: CLIENT_REQUESTER users see only entries for their assigned plants, while ADMIN and SUPERVISOR users see all entries. Each entry includes a serialNumbers array populated from active Consumable records that have a uniqueId. Required permission: stock:read
​
plantId
string
Filter entries by plant ID.
​
itemType
string
Filter by item type. Must be CONSUMABLE or SPARE_PART.
​
lowStockOnly
boolean
When true, returns only entries where cantidad < minLevel.
​
id
string
Unique stock entry ID.
​
clientId
string
Owning client ID.
​
plantId
string
Owning plant ID.
​
itemType
string
CONSUMABLE or SPARE_PART.
​
materialCode
string
Unique catalog material code.
​
nombre
string
Material display name.
​
cantidad
number
Current stock quantity.
​
minLevel
number
Low-stock alert threshold.
​
maxLevel
number
Reorder target quantity.
​
unidad
string
Unit of measure (e.g., "unidad", "litro").
​
serialNumbers
string[]
Array of unique IDs of active serialized consumables for this plant + material combination.
​
client
object
​
plant
object
curl -X GET "https://your-domain.com/api/stock?plantId=plant_abc&lowStockOnly=true" \
  -H "Cookie: sb-access-token=<token>"
Error responses:
StatusDescription
401Not authenticated.
403Insufficient permission (stock:read required).
500Internal server error fetching stock entries.

​
POST /api/stock

Creates a new stock entry or increments an existing one. The materialCode must match a record in the MaterialCatalog. If the catalog item has requiresSerial: true, a uniqueId is required and a Consumable record is created before the stock entry is upserted. For serialized materials, quantity is always incremented by 1 regardless of the cantidad value sent. Required permission: stock:write
​
clientId
string
required
ID of the client that owns this stock entry.
​
plantId
string
required
ID of the plant where stock is held.
​
materialCode
string
required
Code of an existing MaterialCatalog entry. Returns 400 if not found.
​
cantidad
number
Quantity to add. For bulk (non-serialized) materials, this value is incremented onto the existing entry. Ignored for serialized materials (always +1). Defaults to 0 if omitted.
​
minLevel
number
Low-stock alert threshold. Updates the existing entry if one already exists.
​
maxLevel
number
Reorder target quantity. Updates the existing entry if one already exists.
​
unidad
string
Unit of measure. Defaults to "unidad".
​
uniqueId
string
Serial number for the consumable unit. Required when the catalog item has requiresSerial: true. Must be globally unique across all Consumable records.
​
id
string
Stock entry ID.
​
clientId
string
Owning client ID.
​
plantId
string
Owning plant ID.
​
itemType
string
Derived from the catalog item’s type field.
​
materialCode
string
Catalog material code.
​
nombre
string
Material name sourced from the catalog.
​
cantidad
number
Updated stock quantity after upsert.
​
minLevel
number
Alert threshold.
​
maxLevel
number
Reorder target.
​
unidad
string
Unit of measure.
curl -X POST "https://your-domain.com/api/stock" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=<token>" \
  -d '{
    "clientId": "client_abc",
    "plantId": "plant_xyz",
    "materialCode": "FILT-001",
    "cantidad": 10,
    "minLevel": 5,
    "maxLevel": 50,
    "unidad": "unidad"
  }'
To add a serialized consumable (e.g., a membrane with a serial number), include "uniqueId": "SN-00123". The system will create a Consumable record and increment the stock entry by exactly 1.
Error responses:
StatusDescription
400Missing required fields (clientId, plantId, or materialCode).
400materialCode not found in the material catalog.
400Material requires a serial number (requiresSerial: true) but uniqueId was not provided.
400The uniqueId is already registered to another consumable record.
401Not authenticated.
403Insufficient permission (stock:write required).
500Internal server error.

​
POST /api/stock/[id]/adjust

Performs an inventory adjustment on an existing stock entry. Supports two actions: ADJUST_QTY sets the quantity to a new absolute value, and DELETE removes the stock entry entirely and deactivates all associated Consumable records. A justification is always required. All adjustments are written to the audit log and push a push notification to all SUPERVISOR and ADMIN users via OneSignal. Required permission: stock:write
​
action
string
required
ADJUST_QTY to set a new quantity, or DELETE to remove the entry entirely.
​
justificacion
string
required
Human-readable reason for the adjustment. Cannot be blank.
​
newCantidad
number
New absolute quantity. Required when action is ADJUST_QTY. Must be >= 0.
​
success
boolean
true on successful completion.
​
action
string
Echo of the action performed: STOCK_ADJUST or STOCK_DELETE.
​
oldState
object
​
newState
object
curl -X POST "https://your-domain.com/api/stock/se_abc123/adjust" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=<token>" \
  -d '{
    "action": "ADJUST_QTY",
    "justificacion": "Physical count after quarterly audit",
    "newCantidad": 42
  }'
The DELETE action permanently removes the stock entry and sets all associated serialized Consumable records to active: false. This action is irreversible and is recorded in the audit log with the full previous state.
Error responses:
StatusDescription
400justificacion is blank or missing.
400action is not DELETE or ADJUST_QTY.
400newCantidad is not a non-negative number (when using ADJUST_QTY).
404Stock entry with the given id not found.
401Not authenticated.
403Insufficient permission (stock:write required).
500Internal server error.

​
GET /api/stock/available

Returns all consumables and spare parts that are currently in stock and uninstalled for a given plant. The response combines two sources: bulk stock entries (where cantidad > 0, after subtracting out serialized units) and individual active Consumable records that have a uniqueId. This endpoint is used to populate installation selection lists in the UI. Required permission: stock:read
​
plantId
string
Plant ID to filter available items. Pass "all" or omit to retrieve across all plants visible to the authenticated user.
​
type
string
BULK for non-serialized quantities; SERIALIZED for individual tracked units.
​
plantId
string
Plant where the item is held.
​
materialCode
string
Catalog material code.
​
nombre
string
Material display name.
​
maxQuantity
number
Maximum installable quantity. Always 1 for SERIALIZED items.
​
label
string
Human-readable display label for UI dropdowns.
​
id
string
Consumable record ID. Present on SERIALIZED items only.
​
uniqueId
string
Serial number. Present on SERIALIZED items only.
​
expirationMonths
number
Months until expiration after installation. Present on SERIALIZED items only (nullable).
curl -X GET "https://your-domain.com/api/stock/available?plantId=plant_xyz" \
  -H "Cookie: sb-access-token=<token>"
Error responses:
StatusDescription
401Not authenticated.
403Insufficient permission (stock:read required).
500Internal server error.

​
GET /api/stock/transfer

Returns a list of past stock transfers. Results are automatically scoped by role: CLIENT_REQUESTER users see only transfers involving their assigned plants; CLIENT_RESPONSIBLE users see transfers for their client’s plants; ADMIN and SUPERVISOR users see all transfers. Required permission: stock:read
​
plantId
string
Further filter to transfers where this plant is either the source or the destination.
​
id
string
Transfer record ID.
​
fromPlantId
string
Source plant ID.
​
toPlantId
string
Destination plant ID.
​
itemType
string
CONSUMABLE or SPARE_PART.
​
materialCode
string
Catalog material code.
​
nombre
string
Material name at time of transfer.
​
cantidad
number
Units transferred.
​
status
string
COMPLETED, PENDING, or CANCELLED.
​
createdAt
string
ISO 8601 timestamp of when the transfer was initiated.
​
completedAt
string
ISO 8601 timestamp of completion (nullable).
​
fromPlant
object
​
toPlant
object
​
transferredBy
object
curl -X GET "https://your-domain.com/api/stock/transfer?plantId=plant_xyz" \
  -H "Cookie: sb-access-token=<token>"

​
POST /api/stock/transfer

Transfers stock from one plant to another within the same client. The operation is executed inside a single database transaction: the source stock is decremented, the destination is upserted, the transfer record is created with status COMPLETED, and any matching PENDING inter-plant debts from the source plant to the destination plant for the same material are automatically resolved (partially or fully, in FIFO order). Required permission: stock:transfer
​
fromPlantId
string
required
ID of the plant sending the stock.
​
toPlantId
string
required
ID of the plant receiving the stock. Must be different from fromPlantId.
​
itemType
string
required
CONSUMABLE or SPARE_PART.
​
materialCode
string
required
Catalog material code to transfer.
​
cantidad
number
required
Units to transfer. Must be greater than 0 and not exceed the source plant’s current stock.
​
nombre
string
Override the material name on the transfer record. Falls back to the source stock entry’s nombre.
​
id
string
Transfer record ID.
​
fromPlantId
string
Source plant ID.
​
toPlantId
string
Destination plant ID.
​
itemType
string
Item type transferred.
​
materialCode
string
Material code transferred.
​
nombre
string
Material name on the record.
​
cantidad
number
Units transferred.
​
status
string
Always COMPLETED for transfers created via this endpoint.
​
createdAt
string
ISO 8601 creation timestamp.
​
completedAt
string
ISO 8601 completion timestamp.
curl -X POST "https://your-domain.com/api/stock/transfer" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=<token>" \
  -d '{
    "fromPlantId": "plant_north",
    "toPlantId": "plant_south",
    "itemType": "CONSUMABLE",
    "materialCode": "FILT-001",
    "cantidad": 5
  }'
If the source plant has outstanding debts to the destination plant for the same materialCode, those debts are resolved automatically in FIFO order as part of the same transaction. No separate debt-resolution call is needed.
Error responses:
StatusDescription
400Missing required fields.
400cantidad is <= 0.
400fromPlantId equals toPlantId.
400Source stock entry does not exist or has insufficient quantity.
404Destination plant not found.
401Not authenticated.
403Insufficient permission (stock:transfer required).
500Internal server error (transaction rolled back).

​
GET /api/stock/debts

Returns inter-plant debt records. A debt is created when one plant uses consumables that belong to another plant (e.g., during an urgent repair). Results are scoped by role in the same way as the transfers endpoint. Required permission: stock:read
​
plantId
string
Filter to debts where this plant is either the creditor or the debtor.
​
status
string
Filter by debt status. One of PENDING (default) or RESOLVED.
​
id
string
Debt record ID.
​
creditorPlantId
string
ID of the plant that is owed stock.
​
debtorPlantId
string
ID of the plant that owes stock.
​
materialCode
string
Catalog material code.
​
nombre
string
Material name.
​
cantidad
number
Units owed.
​
consumableId
string
Linked Consumable record ID (nullable).
​
status
string
PENDING or RESOLVED.
​
createdAt
string
ISO 8601 creation timestamp.
​
resolvedAt
string
ISO 8601 resolution timestamp (nullable).
​
creditorPlant
object
​
debtorPlant
object
curl -X GET "https://your-domain.com/api/stock/debts?plantId=plant_south&status=PENDING" \
  -H "Cookie: sb-access-token=<token>"
Error responses:
StatusDescription
401Not authenticated.
403Insufficient permission (stock:read required).
500Internal server error.

​
POST /api/stock/debts/[id]/resolve

Marks an inter-plant debt as RESOLVED and records the resolution timestamp. This endpoint accepts both POST and PATCH methods. Note that if the debt was created as part of a transfer, it may already have been resolved automatically — calling this endpoint on an already-resolved debt returns a 400 error. The action is written to the audit log. Required permission: stock:write
This endpoint accepts both POST and PATCH with identical behavior. No request body is required.
​
id
string
Debt record ID.
​
creditorPlantId
string
Creditor plant ID.
​
debtorPlantId
string
Debtor plant ID.
​
materialCode
string
Material code.
​
nombre
string
Material name.
​
cantidad
number
Units that were owed.
​
status
string
Always RESOLVED on a successful response.
​
resolvedAt
string
ISO 8601 resolution timestamp.
curl -X POST "https://your-domain.com/api/stock/debts/debt_abc123/resolve" \
  -H "Cookie: sb-access-token=<token>"
Error responses:
StatusDescription
400Debt is already in RESOLVED status.
404Debt record not found.
401Not authenticated.
403Insufficient permission (stock:write required).
500Internal server error.

​
GET /api/catalog

Returns active material catalog entries. The catalog is the source of truth for all material codes used in stock entries and transfers. Each entry defines whether a material requires serial tracking (requiresSerial) and optionally how many months after installation it expires (expirationMonths). Required permission: stock:read
​
clientId
string
Filter catalog entries to a specific client. Returns all active entries when omitted.
​
id
string
Catalog entry ID.
​
code
string
Unique material code (used as the key for stock entries).
​
nombre
string
Material display name.
​
descripcion
string
Optional description (nullable).
​
type
string
CONSUMABLE or SPARE_PART.
​
requiresSerial
boolean
Whether each unit must have a unique serial number.
​
expirationMonths
number
Months until expiration after installation (nullable).
​
active
boolean
Whether this catalog entry is active.
​
clientId
string
Owning client ID (nullable for shared catalog items).
​
client
object
curl -X GET "https://your-domain.com/api/catalog?clientId=client_abc" \
  -H "Cookie: sb-access-token=<token>"
Error responses:
StatusDescription
401Not authenticated.
403Insufficient permission (stock:read required).
500Internal server error.

Build docs developers (and LLMs) love

Get started for freeTalk to us