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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +20 -0
- data/LICENSE +21 -0
- data/README.md +405 -0
- data/lib/emissaoja/cliente.rb +208 -0
- data/lib/emissaoja/erro.rb +54 -0
- data/lib/emissaoja/recursos/base.rb +43 -0
- data/lib/emissaoja/recursos/cnpj.rb +17 -0
- data/lib/emissaoja/recursos/emissoes.rb +30 -0
- data/lib/emissaoja/recursos/empresa.rb +81 -0
- data/lib/emissaoja/recursos/notas.rb +125 -0
- data/lib/emissaoja/recursos/operacoes.rb +33 -0
- data/lib/emissaoja/recursos/servicos.rb +54 -0
- data/lib/emissaoja/recursos/tomadores.rb +58 -0
- data/lib/emissaoja/transporte.rb +93 -0
- data/lib/emissaoja/version.rb +6 -0
- data/lib/emissaoja.rb +31 -0
- metadata +73 -0
|
@@ -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
|
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"
|