Skip to main content

Integração via Azure Blob Storage

Quando usar​

Use este modelo quando sua empresa:

  • não possui API disponível para integração;
  • prefere envio em lote (batch) de dados;
  • precisa de um canal simples para publicação periódica dos arquivos.

Como funciona​

A WeRetail disponibiliza para sua equipe técnica:

  • uma chave de acesso ao Storage;
  • uma pasta dedicada para sua empresa;
  • o padrão de arquivos aceitos.

O fluxo operacional é:

  1. Seu sistema gera arquivos JSON por tipo de dado.
  2. Os arquivos são enviados para a pasta da sua empresa no Blob Storage.
  3. A WeRetail identifica os arquivos pendentes e processa automaticamente.
  4. Após processamento, os dados ficam disponíveis na plataforma.

Fluxo da integração via Blob Storage

Convenção de tipos de arquivo​

Os arquivos são identificados por prefixo de nome. Os principais prefixos aceitos atualmente são:

  • LOJAS-: cadastro e dados estruturais de lojas.
  • VENDEDORES-: cadastro e dados de vendedores.
  • CLIENTES-: cadastro e dados de clientes.
  • PRODUTOS-: cadastro de produtos e atributos comerciais.
  • ESTOQUE_PRODUTOS-: posição de estoque por item/produto.
  • MOVIMENTACAO-: vendas, trocas, devoluções, transferências, consignados e demais movimentações por loja.
  • PEDIDO_VENDAS-: pedidos de venda externos.

Formato de conteúdo​

  • Formato: JSON.
  • Estrutura: lista de objetos (cada objeto representa um registro).
  • Campos: devem seguir o contrato técnico de cada tipo.

Consulte o contrato completo em Estrutura dos Arquivos de Integração.

Veja também os exemplos de código para envio ao Blob Storage em C#, Python, JavaScript/TypeScript, Java e cURL.

Boas práticas​

  • Envie somente colunas do contrato do tipo correspondente.
  • Mantenha nomes de campos exatamente como documentado.
  • Não misture tipos diferentes no mesmo arquivo. Arquivos com tipos misturados serão descartados.
  • Evite arquivos com muitas linhas. Se o seu resultset retornar muitos registros, divida-o em arquivos menores, com no máximo 1200 linhas/registros cada. Você pode enviar vários arquivos sequenciais.
  • Prefira arquivos menores, pois eles são processados mais rapidamente. Em caso de erro, a WeRetail gera um log e comunica a equipe interna. Você também pode usar um webhook da WeRetail para receber avisos sobre erros.
  • Esta estrutura foi projetada para comunicação rápida e, por isso, abre mão de algumas validações redundantes. Trata-se de um processamento assíncrono; erros devem ser tratados como cenários de exceção.
  • Garanta consistência de CNPJ, códigos e datas na origem.

Como organizar a sua integração​

A WeRetail possui um sincronizador desenvolvido internamente, que pode ser adaptado a vários cenários.

A principal estratégia é separar os dados pela data de cadastro ou de geração. Clientes, lojas, produtos e movimentações podem ser agrupados por data e enviados em arquivos correspondentes a cada dia. Caso ocorra algum problema, basta reprocessar o dia específico, sem precisar individualizar cada registro.

O Blob Storage possui boa tolerância a grandes volumes de leitura e escrita. Assim, priorizamos a performance da sincronização de dados e tratamos erros como cenários de exceção. Depois que a integração é homologada, problemas recorrentes relacionados à estrutura dos dados são pouco frequentes.