> ## 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 Situação de Pedido

> Receba notificações quando a situação de pedidos for alterada.

## Descrição

Este webhook é acionado automaticamente sempre que a situação de um pedido for alterada no Olist ERP.

## Quando é Acionado

* Mudança de situação do pedido (aberto → aprovado → faturado, etc.)
* Aprovação de pedido
* Faturamento de pedido
* Cancelamento de pedido
* Separação iniciada/concluída
* Pedido enviado
* Pedido entregue

## Estrutura da Notificação

```json theme={null}
{
  "evento": "atualizacao_situacao_pedido",
  "data_hora": "20/05/2024 20:10:45",
  "pedidos": [
    {
      "id": 789456,
      "numero": "12345",
      "numero_ecommerce": "LOJA-2024-5678",
      "situacao_anterior": "aprovado",
      "situacao_atual": "faturado",
      "data_pedido": "18/05/2024",
      "data_aprovacao": "18/05/2024 15:30:00",
      "data_faturamento": "20/05/2024 20:10:00",
      "cliente": {
        "id": 45678,
        "nome": "João da Silva",
        "cpf_cnpj": "123.456.789-00",
        "email": "joao@email.com",
        "telefone": "(11) 98765-4321"
      },
      "valor_total": 1599.90,
      "valor_desconto": 0.00,
      "valor_frete": 49.90,
      "forma_pagamento": "Cartão de Crédito",
      "parcelas": 3,
      "nota_fiscal": {
        "numero": "12345",
        "serie": "1",
        "chave_acesso": "35240512345678901234550010000123451234567890"
      },
      "rastreamento": {
        "codigo": "BR123456789BR",
        "transportadora": "Correios",
        "url": "https://rastreamento.correios.com.br/app/index.php?objeto=BR123456789BR"
      },
      "observacoes": "Pedido faturado e enviado para expedição"
    }
  ]
}
```

## Campos da Notificação

| Campo                         | Tipo    | Descrição                                   |
| ----------------------------- | ------- | ------------------------------------------- |
| evento                        | string  | Sempre "atualizacao\_situacao\_pedido"      |
| data\_hora                    | string  | Data e hora do evento (dd/mm/yyyy hh:mm:ss) |
| pedidos\[]                    | array   | Lista de pedidos com situação alterada      |
| pedidos\[].id                 | int     | ID do pedido no Olist ERP                   |
| pedidos\[].numero             | string  | Número do pedido                            |
| pedidos\[].numero\_ecommerce  | string  | Número do pedido no e-commerce de origem    |
| pedidos\[].situacao\_anterior | string  | Situação anterior do pedido                 |
| pedidos\[].situacao\_atual    | string  | Situação atual do pedido                    |
| pedidos\[].data\_pedido       | string  | Data do pedido (dd/mm/yyyy)                 |
| pedidos\[].data\_aprovacao    | string  | Data/hora da aprovação                      |
| pedidos\[].data\_faturamento  | string  | Data/hora do faturamento                    |
| pedidos\[].cliente.id         | int     | ID do cliente                               |
| pedidos\[].cliente.nome       | string  | Nome do cliente                             |
| pedidos\[].cliente.cpf\_cnpj  | string  | CPF ou CNPJ do cliente                      |
| pedidos\[].cliente.email      | string  | E-mail do cliente                           |
| pedidos\[].cliente.telefone   | string  | Telefone do cliente                         |
| pedidos\[].valor\_total       | decimal | Valor total do pedido                       |
| pedidos\[].valor\_desconto    | decimal | Valor de desconto aplicado                  |
| pedidos\[].valor\_frete       | decimal | Valor do frete                              |
| pedidos\[].forma\_pagamento   | string  | Forma de pagamento                          |
| pedidos\[].parcelas           | int     | Número de parcelas                          |
| pedidos\[].nota\_fiscal       | object  | Dados da NF (se faturado)                   |
| pedidos\[].rastreamento       | object  | Dados de rastreamento (se enviado)          |
| pedidos\[].observacoes        | string  | Observações da alteração                    |

## Situações Possíveis

| Situação          | Descrição            | Fluxo Típico                 |
| ----------------- | -------------------- | ---------------------------- |
| aberto            | Pedido criado        | Início                       |
| aprovado          | Pagamento aprovado   | aberto → aprovado            |
| preparando\_envio | Em separação         | aprovado → preparando\_envio |
| faturado          | Nota fiscal emitida  | preparando\_envio → faturado |
| pronto\_envio     | Aguardando expedição | faturado → pronto\_envio     |
| enviado           | Enviado ao cliente   | pronto\_envio → enviado      |
| entregue          | Entrega confirmada   | enviado → entregue           |
| cancelado         | Pedido cancelado     | qualquer → cancelado         |
| devolvido         | Produto devolvido    | entregue → devolvido         |

## Exemplo de Implementação

### PHP

```php theme={null}
<?php
$json = file_get_contents('php://input');
$data = json_decode($json, true);

if ($data['evento'] === 'atualizacao_situacao_pedido') {
    foreach ($data['pedidos'] as $pedido) {
        $numero = $pedido['numero'];
        $situacao_nova = $pedido['situacao_atual'];
        $cliente = $pedido['cliente'];

        // Atualiza situação no sistema local
        atualizarSituacaoPedido($numero, $situacao_nova);

        // Ações específicas por situação
        switch ($situacao_nova) {
            case 'aprovado':
                enviarEmailAprovacao($cliente['email'], $numero);
                iniciarSeparacao($pedido['id']);
                break;

            case 'faturado':
                enviarEmailNotaFiscal(
                    $cliente['email'],
                    $pedido['nota_fiscal']['chave_acesso']
                );
                break;

            case 'enviado':
                enviarEmailRastreamento(
                    $cliente['email'],
                    $pedido['rastreamento']['codigo'],
                    $pedido['rastreamento']['url']
                );
                enviarSMSRastreamento($cliente['telefone'], $pedido['rastreamento']['codigo']);
                break;

            case 'entregue':
                enviarEmailSatisfacao($cliente['email'], $numero);
                solicitarAvaliacao($pedido['id']);
                break;

            case 'cancelado':
                enviarEmailCancelamento($cliente['email'], $numero);
                processarEstorno($pedido['id']);
                break;
        }

        // Log da alteração
        registrarLog("Pedido {$numero}: {$pedido['situacao_anterior']} → {$situacao_nova}");
    }

    http_response_code(200);
    echo json_encode(['status' => 'processado']);
}
?>
```

### Python

```python theme={null}
from flask import Flask, request, jsonify
from datetime import datetime

app = Flask(__name__)

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

    if data.get('evento') == 'atualizacao_situacao_pedido':
        for pedido in data.get('pedidos', []):
            numero = pedido['numero']
            situacao = pedido['situacao_atual']
            cliente = pedido['cliente']

            # Atualiza no banco
            atualizar_situacao_pedido(numero, situacao)

            # Processamento por situação
            if situacao == 'aprovado':
                enviar_email_aprovacao(cliente['email'], numero)
                notificar_equipe_logistica(pedido['id'])

            elif situacao == 'faturado':
                enviar_nfe_cliente(
                    email=cliente['email'],
                    chave_nfe=pedido['nota_fiscal']['chave_acesso']
                )

            elif situacao == 'enviado':
                enviar_notificacao_envio(
                    email=cliente['email'],
                    telefone=cliente['telefone'],
                    rastreamento=pedido['rastreamento']['codigo']
                )

            elif situacao == 'entregue':
                enviar_pesquisa_satisfacao(cliente['email'], numero)
                liberar_cashback(pedido['id'])

            elif situacao == 'cancelado':
                processar_cancelamento(pedido['id'])
                enviar_email_cancelamento(cliente['email'])

            # Analytics
            registrar_evento_analytics({
                'pedido': numero,
                'situacao': situacao,
                'valor': pedido['valor_total'],
                'timestamp': datetime.now()
            })

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

    return jsonify({'status': 'erro'}), 400
```

### Node.js

```javascript theme={null}
const express = require('express');
const app = express();

app.use(express.json());

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

    if (data.evento === 'atualizacao_situacao_pedido') {
        for (const pedido of data.pedidos) {
            const { numero, situacao_atual, cliente, rastreamento, nota_fiscal } = pedido;

            // Atualiza no banco de dados
            await atualizarSituacaoPedido(numero, situacao_atual);

            // Processamento específico por situação
            switch (situacao_atual) {
                case 'aprovado':
                    await enviarEmailAprovacao(cliente.email, numero);
                    await notificarEquipeLogistica(pedido.id);
                    break;

                case 'faturado':
                    await enviarNFE({
                        email: cliente.email,
                        numero: nota_fiscal.numero,
                        chave: nota_fiscal.chave_acesso
                    });
                    break;

                case 'enviado':
                    await Promise.all([
                        enviarEmailRastreamento(cliente.email, rastreamento.codigo, rastreamento.url),
                        enviarSMS(cliente.telefone, `Pedido ${numero} enviado! Rastreio: ${rastreamento.codigo}`),
                        enviarPushNotification(cliente.id, 'Seu pedido foi enviado!')
                    ]);
                    break;

                case 'entregue':
                    await enviarPesquisaSatisfacao(cliente.email, numero);
                    await registrarEntrega(pedido.id);
                    break;

                case 'cancelado':
                    await processarCancelamento(pedido.id);
                    await enviarEmailCancelamento(cliente.email, numero);
                    await processarEstorno(pedido.id);
                    break;
            }

            // Dashboard em tempo real
            await atualizarDashboard({
                pedido: numero,
                situacao: situacao_atual,
                valor: pedido.valor_total
            });

            console.log(`Pedido ${numero} atualizado para ${situacao_atual}`);
        }

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

app.listen(3000);
```

## Configuração

Para ativar este webhook:

1. Acesse **Configurações > Integrações > Webhooks**
2. Clique em **Novo Webhook**
3. Selecione o evento **Atualização de Situação de Pedido**
4. Informe a URL do seu endpoint
5. Opcionalmente, selecione situações específicas para monitorar
6. Salve as configurações

## Casos de Uso

* **Notificações ao cliente**: E-mail/SMS automático em cada etapa
* **Dashboard em tempo real**: Atualize painéis de acompanhamento
* **Integração com marketplaces**: Sincronize status em múltiplos canais
* **Automação logística**: Acione processos de separação e envio
* **CRM automático**: Atualize jornada do cliente
* **BI e Analytics**: Alimente relatórios em tempo real
* **Pesquisa de satisfação**: Envie automaticamente após entrega

## Boas Práticas

* **Notificações contextuais**: Personalize mensagens para cada situação
* **Múltiplos canais**: Use e-mail, SMS e push notification
* **Templates profissionais**: Use templates bem desenhados
* **Tracking de eventos**: Registre todas as mudanças para analytics
* **Idempotência**: Evite processar a mesma mudança múltiplas vezes
* **Tratamento de erros**: Implemente retry para falhas temporárias

## Observações

* Algumas mudanças de situação podem ser revertidas (ex: cancelamento)
* Pedidos podem pular situações intermediárias em alguns fluxos
* A situação "cancelado" pode ocorrer a partir de qualquer estado
* Dados de nota\_fiscal e rastreamento são condicionais
* Múltiplos pedidos podem ser notificados em uma única requisição
* O webhook é enviado apenas para mudanças efetivas de situação