Class: Integrobr::NfseSdk::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/integrobr/nfse_sdk/client.rb

Overview

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

Constant Summary collapse

BASE_URL_PADRAO = 
"https://api.recebidas.integrobr.com/api"

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, base_url: BASE_URL_PADRAO, timeout: 30, transporte: nil) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String) —

    chave de API — ibr_live_... (produção) ou ibr_test_... (sandbox).

  • base_url (String) (defaults to: BASE_URL_PADRAO) —

    sobrescreve a URL base — usado só em testes/desenvolvimento.

  • timeout (Integer) (defaults to: 30) —

    timeout por requisição, em segundos.

  • transporte (#call, nil) (defaults to: nil) —

    função de transporte HTTP customizada — usada em testes.

Raises:

  • (ArgumentError) 


20
21
22
23
24
25
26
27
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 20

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

Instance Method Details

#criar_empresa(dados) ⇒ Object

POST /v1/companies — cadastra um CNPJ para monitoramento.

Parameters:

  • dados (Hash) —

    cnpj (obrigatório), nomeExibicao, nsuInicial.



51
52
53
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 51

def criar_empresa(dados)
  requisitar(:post, "/v1/companies", corpo: dados)
end

#enviar_certificado(id, caminho_arquivo, senha) ⇒ Object

POST /v1/companies/id/certificate — envia (ou troca) o certificado A1 (.pfx/.p12, até 10MB).



56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 56

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

#listar_documentos(filtros = {}) ⇒ Object

GET /v1/documents — uma página de notas. Use paginar_documentos pra percorrer tudo.

Parameters:

  • filtros (Hash) (defaults to: {}) —

    cnpjs (String ou Array), situacao, papel, prestador, numero, chaveAcesso, valorMinCentavos, valorMaxCentavos, dataInicio, dataFim, cursor, limite.



87
88
89
90
91
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 87

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

#listar_empresas ⇒ Object

GET /v1/companies — todas as empresas do ambiente da chave usada. Não é paginado.



40
41
42
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 40

def listar_empresas
  requisitar(:get, "/v1/companies")
end

#obter_consumo ⇒ Object

GET /v1/usage — franquia, consumo e excedente do ciclo em andamento.



35
36
37
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 35

def obter_consumo
  requisitar(:get, "/v1/usage")
end

#obter_conta ⇒ Object

GET /v1/account — identifica a conta dona da chave de API usada.



30
31
32
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 30

def obter_conta
  requisitar(:get, "/v1/account")
end

#obter_documento(id) ⇒ Object

GET /v1/documents/id — inclui XML original e linha do tempo de eventos.



94
95
96
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 94

def obter_documento(id)
  requisitar(:get, "/v1/documents/#{URI.encode_www_form_component(id)}")
end

#obter_empresa(id) ⇒ Object

GET /v1/companies/id



45
46
47
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 45

def obter_empresa(id)
  requisitar(:get, "/v1/companies/#{URI.encode_www_form_component(id)}")
end

#paginar_documentos(filtros = {}) ⇒ Object

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.



104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 104

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

#pausar_empresa(id) ⇒ Object

POST /v1/companies/id/pause



70
71
72
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 70

def pausar_empresa(id)
  requisitar(:post, "/v1/companies/#{URI.encode_www_form_component(id)}/pause")
end

#remover_empresa(id) ⇒ Object

DELETE /v1/companies/id — solicita a remoção (primeiro passo; a confirmação é feita pelo painel).



80
81
82
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 80

def remover_empresa(id)
  requisitar(:delete, "/v1/companies/#{URI.encode_www_form_component(id)}")
end

#retomar_empresa(id) ⇒ Object

POST /v1/companies/id/resume



75
76
77
 
# File 'lib/integrobr/nfse_sdk/client.rb', line 75

def retomar_empresa(id)
  requisitar(:post, "/v1/companies/#{URI.encode_www_form_component(id)}/resume")
end