Inventory API: Receipts, Remitos, and Stock Adjustments

The inventory API group covers three stock management workflows: direct goods receipt for immediate single-item additions without an approval step, the remito workflow for multi-item supplier deliveries that require admin confirmation before stock is updated, and manual adjustments for ad-hoc corrections backed by a full audit trail. All endpoints require a JWT Bearer token.

POST /api/recepcion

Immediately increases the stock level of a single product. The movement is recorded in MovimientoStock and takes effect instantly — there is no approval step. Auth: ADMIN or EMPLEADO The empleadoId performing the receipt is extracted from the JWT; it does not need to be sent in the request body.

Request Body (`RecepcionRequest`)

productoId

Long

required

ID of the product whose stock is being replenished.

cantidad

Integer

required

Number of units received. Minimum 1.

notas

string

Optional free-text note about the receipt (e.g. delivery reference). Maximum 500 characters.

recepcionRemitoId

Long

Optional ID of an existing remito to associate this movement with. Use when manually linking a direct receipt to a supplier remito record.

Response `201 Created`

Returns a RecepcionResponse.

movimientoId

Long

ID of the generated MovimientoStock record.

productoId

Long

ID of the restocked product.

sku

string

SKU of the restocked product.

nombreProducto

string

Display name of the restocked product.

cantidadRecibida

Integer

Units added to stock.

stockAnterior

Integer

Stock level immediately before this receipt.

stockNuevo

Integer

Stock level after this receipt (stockAnterior + cantidadRecibida).

fecha

OffsetDateTime

Timestamp of the movement in ISO-8601 format.

curl -X POST http://localhost:8081/api/recepcion \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "productoId": 12,
    "cantidad": 50,
    "notas": "Reposición semanal proveedor Brida S.A."
  }'

POST /api/recepciones-remito

Creates a pending supplier delivery (remito). The remito captures header information — supplier, remito number, and notes — but does not update stock. An admin must approve the remito before stock levels change. Auth: ADMIN or EMPLEADO The empleadoId who created the remito is extracted from the JWT automatically.

Request Body (`RecepcionRemitoRequest`)

proveedorId

Long

required

ID of the supplier issuing the remito.

numeroRemito

string

required

Supplier’s document number for this delivery. Maximum 100 characters. Used as a human-readable reference and deduplication key.

notas

string

Optional free-text notes about the delivery. Maximum 500 characters.

Response `201 Created`

Returns a RecepcionRemitoResponse. The estado field will be PENDIENTE.

After creating a remito header, add individual product lines by creating RecepcionRequest records with recepcionRemitoId set to the new remito ID. Then submit the remito for admin approval via PATCH /api/recepciones-remito/{id}/confirmar.

GET /api/recepciones-remito/mis-recepciones

Returns all remito receipts created by the authenticated user. Both ADMIN and EMPLEADO callers see only their own records. Auth: ADMIN or EMPLEADO

Response `200 OK`

Returns an array of RecepcionRemitoResponse. See RecepcionRemitoResponse fields below.

GET /api/recepciones-remito/pendientes

Returns all remitos currently in PENDIENTE state, across all employees. Use this endpoint to build the admin approval queue. Auth: ADMIN

Response `200 OK`

Returns an array of RecepcionRemitoResponse where estado = PENDIENTE.

GET /api/recepciones-remito

Returns all remitos regardless of state (PENDIENTE, CONFIRMADO, or RECHAZADO). Auth: ADMIN

Response `200 OK`

Returns an array of RecepcionRemitoResponse.

GET /api/recepciones-remito/{id}

Returns the full details of a single remito, including its item list. Auth: ADMIN or EMPLEADO

Path Parameters

Long

required

Internal remito identifier.

Response `200 OK`

Returns a RecepcionRemitoResponse.

PATCH /api/recepciones-remito/{id}/confirmar

Confirms or rejects a pending remito. On confirmation (aprobar: true), all associated MovimientoStock records are applied and product stock levels are updated atomically. On rejection (aprobar: false), no stock change occurs. Auth: ADMIN

Path Parameters

Long

required

Internal remito identifier. Must currently be in PENDIENTE state.

Request Body (`ConfirmarRemitoRequest`)

aprobar

boolean

required

true to confirm the remito and update stock; false to reject it. The resulting estado will be CONFIRMADO or RECHAZADO respectively.

notasAdmin

string

Optional admin notes explaining the decision (e.g. reason for rejection). Maximum 500 characters.

Response `200 OK`

Returns the updated RecepcionRemitoResponse with the new estado and confirmadoAt timestamp.

RecepcionRemitoResponse Fields

Long

Internal remito identifier.

proveedorId

Long

ID of the associated supplier.

nombreProveedor

string

Display name of the supplier.

numeroRemito

string

Supplier’s document number for this delivery.

estado

string

Current approval state. One of PENDIENTE, CONFIRMADO, RECHAZADO.

nombreEmpleado

string

Full name of the employee who created the remito.

nombreAdmin

string

Full name of the admin who confirmed or rejected the remito. null while still pending.

notas

string

Employee notes recorded at creation time. May be null.

notasAdmin

string

Admin notes recorded at confirmation / rejection time. May be null.

createdAt

OffsetDateTime

Timestamp when the remito was created.

confirmadoAt

OffsetDateTime

Timestamp when the remito was confirmed or rejected. null while still pending.

items

array

Stock movement lines associated with this remito. Populated after individual RecepcionRequest records are linked.

Show ItemRecepcionResponse fields

movimientoId

Long

ID of the MovimientoStock record.

productoId

Long

ID of the product received.

sku

string

SKU of the product received.

nombreProducto

string

Product display name.

cantidad

Integer

Units received in this line.

stockAnterior

Integer

Stock level before confirmation.

stockNuevo

Integer

Stock level after confirmation. Equals stockAnterior if the remito was rejected.

fecha

OffsetDateTime

Timestamp of the movement application.

POST /api/ajustes-stock

Manually increases or decreases the stock of any product. Every adjustment creates an immutable MovimientoStock audit record attributed to the calling admin. Auth: ADMIN

Request Body (`AjusteStockRequest`)

productoId

Long

required

ID of the product to adjust.

cantidad

Integer

required

Units to add (positive integer) or remove (negative integer). For example, 10 adds ten units; -3 removes three units.

motivo

string

required

Human-readable reason for the adjustment (e.g. "Rotura en depósito", "Corrección inventario físico"). Maximum 500 characters.

Response `201 Created`

Returns an AjusteStockResponse.

movimientoId

Long

ID of the created MovimientoStock record.

productoId

Long

ID of the adjusted product.

sku

string

SKU of the adjusted product.

nombreProducto

string

Display name of the adjusted product.

cantidad

Integer

The signed adjustment applied (+ for addition, - for removal).

stockAnterior

Integer

Stock level before the adjustment.

stockNuevo

Integer

Stock level after the adjustment.

motivo

string

Reason for the adjustment as supplied in the request.

nombreAdmin

string

Full name of the admin who performed the adjustment.

fecha

OffsetDateTime

Timestamp of the adjustment in ISO-8601 format.

Stock adjustments are irreversible through the API. Negative adjustments can drive stockActual below zero if no floor validation is configured. Always verify the current stock via GET /api/productos/{id} before submitting a negative adjustment.

curl -X POST http://localhost:8081/api/ajustes-stock \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "productoId": 47,
    "cantidad": -5,
    "motivo": "Unidades dañadas detectadas en inventario físico mensual"
  }'

GET /api/ajustes-stock

Returns a paginated list of all manual stock adjustments, ordered from most recent to oldest. Auth: ADMIN

Query Parameters

page

integer

Zero-based page number. Defaults to 0.

size

integer

Number of records per page. Defaults to 50.

Response `200 OK`

Returns a Spring Page<AjusteStockResponse> envelope.

content

array

Array of AjusteStockResponse objects for the current page.

totalElements

Long

Total number of adjustments across all pages.

totalPages

Integer

Total number of pages given the requested size.

number

Integer

Current page number (zero-based).

size

Integer

Page size used for this response.

first

boolean

true if this is the first page.

last

boolean

true if this is the last page.

Reference: `EstadoRecepcionEnum`

Value	Description
`PENDIENTE`	Remito created and awaiting admin review
`CONFIRMADO`	Remito approved; stock has been updated
`RECHAZADO`	Remito rejected by admin; no stock change applied

Overview

Endpoints

Inventory API: Receipts, Remitos, and Stock Adjustments

POST /api/recepcion

Request Body (`RecepcionRequest`)

Response `201 Created`

POST /api/recepciones-remito

Request Body (`RecepcionRemitoRequest`)

Response `201 Created`

GET /api/recepciones-remito/mis-recepciones

Response `200 OK`

GET /api/recepciones-remito/pendientes

Response `200 OK`

GET /api/recepciones-remito

Response `200 OK`

GET /api/recepciones-remito/{id}

Path Parameters

Response `200 OK`

PATCH /api/recepciones-remito/{id}/confirmar

Path Parameters

Request Body (`ConfirmarRemitoRequest`)

Response `200 OK`

RecepcionRemitoResponse Fields

POST /api/ajustes-stock

Request Body (`AjusteStockRequest`)

Response `201 Created`

GET /api/ajustes-stock

Query Parameters

Response `200 OK`

Reference: `EstadoRecepcionEnum`

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/recepcion

​Request Body (RecepcionRequest)

​Response 201 Created

​POST /api/recepciones-remito

​Request Body (RecepcionRemitoRequest)

​Response 201 Created

​GET /api/recepciones-remito/mis-recepciones

​Response 200 OK

​GET /api/recepciones-remito/pendientes

​Response 200 OK

​GET /api/recepciones-remito

​Response 200 OK

​GET /api/recepciones-remito/{id}

​Path Parameters

​Response 200 OK

​PATCH /api/recepciones-remito/{id}/confirmar

​Path Parameters

​Request Body (ConfirmarRemitoRequest)

​Response 200 OK

​RecepcionRemitoResponse Fields

​POST /api/ajustes-stock

​Request Body (AjusteStockRequest)

​Response 201 Created

​GET /api/ajustes-stock

​Query Parameters

​Response 200 OK

​Reference: EstadoRecepcionEnum

Build docs developers (and LLMs) love

POST /api/recepcion

Request Body (`RecepcionRequest`)

Response `201 Created`

POST /api/recepciones-remito

Request Body (`RecepcionRemitoRequest`)

Response `201 Created`

GET /api/recepciones-remito/mis-recepciones

Response `200 OK`

GET /api/recepciones-remito/pendientes

Response `200 OK`

GET /api/recepciones-remito

Response `200 OK`

GET /api/recepciones-remito/{id}

Path Parameters

Response `200 OK`

PATCH /api/recepciones-remito/{id}/confirmar

Path Parameters

Request Body (`ConfirmarRemitoRequest`)

Response `200 OK`

RecepcionRemitoResponse Fields

POST /api/ajustes-stock

Request Body (`AjusteStockRequest`)

Response `201 Created`

GET /api/ajustes-stock

Query Parameters

Response `200 OK`

Reference: `EstadoRecepcionEnum`