Skip to main content

Descrição

Este webhook é acionado automaticamente sempre que houver alteração no estoque de um ou mais produtos em sua conta do Olist ERP.

Quando é Acionado

O webhook de atualização de estoque é enviado nas seguintes situações:
  • Lançamento manual de estoque
  • Baixa de estoque por venda
  • Devolução de produtos
  • Ajuste de inventário
  • Entrada de mercadoria
  • Transferência entre depósitos

Estrutura da Notificação

A notificação é enviada via POST para a URL configurada, com o seguinte formato:
{
  "evento": "atualizacao_estoque",
  "data_hora": "20/05/2024 15:30:45",
  "produtos": [
    {
      "id": 123456,
      "sku": "PROD-001",
      "nome": "Produto Exemplo",
      "saldo": 50,
      "saldo_anterior": 60,
      "tipo_movimento": "saida",
      "observacao": "Venda pedido #789",
      "deposito_id": 1,
      "deposito_nome": "Depósito Principal"
    }
  ]
}

Campos da Notificação

CampoTipoDescrição
eventostringSempre “atualizacao_estoque”
data_horastringData e hora da alteração (dd/mm/yyyy hh:mm:ss)
produtos[]arrayLista de produtos com estoque alterado
produtos[].idintID do produto no Olist ERP
produtos[].skustringCódigo SKU do produto
produtos[].nomestringNome do produto
produtos[].saldodecimalSaldo atual após a alteração
produtos[].saldo_anteriordecimalSaldo antes da alteração
produtos[].tipo_movimentostringTipo: “entrada”, “saida” ou “ajuste”
produtos[].observacaostringObservação do movimento
produtos[].deposito_idintID do depósito afetado
produtos[].deposito_nomestringNome do depósito

Exemplo de Implementação

PHP

<?php
// Recebe o webhook
$json = file_get_contents('php://input');
$data = json_decode($json, true);

if ($data['evento'] === 'atualizacao_estoque') {
    foreach ($data['produtos'] as $produto) {
        // Atualiza seu sistema local
        atualizarEstoqueLocal(
            $produto['sku'],
            $produto['saldo'],
            $produto['tipo_movimento']
        );

        // Log da alteração
        registrarLog(
            "Estoque atualizado: {$produto['nome']} - Saldo: {$produto['saldo']}"
        );
    }

    // Responde com sucesso
    http_response_code(200);
    echo json_encode(['status' => 'processado']);
}
?>

Python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/estoque', methods=['POST'])
def webhook_estoque():
    data = request.get_json()

    if data.get('evento') == 'atualizacao_estoque':
        for produto in data.get('produtos', []):
            # Atualiza estoque local
            atualizar_estoque_local(
                sku=produto['sku'],
                saldo=produto['saldo'],
                tipo=produto['tipo_movimento']
            )

            print(f"Estoque atualizado: {produto['nome']} - Saldo: {produto['saldo']}")

        return jsonify({'status': 'processado'}), 200

    return jsonify({'status': 'evento_desconhecido'}), 400

Node.js

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/estoque', (req, res) => {
    const data = req.body;

    if (data.evento === 'atualizacao_estoque') {
        data.produtos.forEach(produto => {
            // Atualiza estoque local
            atualizarEstoqueLocal({
                sku: produto.sku,
                saldo: produto.saldo,
                tipo: produto.tipo_movimento
            });

            console.log(`Estoque atualizado: ${produto.nome} - Saldo: ${produto.saldo}`);
        });

        res.status(200).json({ status: 'processado' });
    } else {
        res.status(400).json({ status: 'evento_desconhecido' });
    }
});

app.listen(3000);

Configuração

Para ativar este webhook:
  1. Acesse o painel do Olist ERP
  2. Vá em Configurações > Integrações > Webhooks
  3. Clique em Novo Webhook
  4. Selecione o evento Atualização de Estoque
  5. Informe a URL do seu endpoint
  6. Salve as configurações

Boas Práticas

  • Responda rapidamente: Seu endpoint deve responder em menos de 5 segundos
  • Processe assincronamente: Use filas para processar as notificações
  • Implemente idempotência: Evite duplicação de processamento
  • Valide os dados: Sempre valide o formato e conteúdo recebido
  • Log de erros: Registre falhas para análise posterior
  • Use HTTPS: Garanta a segurança da comunicação

Tratamento de Erros

Se seu endpoint retornar um erro ou timeout, o sistema tentará reenviar a notificação:
  • 1ª tentativa: Imediata
  • 2ª tentativa: Após 1 minuto
  • 3ª tentativa: Após 5 minutos
Após 3 tentativas sem sucesso, a notificação é descartada e você receberá um alerta por e-mail.

Observações

  • Múltiplas alterações em um curto período podem ser agrupadas em uma única notificação
  • Alterações muito rápidas (< 1 segundo) podem ser consolidadas
  • O webhook não é enviado para alterações feitas via API (para evitar loops)
  • Utilize o campo tipo_movimento para identificar a natureza da alteração