Skip to main content

​
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

{
  "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

CampoTipoDescrição
eventostringSempre “atualizacao_situacao_pedido”
data_horastringData e hora do evento (dd/mm/yyyy hh:mm:ss)
pedidos[]arrayLista de pedidos com situação alterada
pedidos[].idintID do pedido no Olist ERP
pedidos[].numerostringNúmero do pedido
pedidos[].numero_ecommercestringNúmero do pedido no e-commerce de origem
pedidos[].situacao_anteriorstringSituação anterior do pedido
pedidos[].situacao_atualstringSituação atual do pedido
pedidos[].data_pedidostringData do pedido (dd/mm/yyyy)
pedidos[].data_aprovacaostringData/hora da aprovação
pedidos[].data_faturamentostringData/hora do faturamento
pedidos[].cliente.idintID do cliente
pedidos[].cliente.nomestringNome do cliente
pedidos[].cliente.cpf_cnpjstringCPF ou CNPJ do cliente
pedidos[].cliente.emailstringE-mail do cliente
pedidos[].cliente.telefonestringTelefone do cliente
pedidos[].valor_totaldecimalValor total do pedido
pedidos[].valor_descontodecimalValor de desconto aplicado
pedidos[].valor_fretedecimalValor do frete
pedidos[].forma_pagamentostringForma de pagamento
pedidos[].parcelasintNúmero de parcelas
pedidos[].nota_fiscalobjectDados da NF (se faturado)
pedidos[].rastreamentoobjectDados de rastreamento (se enviado)
pedidos[].observacoesstringObservações da alteração

​
Situações Possíveis

SituaçãoDescriçãoFluxo Típico
abertoPedido criadoInício
aprovadoPagamento aprovadoaberto → aprovado
preparando_envioEm separaçãoaprovado → preparando_envio
faturadoNota fiscal emitidapreparando_envio → faturado
pronto_envioAguardando expediçãofaturado → pronto_envio
enviadoEnviado ao clientepronto_envio → enviado
entregueEntrega confirmadaenviado → entregue
canceladoPedido canceladoqualquer → cancelado
devolvidoProduto devolvidoentregue → devolvido

​
Exemplo de Implementação

​
PHP

<?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

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

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