Release Notes

Changelog

API REST de Recepción


Objetivo

Disponibilizar en RUB la API de Recepción, para que los sistemas externos (ERP, TMS, WMS y Compras) incluyan, actualicen y consulten órdenes y avisos de recepción por REST / JSON, con validación previa de los productos e integridad de la grabación.

Contexto

La apertura de recepciones dependía, en gran parte, de la digitación o de cargas internas. Los integradores necesitaban un contrato estable para enviar el pedido antes de la conferencia, sin grabar ítems inválidos y sin alterar una orden que ya entró en conferencia.

Qué cambió

La API queda disponible en /api/rest/receiving/v1 y contempla:

Antes de persistir, todos los productos del lote se validan. Por defecto, la grabación es todo o nada: o la orden entra completa, o no se graba nada. Ese comportamiento se puede desactivar para aceptar solo los productos válidos.

Flujo de Decisión del Procesamiento

El motor de recepción valida todos los ítems antes de realizar cualquier grabación. El siguiente diagrama ilustra la secuencia de decisión entre la consistencia estricta (todo o nada) y la continuidad operativa (aceptación parcial):

graph TD
    A[Solicitud POST/PUT /api/rest/receiving/v1] --> B{Validar ítems del lote}
    B -->|Todos válidos| C[Grabar Orden Completa en RUB]
    C --> D[Retorno HTTP 200 Éxito]

    B -->|Hay ítems inválidos| E{¿accept_partial definido?}
    E -->|Sí: true| F[Grabar ítems válidos y registrar observación en la orden]
    E -->|Sí: false| G[Reversión total - Rollback]
    E -->|No informado| H{¿Config recebimentoAceitaParcial activa?}
    H -->|Sí| F
    H -->|No| G

    F --> I[Retorno HTTP 200 con unaccepted_products]
    G --> J[Retorno HTTP 400 Bad Request con unaccepted_products]

Grabación Todo o Nada (Consistencia Estricta)

En la modalidad todo o nada, el motor de recepción exige que el 100% de los productos del lote sean válidos para que la orden sea persistida. Si hay cualquier divergencia de catálogo o ítem inconsistente:

Cómo accionar la grabación todo o nada

  1. Explícitamente en el payload: enviar "accept_partial": false.
  2. Por configuración del sistema: omitir el campo accept_partial cuando la configuración recebimentoAceitaParcial (Permite aceptación parcial de productos en la API) esté desactivada en la tienda o tenant.

Ejemplo: Grabación Todo o Nada con Fallo en Producto

Solicitud enviada (accept_partial: false):

JSON
{
  "code": "ORD-2026-9001",
  "store": 30001,
  "accept_partial": false,
  "items": [
    { "product": "78910001001", "quantity": 50 },
    { "product": "99999999999", "quantity": 10 }
  ]
}

Retorno de la API (HTTP 400 Bad Request — Ningún ítem grabado):

JSON
{
  "status": 400,
  "message": "Ordem não pode ser processada pois contém produtos inválidos e o aceite parcial está desativado.",
  "unaccepted_products": [
    {
      "product": "99999999999",
      "reason": "PRODUTO_NAO_CADASTRADO"
    }
  ]
}

Grabación con Aceptación Parcial (Continuidad Operativa)

La modalidad de aceptación parcial fue diseñada para escenarios en los que la descarga de mercancías en el muelle no puede detenerse por divergencias puntuales de catálogo o ítems secundarios no registrados.

Comportamiento del motor:

Cómo accionar la aceptación parcial

  1. Explícitamente en el payload: enviar "accept_partial": true.
  2. Por configuración del sistema: omitir el campo accept_partial cuando la configuración recebimentoAceitaParcial (Permite aceptación parcial de productos en la API) esté activada en la tienda o tenant.

Ejemplo: Grabación con Aceptación Parcial (Ítem Válido Persistido)

Solicitud enviada (accept_partial: true):

JSON
{
  "code": "ORD-2026-9001",
  "store": 30001,
  "accept_partial": true,
  "items": [
    { "product": "78910001001", "quantity": 50 },
    { "product": "99999999999", "quantity": 10 }
  ]
}

Retorno de la API (HTTP 200 OK — Orden creada con ítems aceptados y observaciones generadas):

JSON
{
  "status": 200,
  "code": "ORD-2026-9001",
  "message": "Ordem de recebimento criada com aceite parcial de produtos.",
  "unaccepted_products": [
    {
      "product": "99999999999",
      "reason": "PRODUTO_NAO_CADASTRADO"
    }
  ]
}

Comparativa: Cuándo Utilizar Cada Modalidad

Criterio Todo o Nada (accept_partial: false) Aceptación Parcial (accept_partial: true)
Garantía de integridad Consistencia estricta (orden idéntica al documento de origen) Consistencia de ítems válidos con aislamiento de pendientes
Comportamiento en inconsistencia Reversión total (rollback) sin grabar ningún ítem Graba ítems válidos, genera observación en la orden para los rechazados y devuelve unaccepted_products
Estado HTTP con aceptación parcial 400 Bad Request 200 OK
Impacto operativo Exige corrección en el catálogo o reenvío integral antes de la descarga Permite iniciar inmediatamente la conferencia física de los productos válidos
Recomendado para Cargas consolidadas con vínculo fiscal estricto (donde lote parcial genera bloqueo) Cargas fracionadas de alta rotación o transferencias donde pendientes se tratan después
Configuración por defecto (cuando se omite) recebimentoAceitaParcial desactivada recebimentoAceitaParcial activada

Las órdenes que ya no pueden editarse — por ejemplo, en conferencia (EM_CONFERENCIA) — no se alteran.

La autenticación sigue el estándar de las demás APIs REST de RUB, con token de aplicación.

El contrato detallado, los ejemplos de payload y los códigos de cada campo están en la Documentación de la API, en la sección de Recepción.

Códigos de retorno

Beneficios