nfe-io 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 787947713cf27bbdb1f9e22775e2ef2aa59ef185e4015c8ae74e99864c833e2d
-  data.tar.gz: a32a98bcdbf26b3f4c6a9c143fd46d796d5e5b7e47114309efcb98a0f779f3da
+  metadata.gz: 5e9b7b2223a90779e218be5ddb727e1f4c9d707a24767075c7d56132c353347c
+  data.tar.gz: 55597041ea75f6c244a5af2e64e0f29ea022b9f5041caf987e6f2bcda6ef3bfa
 SHA512:
-  metadata.gz: 495de7c5b904d2de20c731521b8bc608825dbcadb200d86ce98489638a634e57105df3cb17c2b1016c2fb15be59ada705079b624b7343a510dc02f20d6d7dd49
-  data.tar.gz: 37ab16497cb424cc9fb759c0c824c798cdc06fe5fb5ba35da78d2b7d546507cc194150040011510b5a0c7097672da2e7985b7be27b00ca972a9e998977a75498
+  metadata.gz: d0c6297b2146225c8d9e7c228866a836367b484e727a47956ddb59ef084715a8be11f0a0bdbf8cf51d391a763e9736d293ecfb9a89bd21c47e0c56cc8aaeb57e
+  data.tar.gz: a6cbb185d13215213bec2387b06c988fd41de2446c2c779424fac01c54b8692fa2de7136c783581ea9160b40f15697d1ea83fad9ab9b06d7ac55a2d22e65c02e

data/CHANGELOG.md

@@ -7,6 +7,86 @@ e o projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR/).
 
 ## [Não lançado]
 
+## [1.1.0] - 2026-07-09
+
+> Duas correções de contrato contra a API real: o CRUD de webhooks (provado por
+> sonda ao vivo, 2026-07-02/03, três contas) e a cobertura do retrieve de NFS-e
+> (o DTO descartava mais da metade dos campos). Em ambas, o contrato correto
+> sempre esteve nos specs oficiais (`openapi/nf-servico-v1.yaml` e equivalentes) —
+> o código manuscrito havia divergido deles.
+
+### Corrigido
+
+- **O CRUD de webhooks funcionava 0% das vezes**: a rota company-scoped
+  `/v1/companies/{id}/webhooks` retorna 404 na API atual. O contrato real é
+  account-scoped (`/v2/webhooks`) e exige o request envelopado em
+  `{ "webHook": {...} }` (sem ele responde
+  `400 "missing required properties: 'webHook'"`), devolvendo a resposta também
+  envelopada. Os novos métodos account-scoped envelopam o request
+  (create/update) e desembrulham as respostas (create/retrieve/update/list),
+  com fallback defensivo para corpo cru.
+- **`Nfe::ServiceInvoice` descartava ~25 dos 44 campos do retrieve de NFS-e**
+  (toda a árvore de retenções, `provider`, `taxationType`, `location`,
+  `approximateTax`, ...): o `from_api` agora preserva o payload completo em
+  `invoice.raw` (padrão do `ConsumerInvoice`), em todas as leituras
+  (list/retrieve/cancel/201-issued).
+
+### Adicionado
+
+- Métodos account-scoped em `client.webhooks`: `list_account_webhooks`,
+  `create_account_webhook`, `retrieve_account_webhook`,
+  `update_account_webhook`, `delete_account_webhook`,
+  `delete_all_account_webhooks` (destrutivo, nome propositalmente distinto),
+  `ping_account_webhook` e `fetch_event_types`.
+- Value object **`Nfe::AccountWebhook`** (`Data.define`, com RBS) com o shape
+  real da API: `uri`, `content_type`, `secret` (32–64 caracteres, ecoado no
+  create e omitido nas leituras), `filters`, `insecure_ssl`, `headers`,
+  `properties`, `status`, `created_on`, `modified_on`. Nota: o spec declara
+  `contentType`/`status` como enums inteiros, mas a API serializa strings
+  (`"json"`, `"Active"`) — o DTO segue o fio real.
+- `fetch_event_types` retorna os event types reais de
+  `GET /v2/webhooks/eventTypes` (46 ids ao vivo, padrão
+  `service_invoice.*`/`product_invoice.*`/`consumer_invoice.*`).
+- Teste de alinhamento (RSpec + Psych) amarrando o `Nfe::AccountWebhook` ao
+  schema de `/v2/webhooks` em `openapi/nf-servico-v1.yaml` — um sync de spec
+  que mude o contrato de webhooks quebra a suíte em vez de driftar.
+- YARD do `create_account_webhook` documenta a verificação de URI na criação
+  (a NFE.io faz um ping e exige resposta 2xx) e o `secret` de 32–64 caracteres.
+- YARD do `update_account_webhook` documenta que o `PUT` é substituição
+  integral (confirmado ao vivo em 2026-07-03): campos omitidos voltam ao
+  padrão — update sem `status` **desativa o webhook**. Envie o objeto completo
+  (parta do retrieve).
+- Campos de ISS tipados em `Nfe::ServiceInvoice`: `base_tax_amount`,
+  `iss_rate`, `iss_tax_amount`.
+- Value object **`Nfe::ServiceInvoiceBorrower`** (tomador, com RBS):
+  `federal_tax_number` sempre `String` (tolerante ao CNPJ alfanumérico da
+  IN RFB 2.229/2024, fio Integer ou String) e **ponte Hash** — leituras
+  `borrower["..."]`/`borrower.dig(...)` continuam funcionando (delegam ao
+  payload cru), agora ao lado dos leitores tipados.
+- Teste de alinhamento (RSpec + Psych) amarrando `Nfe::ServiceInvoice` ao
+  schema inline do retrieve em `openapi/nf-servico-v1.yaml`, **ancorado por
+  path** (há colisão de `operationId` no spec) — também serve de gatilho de
+  migração: quando a resposta for componentizada upstream, o teste falha e
+  sinaliza migrar para o modelo gerado.
+- Spec `nf-servico-v1.yaml` atualizado (respostas de erro tipadas com
+  `ErrorsResource` em `components.schemas`) + namespace gerado
+  `Nfe::Generated::NfServicoV1` (somente o modelo de erros; a resposta de
+  sucesso segue inline e o DTO manuscrito).
+
+### Deprecado
+
+- Métodos company-scoped de webhooks (`list`, `create`, `retrieve`, `update`,
+  `delete`, `test` sobre `/v1/companies/{id}/webhooks`): a rota retorna **404**
+  na API atual (confirmado em três contas, 2026-07-02/03). Use os equivalentes
+  account-scoped. O comportamento não mudou; remoção fica para a próxima major.
+- `Nfe::WebhookSubscription` (`url`/`events`/`active`) e
+  `get_available_events`/`AVAILABLE_EVENTS` (literais `invoice.*`): shapes e
+  eventos que a API real rejeita ou desconhece. Use `Nfe::AccountWebhook` e
+  `fetch_event_types`.
+- `Nfe::ServiceInvoice#pdf` e `#xml`: campos-fantasma — a resposta do retrieve
+  não os traz (sempre `nil`). Use `download_pdf`/`download_xml`. Remoção na
+  próxima major.
+
 ## [1.0.0] - 2026-07-02
 
 ### Adicionado
@@ -55,6 +135,7 @@ e o projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR/).
 
 - Última versão da série `0.x` (legada, baseada em `rest-client`). Congelada, sem manutenção.
 
-[Não lançado]: https://github.com/nfe/client-ruby/compare/v1.0.0...HEAD
+[Não lançado]: https://github.com/nfe/client-ruby/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/nfe/client-ruby/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/nfe/client-ruby/compare/v0.3.2...v1.0.0
 [0.3.2]: https://github.com/nfe/client-ruby/releases/tag/v0.3.2

data/README.md

@@ -49,6 +49,21 @@ Ou instalação direta:
 gem install nfe-io
 ```
 
+## Skill para agentes de IA
+
+Além do gem, este repositório publica uma **skill de agente** (`nfeio-ruby-sdk`) que
+ensina assistentes de IA (Claude Code, Cursor, Copilot, etc.) a usar o SDK corretamente.
+São **dois canais distintos**:
+
+| Canal | Comando | O quê |
+|---|---|---|
+| Código (RubyGems) | `gem install nfe-io` | O SDK Ruby |
+| Skill de agente ([skills.sh](https://www.skills.sh/)) | `npx skills add https://github.com/nfe/client-ruby --skill nfeio-ruby-sdk` | O guia de uso para agentes |
+
+O atalho `npx skills add nfe/client-ruby` também funciona. A skill é lida da árvore do
+GitHub (slug `nfe/client-ruby`); ela **não** vem no `gem install` — o gemspec empacota
+apenas `lib/`, `sig/` e os docs.
+
 ## Quickstart
 
 ```ruby
@@ -169,7 +184,7 @@ A `v1` expõe **17 recursos canônicos** no `Nfe::Client` (mais 2 addons RTC).
 | `companies` | `api.nfe.io` (`/v1`) | Empresas + certificado | `create`, `retrieve`, `list`, `update`, `remove`, `upload_certificate`, `get_certificate_status` |
 | `legal_people` | `api.nfe.io` (`/v1`) | Pessoas jurídicas (tomadores) | `create`, `retrieve`, `list`, `update`, `delete`, `create_batch`, `find_by_tax_number` |
 | `natural_people` | `api.nfe.io` (`/v1`) | Pessoas físicas (tomadores) | `create`, `retrieve`, `list`, `update`, `delete`, `create_batch`, `find_by_tax_number` |
-| `webhooks` | `api.nfe.io` (`/v1`) | Assinaturas de webhook | `create`, `retrieve`, `list`, `update`, `delete`, `test`, `verify_signature` |
+| `webhooks` | `api.nfe.io` (`/v2`, conta) | Webhooks da conta | `create_account_webhook`, `retrieve_account_webhook`, `list_account_webhooks`, `update_account_webhook`, `delete_account_webhook`, `ping_account_webhook`, `fetch_event_types`, `verify_signature` |
 | `product_invoices` | `api.nfse.io` (`/v2`) | NF-e | `create`, `create_with_state_tax`, `list`, `retrieve`, `cancel`, `send_correction_letter`, `disable`, `download_*` |
 | `consumer_invoices` | `api.nfse.io` (`/v2`) | NFC-e | `create`, `create_with_state_tax`, `list`, `retrieve`, `cancel`, `disable_range`, `download_pdf`/`download_xml` |
 | `transportation_invoices` | `api.nfse.io` (`/v2`) | CT-e (recepção) | `enable`, `disable`, `get_settings`, `retrieve`, `download_xml`, `get_event` |
@@ -267,7 +282,7 @@ discriminado**:
   `pending?` ⇒ `true`, `issued?` ⇒ `false`.
 - `*Issued` (HTTP 201, já materializado) — expõe `resource`; `issued?` ⇒ `true`.
 
-Não há `create_and_wait` nem `create_batch` na v1.0 — faça **polling** chamando
+Não há `create_and_wait` nem `create_batch` na v1.x — faça **polling** chamando
 `retrieve` até um estado terminal, usando `Nfe::FlowStatus.terminal?`. Os estados
 terminais são: `Issued`, `IssueFailed`, `Cancelled`, `CancelFailed`.
 
@@ -359,16 +374,26 @@ Devolvem bytes: `service_invoices`, `consumer_invoices`,
 
 ## Webhooks
 
-Crie a assinatura e **verifique a assinatura** de cada entrega.
+Crie o webhook (escopo da **conta**, `/v2/webhooks`) e **verifique a
+assinatura** de cada entrega. A NFE.io pinga a `uri` na criação e exige 2xx;
+descubra os filtros válidos com `fetch_event_types`.
 
 ```ruby
-client.webhooks.create("co_1", {
-  url: "https://minha-app.com/webhooks/nfe",
-  events: ["invoice.issued", "invoice.cancelled", "invoice.failed"],
-  secret: ENV["NFE_WEBHOOK_SECRET"]
-})
+client.webhooks.create_account_webhook(
+  uri: "https://minha-app.com/webhooks/nfe",
+  contentType: "json",
+  secret: ENV["NFE_WEBHOOK_SECRET"],   # 32–64 caracteres
+  filters: ["service_invoice.issued_successfully", "service_invoice.issued_error"],
+  status: "Active"
+)
 ```
 
+> ⚠️ `update_account_webhook` faz **PUT integral**: campos omitidos voltam ao
+> padrão — um update sem `status` desativa o webhook. Parta do
+> `retrieve_account_webhook` e envie o objeto completo. Os métodos
+> company-scoped (`create`/`list`/... com `company_id`) estão **deprecated** —
+> a rota `/v1/companies/{id}/webhooks` retorna 404 na API atual.
+
 A verificação é **HMAC-SHA1 sobre os bytes crus** da requisição (header
 `X-Hub-Signature`, comparação case-insensitive e timing-safe). Leia o corpo bruto
 **antes** de fazer parse do JSON — reserializar (`payload.to_json`) muda

data/lib/nfe/generated/generated_marker.rb

@@ -13,6 +13,7 @@ module Nfe
       "contribuintes-v2.json" => "sha256:e2d215a19f5dc85c08067d51644e807aae32b6c4754390872670f2e18a938102",
       "nf-consumidor-v2.yaml" => "sha256:8c39e692ff794ccb2587ebe142be040e44d76cbf970f45e65b28d56a6165bdb5",
       "nf-produto-v2.yaml" => "sha256:e565b47e4d8b17255f99efc2b6354d589d2903c4ba9b97caabd74f84de59e4e2",
+      "nf-servico-v1.yaml" => "sha256:621a3b8e437e5cb37367c8cd26fec93fa2b3f87c9a59252ac987c56bb0c7ba56",
       "nfeio.yaml" => "sha256:813bda287538f8599c3565485eb523d1b1311b26b5be94ead62ba0b7a17f6af3",
       "product-invoice-rtc-v1.yaml" => "sha256:4327ad141eeace6219dc4267678c44a134ae1fdde93f7dd69cf4c9ae9418415a",
       "product-register-pt-br-v1.yaml" => "sha256:beba0a3fb4dc1bc157a5a4a28e55768cea0e7390b491bdd4bedee2ee2297ca64",

data/lib/nfe/generated/nf_servico_v1/errors_resource.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# AUTO-GENERATED — do not edit
+# Source: openapi/nf-servico-v1.yaml
+# Hash: sha256:621a3b8e437e5cb37367c8cd26fec93fa2b3f87c9a59252ac987c56bb0c7ba56
+
+module Nfe
+  module Generated
+    module NfServicoV1
+      ErrorsResource = Data.define(:errors) do
+        def self.from_api(payload)
+          return nil if payload.nil?
+
+          new(
+            errors: payload["errors"],
+          )
+        end
+      end
+    end
+  end
+end

data/lib/nfe/generated.rb

@@ -362,6 +362,7 @@ require_relative "generated/nf_produto_v2/transport_vehicle_resource"
 require_relative "generated/nf_produto_v2/vehicle_detail_resource"
 require_relative "generated/nf_produto_v2/volume_resource"
 require_relative "generated/nf_produto_v2/withdrawal_information_resource"
+require_relative "generated/nf_servico_v1/errors_resource"
 require_relative "generated/nfeio/batch_process_response"
 require_relative "generated/nfeio/environment"
 require_relative "generated/nfeio/file_parsing_options_request"

data/lib/nfe/resources/dto/account_webhook.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for an account-level webhook, as returned by the
+  # +/v2/webhooks+ API (account scope, envelope +{"webHook": {...}}+ on the
+  # wire). This is the shape the live API accepts and returns — confirmed by
+  # probe against +api.nfe.io+ (2026-07-02/03) and matching the schema in
+  # +openapi/nf-servico-v1.yaml+.
+  #
+  # Wire-format note: the OpenAPI spec declares +contentType+/+status+ as int
+  # enums (0/1), but the API serializes strings (+"json"+, +"Active"+) — this
+  # DTO follows the wire. +secret+ (32–64 chars) is echoed only on create and
+  # omitted on reads, so it is +nil+ on retrieve/list.
+  #
+  # {from_api} maps API camelCase onto snake_case, drops unknown keys, and is
+  # nil-tolerant (+from_api(nil)+ returns +nil+).
+  class AccountWebhook < Data.define(
+    :id,
+    :uri,
+    :content_type,
+    :secret,
+    :filters,
+    :insecure_ssl,
+    :headers,
+    :properties,
+    :status,
+    :created_on,
+    :modified_on
+  )
+    # @param payload [Hash, nil] the unwrapped webhook object.
+    # @return [Nfe::AccountWebhook, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        uri: payload["uri"],
+        content_type: payload["contentType"],
+        secret: payload["secret"],
+        filters: payload["filters"],
+        insecure_ssl: payload["insecureSsl"],
+        headers: payload["headers"],
+        properties: payload["properties"],
+        status: payload["status"],
+        created_on: payload["createdOn"],
+        modified_on: payload["modifiedOn"]
+      )
+    end
+  end
+end

data/lib/nfe/resources/dto/service_invoice.rb

@@ -1,17 +1,33 @@
 # frozen_string_literal: true
 
+require "nfe/resources/dto/service_invoice_borrower"
+
 module Nfe
   # Immutable value object for a service invoice (NFS-e) as returned by the
   # NFE.io +api.nfe.io/v1+ service-invoice API.
   #
-  # The +nf-servico-v1.yaml+ OpenAPI spec defines NO component schemas (the
-  # shape is derived from the operations), so this DTO is hand-written — mirror
-  # of the fields the Node/PHP SDKs read. {from_api} maps the API camelCase keys
-  # onto snake_case members, drops unknown keys, and is nil-tolerant
-  # (+from_api(nil)+ returns +nil+).
+  # The +nf-servico-v1.yaml+ OpenAPI spec declares the retrieve success
+  # response **inline** (no named schema in +components.schemas+ — only the
+  # error model is componentized), so this DTO is hand-written and pinned to
+  # the spec by an alignment test. {from_api} maps the API camelCase keys onto
+  # snake_case members and is nil-tolerant (+from_api(nil)+ returns +nil+).
+  # The full parsed payload is preserved under +raw+ for forward
+  # compatibility — fields without a typed member (the withholding tree,
+  # +provider+, +taxationType+, +location+, +approximateTax+, ...) are
+  # accessible through it.
+  #
+  # +borrower+ is hydrated into {Nfe::ServiceInvoiceBorrower} (typed readers
+  # plus a Hash-compatibility bridge, so +borrower["name"]+ keeps working).
   #
   # +flow_status+ drives the polling lifecycle; pass it to
   # {Nfe::FlowStatus.terminal?} to decide when the document is settled.
+  #
+  # @!attribute [r] pdf
+  #   @deprecated Ghost field — the retrieve response carries no +pdf+ key
+  #     (always +nil+). Use {Nfe::Resources::ServiceInvoices#download_pdf}.
+  # @!attribute [r] xml
+  #   @deprecated Ghost field — the retrieve response carries no +xml+ key
+  #     (always +nil+). Use {Nfe::Resources::ServiceInvoices#download_xml}.
   class ServiceInvoice < Data.define(
     :id,
     :flow_status,
@@ -33,12 +49,17 @@ module Nfe
     :pdf,
     :xml,
     :created_on,
-    :modified_on
+    :modified_on,
+    :base_tax_amount,
+    :iss_rate,
+    :iss_tax_amount,
+    :raw
   )
     # Build a {Nfe::ServiceInvoice} from an API payload.
     #
     # @param payload [Hash, nil] the response object.
     # @return [Nfe::ServiceInvoice, nil] +nil+ when +payload+ is +nil+.
+    # rubocop:disable Metrics/MethodLength, Metrics/AbcSize -- wide value-object mapping kept inline for Steep keyword-arg verification
     def self.from_api(payload)
       return nil if payload.nil?
 
@@ -56,15 +77,20 @@ module Nfe
         cancelled_on: payload["cancelledOn"],
         amount_net: payload["amountNet"],
         services_amount: payload["servicesAmount"],
-        borrower: payload["borrower"],
+        borrower: ServiceInvoiceBorrower.from_api(payload["borrower"]),
         city_service_code: payload["cityServiceCode"],
         federal_service_code: payload["federalServiceCode"],
         description: payload["description"],
         pdf: payload["pdf"],
         xml: payload["xml"],
         created_on: payload["createdOn"],
-        modified_on: payload["modifiedOn"]
+        modified_on: payload["modifiedOn"],
+        base_tax_amount: payload["baseTaxAmount"],
+        iss_rate: payload["issRate"],
+        iss_tax_amount: payload["issTaxAmount"],
+        raw: payload
       )
     end
+    # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
   end
 end

data/lib/nfe/resources/dto/service_invoice_borrower.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "nfe/resources/dto/company"
+
+module Nfe
+  # Immutable value object for the borrower (tomador) of a service invoice,
+  # as embedded in the NFS-e retrieve response (+nf-servico-v1.yaml+, inline
+  # schema of +GET /v1/companies/{company_id}/serviceinvoices/{id}+).
+  #
+  # +federal_tax_number+ is normalized to +String+ via {Nfe::Company.stringify}:
+  # the spec declares it +integer int64+, but the alphanumeric CNPJ
+  # (IN RFB 2.229/2024) requires string tolerance — deliberate deviation,
+  # pinned by the alignment test. +address+ stays a raw +Hash+.
+  #
+  # Hash-compatibility bridge: before this DTO existed, +invoice.borrower+
+  # returned the raw wire +Hash+ — {#[]} and {#dig} delegate to {#raw} so
+  # +borrower["name"]+ keeps working alongside the typed readers.
+  class ServiceInvoiceBorrower < Data.define(
+    :id,
+    :name,
+    :federal_tax_number,
+    :email,
+    :phone_number,
+    :address,
+    :parent_id,
+    :raw
+  )
+    # Build a {Nfe::ServiceInvoiceBorrower} from an API payload.
+    #
+    # @param payload [Hash, nil] the borrower object from the wire.
+    # @return [Nfe::ServiceInvoiceBorrower, nil] +nil+ when +payload+ is +nil+.
+    def self.from_api(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        name: payload["name"],
+        federal_tax_number: Company.stringify(payload["federalTaxNumber"]),
+        email: payload["email"],
+        phone_number: payload["phoneNumber"],
+        address: payload["address"],
+        parent_id: payload["parentId"],
+        raw: payload
+      )
+    end
+
+    # Hash-style read, delegated to the raw wire payload (camelCase keys),
+    # e.g. +borrower["federalTaxNumber"]+ returns the wire value untouched.
+    def [](key)
+      raw && raw[key]
+    end
+
+    # Hash-style nested read over the raw wire payload,
+    # e.g. +borrower.dig("address", "city", "name")+.
+    def dig(*keys)
+      raw&.dig(*keys)
+    end
+  end
+end

data/lib/nfe/resources/dto/webhook.rb

@@ -13,6 +13,12 @@ module Nfe
   #
   # {from_api} maps API camelCase onto snake_case, drops unknown keys, and is
   # nil-tolerant (+from_api(nil)+ returns +nil+).
+  #
+  # @deprecated This shape (+url+/+events+/+active+) is rejected by the live
+  #   API (+400 "The Uri field is required"+), and the company-scoped route
+  #   that would return it responds 404 (confirmed on three accounts,
+  #   2026-07-02/03). Use {Nfe::AccountWebhook} with the account-scoped
+  #   methods on {Nfe::Resources::Webhooks}.
   class WebhookSubscription < Data.define(
     :id,
     :url,

data/lib/nfe/resources/webhooks.rb

@@ -2,17 +2,39 @@
 
 require "json"
 require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/account_webhook"
 require "nfe/resources/dto/webhook"
 require "nfe/webhook"
 
 module Nfe
   module Resources
-    # Webhooks resource, company-scoped under +/companies/{id}/webhooks+ on the
-    # +:main+ host family. Exposes CRUD, a synthetic-delivery +test+, the static
-    # list of available events, and a thin {#verify_signature} delegation to
-    # {Nfe::Webhook} (the canonical signature-verification API is the module).
+    # Webhooks resource on the +:main+ host family.
+    #
+    # Webhooks are managed at the **account** level over +/v2/webhooks+ — use
+    # the +*_account_webhook*+ methods. The live API wraps create/update
+    # requests and single-object responses in a +webHook+ envelope; the SDK
+    # envelopes/unwraps transparently. Contract source of truth:
+    # +openapi/nf-servico-v1.yaml+ plus live probes (2026-07-02/03).
+    #
+    # The company-scoped methods (+list+/+create+/+retrieve+/+update+/
+    # +delete+/+test+ under +/v1/companies/{id}/webhooks+) are deprecated: the
+    # route returns 404 on the current API (confirmed on three accounts,
+    # 2026-07-02/03). They remain, unchanged, until the next major.
+    #
+    # Also exposes a thin {#verify_signature} delegation to {Nfe::Webhook}
+    # (the canonical signature-verification API is the module).
     class Webhooks < AbstractResource
-      # The seven event types the NFE.io API can deliver (parity with Node).
+      # Preserve the inherited HTTP DELETE helper under a private name before
+      # the public company-scoped +delete+ shadows it — the account-scoped
+      # deletes still need the raw verb.
+      alias http_delete delete
+      private :http_delete
+
+      # Legacy static list of event types.
+      #
+      # @deprecated These literals do not exist on the live API — the real
+      #   event types follow +service_invoice.*+/+product_invoice.*+/
+      #   +consumer_invoice.*+ (46 ids live). Use {#fetch_event_types}.
       AVAILABLE_EVENTS = %w[
         invoice.issued
         invoice.cancelled
@@ -29,10 +51,144 @@ module Nfe
         :main
       end
 
+      # Account-scoped endpoints live under +/v2+ on the same +:main+ host,
+      # while the (deprecated) company-scoped ones keep the resource default
+      # +/v1+. A path that already carries an explicit version segment passes
+      # through unprefixed.
+      def full_path(path)
+        path.start_with?("/v2/") ? path : super
+      end
+
       public
 
+      # List the account's webhooks (+GET /v2/webhooks+).
+      #
+      # The API wraps the collection as +{"webHooks": [...]}+; the SDK unwraps
+      # it into an {Nfe::ListResponse} of {Nfe::AccountWebhook}. +secret+ is
+      # omitted on reads.
+      #
+      # @return [Nfe::ListResponse]
+      def list_account_webhooks
+        response = get("/v2/webhooks")
+        hydrate_list(Nfe::AccountWebhook, parse_json(response.body), wrapper_key: "webHooks")
+      end
+
+      # Create an account webhook (+POST /v2/webhooks+).
+      #
+      # The request is wrapped in the mandatory +webHook+ envelope (the API
+      # rejects a bare body with +400 "missing required properties: 'webHook'"+)
+      # and the +201 {"webHook": {...}}+ response is unwrapped.
+      #
+      # NFE.io **pings the +uri+ at creation time and requires a 2xx
+      # response** — the endpoint must already be live, or the create fails.
+      # +secret+ must be 32–64 characters; it is echoed back on create and
+      # omitted on subsequent reads.
+      #
+      # @param data [Hash] webhook attributes in wire (camelCase) keys, e.g.
+      #   +{ uri: "https://...", contentType: "json", secret: "<32-64 chars>",
+      #   filters: ["service_invoice.issued_successfully"], status: "Active" }+.
+      #   Discover valid +filters+ with {#fetch_event_types}.
+      # @return [Nfe::AccountWebhook]
+      def create_account_webhook(data)
+        response = post("/v2/webhooks",
+                        body: json_body({ webHook: data }), headers: json_headers)
+        hydrate_account_webhook(response)
+      end
+
+      # Retrieve an account webhook by id (+GET /v2/webhooks/{id}+).
+      #
+      # Unwraps the +{"webHook": {...}}+ envelope, falling back to the raw
+      # body when the envelope is absent. +secret+ is omitted on reads.
+      #
+      # @param webhook_id [String]
+      # @return [Nfe::AccountWebhook]
+      def retrieve_account_webhook(webhook_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        response = get("/v2/webhooks/#{wid}")
+        hydrate_account_webhook(response)
+      end
+
+      # Update an account webhook (+PUT /v2/webhooks/{id}+), request wrapped
+      # in the +webHook+ envelope.
+      #
+      # @note **+PUT+ is a full replacement** (live-confirmed 2026-07-03):
+      #   omitted fields reset to their defaults — an update without +status+
+      #   **deactivates the webhook**. Always send the complete object,
+      #   starting from a retrieve:
+      #
+      #     current = client.webhooks.retrieve_account_webhook(id)
+      #     client.webhooks.update_account_webhook(id, {
+      #       uri: current.uri,
+      #       contentType: current.content_type,
+      #       status: current.status,            # keep it "Active"!
+      #       filters: ["service_invoice.issued_successfully"]
+      #     })
+      #
+      # @param webhook_id [String]
+      # @param data [Hash] the complete webhook attributes (wire camelCase keys).
+      # @return [Nfe::AccountWebhook]
+      def update_account_webhook(webhook_id, data)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        response = put("/v2/webhooks/#{wid}",
+                       body: json_body({ webHook: data }), headers: json_headers)
+        hydrate_account_webhook(response)
+      end
+
+      # Delete a single account webhook by id (+DELETE /v2/webhooks/{id}+).
+      #
+      # @param webhook_id [String]
+      # @return [nil]
+      def delete_account_webhook(webhook_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        http_delete("/v2/webhooks/#{wid}")
+        nil
+      end
+
+      # ⚠️ DESTRUCTIVE: delete **ALL** of the account's webhooks
+      # (+DELETE /v2/webhooks+). Named distinctly from
+      # {#delete_account_webhook} so it can never be reached by a mistyped
+      # single delete.
+      #
+      # @return [nil]
+      def delete_all_account_webhooks
+        http_delete("/v2/webhooks")
+        nil
+      end
+
+      # Trigger a test ping for an account webhook
+      # (+PUT /v2/webhooks/{id}/pings+, responds 204).
+      #
+      # @param webhook_id [String]
+      # @return [nil]
+      def ping_account_webhook(webhook_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        put("/v2/webhooks/#{wid}/pings", body: json_body({}), headers: json_headers)
+        nil
+      end
+
+      # Fetch the live list of webhook event types
+      # (+GET /v2/webhooks/eventTypes+).
+      #
+      # The API wraps the result as +{"eventTypes": [{ "id": ... }, ...]}+;
+      # this extracts the ids (e.g. +"service_invoice.issued_successfully"+,
+      # +"product_invoice.issued"+ — 46 ids live). Use these as +filters+ when
+      # creating or updating a webhook.
+      #
+      # @return [Array<String>]
+      def fetch_event_types
+        response = get("/v2/webhooks/eventTypes")
+        payload = parse_json(response.body)
+        items = [] #: Array[untyped]
+        items = payload["eventTypes"] || items if payload.is_a?(Hash)
+        items.map { |item| item["id"] }.compact
+      end
+
       # List a company's webhook subscriptions.
       #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#list_account_webhooks}.
+      #
       # @param company_id [String]
       # @return [Nfe::ListResponse]
       def list(company_id)
@@ -45,9 +201,13 @@ module Nfe
 
       # Create a webhook subscription. Accepts +url+, +events+, +secret+, +active+.
       #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#create_account_webhook}.
+      #
       # @param company_id [String]
       # @param data [Hash]
-      # @return [Nfe::Webhook]
+      # @return [Nfe::WebhookSubscription, nil]
       def create(company_id, data)
         id = Nfe::IdValidator.company_id(company_id)
         response = post("/companies/#{id}/webhooks",
@@ -57,9 +217,13 @@ module Nfe
 
       # Retrieve a webhook by id.
       #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#retrieve_account_webhook}.
+      #
       # @param company_id [String]
       # @param webhook_id [String]
-      # @return [Nfe::Webhook]
+      # @return [Nfe::WebhookSubscription, nil]
       def retrieve(company_id, webhook_id)
         id = Nfe::IdValidator.company_id(company_id)
         wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
@@ -69,10 +233,14 @@ module Nfe
 
       # Update a webhook.
       #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#update_account_webhook}.
+      #
       # @param company_id [String]
       # @param webhook_id [String]
       # @param data [Hash]
-      # @return [Nfe::Webhook]
+      # @return [Nfe::WebhookSubscription, nil]
       def update(company_id, webhook_id, data)
         id = Nfe::IdValidator.company_id(company_id)
         wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
@@ -83,6 +251,10 @@ module Nfe
 
       # Delete a webhook.
       #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#delete_account_webhook}.
+      #
       # @param company_id [String]
       # @param webhook_id [String]
       # @return [nil]
@@ -95,6 +267,10 @@ module Nfe
 
       # Trigger a synthetic delivery to verify a webhook is reachable.
       #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#ping_account_webhook}.
+      #
       # @param company_id [String]
       # @param webhook_id [String]
       # @return [Hash] +{ success: bool, message: String? }+.
@@ -107,7 +283,10 @@ module Nfe
         { success: payload["success"] || false, message: payload["message"] }
       end
 
-      # The static list of webhook event types the API can deliver.
+      # The legacy static list of webhook event types.
+      #
+      # @deprecated These literals do not exist on the live API. Use
+      #   {#fetch_event_types} for the real, live list.
       #
       # @return [Array<String>]
       def get_available_events
@@ -124,6 +303,12 @@ module Nfe
 
       private
 
+      # Unwrap a single-object +{"webHook": {...}}+ envelope (raw-body
+      # fallback) and hydrate an {Nfe::AccountWebhook}.
+      def hydrate_account_webhook(response)
+        hydrate(Nfe::AccountWebhook, unwrap(parse_json(response.body), "webHook"))
+      end
+
       def json_headers
         { "Content-Type" => "application/json" }
       end
@@ -133,7 +318,7 @@ module Nfe
       end
 
       # Tolerate either a bare array, a +data+-wrapped list, or a +webhooks+
-      # envelope for the list response.
+      # envelope for the (deprecated) company-scoped list response.
       def webhook_items(payload)
         return payload if payload.is_a?(Array)
         return [] unless payload.is_a?(Hash)

data/lib/nfe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nfe
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/nfe/webhook_event.rb

@@ -4,7 +4,7 @@ module Nfe
   # Immutable value object for a verified webhook delivery, produced by
   # {Nfe::Webhook.construct_event} after the HMAC-SHA1 signature checks out.
   #
-  # - +type+ is the event type (e.g. +"invoice.issued"+), unwrapped from the
+  # - +type+ is the event type (e.g. +"service_invoice.issued_successfully"+), unwrapped from the
   #   delivery envelope's +action+ or +event+ key.
   # - +data+ is the payload +Hash+ (the envelope's +payload+ or +data+ key).
   # - +id+ is a stable event/invoice id for deduplication, or +nil+ when the

data/sig/nfe/generated/nf_servico_v1/errors_resource.rbs

@@ -0,0 +1,16 @@
+# AUTO-GENERATED — do not edit
+# Source: openapi/nf-servico-v1.yaml
+# Hash: sha256:621a3b8e437e5cb37367c8cd26fec93fa2b3f87c9a59252ac987c56bb0c7ba56
+
+module Nfe
+  module Generated
+    module NfServicoV1
+      class ErrorsResource < Data
+        attr_reader errors: Array[Hash[String, untyped]]
+        def self.new: (?errors: Array[Hash[String, untyped]]) -> instance
+        def initialize: (?errors: Array[Hash[String, untyped]]) -> void
+        def self.from_api: (Hash[String, untyped]? payload) -> instance?
+      end
+    end
+  end
+end

data/sig/nfe/resources/dto/account_webhook.rbs

@@ -0,0 +1,21 @@
+module Nfe
+  class AccountWebhook < Data
+    attr_reader id: String?
+    attr_reader uri: String?
+    attr_reader content_type: String?
+    attr_reader secret: String?
+    attr_reader filters: Array[String]?
+    attr_reader insecure_ssl: bool?
+    attr_reader headers: untyped
+    attr_reader properties: untyped
+    attr_reader status: String?
+    attr_reader created_on: String?
+    attr_reader modified_on: String?
+
+    def self.from_api: (Hash[untyped, untyped]? payload) -> Nfe::AccountWebhook?
+
+    def self.new: (id: String?, uri: String?, content_type: String?, secret: String?, filters: Array[String]?, insecure_ssl: bool?, headers: untyped, properties: untyped, status: String?, created_on: String?, modified_on: String?) -> instance
+
+    def initialize: (id: String?, uri: String?, content_type: String?, secret: String?, filters: Array[String]?, insecure_ssl: bool?, headers: untyped, properties: untyped, status: String?, created_on: String?, modified_on: String?) -> void
+  end
+end

data/sig/nfe/resources/dto/service_invoice.rbs

@@ -13,7 +13,7 @@ module Nfe
     attr_reader cancelled_on: String?
     attr_reader amount_net: untyped
     attr_reader services_amount: untyped
-    attr_reader borrower: untyped
+    attr_reader borrower: Nfe::ServiceInvoiceBorrower?
     attr_reader city_service_code: untyped
     attr_reader federal_service_code: untyped
     attr_reader description: String?
@@ -21,10 +21,14 @@ module Nfe
     attr_reader xml: untyped
     attr_reader created_on: String?
     attr_reader modified_on: String?
+    attr_reader base_tax_amount: (Float | Integer)?
+    attr_reader iss_rate: (Float | Integer)?
+    attr_reader iss_tax_amount: (Float | Integer)?
+    attr_reader raw: Hash[untyped, untyped]?
 
     def self.from_api: (Hash[untyped, untyped]? payload) -> Nfe::ServiceInvoice?
 
-    def self.new: (id: String?, flow_status: String?, flow_message: String?, status: untyped, environment: untyped, rps_number: untyped, rps_serial_number: untyped, number: untyped, check_code: String?, issued_on: String?, cancelled_on: String?, amount_net: untyped, services_amount: untyped, borrower: untyped, city_service_code: untyped, federal_service_code: untyped, description: String?, pdf: untyped, xml: untyped, created_on: String?, modified_on: String?) -> instance
-    def initialize: (id: String?, flow_status: String?, flow_message: String?, status: untyped, environment: untyped, rps_number: untyped, rps_serial_number: untyped, number: untyped, check_code: String?, issued_on: String?, cancelled_on: String?, amount_net: untyped, services_amount: untyped, borrower: untyped, city_service_code: untyped, federal_service_code: untyped, description: String?, pdf: untyped, xml: untyped, created_on: String?, modified_on: String?) -> void
+    def self.new: (id: String?, flow_status: String?, flow_message: String?, status: untyped, environment: untyped, rps_number: untyped, rps_serial_number: untyped, number: untyped, check_code: String?, issued_on: String?, cancelled_on: String?, amount_net: untyped, services_amount: untyped, borrower: Nfe::ServiceInvoiceBorrower?, city_service_code: untyped, federal_service_code: untyped, description: String?, pdf: untyped, xml: untyped, created_on: String?, modified_on: String?, base_tax_amount: (Float | Integer)?, iss_rate: (Float | Integer)?, iss_tax_amount: (Float | Integer)?, raw: Hash[untyped, untyped]?) -> instance
+    def initialize: (id: String?, flow_status: String?, flow_message: String?, status: untyped, environment: untyped, rps_number: untyped, rps_serial_number: untyped, number: untyped, check_code: String?, issued_on: String?, cancelled_on: String?, amount_net: untyped, services_amount: untyped, borrower: Nfe::ServiceInvoiceBorrower?, city_service_code: untyped, federal_service_code: untyped, description: String?, pdf: untyped, xml: untyped, created_on: String?, modified_on: String?, base_tax_amount: (Float | Integer)?, iss_rate: (Float | Integer)?, iss_tax_amount: (Float | Integer)?, raw: Hash[untyped, untyped]?) -> void
   end
 end

data/sig/nfe/resources/dto/service_invoice_borrower.rbs

@@ -0,0 +1,21 @@
+module Nfe
+  class ServiceInvoiceBorrower < Data
+    attr_reader id: String?
+    attr_reader name: String?
+    attr_reader federal_tax_number: String?
+    attr_reader email: String?
+    attr_reader phone_number: String?
+    attr_reader address: untyped
+    attr_reader parent_id: String?
+    attr_reader raw: Hash[untyped, untyped]?
+
+    def self.from_api: (Hash[untyped, untyped]? payload) -> Nfe::ServiceInvoiceBorrower?
+
+    def self.new: (id: String?, name: String?, federal_tax_number: String?, email: String?, phone_number: String?, address: untyped, parent_id: String?, raw: Hash[untyped, untyped]?) -> instance
+
+    def initialize: (id: String?, name: String?, federal_tax_number: String?, email: String?, phone_number: String?, address: untyped, parent_id: String?, raw: Hash[untyped, untyped]?) -> void
+
+    def []: (untyped key) -> untyped
+    def dig: (*untyped keys) -> untyped
+  end
+end

data/sig/nfe/resources/webhooks.rbs

@@ -4,6 +4,16 @@ module Nfe
       AVAILABLE_EVENTS: Array[String]
 
       def api_family: () -> Symbol
+      def full_path: (String path) -> String
+
+      def list_account_webhooks: () -> Nfe::ListResponse
+      def create_account_webhook: (Hash[untyped, untyped] data) -> Nfe::AccountWebhook?
+      def retrieve_account_webhook: (String webhook_id) -> Nfe::AccountWebhook?
+      def update_account_webhook: (String webhook_id, Hash[untyped, untyped] data) -> Nfe::AccountWebhook?
+      def delete_account_webhook: (String webhook_id) -> nil
+      def delete_all_account_webhooks: () -> nil
+      def ping_account_webhook: (String webhook_id) -> nil
+      def fetch_event_types: () -> Array[String]
 
       def list: (String company_id) -> Nfe::ListResponse
       def create: (String company_id, Hash[untyped, untyped] data) -> Nfe::WebhookSubscription?
@@ -16,6 +26,8 @@ module Nfe
 
       private
 
+      def http_delete: (String path, ?query: Hash[untyped, untyped], ?request_options: Nfe::RequestOptions?, ?headers: Hash[String, String]) -> Nfe::Http::Response
+      def hydrate_account_webhook: (Nfe::Http::Response response) -> Nfe::AccountWebhook?
       def json_headers: () -> Hash[String, String]
       def json_body: (untyped data) -> String
       def webhook_items: (untyped payload) -> Array[untyped]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nfe-io
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - NFE.io Team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -505,6 +505,7 @@ files:
 - lib/nfe/generated/nf_produto_v2/vehicle_detail_resource.rb
 - lib/nfe/generated/nf_produto_v2/volume_resource.rb
 - lib/nfe/generated/nf_produto_v2/withdrawal_information_resource.rb
+- lib/nfe/generated/nf_servico_v1/errors_resource.rb
 - lib/nfe/generated/nfeio/batch_process_response.rb
 - lib/nfe/generated/nfeio/environment.rb
 - lib/nfe/generated/nfeio/file_parsing_options_request.rb
@@ -710,6 +711,7 @@ files:
 - lib/nfe/resources/companies.rb
 - lib/nfe/resources/consumer_invoice_query.rb
 - lib/nfe/resources/consumer_invoices.rb
+- lib/nfe/resources/dto/account_webhook.rb
 - lib/nfe/resources/dto/addresses/address_lookup_response.rb
 - lib/nfe/resources/dto/company.rb
 - lib/nfe/resources/dto/consumer_invoice.rb
@@ -726,6 +728,7 @@ files:
 - lib/nfe/resources/dto/product_invoice_query/product_invoice_details.rb
 - lib/nfe/resources/dto/product_invoice_query/product_invoice_events_response.rb
 - lib/nfe/resources/dto/service_invoice.rb
+- lib/nfe/resources/dto/service_invoice_borrower.rb
 - lib/nfe/resources/dto/state_taxes/nfe_state_tax.rb
 - lib/nfe/resources/dto/tax_codes/tax_code_paginated_response.rb
 - lib/nfe/resources/dto/webhook.rb
@@ -1126,6 +1129,7 @@ files:
 - sig/nfe/generated/nf_produto_v2/vehicle_detail_resource.rbs
 - sig/nfe/generated/nf_produto_v2/volume_resource.rbs
 - sig/nfe/generated/nf_produto_v2/withdrawal_information_resource.rbs
+- sig/nfe/generated/nf_servico_v1/errors_resource.rbs
 - sig/nfe/generated/nfeio/batch_process_response.rbs
 - sig/nfe/generated/nfeio/environment.rbs
 - sig/nfe/generated/nfeio/file_parsing_options_request.rbs
@@ -1333,6 +1337,7 @@ files:
 - sig/nfe/resources/consumer_invoice_pending.rbs
 - sig/nfe/resources/consumer_invoice_query.rbs
 - sig/nfe/resources/consumer_invoices.rbs
+- sig/nfe/resources/dto/account_webhook.rbs
 - sig/nfe/resources/dto/addresses/address_lookup_response.rbs
 - sig/nfe/resources/dto/company.rbs
 - sig/nfe/resources/dto/consumer_invoice.rbs
@@ -1349,6 +1354,7 @@ files:
 - sig/nfe/resources/dto/product_invoice_query/product_invoice_details.rbs
 - sig/nfe/resources/dto/product_invoice_query/product_invoice_events_response.rbs
 - sig/nfe/resources/dto/service_invoice.rbs
+- sig/nfe/resources/dto/service_invoice_borrower.rbs
 - sig/nfe/resources/dto/state_taxes/nfe_state_tax.rbs
 - sig/nfe/resources/dto/tax_codes/tax_code_paginated_response.rbs
 - sig/nfe/resources/dto/webhook.rbs