Recepción de mercadería¶

Cómo registrar por API lo que llega a la bodega desde un proveedor: qué decía la factura o guía, qué se contó de verdad y las fotos de respaldo. Al confirmar la recepción, el stock sube de inmediato.

Sirve para apps de bodega, lectores de código de barras y sistemas de logística que reciben mercadería fuera del ERP.

Prerrequisitos: Primeros pasos.

Este módulo exige sesión de usuario

La recepción de mercadería no acepta el token fijo de empresa: hay que iniciar sesión con un usuario del ERP y usar Authorization: Bearer. El motivo es que cada recepción queda a nombre de quien la hizo.

Si cada bodeguero inicia sesión con su propio usuario, la recepción queda a su nombre sin hacer nada más.
Si tu sistema usa un solo usuario para todos, las recepciones quedan a nombre de ese usuario. Para registrar a la persona real, envía su nombre en el campo usuario, tanto en la recepción directa como en el borrador.

Quién hace qué¶

La recepción separa dos trabajos que suelen hacer personas distintas:

Quién	Qué hace	Dónde
Bodega	Cuenta lo que llegó, lo declara y saca fotos. El stock sube al confirmar.	Por API (esta guía) o app móvil
Compras	Toma la recepción confirmada y la convierte en una compra formal, con precios y costos, que afecta las cuentas por pagar.	En el ERP

La recepción responde "¿qué llegó?"; la compra responde "¿cuánto costó y cuánto debemos?".

Los estados de una recepción¶

Estado	Significado
`BORRADOR`	Conteo en curso. Se puede seguir editando. No mueve stock.
`CONFIRMADA`	Bodega cerró el conteo. El stock ya subió. Falta que Compras la procese.
`IMPORTADA`	Compras la convirtió en una compra formal. Ya no se puede anular por API.
`ANULADA`	Se anuló y el stock se devolvió.

Dos formas de registrar¶

	Recepción directa	Borrador y confirmación
Llamado	`POST /recepciones`	`POST /recepciones/guardar` y luego `POST /recepciones/{id}/confirmar`
Cuándo usarla	El conteo se hace de una vez y se envía completo	El conteo toma tiempo, se hace por partes o hay que poder corregir antes de cerrar
Stock	Sube al crear	Sube al confirmar
Cuenta por bulto (cajas, displays)	Sí, marcando la línea con `"contarPorBulto": true`; la API busca la unidad del proveedor	Sí, enviando la unidad y su factor en cada línea

Recepción directa¶

curl -X POST https://api.opentpv.cl/recepciones \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "idProveedor": 42,
    "rutProveedor": "76543210-K",
    "razonSocialProveedor": "Distribuidora Andina SPA",
    "tipoDocumento": "FACTURA",
    "numeroDocumento": "12345",
    "fechaDocumento": "2026-08-10",
    "bodega": 1,
    "folioOrdenCompra": 587,
    "observacion": "Llegó camión 10:30",
    "usuario": "JPEREZ",
    "items": [
      { "codigo": "PROD001", "descripcion": "Bebida cola 1.5L",
        "cantidadDocumento": 24, "cantidadRecibida": 24 },
      { "codigo": "PROD002", "descripcion": "Bebida naranja 1.5L",
        "cantidadDocumento": 12, "cantidadRecibida": 10,
        "observacion": "2 unidades dañadas, ver foto" }
    ]
  }'

{ "exito": true, "folio": 234, "idRecepcion": 1789,
  "mensaje": "Recepción registrada y stock actualizado" }

Las dos cantidades de cada línea son la clave:

Campo	Qué es
`cantidadDocumento`	Lo que dice la factura o guía del proveedor.
`cantidadRecibida`	Lo que se contó en la bodega. Es lo que sube al stock.

Si no coinciden, la recepción guarda la diferencia. En el ejemplo, de la bebida naranja se facturaron 12 y llegaron 10: el stock sube en 10 y queda registrada una diferencia de 2.

usuario es opcional: si no lo envías, la recepción queda a nombre del usuario de la sesión.

Guarda idRecepcion: lo necesitas para adjuntar fotos, consultar o anular. Si una línea no indica bodega, usa la de la cabecera; si tampoco viene, la 1.

Borrador y confirmación¶

1. Guardar el borrador¶

curl -X POST https://api.opentpv.cl/recepciones/guardar \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "idRecepcion": 0,
    "estado": "BORRADOR",
    "idProveedor": 42,
    "rutProveedor": "76543210-K",
    "tipoDocumento": "FACTURA",
    "numeroDocumento": "12345",
    "fecha": "2026-08-10",
    "idBodega": 1,
    "lineas": [
      { "codigo": "PROD001", "cantidadDocumento": 4, "cantidadRecibida": 4,
        "idUnidadCompra": 3, "nombreUnidadCompra": "DISPLAY", "factorUnidadCompra": 6 }
    ]
  }'

{ "success": true, "message": "Recepción guardada",
  "data": { "idRecepcion": 1789, "folio": 234, "estado": "BORRADOR" } }

idRecepcion en 0 crea una recepción nueva. Con el número de un borrador existente, lo actualiza reemplazando todas sus líneas.
estado en "BORRADOR" guarda sin tocar el stock. En "CONFIRMADA" guarda y sube el stock en el mismo llamado.

2. Confirmar¶

curl -X POST https://api.opentpv.cl/recepciones/1789/confirmar \
  -H "Authorization: Bearer eyJhbGciOi..."

{ "success": true, "message": "Recepción confirmada",
  "data": { "idRecepcion": 1789, "folio": 234, "estado": "CONFIRMADA" } }

El stock sube una sola vez. Si repites el llamado porque no recibiste respuesta, no se vuelve a sumar: responde éxito igual.

Contar por bulto¶

Muchos proveedores facturan por caja o display y no por unidad. En vez de pedirle al bodeguero que multiplique, se cuenta en bultos y la API convierte:

En el ejemplo se contaron 4 displays de 6 unidades: cantidadRecibida 4 y factorUnidadCompra 6. El stock sube en 24 unidades.
Para saber si un producto de ese proveedor se cuenta por bulto:

curl "https://api.opentpv.cl/recepciones/unidad-compra?rutProveedor=76543210-K&codigo=PROD001" \
  -H "Authorization: Bearer eyJhbGciOi..."

{ "success": true, "data": { "idUnidadCompra": 3, "nombre": "DISPLAY", "factor": 6.0 } }

Si data viene en null, el producto se cuenta por unidad: envía la línea sin unidad de compra.

Adjuntar fotos¶

Las fotos se suben como archivo (multipart/form-data, campo file):

# Foto de la factura o guía del proveedor
curl -X POST https://api.opentpv.cl/recepciones/1789/foto-documento \
  -H "Authorization: Bearer eyJhbGciOi..." -F "file=@factura12345.jpg"

# Foto de un problema en la línea 2 (producto dañado, faltante)
curl -X POST https://api.opentpv.cl/recepciones/1789/lineas/2/foto \
  -H "Authorization: Bearer eyJhbGciOi..." -F "file=@producto-danado.jpg"

{ "exito": true, "url": "/uploads/recepciones/76123456-7/1789/doc-20260810114512.jpg" }

El número de línea es su posición dentro de la recepción (1, 2, 3...), tal como viene en items[].linea al consultar el detalle. Cuando lo contado no coincide con lo facturado, conviene adjuntar siempre la foto: es el respaldo para reclamarle al proveedor.

Consultar¶

# Listado, con filtros opcionales
curl "https://api.opentpv.cl/recepciones?desde=2026-08-01&hasta=2026-08-10&estado=CONFIRMADA&bodega=1" \
  -H "Authorization: Bearer eyJhbGciOi..."

# Detalle completo de una recepción: cabecera, líneas, diferencias y fotos
curl https://api.opentpv.cl/recepciones/1789 -H "Authorization: Bearer eyJhbGciOi..."

El listado devuelve un resumen por recepción (folio, proveedor, documento, estado, total de líneas y unidades). El detalle agrega las líneas con su diferencia, las fotos y las fechas de cada etapa. Una búsqueda sin resultados responde una lista vacía, no un error.

Anular¶

curl -X DELETE "https://api.opentpv.cl/recepciones/1789?motivo=Error%20de%20conteo" \
  -H "Authorization: Bearer eyJhbGciOi..."

{ "exito": true, "mensaje": "Recepción anulada y stock revertido" }

El stock que había subido se descuenta. Si entre medio se vendió parte de esa mercadería, el stock puede quedar negativo: revisa antes de anular.
Si Compras ya la convirtió en una compra formal (IMPORTADA), la API responde 409 y la anulación debe hacerse desde el ERP.

Errores frecuentes¶

Enviar en cantidadRecibida lo que dice la factura en vez de lo contado: el stock queda inflado y la diferencia no se registra.
Al contar por bulto, enviar las unidades ya multiplicadas y además el factor: el stock sube multiplicado dos veces.
Actualizar un borrador enviando solo las líneas nuevas: guardar reemplaza todas las líneas, hay que enviar el conteo completo.
Esperar que la recepción genere la cuenta por pagar: eso ocurre cuando Compras la procesa en el ERP.

Relacionado: para aceptar o reclamar ante el SII la factura del proveedor, ver Compras recibidas del SII.