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 40 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 | Numérico com 2 casas decimais separados por '.'
"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):
Obs No arquivo deve contar o header na primeira linha e os campos devem ser separados por ponto e vírgula [ ; ]
cnpj;dtMovimento;codigoProduto;gtin;nomeProduto;qtdVendida;precoCusto;precoVenda;precoPromocao;qtdEstoque;reposicaoEstoque;acertoEstoque;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
Obs.:
- 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: 40 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 | Preço promocional somente se estiver em promoção. |
| 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.