Release Notes

Changelog

API REST de Recebimento


Objetivo

Disponibilizar no RUB a API de Recebimento, para que sistemas externos (ERP, TMS, WMS e Compras) incluam, atualizem e consultem ordens e avisos de recebimento por REST / JSON, com validação prévia dos produtos e integridade da gravação.

Contexto

A abertura de recebimentos dependia, em grande parte, da digitação ou de cargas internas. Integradores precisavam de um contrato estável para enviar o pedido antes da conferência, sem gravar itens inválidos e sem alterar uma ordem que já entrou em conferência.

O que mudou

A API fica disponível em /api/rest/receiving/v1 e contempla:

Antes de persistir, todos os produtos do lote são validados. Por padrão, a gravação é tudo ou nada: ou a ordem entra completa, ou nada é gravado. Esse comportamento pode ser desligado para aceitar só os produtos válidos.

Fluxo de Decisão do Processamento

O motor de recebimento valida todos os itens antes de efetivar qualquer gravação. O diagrama a seguir ilustra a sequência de decisão entre a consistência estrita (tudo ou nada) e a continuidade operacional (aceite parcial):

graph TD
    A[Requisição POST/PUT /api/rest/receiving/v1] --> B{Validar itens do lote}
    B -->|Todos válidos| C[Gravar Ordem Completa no RUB]
    C --> D[Retorno HTTP 200 Sucesso]

    B -->|Há itens inválidos| E{accept_partial definido?}
    E -->|Sim: true| F[Gravar itens válidos e registrar observação na ordem]
    E -->|Sim: false| G[Reversão total - Rollback]
    E -->|Não informado| H{Config recebimentoAceitaParcial ligada?}
    H -->|Sim| F
    H -->|Não| G

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

Gravação Tudo ou Nada (Consistência Estrita)

Na modalidade tudo ou nada, o motor de recebimento exige que 100% dos produtos do lote sejam válidos para que a ordem seja persistida. Se houver qualquer divergência cadastral ou item inconsistente:

Como acionar a gravação tudo ou nada

  1. Explicitamente no payload: enviar "accept_partial": false.
  2. Por configuração do sistema: omitir o campo accept_partial quando a configuração recebimentoAceitaParcial (Permite aceite parcial de produtos na API) estiver desligada na loja ou tenant.

Exemplo: Gravação Tudo ou Nada com Falha em Produto

Requisição enviada (accept_partial: false):

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

Retorno da API (HTTP 400 Bad Request — Nenhum item gravado):

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"
    }
  ]
}

Gravação com Aceite Parcial (Continuidade Operacional)

A modalidade de aceite parcial foi concebida para cenários em que o descarregamento das mercadorias na doca não pode ser paralisado por divergências cadastrais pontuais ou cadastro incompleto de itens secundários.

Comportamento do motor:

Como acionar o aceite parcial

  1. Explicitamente no payload: enviar "accept_partial": true.
  2. Por configuração do sistema: omitir o campo accept_partial quando a configuração recebimentoAceitaParcial (Permite aceite parcial de produtos na API) estiver ligada na loja ou tenant.

Exemplo: Gravação com Aceite Parcial (Item Válido Persistido)

Requisição enviada (accept_partial: true):

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

Retorno da API (HTTP 200 OK — Ordem criada com itens aceitos e observações geradas):

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"
    }
  ]
}

Comparativo: Quando Utilizar Cada Modalidade

Critério Tudo ou Nada (accept_partial: false) Aceite Parcial (accept_partial: true)
Garantia de integridade Consistência estrita (ordem idêntica ao documento de origem) Consistência de itens válidos com isolamento de pendências
Comportamento em inconsistência Reversão total (rollback) sem gravar nenhum item Grava itens válidos, gera observação na ordem para os recusados e devolve unaccepted_products
Status HTTP com aceite parcial 400 Bad Request 200 OK
Impacto operacional Exige correção do cadastro ou reenvio integral antes da descarga Permite iniciar imediatamente a conferência física dos produtos válidos
Recomendado para Cargas fechadas com vínculo fiscal estrito (onde lote parcial gera bloqueio) Cargas fracionadas de alto giro ou transferências onde pendências são tratadas depois
Configuração padrão (quando omitido) recebimentoAceitaParcial desligada recebimentoAceitaParcial ligada

Ordens que já não podem ser editadas — por exemplo, em conferência (EM_CONFERENCIA) — não são alteradas.

A autenticação segue o padrão das demais APIs REST do RUB, com token de aplicativo.

O contrato detalhado, exemplos de payload e códigos de cada campo estão na Documentação da API, na seção de Recebimento.

Códigos de retorno

Benefícios