Integração via API

Visão Geral

A API EstoqueAi, tem como objetivo receber dados de movimentação de venda diária do lojista, permitindo integração eficiente entre sistemas de origem e destino. Os dados podem ser enviados em formato JSON ou Arquivo CSV por meio de requisições REST. Toda movimentação enviada será processada de maneira assíncrona.

Informações Importantes

O arquivo deve ser gerado depois do fechamento da loja para conter todo o movimento do dia.
Caso seja necessário retificar um arquivo enviado, basta gerar um novo arquivo e reenviá-lo novamente.
- 2.1. Apenas o último arquivo enviado será processado;
- 2.2. Arquivos anteriores da mesma data de movimento serão invalidados;
- 2.3. Novos arquivos somente serão aceitos, caso o processamento não tenha sido iniciado;
O arquivo deve ser enviado até às 02:00 do dia seguinte para que possa ser processado na madrugada.
No arquivo deve constar pelo menos toda a movimentação dos produtos vendidos no dia ou com alteração de preço e/ou estoque ou todo o mix da loja;

Atenção

Alguns produtos possuem mais de 1 gtin associados ao mesmo codigoProduto. Informe no campo gtin o gtin principal do produto e, se houver mais gtins do mesmo codProduto, informe no campo todosGtins.

Base URL

Produção: https://api-retaguarda.bagarote.com.br/api/auth-key/{authToken}/

Homologação: https://api-retaguarda-dev.bagarote.com.br/api/auth-key/{authToken}/

Autenticação

A API utiliza autenticação baseada em authToken na URL da requisição. Esse token é fornecido a partir da contratação do serviço, ele pode ser alterado a qualquer momento, garantindo a manutenção do mesmo por cada lojista.

Endpoints

1. Enviar Movimentações da Loja

Objeto: MovimentoRequest
Descrição: Endpoint para envio de movimentações dos produtos enviados em formato JSON.
Método: POST
URL: /movimentos

Headers

Campo	Tipo	Obrigatório	Descrição
Content-Type	String	Sim	`application/json` ou `multipart/form-data`

Parâmetros de Query (obrigatório)

Campo	Tipo	Descrição
modo	String	Define o formato de envio: `JSON` ou `CSV`.

Corpo da Requisição (JSON)

Se modo=JSON, o corpo da requisição:

{
  "cnpj": "99999999000101",	    -- Obrigatório | Sem formatação | Mín e Máx 14 caracteres
  "dtMovimento": "2024-01-01",	    -- Obrigatório | Formatação: 'YYYY-MM-DD'	
  "movimentos": [ 	            -- Obrigatório | Lista de movimentos deve haver ao menos 1 movimento	
    {
      "codigoProduto": "000001",            -- Obrigatório
      "gtin": "7894900027013",	 		    -- Obrigatório | Sem formatação | Mín 8 e Máx 13 caracteres
      "nomeProduto": "COCA COLA ORIGINAL 2L",	            -- Obrigatório | Sugestão: utilizar nome gôndola | Máx 60 caracteres
      "qtdVendida": 10.00,	 	    -- Obrigatório | Numérico com 2 casas decimais separados por '.'
      "precoCusto": 8.00,		    -- Opcional | Numérico com 2 casas decimais separados por '.'
      "precoVenda": 0.00,		    -- Opcional | Numérico com 2 casas decimais separados por '.'
      "precoPromocao": null,    -- Opcional | null, mantido por compatibilidade
      "qtdEstoque": 100.00,	 	    -- Obrigatório | Numérico com 2 casas decimais separados por '.'
      "acertoEstoque": 0.00,	 	    -- Obrigatório | Numérico com 2 casas decimais separados por '.'
      "reposicaoEstoque": 0.00,	 	    -- Obrigatório | Numérico com 2 casas decimais separados por '.'
      "classificador1": "Bebidas",		    -- Opcional | Máx 40 caracteres
      "classificador2": "Refrigerante",		    -- Opcional | Máx 40 caracteres
      "classificador3": "Cola",		    -- Opcional | Máx 40 caracteres
      "todosGtins": "7894900027013/78933873/7894900011593" -- Opcional | Campo char sem limite de caracteres
    }
  ]
}

Upload de Arquivo

Se modo=CSV, envie o arquivo no formato CSV:

Estrutura CSV (Exemplo):

Observação 1: No arquivo deve contar o header na primeira linha e os campos devem ser separados por ponto e vírgula [ ; ].

Observação 2: Os campos do tipo string NÃO PODEM conter o caractere ;, pois ele é utilizado como delimitador no arquivo CSV para separar os dados. O uso desse caractere pode comprometer a estrutura do arquivo e a correta interpretação das informações.

cnpj;dtMovimento;codigoProduto;gtin;nomeProduto;qtdVendida;precoCusto;precoVenda;precoPromocao;qtdEstoque;acertoEstoque;reposicaoEstoque;classificador1;classificador2;classificador3;todosGtins
99999999000101;2024-01-01;000001;7894900027013;COCA COLA ORIGINAL 2L;10.00;8.00;0.00;;100.00;0.00;0.00;Bebida;Refrigerante;Cola;7894900027013/78933873/7894900011593

Observação 3:

A formatação de todos os campos deve seguir o mesmo padrão descrito no JSON

Resposta de Sucesso

Código: 201 CREATE Exemplo (JSON):

HTTP/1.1 201 Created
Content-Type: application/json
Location: ${URL_BASE}/movimentacoes/{idMovimentacao}
ResponseBody:
{
  "idMovimento": "UUID"
}

2. Consultar Histórico de Movimentações

Objeto: MovimentoResponse [array]
Descrição: Retorna o histórico de movimentações da Loja Filtrados por data. Caso o campo dtProcessamento esteja nulo, indica que o movimento está em fila de processamento, caso esteja preenchido indicará a data do processamento o flag falhou (true/false) indica se houve sucesso ou não no processamento, no caso de falha = true o detalhe de erro estará disponível no campo observação.
Método: GET
URL: /movimentos

Parâmetros de Query

Campo	Tipo	Obrigatório	Descrição
dtInicio	String	Não	Data inicial do intervalo. Pattern: 'yyyy-mm-dd'
dtFim	String	Não	Data final do intervalo. Pattern: 'yyyy-mm-dd'

Resposta de Sucesso

Código: 200 OK
Exemplo (JSON):

[
  {
  "idMovimento": "UUID",
  "dtMovimento": "2024-01-01",
  "dtRecebimento": "2024-01-01 23:00:00",
  "dtProcessamento": "2024-01-01 23:01:00",
  "falhou": false, 
  "observacao": "Processado com Sucesso!"
  }
]

3. Consultar Processamento

Objeto: MovimentoResponse
Descrição: Retorna o status de processamento de um determinado movimento
Método: GET
URL: /movimentos/{idMovimento}

Parâmetros de URL

Campo	Tipo	Obrigatório	Descrição
idMovimento	UUID	SIM	ID do movimento enviado.

Resposta de Sucesso

Código: 200 OK
Exemplo (JSON):

{
  "idMovimento": "UUID",
  "dtMovimento": "2024-01-01",
  "dtRecebimento": "2024-01-01 23:00:00",
  "dtProcessamento": "2024-01-01 23:01:00",
  "falhou": false, 
  "observacao": "Processado com Sucesso!"
}

4. Consultar Inventário

Objeto: InventarioResponse
Descrição: Retorna o inventário de todos os produtos realizados no dia
Método: GET
URL: /inventario

Parâmetros de Query

Campo	Tipo	Obrigatório	Descrição
dtInventario	String	Não	Data Inventário (caso não informe retornamos a o inventário da data corrente). Pattern: 'yyyy-mm-dd'

Resposta de Sucesso

Código: 200 OK
Exemplo (JSON):

{
  "idInventario": "UUID",
  "dtInventario": "2024-01-01",
  "cnpj": "CNPJ_LOJISTA",
  "produtos":[
        {
            "codigoProduto": "1",
            "inventarioEstoque": 10,
            "inventarioLoja": 0
        }
  ]
}

5. Confirmar Recebimento do Inventário

Descrição: Confirmação do recebimento dos dados do inventário solicitado
Método: PUT
URL: /inventario/{idInventario}

Parâmetros de URL

Campo	Tipo	Obrigatório	Descrição
idInventario	UUID	SIM	ID do inventário.

Resposta de Sucesso

Código: 200 OK

Códigos de Resposta

Código	Descrição
200	Requisição bem-sucedida.
201	Movimento Recebido com Sucesso.
400	Erro na validação dos dados.
401	Falha na autenticação.
404	Recurso não encontrado.
500	Erro interno no servidor.

Dicionário

MovimentoRequest

Campo	Descrição
cnpj	Número do CNPJ da loja; (14 dígitos completar zeros a esquerda).
dtMovimento	Data da venda do produto ou do acerto de estoque e/ou preço (YYYY-MM-DD).
codigoProduto	Identificador único do produto no sistema comercial da loja.
gtin	O GTIN (EAN) do produto lido pelo PDV; (8 ou 13 dígitos).
nomeProduto	Descrição do produto (Máx: 60 caracteres - Nome descrito nas gôndolas).
qtdVendida	Somatório do quantitativo do produto vendido do mesmo gtin.
precoCusto	Preço de custo de aquisição do produto, último preço de compra.
precoVenda	Preço de venda na loja física atualizado.
precoPromocao	Campo descontinuado - mantido para compatibilidade
qtdEstoque	Qtd. do produto em estoque no fechamento da loja, se negativo precedido de - (menos).
acertoEstoque	Esse campo deve conter além dos acertos de estoque, outros lançamentos, tais como: Avarias, roubo, consumo interno, devoluções, transferências de mercadoria, etc. Esse campo deve ser positivo ou negativo para representar um acerto de entrada ou saída respectivamente.
reposicaoEstoque	Qtd. do produto que foi dado entrada na data do movimento.
classificador1, 2 e 3	Hierarquia para organização do produto.
todosGtins	Todos os gtins comerciais existentes (8 ou 13 digitos) ligados à variavel codigoProduto separados por `/`. Exemplo: `gtin1/gtin2/.../getinN`

MovimentoResponse

Campo	Descrição
idMovimento	Identificador do movimento recebido.
dtMovimento	Data do Movimento (YYYY-MM-DD).
dtRecebimento	Data do Recebimento do arquivo (YYYY-MM-DD HH:mm:ss).
dtProcessamento	Data do Processamento do arquivo (YYYY-MM-DD HH:mm:ss).
falhou	TRUE/FALSE indica se há falha no arquivo
observacao	Descreve o erro de validação em caso de falha.

InventarioResponse

Campo	Descrição
idInventario	Identificador do Inventário Solicitado.
dtInventario	Data do Inventário (YYYY-MM-DD).
cnpj	CNPJ do cliente do inventário.
produtos	Array de Produtos Inventariados (ProdutoInventariadoResponse).

ProdutoInventariadoResponse

Campo	Descrição
codigoProduto	Identificador do Produto na base do cliente.
inventarioEstoque	Quantidade de produtos no estoque da loja.
inventarioLoja	Quantidade de produtos no interior da loja. Ex.: vitrine, prateleira, expositor, etc.

Limites e Restrições

Tamanho máximo do arquivo: 5MB.

Visão Geral​

Informações Importantes

Atenção​

Base URL​

Autenticação​

Endpoints​

1. Enviar Movimentações da Loja​

Headers​

Parâmetros de Query (obrigatório)​

Corpo da Requisição (JSON)​

Upload de Arquivo​

Observação 3:​

Resposta de Sucesso​

2. Consultar Histórico de Movimentações​

Parâmetros de Query​

Resposta de Sucesso​

3. Consultar Processamento​

Parâmetros de URL​

Resposta de Sucesso​

4. Consultar Inventário​

Parâmetros de Query​

Resposta de Sucesso​

5. Confirmar Recebimento do Inventário​

Parâmetros de URL​

Resposta de Sucesso​

Códigos de Resposta​

Dicionário​

MovimentoRequest​

MovimentoResponse​

InventarioResponse​

ProdutoInventariadoResponse​

Limites e Restrições​

Visão Geral

Atenção

Base URL

Autenticação

Endpoints

1. Enviar Movimentações da Loja

Headers

Parâmetros de Query (obrigatório)

Corpo da Requisição (JSON)

Upload de Arquivo

Observação 3:

Resposta de Sucesso

2. Consultar Histórico de Movimentações

Parâmetros de Query

Resposta de Sucesso

3. Consultar Processamento

Parâmetros de URL

Resposta de Sucesso

4. Consultar Inventário

Parâmetros de Query

Resposta de Sucesso

5. Confirmar Recebimento do Inventário

Parâmetros de URL

Resposta de Sucesso

Códigos de Resposta

Dicionário

MovimentoRequest

MovimentoResponse

InventarioResponse

ProdutoInventariadoResponse

Limites e Restrições