Skip to content

fix: update webhook endpoints to api.nfse.io/v2#18

Closed
ianchamba wants to merge 1 commit into
nfe:masterfrom
ianchamba:fix/update-webhook-endpoints
Closed

fix: update webhook endpoints to api.nfse.io/v2#18
ianchamba wants to merge 1 commit into
nfe:masterfrom
ianchamba:fix/update-webhook-endpoints

Conversation

@ianchamba

@ianchamba ianchamba commented Mar 3, 2026

Copy link
Copy Markdown

Summary

  • Webhook API migrated from api.nfe.io/v1/hooks to api.nfse.io/v2/webhooks
  • The old endpoint (/v1/hooks/{id}) returns 404 - webhooks now live at api.nfse.io/v2/webhooks/{id}
  • No company scope needed for webhook endpoints

Changes

lib/NFe/APIResource.php

  • Fixed objectBaseURI() mapping: 'hooks' -> 'webhooks'

lib/NFe/Webhook.php

  • Added endpointAPI() override to use https://api.nfse.io/v2/webhooks as base URL
  • Other resources (companies, service invoices) continue using api.nfe.io/v1 as before
  • Webhook methods kept simple (no company scope parameter)

Test plan

  • Verify NFe_Webhook::fetch($webhookId) hits api.nfse.io/v2/webhooks/{id}
  • Verify NFe_Webhook::create($data) POSTs to api.nfse.io/v2/webhooks
  • Verify other resources (companies, service invoices) still use api.nfe.io/v1

🤖 Generated with Claude Code

@ianchamba
ianchamba force-pushed the fix/update-webhook-endpoints branch from 9fc8862 to 6806d8b Compare March 3, 2026 20:16
@ianchamba ianchamba changed the title fix: update webhook endpoints to company-scoped /webhooks fix: update webhook endpoints to api.nfse.io/v2 Mar 3, 2026
@ianchamba
ianchamba force-pushed the fix/update-webhook-endpoints branch 2 times, most recently from d5aa952 to d3914d7 Compare March 3, 2026 20:26
- Rename 'hooks' to 'webhooks' in APIResource objectBaseURI mapping
- Override endpointAPI() in NFe_Webhook to use https://api.nfse.io/v2/webhooks
  instead of the deprecated api.nfe.io/v1/hooks endpoint
- Override CRUD methods to handle v2 response structure where webhook data
  is wrapped in "webHook" (camelCase singular) instead of "webhooks"
- Update WebhookTest.php to use v2 response properties (uri instead of url)
- Webhook methods remain simple (no company scope needed)

API v2 response example:
  {"webHook": {"id": "...", "uri": "...", "secret": "...", "status": "Active"}}

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@andrenfe

Copy link
Copy Markdown
Member

Fechando como superado. O contrato de webhooks já foi resolvido no #21 (fix-account-webhooks-contract, mergeado): o CRUD passou a ser account-scoped em /v2/webhooks no host api.nfe.io, com envelope { "webHook": {…} } nos dois sentidos — confirmado por sondas ao vivo em 3 contas.

Dois motivos tornam este PR obsoleto:

  1. Foi escrito contra o codebase v2 (pré-reescrita v3 — ex.: private static $webhookBaseURI); a estrutura mudou completamente na GA v3.0.0.
  2. Aponta os webhooks para api.nfse.io/v2, mas o host correto (verificado ao vivo) é api.nfe.io/v2/webhooks — a mudança de host proposta aqui levaria ao endpoint errado.

Obrigado pela contribuição — o objetivo (mover os webhooks para /v2) foi alcançado no #21, no host certo.

@andrenfe andrenfe closed this Jul 10, 2026
andrenfe added a commit that referenced this pull request Jul 14, 2026
A skill versionada no repo estava na baseline v3.1.0 — duas releases atrás.
(As atualizações de v3.2.0 haviam sido aplicadas na cópia local ~/.claude,
removida quando a skill passou a ser versionada aqui.)

v3.2.0 (add-safe-retry-idempotency):
- Retry method-aware (tabela de decisão; POST não retenta em 5xx/ambíguo;
  Idempotency-Key restaura retry pleno mas a API ainda não honra o header).
- FailurePhase + failurePhase/curlErrno na ApiConnectionException.
- Override de retry por chamada (RequestOptions->retry).
- findByExternalId (rota /external, contrato de coleção, miss=200 lista vazia,
  lag de indexação) + isDuplicateExternalId + ciclo de emissão idempotente.
- Pitfalls #17/#18; decision tree; descrições dos reference files.

v3.3.0 (expand-service-invoice-dto):
- ServiceInvoice: campos tipados number/checkCode/description/cityServiceCode/
  baseTaxAmount/issRate/issTaxAmount/amountNet + borrower (Borrower DTO,
  federalTaxNumber int|string|null).
- raw agora populado (SDK-wide, por item em list); provider via raw['provider'].
- totalAmount documentado como phantom @deprecated (sempre null) — pitfall #19.
- Nota sobre o teste de alinhamento YAML<->DTO (ancorado por path).

Fatos verificados contra o src/ (ordem dos args de RequestOptions, cases do
FailurePhase, allowlist de errnos 5/6/7/35, assinatura static de
isDuplicateExternalId, campos do Borrower).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants