12. Notificações via Webhooks (Eventos)¶

A arquitetura de Webhooks permite que o sistema ERP seja notificado em tempo real sempre que ocorre um evento relevante no Portal Retail, como a aprovação de um novo cadastro de Produto ou Fornecedor.

Em vez de enviar payloads pesados (com imagens Base64) diretamente, o Portal envia uma notificação leve contendo apenas os identificadores, permitindo que o ERP decida quando e como buscar os dados completos.

12.1 Fluxo de Operação (Notify & Fetch)¶

O processo segue quatro etapas principais:

Assinatura: O Portal dispara um POST HTTP para a URL configurada no ERP.
Confirmação (ACK): O ERP responde 200 OK confirmando o recebimento da notificação.
Consulta (Fetch): O ERP utiliza o ID recebido para realizar um GET nos endpoints de consulta.
Processamento: O ERP recebe o JSON completo e atualiza sua base local.

Vantagem do Fluxo

Este modelo evita falhas de rede causadas por payloads gigantes e garante que o ERP tenha controle total sobre a transação.

Acordo de Integração

A escolha entre este modelo de Webhook (Event) ou o Envio Direto (Push) via REST/SOAP deve ser combinada entre as partes durante a fase de implantação.

12.2 Formato da Notificação¶

O payload enviado pelo Portal é padronizado e flexível para suportar novas entidades no futuro.

Exemplo de Payload (POST)¶

{
  "eventId": "evt_f48a1c93284",
  "eventType": "product.created", 
  "entityType": "Product",
  "entityId": "98765",
  "timestamp": "2024-12-06T15:30:45Z",
  "data": {
     "hint": "Dipirona 500mg Genérico"
  }
}

Dicionário de Campos¶

Campo	Tipo	Descrição
`eventId`	String	ID único do evento para controle de idempotência.
`eventType`	String	Ação específica: `product.created`, `supplier.created`, etc.
`entityType`	String	Tipo da entidade: `Product`, `Supplier`, `PurchaseGroup`.
`entityId`	String	Identificador interno no Portal Retail (usado para o Fetch).
`timestamp`	DateTime (ISO 8601)	Data e hora UTC do evento.
`data`	Object	Dados de contexto (opcionais) para facilitação de logs.

12.3 Resgate de Dados (Fetch)¶

Após receber a notificação, o ERP deve chamar o endpoint específico para obter a ficha completa da entidade.

🔍 Buscar Produto Criado¶

Endpoint: GET /erp-data/export/product/{entityId}

GET https://api.retailportal.com/erp-data/export/product/98765 HTTP/1.1
X-API-Key: SUA_CHAVE_AQUI

🔍 Buscar Fornecedor Criado¶

Endpoint: GET /erp-data/export/supplier/{entityId}

GET https://api.retailportal.com/erp-data/export/supplier/SUP-ABC HTTP/1.1
X-API-Key: SUA_CHAVE_AQUI

Importante: Imagens em Base64

Lembre-se que nestes endpoints de exportação, as imagens de produtos e documentos de fornecedores serão retornadas no formato Base64 dentro da coleção de arquivos.

12.4 Segurança e Validação¶

Para garantir que a requisição partiu originariamente do Portal Retail, enviamos uma assinatura digital no cabeçalho.

Cabeçalho	Descrição
`X-Retail-Signature`	Assinatura HMAC SHA-256 gerada com seu `Webhook Secret`.

Dica de Implementação

Embora o uso da assinatura seja opcional, é altamente recomendado validar o cabeçalho X-Retail-Signature para evitar ataques de replay ou requisições forjadas por terceiros.

🔄 Política de Retentativas (Retry)¶

Caso o seu servidor de Webhook esteja offline ou retorne erro (5xx), o sistema seguirá o seguinte fluxo:

1ª Falha: Retentativa em 5 minutos.
2ª Falha: Retentativa em 30 minutos.
3ª Falha: Retentativa em 2 horas.
4ª Falha: Notificação enviada para o administrador e desativação temporária do Webhook.