Referência da API REST

A API REST do RUB permite a integração bidirecional entre os sistemas corporativos (ERP, retaguarda, PDVs, coletores e sistemas satélites) e a plataforma RUB. Ela fornece interfaces padronizadas para carga cadastral, acompanhamento operacional em tempo real, orquestração de tarefas de loja e monitoramento.

Documentação Oficial e Contratos no Swagger: A especificação técnica completa e atualizada de todos os endpoints, parâmetros, schemas de dados, códigos de retorno e ferramentas de teste interativo está disponível no Swagger oficial:
👉 https://api.docs.rub.gicbrasil.com

Regra Fundamental de Integração: O RUB opera com duas modalidades estritas de comunicação HTTP:

• JSON (1:1): Exclusivo para operações unitárias (consulta, inclusão ou atualização de um único registro por requisição).
• CSV Massivo (text/csv): Obrigatório sempre que a requisição envolver mais de um registro (cargas iniciais, sincronizações periódicas ou viradas de preço/estoque). Não utilize arrays JSON para envio em lote.

Estrutura de Tenancy

Todas as rotas da API REST iniciam com um parâmetro de contexto (Tenant), que define o escopo corporativo ou operacional da requisição:

https://{url_rub}/{tenantEmpresa}/api/rest/<recurso>
https://{url_rub}/{tenantLoja}/api/rest/<recurso>

Os contextos suportados são:

Autenticação e Segurança

A API utiliza o esquema padrão HTTP Basic Authentication sobre conexões criptografadas (HTTPS).

Todas as requisições devem incluir o cabeçalho Authorization:

Authorization: Basic <credenciais_em_base64>

Onde <credenciais_em_base64> é a codificação em Base64 do par usuario:senha da aplicação integrada.

Códigos de Erro de Autenticação

Padrões de Comunicação

O cabeçalho Content-Type determina o fluxo de processamento de cada endpoint:

1. Envio Unitário (JSON 1:1)

Utilizado para criar, atualizar ou consultar um registro pontual:

• Cabeçalho: Content-Type: application/json; charset=UTF-8
• Corpo: Objeto JSON individual (nunca um array [...]).
• Processamento: Síncrono.
• Resposta: O objeto criado/atualizado ou status de confirmação ApiStatus ({"status": "accepted", "message": "..."}).

2. Envio Massivo (CSV em Lote)

Utilizado para transmissão de grandes volumes de dados (milhares ou dezenas de milhares de linhas):

• Cabeçalho: Content-Type: text/csv; charset=UTF-8
• Formato: Arquivo de texto simples delimitado por ponto e vírgula (;).
• Cabeçalho obrigatório: A primeira linha deve conter os nomes das colunas esperadas pelo endpoint.
• Processamento: Assíncrono com validação prévia de integridade.
• Resposta: Objeto BulkResponse contendo o identificador do lote (id) para acompanhamento.

curl -X POST "https://{url_rub}/{tenantEmpresa}/api/rest/product-store/v1" \
     -H "Authorization: Basic dXN1YXJpbzBzZW5oYQ==" \
     -H "Content-Type: text/csv; charset=UTF-8" \
     --data-binary @produtos_loja.csv

Protocolo de Importação Massiva

A modalidade de importação massiva foi projetada para a transmissão eficiente de grandes volumes de dados. Diferente de APIs REST que utilizam arrays JSON, o RUB processa arquivos CSV assíncronos, garantindo menor consumo de memória e alta performance.

Fluxo de Processamento Assíncrono

graph TD
    ERP["Sistema Corporativo (ERP)"] -->|1 . POST com Content - Type: text/csv| RUB["Servidor RUB"]
    RUB -->|" 2. Valida sintaxe e integridade básica "| QUEUE["Fila Assíncrona de Processamento"]
    RUB -->|" 3. Responde HTTP 200 com BulkResponse (id / UUID) "| ERP
    QUEUE -->|" Processa linhas em background "| DB[(Banco de Dados RUB)]
    ERP -.->|" 4. GET /import/v1/{id} (polling periódico) "| RUB
    RUB -.->|" 5. Retorna ImportStatusResponse (status e progresso) "| ERP

Regras de Formatação do CSV

• Codificação: Obrigatório UTF-8 (sem BOM).
• Separador de Colunas: Ponto e vírgula (;). Não utilize vírgula ou tabulação.
• Delimitador de Texto: Aspas duplas ("), opcionais na maioria dos campos, mas recomendadas para campos com espaços. Caso o texto contenha aspas, escape-as duplicando ("").
• Linha de Cabeçalho: A primeira linha deve conter obrigatoriamente o nome dos campos, idênticos aos especificados no Swagger do endpoint.
• Linhas em Branco: Linhas vazias são ignoradas automaticamente.
• Separador Decimal: Ponto (.), e nunca vírgula (ex.: 100.5, 24.90).
• Datas e Horários: Formato yyyy-MM-dd HH:mm:ss (ex.: 2026-07-28 12:00:00).

Resposta de Carga (BulkResponse)

Ao postar um arquivo CSV, o RUB valida a sintaxe e a existência de campos obrigatórios. Se o arquivo for aceito, o servidor retorna status HTTP 200 com a estrutura BulkResponse:

{
  "id": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "total": 1500,
  "accepted": 1498,
  "errors": [
    {
      "line": 12,
      "message": "Produto 99999 inexistente na empresa"
    },
    {
      "line": 84,
      "message": "Quantidade inválida para embalagem"
    }
  ]
}

• total: Quantidade total de linhas de dados identificadas no arquivo (desconsiderando o cabeçalho).
• accepted: Quantidade de registros válidos aceitos e enfileirados para persistência.
• errors: Lista de registros rejeitados na pré-validação com a linha (line) e a mensagem de erro (message).
• id: Identificador único do lote (UUID), utilizado para consultar o progresso em GET /{tenantLoja}/api/rest/import/v1/{id} (retorna null apenas se nenhuma linha foi aceita).

Consulta de Status do Lote (ImportStatusResponse)

O acompanhamento do processamento do lote é feito via polling no endpoint de importação:

GET https://{url_rub}/{tenantLoja}/api/rest/import/v1/{id}

Estados retornados no campo status:

Versionamento e Tratamento de Erros

Versionamento de Endpoints

• Endpoints com versão explícita na rota (ex.: /category/v1, /product/v2) devem ser chamados com sua respectiva versão.
• Endpoints sem versão explícita na rota (ex.: /tasks, /store, /address/v1) são considerados implicitamente como versão /v1. Ambas as formas /api/rest/tasks e /api/rest/tasks/v1 são equivalentes.

Padrão de Erro (ApiError)

Todas as respostas de erro da API (códigos 4xx e 5xx) utilizam o schema ApiError:

{
  "code": 400,
  "message": "Parâmetro 'store' é obrigatório no contexto empresa"
}

Formatação de Datas e Valores

• Datas e Horários: Formato ISO yyyy-MM-dd HH:mm:ss (ex.: 2026-07-28 14:30:00) ou padrão ISO-8601 com fuso horário (2026-07-28T14:30:00-03:00).
• Valores Decimais: Quantidades e preços são expressos em ponto flutuante com ponto (.) decimal (ex.: 100.5, 24.99). Em campos CSV, nunca utilize vírgula como separador decimal.
• Exclusões (DELETE): Requisições DELETE executadas com sucesso retornam HTTP 200 sem corpo.

Catálogo de Serviços e Swagger

Para consultar o contrato detalhado de cada serviço (rotas, métodos HTTP, parâmetros de URL, schemas de entrada e saída, códigos de retorno e exemplos interativos), acesse a documentação Swagger organizada pelas seguintes áreas:

• Cadastros (Contexto Empresa):

  • Lojas: Cadastro e ativação/inativação das unidades de negócio (filiais).
  • Produtos (Empresa): Catálogo corporativo de produtos (product/v2, com embalagens e códigos de barras aninhados) e consultas de produto por contexto.
  • Produtos por Loja: Vínculo de produto com filial (product-store) — sortimento ativo, custo, preços por embalagem e códigos de barras internos.
  • Classes de Produto: Hierarquia mercadológica de categorias e vínculo com setores.
  • Cadeias: Agrupamento lógico de famílias de produtos que compartilham etiqueta de gôndola.
  • Fornecedores: Cadastro unificado de indústrias, contatos comerciais/operacionais e propriedades.
  • Setores e Filas: Setores da empresa, vínculos com lojas e filas operacionais de tarefas.

• Operação de Loja (Contexto Loja / Flexível):

  • Estoque: Fotografia e ajuste de saldos de estoque por produto, filial e local/endereço.
  • Movimentações: Registro de vendas (PDV), entradas por nota, perdas, devoluções e transferências.
  • Endereçamento: Endereços físicos da loja (picking, depósito, aéreo) e conferência de produtos alocados.
  • Códigos de Barras: Resolução instantânea de código lido para produto, embalagem e endereço.
  • Etiquetas: Solicitação de impressão de etiquetas de preço e gôndola.
  • Promotores: Controle de acesso e presença de promotores na loja por cartão e indústria.
  • Tarefas: Ciclo de vida completo das ordens de serviço (reposição, contagem, conferência).
  • Auditorias: Auditorias de presença/etiqueta e recepção de telemetria de robôs de chão de loja.

• Integração Massiva (CSV):

  • Endpoints que suportam carga em lote via Content-Type: text/csv e consulta do processamento assíncrono em GET /import/v1/{id}.

• Segurança e Monitoramento:

  • Usuários: Administração de colaboradores, senhas, perfis de permissão e ativação/inativação.
  • Acessos: Métricas e auditoria volumétrica de conexões ao RUB por período, filial e tipo de cliente.

Acesse a especificação completa e execute chamadas de teste diretamente no Swagger:
👉 https://api.docs.rub.gicbrasil.com