Consulta de recepción y stock

Proyecciones calculadas y cola de diferencias.

Agregado de operaciones

GET /api/v1/agent/operations?asOf=2026-10-01 requiere operations:read. Respuesta: { data: { asOf, customers, sales, receipts, credits, orders, candidates, products, notes, receiving, receivingIssues, movements, purchases, suppliers, documents } }.

products agrega received, quantity y hasOpening. purchases agrega receivingStatus, detailPending y receivingLines. notes agrega receivingStatus sin reemplazar su status físico draft/received. El agregado sólo incluye registros activos; no reemplaza una sincronización de anulaciones.

Los from/to del agregado no recortan cada colección como un exportador por período: usar asOf para los cálculos y filtrar explícitamente en el consumidor cuando corresponda.

Cola de diferencias

GET /api/v1/agent/receiving-exceptions requiere operations:read. Filtros: supplierId, invoiceId, deliveryNoteId, productId, status, search, limit y cursor. limit de 1 a 200, defecto 50; status omitido excluye complete, status=all incluye todos.

Respuesta: data, total, counters, revision y nextCursor en el nivel raíz. Seguir nextCursor manteniendo filtros. 409 VERSION_CONFLICT exige reiniciar; 400 INVALID_CURSOR indica que el cursor no corresponde a la consulta.

Campos de ReceivingRow

key, resource, recordId, lineId y supplierId identifican el origen. invoiceId, invoiceLineId, invoiceNumber, productId y supplierCode pueden ser null. description y unit conservan el detalle. invoicedQuantity, receivedQuantity, missingQuantity, excessQuantity y unlinkedQuantity expresan cantidades, no dinero.

receivingStatus, detailPending y reasons explican el caso. deliveryNoteIds, deliveryNoteNumbers, orderReferences, deliveries y documentIds aportan relaciones. Cada delivery identifica noteId, lineId, number, date, quantity y reasons.

Diccionario de campos

Obligatorio / Opcional: campos del registro de negocio; dentro de una lista u objeto, se aplica cuando ese contenedor está presente. Servidor: identidad y auditoría. Respuesta: campos agregados o administrados por el servidor; no enviarlos como una edición ordinaria. La presencia de los calculados depende del endpoint.

Campo	Tipo / valores	Condición	Significado y restricciones
`key`	`string`	Respuesta	Clave estable de la fila de recepción.
`resource`	`"invoices" \| "delivery-notes"`	Respuesta	Nombre del recurso relacionado.
`recordId`	`uuid`	Respuesta	UUID del registro relacionado.
`lineId`	`string`	Respuesta	ID textual de la línea destino, local a la factura.
`supplierId`	`uuid`	Respuesta	UUID de suppliers; distingue la cuenta del proveedor.
`supplierName`	`string`	Respuesta	Nombre del proveedor en la proyección.
`invoiceId`	`uuid \| null`	Respuesta	UUID de la factura asociada; el recurso destino depende del circuito.
`invoiceLineId`	`string \| null`	Respuesta	ID local de la línea de factura; null si no existe destino conocido.
`invoiceNumber`	`string \| null`	Respuesta	Número de factura relacionado; null si no se conoce.
`productId`	`uuid \| null`	Respuesta	UUID de products.
`supplierCode`	`string \| null`	Respuesta	Código de proveedor opcional. Coincidencia exacta cuando ambas líneas lo informan.
`description`	`string`	Respuesta	Descripción registrada.
`unit`	`string`	Respuesta	Unidad textual exacta. No hay conversiones automáticas.
`invoicedQuantity`	`string \| null`	Respuesta	Cantidad facturada; null cuando falta el detalle.
`receivedQuantity`	`string`	Respuesta	Cantidad vinculada recibida, incluso vínculos incompatibles señalados en reasons.
`missingQuantity`	`string \| null`	Respuesta	Cantidad faltante; null cuando no puede calcularse.
`excessQuantity`	`string`	Respuesta	Cantidad recibida por encima de lo facturado.
`unlinkedQuantity`	`string`	Respuesta	Parte física recibida sin asignación a factura.
`receivingStatus`	`"unlinked" \| "pending" \| "partial" \| "complete" \| "excess" \| "mismatch"`	Respuesta	Estado de conciliación de cantidades.
`detailPending`	`boolean`	Respuesta	Falta el detalle físico necesario para conciliar.
`deliveryNoteIds`	`array`	Respuesta	UUID de remitos relacionados.
`deliveryNoteNumbers`	`array`	Respuesta	Números de remitos relacionados.
`orderReferences`	`array`	Respuesta	Referencias documentadas de pedidos; no son claves foráneas.
`reasons`	`array`	Respuesta	Motivos concretos de incompatibilidad.
`documentIds`	`array`	Respuesta	UUID de los respaldos. No contiene imágenes ni archivos.
`deliveries`	`array`	Respuesta	Recepciones que componen esta fila.
`deliveries[].noteId`	`uuid`	Respuesta	UUID del remito que originó esta recepción.
`deliveries[].lineId`	`string`	Respuesta	ID textual de la línea destino, local a la factura.
`deliveries[].number`	`string`	Respuesta	Número de comprobante conservado como texto, con sus ceros y formato.
`deliveries[].date`	`string`	Respuesta	Fecha civil del movimiento, YYYY-MM-DD.
`deliveries[].quantity`	`string`	Respuesta	Cantidad decimal exacta. En entradas de líneas/movimientos es positiva, hasta 4 decimales.
`deliveries[].reasons`	`array`	Respuesta	Motivos concretos de incompatibilidad.