# Webhooks

Como o plugin recebe e valida as notificações de pagamento.

O plugin expõe um endpoint REST que recebe as notificações da FaciPay e atualiza o estado das
ordens. É a **fonte da verdade** do pagamento.

## Endpoint

```
POST https://a-sua-loja.com/wp-json/facipay/v1/incoming
```

Público (sem autenticação WordPress), protegido por **HMAC**. Copia este URL das definições e
entrega-o à equipa FaciPay, que o regista contra as credenciais da sua conta. O registo é ao nível
da conta: este único endpoint recebe **todas** as notificações da sua loja — não é configurado por
ordem.

## Verificação HMAC

O header `x-facipay-content-token` contém o HMAC SHA-256 do body cru, calculado com o seu
**Webhook Secret**. O plugin valida-o com `hash_equals` (tempo constante) e aceita os formatos
`sha256=…`, `sha256:…`, hex cru ou base64.

## Mapeamento de estados

| Estado recebido | Estado WooCommerce |
|---|---|
| `con` / `completed` / `paid` / `success` | `processing` (pago) |
| `pen` / `pending` / `processing` | `on-hold` (referência pendente) |
| `can` / `cancelled` / `expired` / `failed` | `failed` |
| `refunded` | `refunded` |
| outro | inalterado |

O plugin é **idempotente**: regista o último `paymentId` + estado e responde `200` sem
reprocessar se o mesmo evento chegar repetido.

## Dados guardados na ordem

Para Referência EMIS pendente, o plugin guarda a referência, entidade e número de terminal
(`_facipay_payment_reference`, `_facipay_payment_ref_entity_name`,
`_facipay_payment_ref_entity_number`), além de cliente, taxa (`_facipay_fee`) e valor líquido
(`_facipay_payout`) — visíveis nos detalhes da ordem.

## Respostas

| Código | Significado |
|---|---|
| `200` | Processado (ou já processado). |
| `400` | Campos em falta / JSON inválido. |
| `401` | Assinatura HMAC inválida. |
| `404` | Ordem não encontrada. |

<Note>
Para desenvolvimento, existe a constante `FACIPAY_SKIP_HMAC` que (com `WP_DEBUG`) ignora a
validação HMAC. **Nunca** a use em produção.
</Note>