emissaoja 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,54 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Emissaoja
4
+ # Erro da API do emissaoja ou do próprio cliente (rede, tempo esgotado, chave ausente, referência inválida).
5
+ #
6
+ # Decida pelo +code+ (a lista fechada da API, em snake_case), nunca pelo texto da mensagem:
7
+ #
8
+ # begin
9
+ # ej.notas.emitir("pedido-0001", tomador_tipo: "pj", tomador_id: id, valor: 1500)
10
+ # rescue Emissaoja::Erro => e
11
+ # e.status # 422 (HTTP; 0 quando o erro é local, de rede ou de tempo)
12
+ # e.code # "nota_bloqueada"
13
+ # e.message # "Antes de emitir, resolva:"
14
+ # e.bloqueios # [{"code" => "tomador_incompleto", "mensagem" => "...", "acao" => "completar_tomador"}]
15
+ # e.extras # os demais campos do corpo: bloqueios, nota_igual_recente, pedido_id, retry_after...
16
+ # e.request_id # cabeçalho x-request-id da resposta, para falar com o suporte
17
+ # end
18
+ class Erro < StandardError
19
+ # @return [Integer] status HTTP; 0 para erro local, falha de rede ou tempo esgotado
20
+ attr_reader :status
21
+
22
+ # @return [String] código da lista fechada da API (ex.: "chave_invalida", "nota_bloqueada", "limite_notas");
23
+ # "erro_desconhecido" quando a resposta não traz um
24
+ attr_reader :code
25
+
26
+ # @return [Hash{String => Object}] os outros campos do corpo do erro (tudo menos status, code e message)
27
+ attr_reader :extras
28
+
29
+ # @return [String, nil] valor do cabeçalho x-request-id da resposta
30
+ attr_reader :request_id
31
+
32
+ # @param status [Integer] status HTTP (0 para erro local, de rede ou de tempo)
33
+ # @param corpo [Hash, nil] corpo do erro, como {"code" => ..., "message" => ...}; chaves String ou Symbol
34
+ # @param request_id [String, nil] cabeçalho x-request-id
35
+ def initialize(status, corpo = nil, request_id: nil)
36
+ dados = corpo.is_a?(Hash) ? corpo.transform_keys(&:to_s) : {}
37
+ mensagem = dados["message"].to_s
38
+ super(mensagem.empty? ? "HTTP #{status}" : mensagem)
39
+ @status = status.to_i
40
+ codigo = dados["code"].to_s
41
+ @code = codigo.empty? ? "erro_desconhecido" : codigo
42
+ @extras = dados.reject { |campo, _| %w[status message code].include?(campo) }
43
+ @request_id = request_id
44
+ end
45
+
46
+ # Os bloqueios de um 422 nota_bloqueada, cada um com "code", "mensagem" e "acao" (o que falta no cadastro).
47
+ # Vazio nos outros erros.
48
+ # @return [Array<Hash{String => String}>]
49
+ def bloqueios
50
+ lista = extras["bloqueios"]
51
+ lista.is_a?(Array) ? lista : []
52
+ end
53
+ end
54
+ end
@@ -0,0 +1,43 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Emissaoja
4
+ # Os recursos da API, acessados pelo cliente: ej.empresa, ej.tomadores, ej.servicos, ej.notas, ej.emissoes,
5
+ # ej.operacoes e ej.cnpj.
6
+ module Recursos
7
+ # Base comum dos recursos: guarda o cliente e os auxiliares de chamada, de caminho e de espera.
8
+ class Base
9
+ # @param cliente [Cliente]
10
+ def initialize(cliente)
11
+ @cliente = cliente
12
+ end
13
+
14
+ private
15
+
16
+ def json(metodo, caminho, corpo: nil, query: nil, cabecalhos: nil)
17
+ @cliente.requisitar_json(metodo, caminho, corpo: corpo, query: query, cabecalhos: cabecalhos)
18
+ end
19
+
20
+ def bytes(caminho)
21
+ @cliente.requisitar_bytes(caminho)
22
+ end
23
+
24
+ # Codifica um segmento do caminho (RFC 3986, mesma regra de ERB::Util.url_encode): letras, números, "-",
25
+ # ".", "_" e "~" passam; o resto vira %XX dos bytes UTF-8. Espaço vira %20 (nunca "+") e "/" vira %2F.
26
+ def segmento(valor)
27
+ valor.to_s.b.gsub(/[^A-Za-z0-9_.~-]/n) { |byte| format("%%%02X", byte.ord) }
28
+ end
29
+
30
+ def agora
31
+ Process.clock_gettime(Process::CLOCK_MONOTONIC)
32
+ end
33
+
34
+ def esperar(segundos)
35
+ @cliente.esperar(segundos)
36
+ end
37
+
38
+ def tempo_esgotado(mensagem, extras = {})
39
+ Erro.new(0, { "code" => "tempo_esgotado", "message" => mensagem }.merge(extras))
40
+ end
41
+ end
42
+ end
43
+ end
@@ -0,0 +1,17 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Emissaoja
4
+ module Recursos
5
+ # Consulta de CNPJ nos dados cadastrais da Receita Federal. Não cria tomador: serve para conferir antes de
6
+ # cadastrar (ej.tomadores.criar já preenche pelo CNPJ).
7
+ class Cnpj < Base
8
+ # GET /v1/cnpj/{cnpj}: razão social, situação cadastral, CNAEs, endereço, Simples, MEI e sócios (CPF mascarado).
9
+ # Aceita o CNPJ com ou sem máscara: pontos, barra, hífen e espaços saem antes da chamada.
10
+ # @param cnpj [String]
11
+ # @return [Hash]
12
+ def consultar(cnpj)
13
+ json("GET", "/v1/cnpj/#{segmento(cnpj.to_s.gsub(/[^0-9A-Za-z]/, "").upcase)}")
14
+ end
15
+ end
16
+ end
17
+ end
@@ -0,0 +1,30 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Emissaoja
4
+ module Recursos
5
+ # Pedidos de emissão (o que ej.notas.emitir devolve): acompanhar, listar e conferir.
6
+ class Emissoes < Base
7
+ # GET /v1/emissoes/{id}: o pedido, com "estado" (na_fila, emitindo, confirmando, autorizada, recusada ou
8
+ # incerta) e "proxima_consulta_ms" (quando consultar de novo).
9
+ # @param id [String]
10
+ # @return [Hash] {"pedido" => {...}}
11
+ def obter(id)
12
+ json("GET", "/v1/emissoes/#{segmento(id)}")
13
+ end
14
+
15
+ # GET /v1/emissoes: pedidos em andamento, ou nos estados pedidos.
16
+ # @param estados [String, Array<String>, nil] "na_fila,emitindo" ou %w[na_fila emitindo]
17
+ # @return [Hash] {"pedidos" => [...]}
18
+ def listar(estados: nil)
19
+ json("GET", "/v1/emissoes", query: { estados: estados })
20
+ end
21
+
22
+ # POST /v1/emissoes/{id}/conferir: confere no Emissor Nacional um pedido "incerta" (se a nota saiu ou não).
23
+ # @param id [String]
24
+ # @return [Hash] {"pedido" => {...}}
25
+ def conferir(id)
26
+ json("POST", "/v1/emissoes/#{segmento(id)}/conferir")
27
+ end
28
+ end
29
+ end
30
+ end
@@ -0,0 +1,81 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Emissaoja
4
+ module Recursos
5
+ # A empresa da conta: conexão com o Emissor Nacional (CNPJ e senha do portal) e configuração fiscal.
6
+ # Uma conta tem uma empresa.
7
+ class Empresa < Base
8
+ # GET /v1/empresa: empresa (nil antes de conectar), credencial, onboarding, importação e avisos.
9
+ # @return [Hash]
10
+ def obter
11
+ json("GET", "/v1/empresa")
12
+ end
13
+
14
+ # PUT /v1/empresa/credencial: conecta a empresa com o CNPJ e a senha do Emissor Nacional. Responde na hora
15
+ # (202) com a "tentativa"; a verificação no portal segue em segundo plano (acompanhe com #aguardar_credencial)
16
+ # e, com a senha aceita, o emissaoja lê o cadastro fiscal e traz as notas dos últimos 90 dias.
17
+ #
18
+ # A verificação aceita até 3 senhas erradas por CNPJ em 24 h, para o portal não bloquear a conta da empresa:
19
+ # confira a senha antes de tentar de novo.
20
+ #
21
+ # @param cnpj [String] só números
22
+ # @param senha [String] senha do Emissor Nacional (não volta em nenhuma resposta)
23
+ # @param ciente_ultima_tentativa [Boolean] true para confirmar a última tentativa permitida
24
+ # (quando a API responde 409 confirmar_ultima_tentativa)
25
+ # @return [Hash] {"tentativa" => {"id" => ..., "estado" => ..., "proximo_passo" => "aguardar", ...}}
26
+ def conectar(cnpj, senha, ciente_ultima_tentativa: false)
27
+ corpo = { "cnpj" => cnpj.to_s, "senha" => senha.to_s, "ciente_ultima_tentativa" => ciente_ultima_tentativa ? true : false }
28
+ json("PUT", "/v1/empresa/credencial", corpo: corpo)
29
+ end
30
+
31
+ # GET /v1/empresa/credencial: a tentativa em andamento (ou a última), com "estado" e "proximo_passo"
32
+ # ("aguardar", "configurando", "pronto", "corrigir_senha", "tentar_mais_tarde", "redefinir_no_portal",
33
+ # "suporte").
34
+ # @return [Hash] {"credencial" => {...}, "onboarding" => {"estado" => ...}, "tentativa" => {...} ou nil}
35
+ def credencial
36
+ json("GET", "/v1/empresa/credencial")
37
+ end
38
+
39
+ # Consulta #credencial até a tentativa sair de "aguardar" (senha aceita ou recusada, portal fora...).
40
+ # @param intervalo [Numeric] segundos entre as consultas (padrão 2)
41
+ # @param timeout [Numeric] segundos no total (padrão 120)
42
+ # @return [Hash] a última resposta de #credencial
43
+ # @raise [Erro] code "tempo_esgotado" (status 0) se não terminar a tempo
44
+ def aguardar_credencial(intervalo: 2, timeout: 120)
45
+ fim = agora + timeout
46
+ loop do
47
+ resposta = credencial
48
+ tentativa = resposta["tentativa"]
49
+ return resposta unless tentativa.is_a?(Hash) && tentativa["proximo_passo"] == "aguardar"
50
+ raise tempo_esgotado("A verificação da senha não terminou a tempo.") if agora >= fim
51
+
52
+ esperar(intervalo)
53
+ end
54
+ end
55
+
56
+ # GET /v1/empresa/onboarding: estágios, perguntas pendentes e bloqueio.
57
+ # @return [Hash]
58
+ def onboarding
59
+ json("GET", "/v1/empresa/onboarding")
60
+ end
61
+
62
+ # PUT /v1/empresa/fiscal: responde as perguntas que o cadastro fiscal não responde sozinho (onboarding em
63
+ # "perguntas"). Só os campos informados vão no corpo.
64
+ # @param aliquota_simples [Numeric, nil] alíquota do Simples Nacional, em % (maior que 0, até 33)
65
+ # @param reg_ap_trib_sn [Integer, nil] regime de apuração dos tributos do Simples Nacional: 1, 2 ou 3
66
+ # @return [Hash]
67
+ def fiscal(aliquota_simples: nil, reg_ap_trib_sn: nil)
68
+ corpo = {}
69
+ corpo["aliquota_simples"] = aliquota_simples unless aliquota_simples.nil?
70
+ corpo["reg_ap_trib_sn"] = reg_ap_trib_sn unless reg_ap_trib_sn.nil?
71
+ json("PUT", "/v1/empresa/fiscal", corpo: corpo)
72
+ end
73
+
74
+ # POST /v1/empresa/reler-fisco: lê o cadastro fiscal de novo no portal (202).
75
+ # @return [Hash]
76
+ def reler_fisco
77
+ json("POST", "/v1/empresa/reler-fisco")
78
+ end
79
+ end
80
+ end
81
+ end
@@ -0,0 +1,125 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Emissaoja
4
+ module Recursos
5
+ # Notas: emitir (com idempotência), acompanhar o pedido, listar, baixar PDF e XML e cancelar.
6
+ class Notas < Base
7
+ # Formato da referência (cabeçalho Idempotency-Key): 8 a 64 caracteres, letras, números, _ e -.
8
+ REFERENCIA = /\A[A-Za-z0-9_-]{8,64}\z/
9
+
10
+ # Estados em que o pedido de emissão para de mudar.
11
+ ESTADOS_FINAIS = %w[autorizada recusada incerta].freeze
12
+
13
+ # POST /v1/notas: prévia + emissão num passo, com o cabeçalho Idempotency-Key = referencia.
14
+ #
15
+ # r = ej.notas.emitir("pedido-0001", tomador_tipo: "pj", tomador_id: id, valor: 1500, descricao: "Consultoria")
16
+ # r["pedido"]["id"] # acompanhe com #aguardar
17
+ #
18
+ # A referência é um id seu, único por nota. Repetir a chamada com a mesma referência devolve o mesmo pedido
19
+ # ("repetido" => true) e nunca emite duas vezes; use isso para repetir depois de falha de rede, tempo
20
+ # esgotado ou 503 fila_indisponivel. A referência é conferida aqui, antes de qualquer chamada à API.
21
+ #
22
+ # @param referencia [String] 8 a 64 caracteres: letras, números, _ e -
23
+ # @param tomador_tipo [String] "pj" ou "pf"
24
+ # @param tomador_id [String] id do tomador
25
+ # @param valor [Numeric] em reais, até 2 casas (Integer, Float ou BigDecimal)
26
+ # @param campos [Hash] opcionais: servico_id (omitido: o serviço principal), descricao (até 2000 caracteres),
27
+ # competencia ("AAAA-MM-DD"; omitida: hoje), retem_iss, aliquota_iss, municipio_prestacao (código IBGE),
28
+ # confirmo_repeticao, permitir_repetida_de. Os nil não vão no corpo.
29
+ # @return [Hash] {"pedido" => {...}, "previa" => {...}} (202) ou {"pedido" => {...}, "repetido" => true} (200)
30
+ # @raise [Erro] chave_idempotencia_invalida (status 0, sem chamar a API), nota_bloqueada (422, veja
31
+ # Erro#bloqueios), possivel_duplicada, emissao_repetida_recente, limite_notas...
32
+ def emitir(referencia, tomador_tipo:, tomador_id:, valor:, **campos)
33
+ chave = referencia.to_s
34
+ unless REFERENCIA.match?(chave)
35
+ raise Erro.new(0, { "code" => "chave_idempotencia_invalida",
36
+ "message" => "Informe a referência da nota: 8 a 64 caracteres (letras, números, _ e -), única por nota." })
37
+ end
38
+
39
+ corpo = { "tomador_tipo" => tomador_tipo, "tomador_id" => tomador_id, "valor" => valor }
40
+ campos.each { |nome, item| corpo[nome.to_s] = item unless item.nil? }
41
+ json("POST", "/v1/notas", corpo: corpo, cabecalhos: { "Idempotency-Key" => chave })
42
+ end
43
+
44
+ # Consulta o pedido (GET /v1/emissoes/{id}) até "autorizada", "recusada" ou "incerta". Entre as consultas,
45
+ # espera o que a API pede em "proxima_consulta_ms" (3 s quando ela não diz), nunca menos que intervalo_minimo.
46
+ #
47
+ # @param pedido_id [String] o "id" do pedido devolvido por #emitir
48
+ # @param timeout [Numeric] segundos no total (padrão 180)
49
+ # @param intervalo_minimo [Numeric] segundos (padrão 1)
50
+ # @return [Hash] {"pedido" => {"estado" => "autorizada", "numero" => ..., "chave_acesso" => ...,
51
+ # "nota" => {"origem" => "local", "id" => ...}, ...}}
52
+ # @raise [Erro] code "tempo_esgotado" (status 0, extras["pedido_id"]) se não terminar a tempo; o pedido
53
+ # continua andando e pode ser consultado depois com ej.emissoes.obter
54
+ def aguardar(pedido_id, timeout: 180, intervalo_minimo: 1)
55
+ fim = agora + timeout
56
+ loop do
57
+ resposta = @cliente.emissoes.obter(pedido_id)
58
+ pedido = resposta["pedido"].is_a?(Hash) ? resposta["pedido"] : {}
59
+ return resposta if ESTADOS_FINAIS.include?(pedido["estado"])
60
+ if agora >= fim
61
+ raise tempo_esgotado("O pedido não terminou a tempo; consulte de novo mais tarde.", { "pedido_id" => pedido_id })
62
+ end
63
+
64
+ esperar([intervalo_minimo, proxima_consulta(pedido)].max)
65
+ end
66
+ end
67
+
68
+ # GET /v1/notas: notas locais e importadas, paginadas por cursor.
69
+ # @param periodo [String, nil] "mes_atual", "mes_anterior", "ano_atual", "12_meses" (padrão da API) ou
70
+ # "personalizado" (com de e ate)
71
+ # @param de [String, Date, nil] AAAA-MM-DD
72
+ # @param ate [String, Date, nil] AAAA-MM-DD
73
+ # @param situacao [String, nil] "todas" (padrão da API), "emitidas" ou "canceladas"
74
+ # @param busca [String, nil] número da nota, CPF/CNPJ ou nome do tomador
75
+ # @param cursor [String, nil] o "proximo_cursor" da página anterior
76
+ # @param limite [Integer, nil] até 50
77
+ # @return [Hash] {"notas" => [...], "total" => n, "janela_cheia" => false, "proximo_cursor" => ... ou nil}
78
+ def listar(periodo: nil, de: nil, ate: nil, situacao: nil, busca: nil, cursor: nil, limite: nil)
79
+ json("GET", "/v1/notas", query: { periodo: periodo, de: de, ate: ate, situacao: situacao, busca: busca,
80
+ cursor: cursor, limite: limite })
81
+ end
82
+
83
+ # GET /v1/notas/{origem}/{id}/pdf: o DANFSe em PDF.
84
+ #
85
+ # File.binwrite("nota.pdf", ej.notas.pdf(nota["origem"], nota["id"]))
86
+ #
87
+ # @param origem [String] "local" (emitida pelo emissaoja) ou "importada"
88
+ # @param id [String]
89
+ # @return [String] bytes do PDF (encoding ASCII-8BIT)
90
+ def pdf(origem, id)
91
+ bytes("/v1/notas/#{segmento(origem)}/#{segmento(id)}/pdf")
92
+ end
93
+
94
+ # GET /v1/notas/{origem}/{id}/xml: o XML da NFS-e.
95
+ # @param origem [String] "local" ou "importada"
96
+ # @param id [String]
97
+ # @return [String] texto em UTF-8
98
+ def xml(origem, id)
99
+ bytes("/v1/notas/#{segmento(origem)}/#{segmento(id)}/xml").force_encoding(Encoding::UTF_8)
100
+ end
101
+
102
+ # POST /v1/notas/{origem}/{id}/cancelar: pede o cancelamento no Emissor Nacional. Responde 202 com a
103
+ # "operacao"; acompanhe com ej.operacoes.aguardar(operacao["id"]).
104
+ # @param origem [String] "local" ou "importada"
105
+ # @param id [String]
106
+ # @param motivo [String, Integer] "1" (erro na emissão) ou "2" (serviço não prestado)
107
+ # @param justificativa [String, nil] de 15 a 255 caracteres
108
+ # @return [Hash] {"operacao" => {"id" => ..., "estado" => "processando", ...}}
109
+ def cancelar(origem, id, motivo:, justificativa: nil)
110
+ corpo = { "motivo" => motivo.to_s }
111
+ corpo["justificativa"] = justificativa unless justificativa.nil? || justificativa.to_s.empty?
112
+ json("POST", "/v1/notas/#{segmento(origem)}/#{segmento(id)}/cancelar", corpo: corpo)
113
+ end
114
+
115
+ private
116
+
117
+ # Segundos até a próxima consulta: proxima_consulta_ms da API, ou 3 s quando ela não diz.
118
+ def proxima_consulta(pedido)
119
+ ms = pedido["proxima_consulta_ms"]
120
+ ms = 3000 unless ms.is_a?(Numeric) && ms.positive?
121
+ ms / 1000.0
122
+ end
123
+ end
124
+ end
125
+ end
@@ -0,0 +1,33 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Emissaoja
4
+ module Recursos
5
+ # Operações assíncronas; hoje, o cancelamento de nota (ej.notas.cancelar).
6
+ class Operacoes < Base
7
+ # GET /v1/operacoes/{id}: "estado" processando, concluida ou falhou (com "erro").
8
+ # @param id [String]
9
+ # @return [Hash] {"operacao" => {"id" => ..., "tipo" => ..., "estado" => ..., "resultado" => ..., "erro" => ...}}
10
+ def obter(id)
11
+ json("GET", "/v1/operacoes/#{segmento(id)}")
12
+ end
13
+
14
+ # Consulta #obter até a operação sair de "processando" (concluida ou falhou).
15
+ # @param id [String]
16
+ # @param intervalo [Numeric] segundos entre as consultas (padrão 2)
17
+ # @param timeout [Numeric] segundos no total (padrão 180)
18
+ # @return [Hash] a última resposta de #obter
19
+ # @raise [Erro] code "tempo_esgotado" (status 0) se não terminar a tempo
20
+ def aguardar(id, intervalo: 2, timeout: 180)
21
+ fim = agora + timeout
22
+ loop do
23
+ resposta = obter(id)
24
+ operacao = resposta["operacao"].is_a?(Hash) ? resposta["operacao"] : {}
25
+ return resposta unless operacao["estado"] == "processando"
26
+ raise tempo_esgotado("A operação não terminou a tempo.") if agora >= fim
27
+
28
+ esperar(intervalo)
29
+ end
30
+ end
31
+ end
32
+ end
33
+ end
@@ -0,0 +1,54 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Emissaoja
4
+ module Recursos
5
+ # Serviços da empresa (o que vai na nota: descrição, código de tributação nacional, ISS) e o catálogo
6
+ # nacional de códigos de serviço.
7
+ class Servicos < Base
8
+ # GET /v1/servicos.
9
+ # @param ativos [String, Boolean, nil] "1" (ativos), "0" (inativos) ou "todos"; true vale "1" e false vale "0"
10
+ # @return [Hash] {"servicos" => [...]}
11
+ def listar(ativos: nil)
12
+ ativos = { true => "1", false => "0" }.fetch(ativos, ativos)
13
+ json("GET", "/v1/servicos", query: { ativos: ativos })
14
+ end
15
+
16
+ # POST /v1/servicos.
17
+ #
18
+ # item = ej.servicos.catalogo("consultoria em informática")["itens"].first
19
+ # ej.servicos.criar(descricao: "Consultoria em TI", c_trib_nac: item["c_trib_nac"],
20
+ # trib_issqn: "tributavel", retem_iss: false)
21
+ #
22
+ # @param campos [Hash] descricao, c_trib_nac, trib_issqn ("tributavel" ou "nao_incidencia") e retem_iss
23
+ # (obrigatórios); nbs, c_trib_mun, tp_oper e aliquota_iss (opcionais)
24
+ # @return [Hash] {"servico" => {...}}
25
+ def criar(campos = {})
26
+ json("POST", "/v1/servicos", corpo: campos)
27
+ end
28
+
29
+ # PUT /v1/servicos/{id}: edição parcial. Campo com nil vai como null (limpa o valor).
30
+ # @param id [String]
31
+ # @param campos [Hash]
32
+ # @return [Hash] {"servico" => {...}, "vinculos_atualizados" => n}
33
+ def atualizar(id, campos = {})
34
+ json("PUT", "/v1/servicos/#{segmento(id)}", corpo: campos)
35
+ end
36
+
37
+ # DELETE /v1/servicos/{id}: desativa o serviço (o último ativo não pode: 409 ultimo_servico_ativo).
38
+ # As notas emitidas continuam apontando para ele.
39
+ # @param id [String]
40
+ # @return [Hash] {"servico" => {...}}
41
+ def desativar(id)
42
+ json("DELETE", "/v1/servicos/#{segmento(id)}")
43
+ end
44
+
45
+ # GET /v1/catalogo/servicos: catálogo nacional de códigos de serviço, por texto.
46
+ # @param q [String] texto da busca
47
+ # @param limite [Integer, nil] até 50
48
+ # @return [Hash] {"itens" => [{"c_trib_nac" => ..., "descricao" => ..., "item_lc116" => ..., "nbs_sugeridos" => [...]}]}
49
+ def catalogo(q, limite: nil)
50
+ json("GET", "/v1/catalogo/servicos", query: { q: q, limite: limite })
51
+ end
52
+ end
53
+ end
54
+ end
@@ -0,0 +1,58 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Emissaoja
4
+ module Recursos
5
+ # Tomadores, os clientes da nota: pessoa jurídica ("pj", pelo CNPJ) ou física ("pf", pelo CPF).
6
+ # Tomador não se apaga: as notas emitidas apontam para ele.
7
+ class Tomadores < Base
8
+ # GET /v1/tomadores: lista paginada.
9
+ # @param busca [String, nil] nome ou documento
10
+ # @param pagina [Integer, nil] a partir de 1
11
+ # @param limite [Integer, nil] até 50
12
+ # @param ordem [String, nil] "nome" ou "recentes"
13
+ # @return [Hash] {"tomadores" => [...], "total" => n, "pagina" => n, "limite" => n}
14
+ def listar(busca: nil, pagina: nil, limite: nil, ordem: nil)
15
+ json("GET", "/v1/tomadores", query: { busca: busca, pagina: pagina, limite: limite, ordem: ordem })
16
+ end
17
+
18
+ # GET /v1/tomadores/busca: busca rápida por nome ou documento (2 caracteres ou mais).
19
+ # @param q [String]
20
+ # @return [Hash] {"tomadores" => [...]}
21
+ def buscar(q)
22
+ json("GET", "/v1/tomadores/busca", query: { q: q })
23
+ end
24
+
25
+ # POST /v1/tomadores: cria pelo CNPJ (nome e endereço vêm da Receita) ou pelo CPF com o nome.
26
+ # Se o tomador já existia, devolve o mesmo, com "ja_existia" => true.
27
+ # @param documento [String] CNPJ ou CPF
28
+ # @param nome [String, nil] obrigatório para CPF
29
+ # @return [Hash] {"tomador" => {"tipo" => "pj", "id" => ..., "nome" => ..., ...}, "ja_existia" => false}
30
+ def criar(documento, nome: nil)
31
+ corpo = { "documento" => documento.to_s }
32
+ corpo["nome"] = nome unless nome.nil? || nome.to_s.empty?
33
+ json("POST", "/v1/tomadores", corpo: corpo)
34
+ end
35
+
36
+ # GET /v1/tomadores/{tipo}/{id}: a ficha do tomador.
37
+ # @param tipo [String] "pj" ou "pf"
38
+ # @param id [String]
39
+ # @return [Hash] {"tomador" => {...}}
40
+ def obter(tipo, id)
41
+ json("GET", "/v1/tomadores/#{segmento(tipo)}/#{segmento(id)}")
42
+ end
43
+
44
+ # PUT /v1/tomadores/{tipo}/{id}: edição parcial de endereço e contato (o documento não muda).
45
+ #
46
+ # ej.tomadores.atualizar("pj", id, email: "financeiro@cliente.com.br", telefone: "3133334444")
47
+ #
48
+ # @param tipo [String] "pj" ou "pf"
49
+ # @param id [String]
50
+ # @param campos [Hash] nome, cep, endereco, numero, complemento, bairro, cidade, estado,
51
+ # codigo_municipio_ibge, telefone, email, inscricao_municipal (lista completa no OpenAPI)
52
+ # @return [Hash] {"tomador" => {...}}
53
+ def atualizar(tipo, id, campos = {})
54
+ json("PUT", "/v1/tomadores/#{segmento(tipo)}/#{segmento(id)}", corpo: campos)
55
+ end
56
+ end
57
+ end
58
+ end
@@ -0,0 +1,93 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "net/http"
4
+ require "openssl"
5
+ require "uri"
6
+
7
+ module Emissaoja
8
+ # Transporte HTTP padrão: Net::HTTP da biblioteca padrão, uma conexão por chamada e nenhuma repetição
9
+ # automática (emitir e conectar têm efeito; quem decide repetir é quem chama, com a mesma referência).
10
+ #
11
+ # Para testes, ou para usar outro cliente HTTP, passe em Cliente.new(transporte: ...) qualquer objeto que
12
+ # responda a call(metodo, url, cabecalhos, corpo, timeout) e devolva [status, cabecalhos, corpo]:
13
+ # status Integer, cabecalhos Hash (nome => valor) e corpo String com os bytes da resposta.
14
+ class TransporteNetHTTP
15
+ METODOS = {
16
+ "GET" => Net::HTTP::Get,
17
+ "POST" => Net::HTTP::Post,
18
+ "PUT" => Net::HTTP::Put,
19
+ "PATCH" => Net::HTTP::Patch,
20
+ "DELETE" => Net::HTTP::Delete
21
+ }.freeze
22
+
23
+ # POST/PUT/PATCH sem corpo: o Net::HTTP manda corpo vazio e, sem Content-Type, inventa
24
+ # application/x-www-form-urlencoded (com aviso). A API recusaria esse tipo (415), então estas
25
+ # subclasses mandam o corpo vazio com Content-Length 0 e nenhum Content-Type.
26
+ module SemTipoPadrao
27
+ private
28
+
29
+ def supply_default_content_type; end
30
+ end
31
+
32
+ SEM_CORPO = {
33
+ "POST" => Class.new(Net::HTTP::Post) { include SemTipoPadrao },
34
+ "PUT" => Class.new(Net::HTTP::Put) { include SemTipoPadrao },
35
+ "PATCH" => Class.new(Net::HTTP::Patch) { include SemTipoPadrao }
36
+ }.freeze
37
+
38
+ # Viram code "tempo_esgotado". Net::OpenTimeout, Net::ReadTimeout e Net::WriteTimeout herdam de Timeout::Error.
39
+ ERROS_DE_TEMPO = [Timeout::Error, Errno::ETIMEDOUT, (IO::TimeoutError if defined?(IO::TimeoutError))].compact.freeze
40
+
41
+ # Viram code "rede": DNS, conexão recusada ou derrubada, TLS, resposta HTTP malformada.
42
+ ERROS_DE_REDE = [
43
+ SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError,
44
+ Net::ProtocolError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError
45
+ ].freeze
46
+
47
+ # @param metodo [String] "GET", "POST", "PUT", "PATCH" ou "DELETE"
48
+ # @param url [String] URL completa, com a query já montada
49
+ # @param cabecalhos [Hash{String => String}]
50
+ # @param corpo [String, nil] JSON já serializado, ou nil
51
+ # @param timeout [Numeric] segundos para conectar, para enviar e para cada leitura
52
+ # @return [Array(Integer, Hash{String => String}, String)] status, cabeçalhos (nomes em minúsculas) e corpo em bytes
53
+ # @raise [Erro] code "tempo_esgotado" ou "rede", com status 0
54
+ def call(metodo, url, cabecalhos, corpo, timeout)
55
+ uri = URI.parse(url)
56
+ requisicao = montar_requisicao(metodo, uri, cabecalhos, corpo)
57
+ http = Net::HTTP.new(uri.hostname, uri.port)
58
+ http.use_ssl = uri.scheme == "https"
59
+ http.open_timeout = timeout
60
+ http.read_timeout = timeout
61
+ http.write_timeout = timeout
62
+ http.max_retries = 0 # o Net::HTTP repetiria GET/PUT/DELETE sozinho depois de uma falha de leitura
63
+ resposta = http.start { |conexao| conexao.request(requisicao) }
64
+ [resposta.code.to_i, cabecalhos_de(resposta), resposta.body.to_s.b]
65
+ rescue *ERROS_DE_TEMPO
66
+ raise Erro.new(0, { "code" => "tempo_esgotado", "message" => "A API do emissaoja não respondeu em #{timeout} s." })
67
+ rescue *ERROS_DE_REDE => e
68
+ raise Erro.new(0, { "code" => "rede", "message" => "Falha de rede ao chamar a API do emissaoja: #{e.message}" })
69
+ end
70
+
71
+ private
72
+
73
+ def montar_requisicao(metodo, uri, cabecalhos, corpo)
74
+ nome = metodo.to_s.upcase
75
+ classe = METODOS.fetch(nome) { raise ArgumentError, "método HTTP não suportado: #{metodo}" }
76
+ classe = SEM_CORPO.fetch(nome, classe) if corpo.nil?
77
+ requisicao = classe.new(uri.request_uri)
78
+ cabecalhos.each { |nome, valor| requisicao[nome] = valor }
79
+ if corpo
80
+ requisicao.body = corpo
81
+ elsif requisicao.request_body_permitted?
82
+ requisicao["Content-Length"] = "0" # POST/PUT sem corpo: o Net::HTTP não mandaria o tamanho
83
+ end
84
+ requisicao
85
+ end
86
+
87
+ def cabecalhos_de(resposta)
88
+ cabecalhos = {}
89
+ resposta.each_header { |nome, valor| cabecalhos[nome] = valor }
90
+ cabecalhos
91
+ end
92
+ end
93
+ end
@@ -0,0 +1,6 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Emissaoja
4
+ # Versão da gem. Também vai no cabeçalho User-Agent ("emissaoja-ruby/0.1.0").
5
+ VERSION = "0.1.0"
6
+ end
data/lib/emissaoja.rb ADDED
@@ -0,0 +1,31 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Cliente oficial em Ruby da API do emissaoja (https://emissaoja.com.br/docs/): emissão de NFS-e no Emissor
4
+ # Nacional com o CNPJ e a senha do portal, sem certificado digital, para MEI e empresas do Simples Nacional.
5
+ #
6
+ # require "emissaoja"
7
+ #
8
+ # ej = Emissaoja::Cliente.new(chave: ENV["EMISSAOJA_KEY"], base_url: Emissaoja::BASE_SANDBOX)
9
+ # r = ej.notas.emitir("pedido-0001", tomador_tipo: "pj", tomador_id: id, valor: 1500, descricao: "Consultoria")
10
+ # pedido = ej.notas.aguardar(r["pedido"]["id"])["pedido"]
11
+ # File.binwrite("nota.pdf", ej.notas.pdf(pedido["nota"]["origem"], pedido["nota"]["id"])) if pedido["estado"] == "autorizada"
12
+ module Emissaoja
13
+ # API de produção (padrão do Cliente). Chaves ej_live_.
14
+ BASE_PRODUCAO = "https://emissaoja.com.br"
15
+
16
+ # Ambiente de testes: o mesmo emissaoja com um Emissor Nacional simulado (nada vai ao fisco). Chaves ej_test_.
17
+ BASE_SANDBOX = "https://sandbox.emissaoja.com.br"
18
+ end
19
+
20
+ require_relative "emissaoja/version"
21
+ require_relative "emissaoja/erro"
22
+ require_relative "emissaoja/transporte"
23
+ require_relative "emissaoja/recursos/base"
24
+ require_relative "emissaoja/recursos/empresa"
25
+ require_relative "emissaoja/recursos/tomadores"
26
+ require_relative "emissaoja/recursos/servicos"
27
+ require_relative "emissaoja/recursos/notas"
28
+ require_relative "emissaoja/recursos/emissoes"
29
+ require_relative "emissaoja/recursos/operacoes"
30
+ require_relative "emissaoja/recursos/cnpj"
31
+ require_relative "emissaoja/cliente"