> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.erp.olist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook - Atualização de Estoque

> Receba notificações em tempo real quando o estoque de produtos for alterado.

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

```json theme={null}
{
  "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

| Campo                       | Tipo    | Descrição                                      |
| --------------------------- | ------- | ---------------------------------------------- |
| evento                      | string  | Sempre "atualizacao\_estoque"                  |
| data\_hora                  | string  | Data e hora da alteração (dd/mm/yyyy hh:mm:ss) |
| produtos\[]                 | array   | Lista de produtos com estoque alterado         |
| produtos\[].id              | int     | ID do produto no Olist ERP                     |
| produtos\[].sku             | string  | Código SKU do produto                          |
| produtos\[].nome            | string  | Nome do produto                                |
| produtos\[].saldo           | decimal | Saldo atual após a alteração                   |
| produtos\[].saldo\_anterior | decimal | Saldo antes da alteração                       |
| produtos\[].tipo\_movimento | string  | Tipo: "entrada", "saida" ou "ajuste"           |
| produtos\[].observacao      | string  | Observação do movimento                        |
| produtos\[].deposito\_id    | int     | ID do depósito afetado                         |
| produtos\[].deposito\_nome  | string  | Nome do depósito                               |

## Exemplo de Implementação

### PHP

```php theme={null}
<?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

```python theme={null}
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

```javascript theme={null}
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