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

# Introdução aos Webhooks

> Como receber notificações automáticas do sistema PIED

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

```mermaid theme={null}
sequenceDiagram
    participant PIED
    participant Seu Sistema
    
    PIED->>Seu Sistema: POST /webhook
    Note over Seu Sistema: Processa evento
    Seu Sistema->>PIED: 200 OK
```

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

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

```json theme={null}
{
  "event": "order.created",
  "data": {
    // Dados específicos do evento
  }
}
```

## Exemplo de Payload

### Pedido Criado

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

<CardGroup cols={2}>
  <Card title="Segurança" icon="shield">
    * Use HTTPS sempre
    * Valide a origem das requisições
    * Implemente autenticação se necessário
  </Card>

  <Card title="Confiabilidade" icon="check-circle">
    * Responda com 200 OK rapidamente
    * Processe dados de forma assíncrona
    * Implemente retry para falhas
  </Card>
</CardGroup>

## Testando Webhooks

Para testar durante desenvolvimento, use ferramentas como:

* **ngrok**: Exponha localhost publicamente
* **webhook.site**: Capture e inspecione webhooks
* **Postman**: Simule payloads de webhook

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

<CardGroup cols={2}>
  <Card title="API Reference" icon="square-terminal" href="/v2/api-reference/webhook/post-webhook">
    Configure webhooks via API v2
  </Card>

  <Card title="Integrações" icon="plug" href="/integrations/introduction">
    Use webhooks com plataformas de automação
  </Card>
</CardGroup>

## Suporte

Para configurar webhooks ou resolver problemas:

* **Email**: [suporte@pieta.tech](mailto:suporte@pieta.tech)
* **Documentação**: Consulte a referência da API
* **Logs**: Mantenha logs detalhados para diagnóstico