Integração Básica

Esta seção apresenta a Integração Básica do RUB: o conjunto essencial de dados que o RUB espera receber dos sistemas corporativos (ERP, retaguarda e PDV), como as entidades de integração se relacionam entre si, em que ordem devem ser carregadas e onde cada uma delas é exposta na API pública. Para uma visão geral do que é o RUB e dos contextos Empresa/Loja, consulte a página principal da Interface.

Módulos Atendidos pela Integração Básica: A implantação da Integração Básica fornece a base cadastral, de preços, estoques e movimentações indispensável para atender plenamente os seguintes módulos operacionais do RUB no chão de loja:

• Auditoria de Presença — detecção de rupturas e verificação de itens com estoque sistêmico expostos na área de vendas.
• Etiqueta — auditoria e conformidade dos preços de gôndola frente aos preços vigentes no sistema, evitando divergências no caixa.
• Consulta — pesquisa operacional rápida em dispositivos móveis por código de barras, descrição ou setor, exibindo preços vigentes, saldo de estoque físico/disponível e localização do item.
• Ressuprimentos (Tarefas) — motor inteligente de geração e direcionamento automatizado de tarefas de reposição e abastecimento da retaguarda/depósito para a gôndola, baseado no histórico de consumo e movimentações de venda.
• Endereçamento — mapeamento estruturado e manutenção dos endereços físicos de exposição e armazenagem (gôndolas, pontas, aéreos e depósito), orientando com precisão os colaboradores na alocação e localização dos produtos.

O que é a Integração do RUB

A integração é o processo pelo qual os sistemas corporativos alimentam o RUB com os dados que ele precisa para operar e, opcionalmente, recebem de volta os eventos gerados na loja (ajustes de estoque, resultados de auditoria, contagens, etc.).

Ela pode ser realizada por diferentes mecanismos — banco de dados intermediário (tabelas com prefixo RUB_ no sentido ERP → RUB e RUBW_ no sentido RUB → ERP), arquivos ou a API REST pública documentada em https://api.docs.rub.gicbrasil.com. Independentemente do mecanismo, o modelo conceitual é o mesmo: as entidades, seus campos e seus relacionamentos descritos nesta seção valem para todos eles. Nesta documentação, os exemplos de uso são apresentados no formato da API REST por ser o mecanismo mais direto e autoexplicativo.

JSON (1:1) e CSV (massivo)

A API REST oferece dois formatos de envio, escolhidos pelo cabeçalho Content-Type da requisição POST ao mesmo endpoint do recurso:

O arquivo CSV segue estas regras:

• Separador de campos: ponto e vírgula (;); campos delimitados por aspas duplas ("); codificação UTF-8.
• A primeira linha é o cabeçalho, obrigatória, com os nomes dos campos exatamente como na API (code, name, store, product, quantity, ...).
• Colunas extras, não previstas no modelo, são tratadas como propriedades extras da entidade e devem vir após os campos base.
• O processamento é assíncrono: o RUB pré-valida o arquivo linha a linha, enfileira as linhas aceitas e responde imediatamente com um BulkResponse (id, total, accepted, errors[] com line e message). O id permite acompanhar o processamento em GET /{tenant}/api/rest/import/v1/{id}.

Exemplo de CSV para Cadeias:

POST /empresa/api/rest/group/v1
Content-Type: text/csv

"code";"name"
"90010";"HIGIENE E LIMPEZA"
"90011";"AMACIANTE COMFORT 2L"

Registros aninhados no JSON (embalagens e códigos de barras dentro do produto; preços dentro do produto-loja) são, no CSV, arquivos separados e planos, cada um com seu endpoint próprio (veja a tabela em Referência à API Pública).

Regra de ouro da integração: o RUB é um espelho da retaguarda. Tudo que a loja precisa enxergar — o que é o produto, como ele é embalado, quais códigos de barras o identificam, quanto custa, quanto tem em estoque e o que entrou e saiu — deve ser informado pelo sistema corporativo em sua menor unidade comercializada (latas para um refrigerante, gramas para um item de peso variável). Quanto mais fiel e frequente for essa alimentação, mais precisas serão as tarefas que o RUB gera para a loja.

Princípio

• Códigos de integração são do ERP. O RUB identifica cada entidade pelo código do sistema de origem (PLU/SKU, código do fornecedor, código da loja, etc.). O RUB nunca inventa códigos para entidades integradas; ele guarda o código externo como chave de correlação.
• Idempotência. Reenviar o mesmo registro não gera duplicidade: a operação é de criar ou atualizar (upsert) pela chave de integração. Para movimentos, o campo code único é o que garante que uma mesma venda não seja contabilizada duas vezes.
• Menor unidade comercializada. Estoques e movimentos são sempre expressos na menor unidade vendida do produto. Embalagens maiores (caixa, fardo, pack) são descritas pela sua quantidade em relação a essa unidade.
• Ordem de carga. As entidades possuem dependências (veja o diagrama abaixo). Cargas iniciais devem respeitar essa ordem para que as referências (classe, fornecedor, cadeia, produto, loja) existam quando forem apontadas.
• Incremental x Sincronização total. Na API, o método POST é incremental (adiciona ou atualiza sem remover o que já existe), enquanto o PUT faz sincronização total do registro (remove propriedades/embalagens/códigos não presentes no payload).
• JSON para 1:1, CSV para massivo. Use JSON para um registro por requisição e CSV (text/csv) para cargas em lote; ambos no mesmo endpoint do recurso.

Entidades da Integração Básica

A Integração Básica é o conjunto mínimo e indispensável de dados que o RUB precisa receber dos demais sistemas para poder operar e orquestrar o chão de loja. Através desta carga, os módulos de Auditoria de Presença, Etiqueta, Consulta, Ressuprimentos (Tarefas) e Endereçamento operam com total capacidade analítica e de execução em campo. Qualquer outra integração (como pedidos de compra para conferência cega no recebimento de mercadorias, conciliação avançada de inventário ou regras promocionais dinâmicas) é considerada complementar e depende da básica estar funcionando.

As entidades da Integração Básica são:

Cada página de entidade detalha o conceito, o modelo de dados (campos, tipos e obrigatoriedade), os relacionamentos e exemplos práticos de uso.

Diagrama de Dependência entre Entidades

O diagrama abaixo mostra quem depende de quem: uma seta A --> B significa que A referencia B e, portanto, B precisa existir antes de A ser integrado. As entidades em azul pertencem ao contexto Empresa; as em verde, ao contexto Loja.

graph TD
    classDef empresa fill: #dbeafe, stroke: #1d4ed8, color: #1e3a8a
    classDef loja fill: #dcfce7, stroke: #15803d, color: #14532d
    classDef opcional stroke-dasharray: 5 5
    CLASSE["Classe de Produto<br/><small>CODIGO, NOME, CODIGO_PAI, ATIVO</small>"]:::empresa
    FORN["Fornecedor<br/><small>CODIGO, NOME, CNPJ, ATIVO</small>"]:::empresa
    CADEIA["Cadeia<br/><small>CODIGO, NOME</small>"]:::empresa
    LOJA["Loja<br/><small>CODIGO, DESCRICAO, ATIVA</small>"]:::empresa
    PE["Produto Empresa<br/><small>CODIGO, NOME, GERENCIADO, PESO_VARIAVEL</small>"]:::empresa
    EMB["Embalagem<br/><small>PRODUTO, QTD, DESCRICAO</small>"]:::empresa
    CB["Código de Produto<br/><small>PRODUTO, QTD, CODIGO</small>"]:::empresa
    PROD["Produto (Loja)<br/><small>ID_LOJA, CODIGO, CUSTO, ATIVO, VIDA_UTIL</small>"]:::loja
    EMBL["Embalagem Loja<br/><small>ID_LOJA, PRODUTO, QTD, PRECO</small>"]:::loja
    EST["Estoque<br/><small>ID_LOJA, PRODUTO, LOCAL, QTD</small>"]:::loja
    MOV["Movimento<br/><small>ID_LOJA, PRODUTO, CODIGO, TIPO, QTD</small>"]:::loja
    CLASSE -->|CODIGO_PAI<br/>opcional| CLASSE
    FORN -.->|CLASSE_PRODUTO<br/>opcional| CLASSE
    PE -->|CLASSE_PRODUTO| CLASSE
    PE -->|FORNECEDOR| FORN
    PE -.->|CADEIA<br/>opcional| CADEIA
    EMB -->|PRODUTO| PE
    CB -->|PRODUTO + QTD| EMB
    PROD -->|CODIGO| PE
    PROD -->|ID_LOJA| LOJA
    PROD -.->|CODIGO_PAI<br/>opcional| PROD
    EMBL -->|ID_LOJA + PRODUTO| PROD
    EMBL -->|QTD| EMB
    EST -->|ID_LOJA + PRODUTO| PROD
    MOV -->|ID_LOJA + PRODUTO| PROD

Ordem recomendada de carga

A partir do diagrama, uma carga inicial deve seguir a sequência abaixo. Em regime, cada entidade pode ser atualizada isoladamente sempre que mudar na retaguarda.

1. Lojas — cadastro das unidades (/empresa/api/rest/store).
2. Classes de Produto — das classes-raiz para as folhas, pois uma classe pode referenciar sua classe pai.
3. Fornecedores e Cadeias — independentes entre si.
4. Produto Empresa, já com suas Embalagens e Códigos de Produto (em JSON os três viajam juntos no mesmo payload de ProductFull; em CSV são três arquivos, nesta ordem).
5. Produto (Loja) com suas Embalagens Loja (preços) para cada loja em que o produto é comercializado.
6. Estoque — saldo inicial de cada produto em cada loja.
7. Movimentos — a partir daí, de forma contínua e o mais próximo possível do tempo real.

Leitura rápida do modelo

• Um Produto Empresa pertence a uma Classe de Produto, tem um Fornecedor principal e, opcionalmente, uma Cadeia.
• Um Produto Empresa possui uma ou mais Embalagens; cada Embalagem possui zero ou mais Códigos de Produto (códigos de barras).
• Um Produto Empresa existe em zero ou mais Lojas por meio da entidade Produto; é esse vínculo que diz se o item é ativo naquela unidade, qual o custo e a vida útil.
• Cada Produto (Loja) possui uma Embalagem Loja por embalagem comercializada, carregando o preço unitário e o preço da embalagem.
• Estoque e Movimento são sempre por Loja e por Produto, expressos na menor unidade comercializada; o Estoque pode ainda ser detalhado por Local (endereço).

Referência da API REST

As diretrizes de integração, tenancy ({tenantEmpresa}, {tenantLoja}), autenticação Basic, protocolos de envio (JSON 1:1 e CSV massivo assíncrono) e tratamento de erros estão descritos em detalhes na seção Referência da API REST.

O contrato técnico de cada endpoint, seus parâmetros, schemas e exemplos práticos encontram-se documentados diretamente no Swagger oficial: 👉 https://api.docs.rub.gicbrasil.com