Estrutura dos Arquivos de Integração

Este documento descreve os tipos de arquivos aceitos na integração via Blob Storage e a lista completa de colunas permitidas por tipo.

Regras gerais

• Formato esperado: JSON.
• Cada item do JSON deve ser um objeto com pares campo: valor.
• Campos fora do contrato do tipo podem ser desconsiderados.
• Campos ausentes podem ser preenchidos automaticamente com valor vazio durante o processamento.
• Tipos aceitos na entrada: string, int, bool e decimal.
• O integrador normaliza os tipos antes de inserir no banco.
• Para campos de data, prefira o padrão yyyy-MM-ddT00:00:00.
• A integração é idempotente: o mesmo registro pode ser enviado mais de uma vez e o WeRetail consegue tratar corretamente as duplicidades.
• A integração é baseada em regras de negócio do cliente e, em geral, aceita a reapresentação do mesmo dado sem criar duplicidade funcional.

Introdução

A integração da WeRetail foi desenhada para operar de forma simples, segura e repetível. Em termos práticos:

• o cliente pode enviar os mesmos registros mais de uma vez sem que isso gere inconsistência no processamento;
• o WeRetail identifica e trata duplicidades na origem dos dados;
• a troca de informação é feita em formato padronizado e com validação por tipo de arquivo;
• a operação é orientada ao fluxo real do negócio, e não apenas a um feed técnico isolado.

Esses princípios permitem que a integração funcione com alta resiliência, mesmo em cenários de reprocessamento, reconciliação ou sincronização de dados em intervalos curtos.

1) Lojas

Baixar JSON de Exemplo

• Prefixo: LOJAS-
• Tipo de dado: cadastro de lojas.

Campo	Obrigatório	Tipo	Descrição
portal	Sim	int, string	Pode ser enviado fixo como 1, exceto quando houver estrutura de portais para franqueados.
empresa	Sim	int, string	Identificador da loja/empresa na origem.
nome_emp	Sim	string	Nome da loja.
razao_emp	Sim	string	Razão social da loja.
cnpj_emp	Sim	string	CNPJ da loja (somente números).
endereco_emp	Não	string	Logradouro da loja.
num_emp	Não	string, int	Número do endereço da loja.
complement_emp	Não	string	Complemento do endereço.
bairro_emp	Não	string	Bairro da loja.
cep_emp	Não	string	CEP da loja.
cidade_emp	Não	string	Cidade da loja.
estado_emp	Não	string	Estado da loja.
email_emp	Não	string	E-mail comercial da loja.

2) Vendedores

Baixar JSON de Exemplo

• Prefixo: VENDEDORES-
• Tipo de dado: cadastro de vendedores.

Campo	Obrigatório	Tipo	Descrição
portal	Sim	int, string	Recomenda-se enviar 1 quando não houver multiportal.
cod_vendedor	Sim	string, int	Código do vendedor na origem.
nome_vendedor	Sim	string	Nome do vendedor.
tipo_vendedor	Sim	string	Tipo do vendedor: V (Vendedor) ou R (Representante).
end_vend_rua	Não	string	Rua do endereço do vendedor.
end_vend_numero	Não	string, int	Número do endereço do vendedor.
end_vend_complemento	Não	string	Complemento do endereço do vendedor.
end_vend_bairro	Não	string	Bairro do endereço do vendedor.
end_vend_cep	Não	string	CEP do endereço do vendedor.
end_vend_cidade	Não	string	Cidade do vendedor.
end_vend_uf	Não	string	UF do vendedor.
fone_vendedor	Não	string	Telefone do vendedor.
mail_vendedor	Não	string	E-mail do vendedor.
dt_upd	Não	string	Data da última atualização do cadastro.
cpf_vendedor	Não	string	CPF do vendedor.
ativo	Não	bool, string	Indica se o vendedor está ativo.
data_admissao	Não	string	Data de admissão do vendedor.
data_saida	Não	string	Data de saída ou desligamento.
timestamp	Não	string, datetime	Marca temporal de atualização.
matricula	Não	string, int	Matrícula funcional do vendedor.
id_tipo_venda	Não	int, string	Código do tipo de venda.
descricao_tipo_venda	Não	string	Descrição do tipo de venda.

3) Clientes

Baixar JSON de Exemplo

• Prefixo: CLIENTES-
• Tipo de dado: cadastro de clientes.

O cadastro de clientes é obrigatório somente quando a operação pretende usar o CRM da WeRetail. Em cenários em que o cliente não vai explorar o CRM, esse arquivo pode ser omitido ou enviado apenas com os dados necessários para o fluxo operacional.

Campo	Obrigatório	Tipo	Descrição
portal	Sim	int, string	Recomenda-se enviar 1 quando não houver multiportal.
cod_cliente	Sim	string, int	Código do cliente na origem. Pode ser um identificador único interno, CPF, CNPJ, documento ou qualquer chave exclusiva do cliente. O WeRetail gera uma sequência interna para o cadastro, então esse valor não precisa ser um número sequencial do sistema central.
nome_cliente	Sim	string	Nome do cliente.
data_nascimento	Não	string	Data de nascimento do cliente. Preferir yyyy-MM-ddT00:00:00.
razao_cliente	Sim	string	Nome ou razão social do cliente. Pode ser igual a nome_cliente.
doc_cliente	Não	string	Documento do cliente.
tipo_cliente	Não	string	Tipo cadastral do cliente.
cidade_cliente	Não	string	Cidade do cliente.
uf_cliente	Não	string	UF do cliente.
pais	Não	string	País do cliente.
cel_cliente	Não	string	Celular do cliente. É obrigatório caso o CRM WeRetail seja utilizado.
email_cliente	Não	string	E-mail do cliente.
ativo	Não	bool, string	Indica se o cliente está ativo.
dt_update	Não	string	Data da última atualização.
cliente_anonimo	Não	bool	Indica cliente anônimo.

4) Produtos

Baixar JSON de Exemplo

• Prefixo: PRODUTOS-
• Tipo de dado: cadastro de produtos.

Esta interface recebe os produtos no nível de Produto + cor + tamanho, ou seja, o cadastro é de SKU. O WeRetail trata essa estrutura como o nível de item operacional para vendas, trocas e estoque.

Os campos obrigatórios são: portal, cod_produto, nome, cod_barra e referencia.

Caso você não tenha um campo específico cod_produto, pode enviar neste campo o cod_barras. O WeRetail irá criar um código incremental interno para controle e individualizar este cadastro.

O campo referencia agrupa os códigos de barras de um mesmo produto. Por exemplo, a Camisa Social, referência 0001, possui as cores Branco, Verde e Preto, com tamanhos P, M, G e GG. Use a mesma referencia para agrupar as cores e os tamanhos.

Os campos id_cor, desc_cor, id_tamanho e desc_tamanho não são obrigatórios, mas são extremamente desejáveis para relatórios.

Campo	Obrigatório	Tipo	Descrição
portal	Sim	int, string	Recomenda-se enviar 1 quando não houver multiportal.
cod_produto	Sim	string, int	Código do produto na origem. Caso não exista um campo específico, pode receber o cod_barras. O WeRetail gera um código incremental interno.
nome	Sim	string	Nome do produto.
cod_barra	Sim	string	Código de barras do item.
desc_cor	Não	string	Cor do produto. Campo desejável para relatórios.
desc_tamanho	Não	string	Tamanho do produto. Campo desejável para relatórios.
desc_setor	Não	string	Setor ou categoria principal do produto.
desc_linha	Não	string	Linha do produto.
desc_marca	Não	string	Marca do produto.
desc_colecao	Não	string	Coleção do produto.
desc_espessura	Não	string	Espessura do produto, quando aplicável.
desc_classificacao	Não	string	Classificação comercial ou de catálogo.
referencia	Sim	string	Referência usada para agrupar os códigos de barras de um mesmo produto, incluindo suas cores e tamanhos.
cod_auxiliar	Não	string, int	Código auxiliar de integração.
unidade	Não	string	Unidade de medida do item.
dt_update	Não	string	Data da última atualização do produto.
desativado	Não	bool, string	Indica se o produto foi desativado.
id_espessura	Não	int, string	Código da espessura.
id_classificacao	Não	int, string	Código da classificação.
id_cor	Não	int, string	Código da cor. Campo desejável para relatórios.
id_tamanho	Não	int, string	Código do tamanho. Campo desejável para relatórios.
id_setor	Não	int, string	Código do setor.
id_linha	Não	int, string	Código da linha.
id_marca	Não	int, string	Código da marca.
id_colecao	Não	int, string	Código da coleção.
id_produtos_opticos_tipo	Não	int, string	Código do tipo óptico do produto.
id_sped_tipo_item	Não	int, string	Código do tipo de item no SPED.

5) Estoque

Baixar JSON de Exemplo

• Prefixo: ESTOQUE_PRODUTOS
• Tipo de dado: posição de estoque por item.

Estoque é a posição atual, não as movimentações. Ele é enviado no nível de SKU, seguindo o mesmo código de produto informado no cadastro de produtos.

Os campos obrigatórios são: portal, cnpj_emp, cod_produto e quantidade.

O campo cod_produto segue a mesma regra do cadastro de produtos: pode ser qualquer código único do cliente, desde que o mesmo código seja reaproveitado nas vendas, trocas e cadastro de produtos.

Campo	Obrigatório	Tipo	Descrição
portal	Sim	int, string	Recomenda-se enviar 1 quando não houver multiportal.
cnpj_emp	Sim	string	CNPJ da loja (somente números).
cod_produto	Sim	string, int	Código do produto na origem. Deve coincidir com o código informado no cadastro de produtos.
quantidade	Sim	int, decimal, string	Quantidade atual em estoque.
cod_barra	Não	string	Código de barras do item.
preco_custo	Não	decimal, int	Preço de custo do item.
preco_venda	Não	decimal, int	Preço de venda do item.
custo_medio	Não	decimal, int	Custo médio do produto.
localizacao	Não	string	Localização física do item no armazém.

6) Movimentações

Baixar JSON de Exemplo

• Prefixo: MOVIMENTACAO

• Tipo de dado: movimentações de venda, faturamento e trocas.

O WeRetail trata as vendas por meio do CFOP da operação. A partir disso, a mesma base de movimento pode representar venda, troca, transferência, devolução ou outro tipo de movimentação operacional.

Portanto, nesta interface deve ser enviado todo o movimento de acordo com a CFOP da operação, sempre no nível de SKU. Isso significa que cada item movimentado precisa refletir o produto, a quantidade e o contexto fiscal da operação.

Nesta interface estarão todas as movimentações pertinentes ao negócio, como vendas, trocas, devoluções, transferências, consignados e qualquer outra operação que se queira acompanhar no WeRetail.

Campo	Obrigatório	Tipo	Descrição
portal	Sim	int, string	Código do portal ou 1 fixo.
codigo_cliente	Sim	string, int	Código do cliente conforme enviado no cadastro de clientes.
chave_nf	Sim	string	Chave da nota fiscal eletrônica.
cnpj_emp	Sim	string	CNPJ da filial/loja que efetuou a venda.
cod_vendedor	Sim	string, int	Código do vendedor conforme enviado no cadastro de vendedores.
cod_produto	Sim	string, int	Código do produto conforme informado no cadastro de produtos.
transacao	Sim	string, int	Identificador único da transação.
documento	Sim	string, int	Número do ticket ou documento da movimentação.
ordem	Sim	int	Ordem do item dentro da venda. Pode ser sequencial.
data_documento	Sim	string	Data da transação. Preferir yyyy-MM-ddT00:00:00.
quantidade	Sim	int, decimal, string	Quantidade do item.
valor_total	Sim	decimal, int, string	Valor total do lançamento.
data_lancamento	Não	string	Data de lançamento da operação. Pode ser igual a data_documento.
desc_cfop	Não	string	Descrição do CFOP.
id_cfop	Não	int, string	Código do CFOP.
valor_liquido	Não	decimal, int	Valor líquido do item.
valor_icms	Não	decimal, int	Valor do ICMS.
aliquota_icms	Não	decimal	Alíquota do ICMS.
base_icms	Não	decimal	Base de cálculo do ICMS.
valor_pis	Não	decimal, int	Valor do PIS.
aliquota_pis	Não	decimal	Alíquota do PIS.
base_pis	Não	decimal	Base de cálculo do PIS.
valor_cofins	Não	decimal, int	Valor do COFINS.
aliquota_cofins	Não	decimal	Alíquota do COFINS.
base_cofins	Não	decimal	Base de cálculo do COFINS.
valor_ipi	Não	decimal, int	Valor do IPI.
aliquota_ipi	Não	decimal	Alíquota do IPI.
base_ipi	Não	decimal	Base de cálculo do IPI.
total_dinheiro	Não	decimal, int	Total pago em dinheiro.
total_cheque	Não	decimal, int	Total pago em cheque.
total_cartao	Não	decimal, int	Total pago em cartão.
total_crediario	Não	decimal, int	Total pago em crediário.
total_convenio	Não	decimal, int	Total pago por convênio.
frete	Não	decimal, int	Valor do frete.
operacao	Não	string	Tipo de operação da venda.
tipo_transacao	Não	string	Tipo da transação.
cancelado	Não	bool, string	Indica se a operação foi cancelada.
excluido	Não	bool, string	Indica se o registro foi excluído.
identificador	Não	string, int	Identificador único do item.
obs	Não	string	Observações da operação.
preco_unitario	Não	decimal, int	Preço unitário do item.
hora_lancamento	Não	string	Hora do lançamento do documento.
natureza_operacao	Não	string	Natureza da operação.
tabela_preco	Não	string	Tabela de preço aplicada.
nome_tabela_preco	Não	string	Nome da tabela de preço.
cod_sefaz_situacao	Não	string, int	Situação fiscal na SEFAZ.
desc_sefaz_situacao	Não	string	Descrição da situação fiscal.
protocolo_aut_nfe	Não	string	Protocolo de autorização da NFE.
dt_update	Não	string	Data da última atualização.
total_cheque_prazo	Não	decimal, int	Total de cheque a prazo.
cod_natureza_operacao	Não	string, int	Código da natureza da operação.
preco_tabela_epoca	Não	decimal, int	Preço da tabela em época específica.
desconto_total_item	Não	decimal, int	Desconto total do item.
transacao_pedido_venda	Não	string, int	Identificador da transação do pedido.
codigo_modelo_nf	Não	string, int	Código do modelo da NF.
acrescimo	Não	decimal, int	Valor de acréscimo.
total_pix	Não	decimal, int	Total pago em PIX.

7) Pedidos

Baixar JSON de Exemplo

• Prefixo: PEDIDO_VENDAS
• Tipo de dado: pedidos de venda externos.

Campo	Obrigatório	Tipo	Descrição
pedido	Sim	string, int	Identificador do pedido na origem.
emissao	Sim	string	Data de emissão do pedido. Preferir yyyy-MM-ddT00:00:00.
cod_vendedor	Sim	string, int	Código do vendedor na origem.
cnpj_emp	Sim	string	CNPJ da loja (somente números).
cod_produto	Sim	string, int	Código do produto na origem.
cod_cliente	Sim	string, int	Código ou documento do cliente na origem.
qtde_original	Sim	int, decimal, string	Quantidade original do pedido.
preco	Sim	decimal, int, string	Preço unitário do item.
lastupdateon	Não	string	Data da última atualização registrada.
lastsyncon	Não	string	Data da última sincronização.
qtde_faturada	Não	int, decimal, string	Quantidade faturada do pedido.
qtde_cancelada	Não	int, decimal, string	Quantidade cancelada do pedido.
qtde_entregar	Não	int, decimal, string	Quantidade pendente de entrega.
valor_original	Não	decimal, int, string	Valor original do pedido.
valor_faturado	Não	decimal, int, string	Valor faturado do pedido.
valor_cancelado	Não	decimal, int, string	Valor cancelado do pedido.
valor_entregar	Não	decimal, int, string	Valor pendente de entrega.
valor_embalado	Não	decimal, int, string	Valor embalado do pedido.
desconto_item	Não	decimal, int, string	Desconto aplicado no item.
tipo	Não	string	Tipo do pedido ou operação.