Fornecedor

Integração Básica do RUB — entidade obrigatória, de contexto Empresa. Na API pública é representada pela tag Supplier e pelos schemas Supplier e Contact.

O que é um Fornecedor

O Fornecedor é a origem comercial do produto — a indústria ou marca responsável por ele: Unilever, Nestlé, Ambev, Coca-Cola, P&G. Cada Produto Empresa aponta para um Fornecedor principal.

No RUB o Fornecedor tem um papel diferente do que costuma ter no ERP. Para o ERP, o fornecedor é uma pessoa jurídica com quem se negocia, emite pedido e recebe nota fiscal — e por isso a mesma indústria pode aparecer como dezenas de cadastros (uma filial por estado, distribuidores, atacadistas). Para o RUB, o Fornecedor serve a fins estatísticos e operacionais de loja:

• Análises por indústria — qual a ruptura dos produtos Unilever? Quantas divergências de etiqueta em itens Nestlé? Quanto tempo leva a reposição de produtos Ambev?
• Relacionamento com promotores — os promotores de vendas que visitam a loja representam uma indústria, não uma filial fiscal. O RUB registra entrada/saída de promotores e pode vincular as tarefas que eles executam (reposição, arrumação de gôndola) ao Fornecedor correspondente.
• Contatos — telefones e nomes de contatos comerciais e de promotores, usados pela loja para acionar o fornecedor em caso de ruptura ou problema de exposição.

Regra importante: informe um único Fornecedor por indústria, e não um por pessoa jurídica. É esperado que exista um único fornecedor "Unilever" no RUB, em vez de um fornecedor para cada CNPJ que distribui mercadorias da Unilever no Brasil. Caso contrário, as estatísticas ficam fragmentadas e perdem utilidade.

Modelo de dados

Chave e identidade

A chave é o CODIGO, definido pelo sistema corporativo. Quando o ERP tem múltiplos cadastros para a mesma indústria, o integrador deve eleger um código representativo (por exemplo, o da matriz ou um código de "grupo econômico") e usá-lo consistentemente nos produtos.

Contatos

Na API o Fornecedor carrega uma lista de contatos (contacts[]), cada um com nome, telefone e tipo:

Relacionamentos

graph LR
    FORN["Fornecedor<br/>CODIGO, NOME, CNPJ, ATIVO"]
    FORN -.->|CLASSE_PRODUTO<br/>opcional| CLASSE["Classe de Produto"]
    PE1["Produto Empresa<br/>10021"] -->|FORNECEDOR| FORN
    PE2["Produto Empresa<br/>10022"] -->|FORNECEDOR| FORN
    CONT["Contato<br/>nome, telefone, tipo"] -->|contacts| FORN
    PROM["Promotor<br/>(entrada/saída)"] -.->|providers| FORN

• Um Fornecedor possui zero ou mais Produtos Empresa e zero ou mais Contatos.
• Um Produto Empresa tem um Fornecedor principal.
• Um Fornecedor pode indicar uma Classe de Produto em que atua (opcional).
• Depende apenas, opcionalmente, da Classe de Produto.

Equivalência na API

Exemplos de uso

Cenário 1 — Consolidando filiais em uma indústria

O ERP possui três cadastros para a Unilever (5001 matriz SP, 5002 filial PE, 5003 distribuidor MG). O integrador elege 5001 como código representativo e envia um Fornecedor:

POST /empresa/api/rest/supplier/v1
{
  "code": "5001",
  "name": "UNILEVER",
  "cnpj": "61.068.276/0001-04",
  "category": "HIGIENE",
  "active": true,
  "contacts": [
    { "name": "Marcos Andrade", "phone": "(11) 99999-1010", "type": 1 },
    { "name": "Juliana Reis",   "phone": "(11) 98888-2020", "type": 2 }
  ]
}

Ao integrar os produtos, o ERP traduz qualquer uma das três filiais para 5001 no campo supplier do Produto Empresa.

Cenário 2 — Carga inicial massiva (CSV)

Na carga inicial, o ERP exporta os fornecedores já consolidados por indústria em um arquivo CSV (Content-Type: text/csv):

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

"code";"name";"cnpj";"category";"active"
"5010";"AMBEV";"07.526.557/0001-00";"200";"true"
"5011";"COCA-COLA FEMSA";"";"200";"true"
"5012";"NESTLE";"";"";"true"
"5013";"PROCTER & GAMBLE";"";"210";"true"

A resposta BulkResponse informa id, total, accepted e a lista de errors com a linha e a mensagem (ex.: category inexistente).

Cenário 3 — Atualizando apenas contatos

A indústria trocou o promotor que atende a região. Como o POST é incremental, basta enviar o Fornecedor com o novo contato — os campos e contatos anteriores são preservados:

POST /empresa/api/rest/supplier/v1
{
  "code": "5001",
  "name": "UNILEVER",
  "active": true,
  "contacts": [
    { "name": "Carlos Nunes", "phone": "(11) 97777-3030", "type": 2 }
  ]
}

Para importar contatos em massa a partir de um cadastro separado no ERP (contato → fornecedor), utilize POST /empresa/api/rest/supplier/v1/contact com CSV, informando em cada linha o código do fornecedor (supplier), name, phone e type:

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

"supplier";"name";"phone";"type"
"5001";"Carlos Nunes";"(11) 97777-3030";"2"
"5010";"Paula Martins";"(21) 96666-4040";"1"

Para substituir completamente o Fornecedor e sua lista de contatos (removendo os antigos e as propriedades extras não enviadas), utilize PUT /empresa/api/rest/supplier/v1/contact com o registro completo do Fornecedor.

Cenário 4 — Promotor em loja

Com o Fornecedor e seus contatos cadastrados, quando o promotor da Unilever chega à loja, o recepcionista registra sua entrada informando o (s) fornecedor (es) que ele representa:

POST /loja1/api/rest/promoter/arrival/44710001
{
  "user": "recepcao",
  "providers": [ { "code": "5001" } ]
}

A partir daí o RUB consegue medir tempo de permanência, tarefas executadas e associar tudo isso à indústria — o que só é possível porque o Fornecedor representa a indústria e não o CNPJ.

Boas práticas

• Um Fornecedor por indústria. Consolide filiais e distribuidores antes de integrar.
• Escolha um code estável e documente a regra de consolidação no ERP (ex.: tabela de mapeamento CNPJ → código RUB).
• Preencha category quando o fornecedor atua majoritariamente em uma Classe; isso melhora as análises cruzadas Fornecedor × Classe.
• Mantenha contacts atualizados — são eles que a loja usa para acionar a indústria em caso de ruptura prolongada.
• Use active: false para fornecedores descontinuados em vez de removê-los.

Referência na API

O contrato técnico completo dos endpoints de Fornecedores (parâmetros de rota, contatos, schemas JSON 1:1, formatos de importação massiva CSV e exemplos de requisição/resposta) encontra-se documentado no Swagger oficial:

• Swagger da API: https://api.docs.rub.gicbrasil.com (tag Fornecedores)
• Diretrizes da API REST: consulte a Referência da API REST para regras de tenancy, autenticação e fluxo de processamento de lotes.