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

1. O arquivo deve ser gerado depois do fechamento da loja para conter todo o movimento do dia.
2. Caso seja necessário retificar um arquivo enviado, basta gerar um novo arquivo e reenviá-lo novamente.
   • Apenas o último arquivo enviado será processado;
   • Arquivos anteriores da mesma data de movimento serão invalidados;
   • Novos arquivos somente serão aceitos caso o processamento não tenha sido iniciado;
3. O arquivo deve ser enviado até às 02:00 do dia seguinte para que possa ser processado na madrugada.
4. 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 um GTIN associado ao mesmo codigoProduto. Para cada GTIN comercializado (constante da NFCe), informe o somatório da qtdVendida deste GTIN separadamente.

---

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 e pode ser alterado a qualquer momento.

---

Endpoints

1. Enviar Movimentações da Loja

• Descrição: Envio de movimentações dos produtos (JSON ou CSV)
• 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

Campo	Tipo	Descrição
modo	String	Define o formato: JSON ou CSV

Corpo da Requisição (JSON)

{
  "cnpj": "99999999000101",
  "dtMovimento": "2024-01-01",
  "movimentos": [
    {
      "codigoProduto": "000001",
      "gtin": "7894900027013",
      "nomeProduto": "COCA COLA ORIGINAL 2L",
      "qtdVendida": 10.00,
      "precoCusto": 8.00,
      "precoVenda": 0.00,
      "precoPromocao": null,
      "qtdEstoque": 100.00,
      "acertoEstoque": 0.00,
      "reposicaoEstoque": 0.00,
      "classificador1": "Bebidas",
      "classificador2": "Refrigerante",
      "classificador3": "Cola"
    }
  ]
}

Upload de Arquivo CSV

• Estrutura do arquivo:

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

• O header deve estar presente e os campos separados por ponto e vírgula (;)

Resposta de Sucesso

• Código: 201 Created
• Exemplo:

{
  "idMovimento": "UUID"
}

---

2. Consultar Histórico de Movimentações

• Método: GET
• URL: /movimentos

Parâmetros de Query

Campo	Tipo	Obrigatório	Descrição
dtInicio	String	Não	Data inicial do intervalo
dtFim	String	Não	Data final do intervalo

Resposta de Sucesso

• Código: 200 OK
• Exemplo:

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

---

3. Consultar Processamento

• 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:

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

---

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

Campo	Descrição
cnpj	Número do CNPJ da loja (14 dígitos, sem formatação)
dtMovimento	Data da venda ou ajuste de estoque/preço (YYYY-MM-DD)
codigoProduto	Identificador único do produto
gtin	Código GTIN (EAN) lido pelo PDV (8 ou 13 dígitos)
nomeProduto	Nome do produto como exposto na gôndola (Máx: 40 caracteres)
qtdVendida	Quantidade total vendida do produto naquele GTIN
precoCusto	Preço de custo do produto
precoVenda	Preço de venda
precoPromocao	Preço promocional (se houver)
qtdEstoque	Quantidade em estoque no fechamento do dia
acertoEstoque	Ajuste de estoque via inventário
reposicaoEstoque	Quantidade reposta no estoque naquele dia
classificador1-3	Hierarquias de categorização do produto

---

Limites e Restrições

• Tamanho máximo do arquivo: 5MB