Skip to main content

​
Webhooks PIED

Os webhooks permitem que seu sistema receba notificações automáticas quando eventos importantes acontecem no PIED, como criação de pedidos ou atualizações de orçamentos.

​
Como Funcionam

Quando um evento configurado ocorre, o PIED envia uma requisição HTTP POST para a URL que você especificar, contendo os dados do evento.

​
Eventos Disponíveis

​
Orçamentos

  • budget.created - Orçamento criado
  • budget.updated - Orçamento atualizado

​
Pedidos

  • order.created - Pedido criado
  • order.updated - Pedido atualizado

​
Configuração

​
1. Prepare seu Endpoint

Crie um endpoint HTTPS que aceite POST com JSON: 
app.post('/webhook', (req, res) => {
  const { event, data } = req.body;
  
  switch(event) {
    case 'order.created':
      console.log('Novo pedido:', data.code);
      break;
    case 'budget.updated':
      console.log('Orçamento atualizado:', data.code);
      break;
  }
  
  res.status(200).send('OK');
});

​
2. Configure no PIED

Entre em contato com o suporte para configurar:
  • URL do seu endpoint
  • Eventos que deseja receber
  • Autenticação (se necessária)

​
Estrutura do Payload

Todos os webhooks seguem esta estrutura: 
{
  "event": "order.created",
  "data": {
    // Dados específicos do evento
  }
}

​
Exemplo de Payload

​
Pedido Criado

{
  "event": "order.created",
  "data": {
    "id": "Identificador (ID) da requisição",
    "name": "Nome da requisição",
    "code": "200000000",
    "kind": "Kit Express",
    "type": "order",
    "totalPower": 5.265,
    "dealStatus": "Status do negócio (ex: 'zeradinho')",
    "stockStatus": "Status do estoque (ex: 'removed')",
    "originalValue": 10000,
    "finalValue": 9000,
    "responsible": {
      "name": "Nome do responsável",
      "surname": "Sobrenome do responsável",
      "cellphone": "(00) 00000-0000",
      "email": "[email protected]"
    },
    "company": {
      "address": {
        "CEP": "00000-000",
        "patio": "Nome da Rua",
        "neighborhood": "Nome do Bairro",
        "city": "Nome da Cidade",
        "state": "SC",
        "number": "1000"
      },
      "companyName": "Razão social",
      "fantasyName": "Nome fantasia",
      "cpf": null,
      "cnpj": "00.000.000/0000-00",
      "mainContact": {
        "name": "Nome do contato principal",
        "surname": "Sobrenome do contato principal",
        "cellphone": "(00) 00000-0000",
        "email": "[email protected]"
      }
    },
    "products": [
      {
        "productCode": "codigo123",
        "type": "module",
        "name": "Nome do produto",
        "quantity": 10,
        "singlePrice": 1000,
        "totalPrice": 10000,
        "center": {
          "name": "Nome do centro de distribuição",
          "code": "CD001"
        }
      },
      {
        "productCode": "codigo456",
        "type": "inverter",
        "name": "Nome do inversor",
        "quantity": 1,
        "singlePrice": 3000,
        "totalPrice": 3000,
        "center": {
          "name": "Nome do centro de distribuição",
          "code": "CD002"
        }
      }
    ],
    "payment": {
      "type": "credito",
      "showConditionsRule": "YesShowFinalValueUpdated",
      "condition": {
        "_id": "Identificador da condição",
        "name": "1x",
        "quantityOfInstallments": 1,
        "conditionType": "decrease",
        "modifierType": "fixed",
        "value": 100
      },
      "status": "notRequested",
      "description": "",
      "files": []
    },
    "lastUpdate": "2025-10-23T19:12:24.391Z"
  }
}

​
Ações que Disparam Webhooks

​
✅ Disparam Webhooks

Orçamentos:
  • Criação de orçamento
  • Alteração de status
  • Aplicação de desconto/acréscimo
  • Conversão em pedido
  • Adição/remoção de tags
Pedidos:
  • Criação de pedido
  • Alteração de status
  • Alteração de status de pagamento
  • Edição de dados comerciais
  • Adição/remoção de tags
Empresas:
  • Criação de empresa
  • Alteração de status
  • Edição de dados
  • Adição/remoção de tags

​
❌ Não Disparam Webhooks

  • Comentários e tarefas
  • Alteração de responsável
  • Edição de frete
  • Campos customizados
  • Anotações internas
  • Upload de arquivos

​
Boas Práticas

Segurança

  • Use HTTPS sempre
  • Valide a origem das requisições
  • Implemente autenticação se necessário

Confiabilidade

  • Responda com 200 OK rapidamente
  • Processe dados de forma assíncrona
  • Implemente retry para falhas

​
Testando Webhooks

Para testar durante desenvolvimento, use ferramentas como:
  • ngrok: Exponha localhost publicamente
  • webhook.site: Capture e inspecione webhooks
  • Postman: Simule payloads de webhook
# Exemplo com ngrok
ngrok http 3000
# Use a URL gerada para configurar o webhook

​
Monitoramento

Monitore seus webhooks:
  • Log todas as requisições recebidas
  • Acompanhe taxa de sucesso/falha
  • Configure alertas para falhas consecutivas
  • Mantenha histórico para auditoria

​
Próximos Passos

API Reference

Configure webhooks via API v2

Integrações

Use webhooks com plataformas de automação

​
Suporte

Para configurar webhooks ou resolver problemas:
  • Email: [email protected]
  • Documentação: Consulte a referência da API
  • Logs: Mantenha logs detalhados para diagnóstico