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@email.com"
    },
    "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@email.com"
      }
    },
    "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: suporte@pieta.tech
Documentação: Consulte a referência da API
Logs: Mantenha logs detalhados para diagnóstico

​Webhooks PIED

​Como Funcionam

​Eventos Disponíveis

​Orçamentos

​Pedidos

​Configuração

​1. Prepare seu Endpoint

​2. Configure no PIED

​Estrutura do Payload

​Exemplo de Payload

​Pedido Criado

​Ações que Disparam Webhooks

​✅ Disparam Webhooks

​❌ Não Disparam Webhooks

​Boas Práticas