Implementar CRUD account-scoped de /v2/webhooks (client-php v3.1.0) #22

Origem

📌 Retroativa — auditoria de rastreabilidade da Review da Sprint 11 (@joaokita). Trabalho já entregue em main sem issue associada; issue criada a partir do conteúdo do PR para dar rastreabilidade 1:1.

Contexto

Resumo

O CRUD de webhooks do SDK estava 100% quebrado contra a API real: a rota company-scoped /v1/companies/{id}/webhooks retorna 404 incondicional (confirmado em 3 contas, 2026-07-02/03) — contrato herdado de alucinação do SDK Node. O contrato real é account-scoped: /v2/webhooks com envelope {"webHook": {...}} nos dois sentidos.

Inclui também o commit de release v3.1.0 (bump de Version.php + CHANGELOG). Após o merge, a tag v3.1.0 será criada na master (dispara o release.yml).

Mudanças

• Novos métodos account-scoped em WebhooksResource: listAccountWebhooks, createAccountWebhook, retrieveAccountWebhook, updateAccountWebhook, deleteAccountWebhook, deleteAllAccountWebhooks (destrutivo, nome distinto), pingAccountWebhook, fetchEventTypes (lista viva — os literais invoice.* não existem)
• Novo DTO AccountWebhook com o shape real do fio (contentType/status string; desvio vs enum int do spec OpenAPI pinado em teste de alinhamento YAML↔DTO)
• Deprecations honestas: 6 métodos company-scoped + getAvailableEvents() + DTO Webhook — comportamento inalterado, remoção na próxima major
• Gotchas no phpdoc/docs/README/sample/skill: NFE.io pinga a uri no create (exige 2xx); secret 32–64 chars ecoado só no create; PUT de update é substituição integral (sem status → desativa o hook)
• Mecânica de path: apiVersion(): '' + paths versionados explícitos (precedente AddressesResource) — URLs company-scoped permanecem idênticas, zero mudança no core

Validação

• ✅ 192 testes passando (12 novos: 9 unit co

…(ver PR completo)

Objetivo

Implementar CRUD account-scoped de /v2/webhooks (client-php v3.1.0) — comportamento entregue e em main.

Critérios de Aceitação

• Entregue via PR fix(webhooks): CRUD account-scoped /v2/webhooks + release v3.1.0 #21 (merged em 2026-07-03, Sprint 11).

Dependências

Nenhuma.

Referências

• PR entregue: fix(webhooks): CRUD account-scoped /v2/webhooks + release v3.1.0 #21