integrobr-nfse-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d5ce01ddd63d8629587a1e7e49bf4f307cb5e8ed991f800345c3ed13e32d2fe
+  data.tar.gz: 7ab74b036735f42de1255ab46d251e69632f7ed904619c7e823ef69069280dd7
+SHA512:
+  metadata.gz: c971c00d7dd4b142a548eec6b17526498c0ccbe7a28e2a56fbe95fa3faa746fc754d73145f6724189a30ca3175814a9400b909cc06ab1356ccdbf81879001d26
+  data.tar.gz: 678dedc9c72cc7b01585043e56c9a9e7e0a36fb9b81ff012b6342a8f93723b27c49321cbe6b1cf1c5b5e281e966e8b0178044ef48782ba85c51f239e027bd674

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Integrobr Softwares LTDA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,158 @@
+# integrobr-nfse-sdk (Ruby)
+
+Cliente oficial Ruby para a [API pública do IntegroBR NFS-e Recebidas](https://recebidas.integrobr.com/docs) — consulte e gerencie, de forma programática, as NFS-e (notas de serviço) monitoradas pela sua conta IntegroBR.
+
+- Documentação completa da API: **https://recebidas.integrobr.com/docs**
+- Requer Ruby **3.0+**. Usa só `net/http` da stdlib — sem dependências de runtime.
+
+## Instalação
+
+```bash
+gem install integrobr-nfse-sdk
+```
+
+Ou no `Gemfile`:
+
+```ruby
+gem "integrobr-nfse-sdk"
+```
+
+## Uso rápido
+
+```ruby
+require "integrobr/nfse_sdk"
+
+client = Integrobr::NfseSdk::Client.new(api_key: ENV.fetch("INTEGROBR_API_KEY"))
+
+conta = client.obter_conta
+puts "#{conta['nome']} #{conta['ambiente']}" # "Empresa Exemplo LTDA PRODUCAO"
+
+empresas = client.listar_empresas
+notas = client.listar_documentos(situacao: "AUTORIZADA", limite: 50)
+```
+
+Gere uma chave em **Painel → Chaves de API** (`/painel/chaves-api`). Ela só é exibida uma vez — se perder, revogue e crie outra. Existem dois ambientes de chave, que nunca se misturam:
+
+| Prefixo | Ambiente |
+|---|---|
+| `ibr_test_...` | Sandbox — dados de teste, nunca reais, nunca geram cobrança. |
+| `ibr_live_...` | Produção — dados fiscais reais da sua conta. |
+
+## Empresas (CNPJs monitorados)
+
+```ruby
+# Listar (GET /companies não é paginado)
+empresas = client.listar_empresas
+
+# Cadastrar um CNPJ novo
+empresa = client.criar_empresa(cnpj: "12345678000195", nomeExibicao: "Filial São Paulo")
+
+# Enviar o certificado A1 (.pfx/.p12)
+client.enviar_certificado(empresa["id"], "/caminho/para/certificado.pfx", "senha-do-certificado")
+
+# Pausar / retomar
+client.pausar_empresa(empresa["id"])
+client.retomar_empresa(empresa["id"])
+
+# Solicitar remoção (primeiro passo — a confirmação final é feita pelo painel)
+client.remover_empresa(empresa["id"])
+```
+
+## Documentos (notas fiscais)
+
+`GET /documents` usa paginação por cursor — passe `proximoCursor` de volta em `cursor` na próxima chamada:
+
+```ruby
+cursor = nil
+loop do
+  pagina = client.listar_documentos(cursor: cursor, limite: 100)
+  pagina["itens"].each do |nota|
+    puts "#{nota['numero']} #{nota['valorServicos']} #{nota['situacao']}"
+  end
+  break if pagina["proximoCursor"].nil?
+  cursor = pagina["proximoCursor"]
+end
+```
+
+Ou use `paginar_documentos`, que faz esse loop por você (com bloco, ou devolve um `Enumerator` sem bloco):
+
+```ruby
+client.paginar_documentos(situacao: "AUTORIZADA") do |nota|
+  puts nota["numero"]
+end
+
+# ou, como Enumerator:
+primeiras_10 = client.paginar_documentos.first(10)
+```
+
+Detalhe de uma nota (inclui XML original e linha do tempo de eventos):
+
+```ruby
+detalhe = client.obter_documento(nota["id"])
+pp detalhe["eventos"]
+```
+
+## Consumo do ciclo atual
+
+```ruby
+consumo = client.obter_consumo
+if consumo["temCicloAtivo"]
+  puts "#{consumo['eventosIncluidos']}/#{consumo['franquiaEventos']} eventos usados neste ciclo"
+end
+```
+
+## Tratamento de erros
+
+Toda chamada que falha levanta `Integrobr::NfseSdk::ApiError`, com `status_code`, `mensagens` (sempre um array, mesmo quando a API devolve uma string única) e predicados pros casos mais comuns:
+
+```ruby
+begin
+  client.obter_empresa("id-que-nao-existe")
+rescue Integrobr::NfseSdk::ApiError => e
+  if e.nao_encontrado?
+    # 404 — não existe nesta conta, ou existe só no outro ambiente (sandbox/produção)
+  end
+  if e.rate_limited?
+    # 429 — 120 requisições/minuto por chave; espere e tente de novo
+  end
+  warn "#{e.status_code}: #{e.mensagens.join(' ')}"
+end
+```
+
+## Webhooks
+
+Configure webhooks pelo painel (**Painel → Webhooks**) pra ser avisado em tempo real (`NOTA_RECEBIDA`, `EVENTO_FISCAL_RECEBIDO`) em vez de ficar consultando `GET /documents`. Cada entrega assina o corpo com HMAC-SHA256 no cabeçalho `X-IntegroBR-Signature` — **sempre verifique antes de confiar no payload**:
+
+```ruby
+require "integrobr/nfse_sdk"
+
+# Exemplo com Sinatra — o importante é ler o corpo BRUTO, não decodificado
+post "/webhooks/integrobr" do
+  corpo_bruto = request.body.read
+  assinatura = request.env["HTTP_X_INTEGROBR_SIGNATURE"] || ""
+
+  valido = Integrobr::NfseSdk::Webhooks.verificar_assinatura(corpo_bruto, assinatura, ENV.fetch("INTEGROBR_WEBHOOK_SECRET"))
+  halt 401, "assinatura inválida" unless valido
+
+  payload = JSON.parse(corpo_bruto)
+  puts payload["tipo"]
+  status 200
+end
+```
+
+O segredo do webhook só é exibido uma vez, na criação (ou ao rotacionar) — guarde com o mesmo cuidado de uma senha.
+
+## Limite de requisições
+
+120 requisições por minuto, por chave de API (janela fixa de 60s). Passar do limite devolve `429`, exposto como `e.rate_limited?`.
+
+## Desenvolvimento
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Licença
+
+MIT — veja [LICENSE](./LICENSE).

data/lib/integrobr/nfse_sdk/client.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Integrobr
+  module NfseSdk
+    # Cliente oficial da API pública do IntegroBR NFS-e Recebidas.
+    #
+    #   client = Integrobr::NfseSdk::Client.new(api_key: ENV.fetch("INTEGROBR_API_KEY"))
+    #   empresas = client.listar_empresas
+    class Client
+      BASE_URL_PADRAO = "https://api.recebidas.integrobr.com/api"
+
+      # @param api_key [String] chave de API — `ibr_live_...` (produção) ou `ibr_test_...` (sandbox).
+      # @param base_url [String] sobrescreve a URL base — usado só em testes/desenvolvimento.
+      # @param timeout [Integer] timeout por requisição, em segundos.
+      # @param transporte [#call, nil] função de transporte HTTP customizada — usada em testes.
+      def initialize(api_key:, base_url: BASE_URL_PADRAO, timeout: 30, transporte: nil)
+        raise ArgumentError, "api_key é obrigatório" if api_key.nil? || api_key.empty?
+
+        @api_key = api_key
+        @base_url = base_url
+        @timeout = timeout
+        @transporte = transporte || method(:transporte_padrao)
+      end
+
+      # GET /v1/account — identifica a conta dona da chave de API usada.
+      def obter_conta
+        requisitar(:get, "/v1/account")
+      end
+
+      # GET /v1/usage — franquia, consumo e excedente do ciclo em andamento.
+      def obter_consumo
+        requisitar(:get, "/v1/usage")
+      end
+
+      # GET /v1/companies — todas as empresas do ambiente da chave usada. Não é paginado.
+      def listar_empresas
+        requisitar(:get, "/v1/companies")
+      end
+
+      # GET /v1/companies/{id}
+      def obter_empresa(id)
+        requisitar(:get, "/v1/companies/#{URI.encode_www_form_component(id)}")
+      end
+
+      # POST /v1/companies — cadastra um CNPJ para monitoramento.
+      # @param dados [Hash] cnpj (obrigatório), nomeExibicao, nsuInicial.
+      def criar_empresa(dados)
+        requisitar(:post, "/v1/companies", corpo: dados)
+      end
+
+      # POST /v1/companies/{id}/certificate — envia (ou troca) o certificado A1 (.pfx/.p12, até 10MB).
+      def enviar_certificado(id, caminho_arquivo, senha)
+        raise ArgumentError, "arquivo de certificado não encontrado ou sem permissão de leitura: #{caminho_arquivo}" unless File.readable?(caminho_arquivo)
+
+        arquivo = File.open(caminho_arquivo, "rb")
+        multipart = [
+          ["certificado", arquivo, { filename: File.basename(caminho_arquivo) }],
+          ["senha", senha],
+        ]
+        requisitar(:post, "/v1/companies/#{URI.encode_www_form_component(id)}/certificate", multipart: multipart)
+      ensure
+        arquivo&.close
+      end
+
+      # POST /v1/companies/{id}/pause
+      def pausar_empresa(id)
+        requisitar(:post, "/v1/companies/#{URI.encode_www_form_component(id)}/pause")
+      end
+
+      # POST /v1/companies/{id}/resume
+      def retomar_empresa(id)
+        requisitar(:post, "/v1/companies/#{URI.encode_www_form_component(id)}/resume")
+      end
+
+      # DELETE /v1/companies/{id} — solicita a remoção (primeiro passo; a confirmação é feita pelo painel).
+      def remover_empresa(id)
+        requisitar(:delete, "/v1/companies/#{URI.encode_www_form_component(id)}")
+      end
+
+      # GET /v1/documents — uma página de notas. Use `paginar_documentos` pra percorrer tudo.
+      # @param filtros [Hash] cnpjs (String ou Array), situacao, papel, prestador, numero,
+      #   chaveAcesso, valorMinCentavos, valorMaxCentavos, dataInicio, dataFim, cursor, limite.
+      def listar_documentos(filtros = {})
+        filtros = filtros.dup
+        filtros[:cnpjs] = filtros[:cnpjs].join(",") if filtros[:cnpjs].is_a?(Array)
+        requisitar(:get, "/v1/documents", query: filtros)
+      end
+
+      # GET /v1/documents/{id} — inclui XML original e linha do tempo de eventos.
+      def obter_documento(id)
+        requisitar(:get, "/v1/documents/#{URI.encode_www_form_component(id)}")
+      end
+
+      # Percorre todas as páginas automaticamente, seguindo `proximoCursor` até
+      # ele vir vazio/nil. Sem bloco, devolve um Enumerator (dá pra usar
+      # `.lazy`, `.first(n)` etc). Útil pra sincronizações completas — pra
+      # volumes grandes, prefira filtrar por `dataInicio`/`dataFim` e usar
+      # webhooks pra novidades em tempo real, em vez de repetir isso com
+      # frequência.
+      def paginar_documentos(filtros = {})
+        return enum_for(:paginar_documentos, filtros) unless block_given?
+
+        cursor = filtros[:cursor]
+        loop do
+          pagina = listar_documentos(filtros.merge(cursor: cursor))
+          pagina["itens"].each { |item| yield item }
+          break if pagina["proximoCursor"].nil? || pagina["proximoCursor"].to_s.empty?
+
+          cursor = pagina["proximoCursor"]
+        end
+      end
+
+      private
+
+      def requisitar(metodo, caminho, query: {}, corpo: nil, multipart: nil)
+        query = query.compact
+        url = "#{@base_url}#{caminho}"
+        url += "?#{URI.encode_www_form(query)}" unless query.empty?
+
+        headers = { "Authorization" => "Bearer #{@api_key}" }
+        corpo_para_enviar = nil
+
+        if multipart
+          corpo_para_enviar = nil
+        elsif corpo
+          headers["Content-Type"] = "application/json"
+          corpo_para_enviar = JSON.generate(corpo)
+        end
+
+        resultado = @transporte.call(metodo, url, headers, corpo_para_enviar, multipart)
+        status = resultado[:status]
+        body = resultado[:body]
+
+        return nil if status == 204 || body.nil? || body.empty?
+
+        dados = JSON.parse(body)
+
+        if status < 200 || status >= 300
+          mensagem = dados["message"] || "Erro desconhecido."
+          raise ApiError.new(status, mensagem, dados["error"])
+        end
+
+        dados
+      end
+
+      def transporte_padrao(metodo, url, headers, corpo, multipart)
+        uri = URI(url)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: @timeout) do |http|
+          request = montar_requisicao(metodo, uri, headers, corpo, multipart)
+          resposta = http.request(request)
+          { status: resposta.code.to_i, body: resposta.body }
+        end
+      end
+
+      def montar_requisicao(metodo, uri, headers, corpo, multipart)
+        request = case metodo
+                  when :get then Net::HTTP::Get.new(uri)
+                  when :post then Net::HTTP::Post.new(uri)
+                  when :delete then Net::HTTP::Delete.new(uri)
+                  else raise ArgumentError, "método não suportado: #{metodo}"
+                  end
+        headers.each { |k, v| request[k] = v }
+
+        if multipart
+          request.set_form(multipart, "multipart/form-data")
+        elsif corpo
+          request.body = corpo
+        end
+
+        request
+      end
+    end
+  end
+end

data/lib/integrobr/nfse_sdk/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Integrobr
+  module NfseSdk
+    # Erro devolvido pela API pública do IntegroBR — sempre no formato
+    # `{ statusCode, message, error }`, onde `message` pode ser uma string
+    # única ou uma lista (um item por campo inválido, em erros 400).
+    class ApiError < StandardError
+      attr_reader :status_code, :mensagens, :erro_tipo
+
+      def initialize(status_code, mensagem, erro_tipo = nil)
+        @status_code = status_code
+        @mensagens = mensagem.is_a?(Array) ? mensagem : [mensagem]
+        @erro_tipo = erro_tipo
+        super(@mensagens.join(" "))
+      end
+
+      # 429 — limite de 120 requisições/minuto por chave excedido.
+      def rate_limited?
+        status_code == 429
+      end
+
+      # 401 — chave ausente, inválida ou revogada.
+      def nao_autenticado?
+        status_code == 401
+      end
+
+      # 404 — cobre tanto "não existe" quanto "existe, mas no outro
+      # ambiente (sandbox/produção)" da mesma conta.
+      def nao_encontrado?
+        status_code == 404
+      end
+    end
+  end
+end

data/lib/integrobr/nfse_sdk/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Integrobr
+  module NfseSdk
+    VERSION = "1.0.0"
+  end
+end

data/lib/integrobr/nfse_sdk/webhooks.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Integrobr
+  module NfseSdk
+    module Webhooks
+      module_function
+
+      # Verifica a assinatura HMAC-SHA256 (cabeçalho `X-IntegroBR-Signature`)
+      # de uma entrega de webhook, comparando em tempo constante pra evitar
+      # ataques de timing.
+      #
+      # @param corpo_bruto [String] corpo bruto exatamente como recebido —
+      #   não o objeto já parseado, já que reserializar JSON pode mudar a
+      #   ordem/espaçamento e invalidar a assinatura.
+      # @param assinatura_recebida [String] valor do cabeçalho `X-IntegroBR-Signature`.
+      # @param segredo [String] segredo do webhook, obtido na criação (ou
+      #   rotação) dele pelo painel — só é exibido uma vez.
+      # @return [Boolean]
+      def verificar_assinatura(corpo_bruto, assinatura_recebida, segredo)
+        esperada = OpenSSL::HMAC.hexdigest("SHA256", segredo, corpo_bruto)
+        comparar_tempo_constante(esperada, assinatura_recebida)
+      end
+
+      # @return [Boolean]
+      def comparar_tempo_constante(a, b)
+        return false unless a.is_a?(String) && b.is_a?(String)
+        return false unless a.bytesize == b.bytesize
+
+        resultado = 0
+        a.bytes.zip(b.bytes) { |x, y| resultado |= x ^ y }
+        resultado.zero?
+      end
+    end
+  end
+end

data/lib/integrobr/nfse_sdk.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "nfse_sdk/version"
+require_relative "nfse_sdk/errors"
+require_relative "nfse_sdk/webhooks"
+require_relative "nfse_sdk/client"
+
+module Integrobr
+  module NfseSdk
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: integrobr-nfse-sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- IntegroBR
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Consulte e gerencie, de forma programática, as NFS-e (notas de serviço)
+  monitoradas pela sua conta IntegroBR — as mesmas empresas e documentos que aparecem
+  no painel.
+email:
+- comercial@integrobr.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/integrobr/nfse_sdk.rb
+- lib/integrobr/nfse_sdk/client.rb
+- lib/integrobr/nfse_sdk/errors.rb
+- lib/integrobr/nfse_sdk/version.rb
+- lib/integrobr/nfse_sdk/webhooks.rb
+homepage: https://recebidas.integrobr.com/docs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://recebidas.integrobr.com/docs
+  source_code_uri: https://github.com/integrobr/integrobr-sdk-ruby
+  changelog_uri: https://github.com/integrobr/integrobr-sdk-ruby/releases
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Cliente oficial Ruby para a API pública do IntegroBR NFS-e Recebidas
+test_files: []