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
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 11175b44b4cc034d826c5160d2c88669deefcaa85ba7ca542c750a98a18192bb
|
|
4
|
+
data.tar.gz: f1448f9ab2f44d0a4c0c5fa76e124744fde1dd86c822b3b7f4794db8ebb6ebc1
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: a57976f7b1e0c80c94ee3432177e70566004320de46403d9793e36037e9afdf5af03e84370801a99d94a767fc525d08c14c19cd24166487e55089a681bf5bed6
|
|
7
|
+
data.tar.gz: e9ddd23a9a58f7481e0d8867f7ff0f753a842d0540cc2396deb66fa1f55b2cc7221922ff4711c5d5784f5aba9a8764873ffede53306971174151360b9fbb9a72
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Todas as mudanças relevantes desta gem. Formato baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/); versões seguem [SemVer](https://semver.org/lang/pt-BR/).
|
|
4
|
+
|
|
5
|
+
## [0.1.0] - 2026-11-05
|
|
6
|
+
|
|
7
|
+
Primeira versão pública.
|
|
8
|
+
|
|
9
|
+
### Adicionado
|
|
10
|
+
|
|
11
|
+
- `Emissaoja::Cliente` com os recursos `empresa` (obter, conectar, credencial, aguardar_credencial, onboarding, fiscal, reler_fisco), `tomadores` (listar, buscar, criar, obter, atualizar), `servicos` (listar, criar, atualizar, desativar, catalogo), `notas` (emitir, aguardar, listar, pdf, xml, cancelar), `emissoes` (obter, listar, conferir), `operacoes` (obter, aguardar), `cnpj.consultar` e `status`.
|
|
12
|
+
- `notas.emitir` com referência obrigatória, conferida antes da chamada (`chave_idempotencia_invalida`, sem ir à API) e enviada no cabeçalho `Idempotency-Key`; campos `nil` ficam fora do corpo.
|
|
13
|
+
- `notas.aguardar` no ritmo de `proxima_consulta_ms`; `empresa.aguardar_credencial` e `operacoes.aguardar` com intervalo e tempo máximo; `tempo_esgotado` com o `pedido_id` nos `extras`.
|
|
14
|
+
- `Emissaoja::Erro` com `status`, `code`, `message`, `extras`, `bloqueios` e `request_id` (cabeçalho `x-request-id`); falha de rede vira `rede` e tempo esgotado vira `tempo_esgotado`, com status 0.
|
|
15
|
+
- Chave lida de `EMISSAOJA_KEY` na primeira chamada que precisa dela, quando não informada; `inspect` do cliente não mostra a chave.
|
|
16
|
+
- `Emissaoja::BASE_PRODUCAO` e `Emissaoja::BASE_SANDBOX`.
|
|
17
|
+
- Transporte HTTP com `Net::HTTP` (sem dependências e sem repetição automática), substituível pela opção `transporte`; a espera dos métodos `aguardar` é substituível pela opção `dormir`.
|
|
18
|
+
- `BigDecimal` e `Rational` vão como número no JSON.
|
|
19
|
+
|
|
20
|
+
[0.1.0]: https://github.com/Easymovel/emissaoja-ruby/releases/tag/v0.1.0
|
data/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BINOBO LTDA
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,405 @@
|
|
|
1
|
+
# emissaoja: API de NFS-e nacional para Ruby
|
|
2
|
+
|
|
3
|
+
Gem oficial em Ruby da [API do emissaoja](https://emissaoja.com.br/docs/): emita **NFS-e (nota fiscal de serviço eletrônica) no Emissor Nacional** a partir do seu sistema Ruby ou Rails, com o CNPJ e a senha do portal, **sem certificado digital**, para MEI e empresas do Simples Nacional. Conecte a empresa, cadastre tomadores e serviços, emita a nota, acompanhe o pedido e baixe o PDF (DANFSe) e o XML.
|
|
4
|
+
|
|
5
|
+
- **Sem dependências**: só `Net::HTTP` e `JSON` da biblioteca padrão, Ruby 3.0 ou mais novo.
|
|
6
|
+
- **Idempotência embutida**: `emitir` exige uma referência sua por nota e a envia como `Idempotency-Key`; repetir a chamada devolve o mesmo pedido, sem emitir de novo.
|
|
7
|
+
- **Erros com código estável**: toda falha vira `Emissaoja::Erro`, com `code` (a lista fechada da API), `status`, `extras`, `bloqueios` e `request_id`.
|
|
8
|
+
- **Acompanhamento pronto**: `notas.aguardar` consulta o pedido no ritmo que a API pede (`proxima_consulta_ms`).
|
|
9
|
+
- **Feita para Rails**: uma instância serve a aplicação inteira (Puma, Sidekiq), a chave só é lida na primeira chamada e o transporte HTTP pode ser trocado nos testes.
|
|
10
|
+
|
|
11
|
+
> **A chave de API é secreta.** Quem tem a chave emite notas em nome da empresa. Guarde-a no servidor (credentials do Rails, variável de ambiente, cofre de segredos), nunca no código-fonte, no Git, no navegador ou em app distribuído.
|
|
12
|
+
|
|
13
|
+
## Instalação
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
bundle add emissaoja
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Ou, fora do Bundler:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
gem install emissaoja
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Para usar a API, crie a conta grátis em [emissaoja.com.br](https://emissaoja.com.br/?origem=lib-ruby): entre no [app](https://emissaoja.com.br/app) com a conta Google, aceite os termos e crie a chave em **Conta → API** (ela aparece uma vez e começa com `ej_live_`). Depois, conecte a empresa com o CNPJ e a senha do Emissor Nacional (`ej.empresa.conectar`).
|
|
26
|
+
|
|
27
|
+
## Teste no sandbox em 2 minutos
|
|
28
|
+
|
|
29
|
+
O sandbox, em [sandbox.emissaoja.com.br](https://sandbox.emissaoja.com.br), é o mesmo emissaoja com um **Emissor Nacional simulado**: nada vai ao fisco e nada é cobrado. Entre com a conta Google, aceite os termos e crie uma chave em **Conta → API** (ela começa com `ej_test_` e só vale lá).
|
|
30
|
+
|
|
31
|
+
```ruby
|
|
32
|
+
require "emissaoja"
|
|
33
|
+
|
|
34
|
+
# EMISSAOJA_KEY=ej_test_... (chave do sandbox)
|
|
35
|
+
ej = Emissaoja::Cliente.new(chave: ENV["EMISSAOJA_KEY"], base_url: Emissaoja::BASE_SANDBOX)
|
|
36
|
+
|
|
37
|
+
# 1. Conectar a empresa de exemplo, uma vez (MEI pronto para emitir; no sandbox qualquer senha serve, menos "errada")
|
|
38
|
+
if ej.empresa.obter["empresa"].nil?
|
|
39
|
+
ej.empresa.conectar("11111111000191", "qualquer-senha")
|
|
40
|
+
ej.empresa.aguardar_credencial # até o portal aceitar a senha
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
# 2. Esperar o cadastro fiscal ser lido (onboarding "pronto"; no sandbox, poucos segundos)
|
|
44
|
+
30.times do
|
|
45
|
+
break if ej.empresa.obter.dig("onboarding", "estado") == "pronto"
|
|
46
|
+
|
|
47
|
+
sleep 2
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
# 3. Tomador pelo CNPJ: nome e endereço vêm da Receita (se já existe, volta o mesmo)
|
|
51
|
+
tomador = ej.tomadores.criar("12345678000195")["tomador"]
|
|
52
|
+
|
|
53
|
+
# 4. Emitir: a referência é um id seu, único por nota. Repetir com a mesma referência devolve o mesmo
|
|
54
|
+
# pedido; para emitir outra nota (outro valor, outro tomador), use outra referência.
|
|
55
|
+
r = ej.notas.emitir(
|
|
56
|
+
"pedido-0001",
|
|
57
|
+
tomador_tipo: tomador["tipo"],
|
|
58
|
+
tomador_id: tomador["id"],
|
|
59
|
+
valor: 1500,
|
|
60
|
+
descricao: "Consultoria de novembro"
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
# 5. Acompanhar até autorizada, recusada ou incerta e baixar o PDF
|
|
64
|
+
pedido = ej.notas.aguardar(r["pedido"]["id"])["pedido"]
|
|
65
|
+
if pedido["estado"] == "autorizada"
|
|
66
|
+
puts "NFS-e #{pedido["numero"]}, chave de acesso #{pedido["chave_acesso"]}"
|
|
67
|
+
File.binwrite("nota.pdf", ej.notas.pdf(pedido["nota"]["origem"], pedido["nota"]["id"]))
|
|
68
|
+
else
|
|
69
|
+
puts "#{pedido["estado"]}: #{pedido["motivo"]}"
|
|
70
|
+
end
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Empresas de exemplo do sandbox (qualquer senha, menos `errada`, que o portal simulado recusa):
|
|
74
|
+
|
|
75
|
+
| CNPJ | O que acontece |
|
|
76
|
+
| --- | --- |
|
|
77
|
+
| `11111111000191` | MEI pronto para emitir, com notas e clientes dos últimos 90 dias |
|
|
78
|
+
| `22222222000191` | ME/EPP que pede a alíquota do Simples antes de emitir (`ej.empresa.fiscal(aliquota_simples: ...)`) |
|
|
79
|
+
| `33333333000191` | MEI sem notas anteriores |
|
|
80
|
+
| `44444444000191` | Empresa bloqueada (não optante do Simples) |
|
|
81
|
+
|
|
82
|
+
Tomadores de exemplo: CNPJ `12345678000195` e CPF `52998224725`. Valores com significado ao emitir: `13.13` sai **incerta** (`ej.emissoes.conferir(id)` confere e ela vira autorizada), `77.77` sai incerta e a conferência mostra que a nota não saiu, `66.66` é **recusada** pelo fisco simulado e `99.99` é bloqueada já na prévia (`422 nota_bloqueada`). A empresa conectada e as notas do sandbox continuam lá quando o emissaoja publica uma versão nova.
|
|
83
|
+
|
|
84
|
+
## Em produção
|
|
85
|
+
|
|
86
|
+
Troque a base e a chave. Sem `base_url`, o cliente usa produção (`https://emissaoja.com.br`); sem `chave`, lê `EMISSAOJA_KEY` na primeira chamada.
|
|
87
|
+
|
|
88
|
+
```ruby
|
|
89
|
+
ej = Emissaoja::Cliente.new # produção; EMISSAOJA_KEY=ej_live_...
|
|
90
|
+
|
|
91
|
+
# Uma vez: CNPJ (só números) e senha do Emissor Nacional da empresa
|
|
92
|
+
ej.empresa.conectar("11222333000181", ENV.fetch("SENHA_EMISSOR_NACIONAL"))
|
|
93
|
+
tentativa = ej.empresa.aguardar_credencial["tentativa"]
|
|
94
|
+
puts tentativa["proximo_passo"] # "configurando" ou "pronto"; ou "corrigir_senha", "redefinir_no_portal"...
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
- As chaves `ej_live_` só valem em produção e as `ej_test_` só no sandbox. A chave é secreta: só no servidor, nunca no navegador ou em app distribuído.
|
|
98
|
+
- A verificação aceita até 3 senhas erradas por CNPJ em 24 h, para o portal não bloquear a conta da empresa: confira a senha antes de tentar de novo.
|
|
99
|
+
- A senha do portal nunca volta em resposta nem aparece em log.
|
|
100
|
+
- Opções do cliente: `chave:`, `base_url:` (`Emissaoja::BASE_PRODUCAO` ou `Emissaoja::BASE_SANDBOX`), `timeout:` (segundos, padrão 30), `transporte:` e `dormir:` (para testes).
|
|
101
|
+
|
|
102
|
+
## Recursos
|
|
103
|
+
|
|
104
|
+
Todas as respostas são `Hash` com chaves `String`: o JSON da API, em `snake_case`. A referência completa dos campos está na [documentação](https://emissaoja.com.br/docs/) e no [OpenAPI](https://emissaoja.com.br/v1/openapi.json).
|
|
105
|
+
|
|
106
|
+
### Empresa
|
|
107
|
+
|
|
108
|
+
```ruby
|
|
109
|
+
ej.empresa.obter # empresa (nil antes de conectar), credencial, onboarding e avisos
|
|
110
|
+
ej.empresa.conectar(cnpj, senha) # 202 {"tentativa" => {...}}; a verificação segue em segundo plano
|
|
111
|
+
ej.empresa.aguardar_credencial # repete credencial até proximo_passo sair de "aguardar"
|
|
112
|
+
ej.empresa.onboarding # estágios e perguntas pendentes (estado "perguntas")
|
|
113
|
+
ej.empresa.fiscal(aliquota_simples: 6.0) # responde a pergunta do Simples (há também reg_ap_trib_sn: 1, 2 ou 3)
|
|
114
|
+
ej.empresa.reler_fisco # lê o cadastro fiscal de novo no portal
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`onboarding.estado` segue `configurando → perguntas → pronto`. Emitir antes de `pronto` devolve `422 nota_bloqueada` com o que falta.
|
|
118
|
+
|
|
119
|
+
### Tomadores
|
|
120
|
+
|
|
121
|
+
```ruby
|
|
122
|
+
pj = ej.tomadores.criar("12345678000195")["tomador"] # CNPJ: dados da Receita
|
|
123
|
+
pf = ej.tomadores.criar("52998224725", nome: "Maria da Silva")["tomador"] # CPF: com o nome
|
|
124
|
+
ej.tomadores.buscar("maria")["tomadores"] # por nome ou documento
|
|
125
|
+
ej.tomadores.listar(busca: "silva", pagina: 1, limite: 20, ordem: "recentes")
|
|
126
|
+
ej.tomadores.obter("pf", pf["id"])
|
|
127
|
+
ej.tomadores.atualizar("pf", pf["id"], email: "maria@exemplo.com.br", cep: "30130000")
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Tomador não se apaga: as notas emitidas apontam para ele.
|
|
131
|
+
|
|
132
|
+
### Serviços
|
|
133
|
+
|
|
134
|
+
```ruby
|
|
135
|
+
item = ej.servicos.catalogo("consultoria em informática", limite: 5)["itens"].first # catálogo nacional
|
|
136
|
+
servico = ej.servicos.criar(
|
|
137
|
+
descricao: "Consultoria em TI",
|
|
138
|
+
c_trib_nac: item["c_trib_nac"],
|
|
139
|
+
trib_issqn: "tributavel", # ou "nao_incidencia"
|
|
140
|
+
retem_iss: false
|
|
141
|
+
)["servico"]
|
|
142
|
+
ej.servicos.listar(ativos: "todos") # "1" (ativos), "0" (inativos) ou "todos"
|
|
143
|
+
ej.servicos.atualizar(servico["id"], descricao: "Consultoria em tecnologia")
|
|
144
|
+
ej.servicos.desativar(servico["id"]) # o último serviço ativo não pode ser desativado
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
`trib_issqn` aceita `tributavel` e `nao_incidencia`; isenção, imunidade e exportação ficam fora do emissaoja.
|
|
148
|
+
|
|
149
|
+
### Notas
|
|
150
|
+
|
|
151
|
+
```ruby
|
|
152
|
+
r = ej.notas.emitir(
|
|
153
|
+
"venda-2026-000123", # referência: um id seu, único por nota
|
|
154
|
+
tomador_tipo: "pj",
|
|
155
|
+
tomador_id: pj["id"],
|
|
156
|
+
valor: 1500, # reais, até 2 casas (Integer, Float ou BigDecimal)
|
|
157
|
+
servico_id: servico["id"], # omitido: o serviço principal
|
|
158
|
+
descricao: "Consultoria de novembro",
|
|
159
|
+
competencia: "2026-11-01" # omitida: hoje
|
|
160
|
+
)
|
|
161
|
+
pedido = ej.notas.aguardar(r["pedido"]["id"])["pedido"] # até autorizada, recusada ou incerta
|
|
162
|
+
nota = pedido["nota"] # {"origem" => "local", "id" => ...}
|
|
163
|
+
|
|
164
|
+
File.binwrite("nota.pdf", ej.notas.pdf(nota["origem"], nota["id"])) # String binária (DANFSe)
|
|
165
|
+
File.write("nota.xml", ej.notas.xml(nota["origem"], nota["id"])) # String UTF-8
|
|
166
|
+
|
|
167
|
+
# Lista paginada por cursor (periodo: "mes_atual", "mes_anterior", "ano_atual", "12_meses" ou "personalizado")
|
|
168
|
+
cursor = nil
|
|
169
|
+
loop do
|
|
170
|
+
pagina = ej.notas.listar(periodo: "mes_atual", situacao: "emitidas", cursor: cursor)
|
|
171
|
+
pagina["notas"].each { |n| puts "#{n["numero"]} #{n["valor"]}" }
|
|
172
|
+
cursor = pagina["proximo_cursor"]
|
|
173
|
+
break unless cursor
|
|
174
|
+
end
|
|
175
|
+
|
|
176
|
+
# Cancelar: motivo "1" (erro na emissão) ou "2" (serviço não prestado)
|
|
177
|
+
op = ej.notas.cancelar(nota["origem"], nota["id"], motivo: "1", justificativa: "Valor digitado errado na emissão")
|
|
178
|
+
ej.operacoes.aguardar(op["operacao"]["id"])["operacao"]["estado"] # "concluida" ou "falhou"
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
| `estado` do pedido | O que significa |
|
|
182
|
+
| --- | --- |
|
|
183
|
+
| `na_fila`, `emitindo`, `confirmando` | Em andamento; `aguardar` continua consultando |
|
|
184
|
+
| `autorizada` | A nota saiu: `numero`, `chave_acesso` e `nota` (`origem` e `id`, para o PDF e o XML) |
|
|
185
|
+
| `recusada` | O Emissor Nacional recusou: veja `motivo_code` e `motivo`. Recusada não conta no plano |
|
|
186
|
+
| `incerta` | O portal não confirmou se a nota saiu: confira com `ej.emissoes.conferir(pedido["id"])` antes de emitir de novo |
|
|
187
|
+
|
|
188
|
+
Nota não se altera: para corrigir, cancele e emita outra. Nota autorizada e depois cancelada conta no plano; recusada não.
|
|
189
|
+
|
|
190
|
+
### Emissões e operações
|
|
191
|
+
|
|
192
|
+
```ruby
|
|
193
|
+
ej.emissoes.listar(estados: %w[na_fila emitindo]) # pedidos em andamento
|
|
194
|
+
ej.emissoes.obter(pedido_id) # {"pedido" => {"estado" => ..., "proxima_consulta_ms" => ...}}
|
|
195
|
+
ej.emissoes.conferir(pedido_id) # pedido "incerta": confere no Emissor Nacional
|
|
196
|
+
ej.operacoes.obter(operacao_id) # cancelamento: processando, concluida ou falhou
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### Consulta de CNPJ
|
|
200
|
+
|
|
201
|
+
```ruby
|
|
202
|
+
dados = ej.cnpj.consultar("11.222.333/0001-81") # com ou sem máscara
|
|
203
|
+
puts dados["razao_social"]
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Devolve os dados cadastrais da Receita Federal (razão social, situação, CNAEs, endereço, Simples, MEI, sócios com CPF mascarado). Não cria tomador: `ej.tomadores.criar` já preenche pelo CNPJ.
|
|
207
|
+
|
|
208
|
+
### Status
|
|
209
|
+
|
|
210
|
+
```ruby
|
|
211
|
+
Emissaoja::Cliente.new.status # {"ok" => true, "versao" => "...", "motor" => "ok", "ambiente" => "producao", ...}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
`status` não usa a chave.
|
|
215
|
+
|
|
216
|
+
## Erros
|
|
217
|
+
|
|
218
|
+
Toda resposta fora de `2xx` vira `Emissaoja::Erro`. Decida pelo `code`, nunca pelo texto da mensagem:
|
|
219
|
+
|
|
220
|
+
```ruby
|
|
221
|
+
begin
|
|
222
|
+
ej.notas.emitir("pedido-0002", tomador_tipo: "pj", tomador_id: pj["id"], valor: 100)
|
|
223
|
+
rescue Emissaoja::Erro => e
|
|
224
|
+
case e.code
|
|
225
|
+
when "nota_bloqueada"
|
|
226
|
+
e.bloqueios.each { |b| puts "#{b["code"]}: #{b["mensagem"]} (#{b["acao"]})" } # o que falta no cadastro
|
|
227
|
+
when "limite_notas"
|
|
228
|
+
puts "O limite do plano no mês acabou: https://emissaoja.com.br/#precos"
|
|
229
|
+
else
|
|
230
|
+
warn "#{e.status} #{e.code}: #{e.message} (request_id #{e.request_id})"
|
|
231
|
+
raise
|
|
232
|
+
end
|
|
233
|
+
end
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
`e.status` é o status HTTP (0 para erro local, de rede ou de tempo); `e.extras` traz os outros campos do corpo (`bloqueios`, `nota_igual_recente`, `pedido_id`, `retry_after`, `details`...); `e.request_id` é o cabeçalho `x-request-id`, útil para falar com o suporte.
|
|
237
|
+
|
|
238
|
+
| `code` | HTTP | O que fazer |
|
|
239
|
+
| --- | --- | --- |
|
|
240
|
+
| `chave_invalida` | 401, ou 0 sem chave | Confira a chave ou a variável `EMISSAOJA_KEY`: `ej_live_` em produção, `ej_test_` no sandbox |
|
|
241
|
+
| `validation_error`, `valor_invalido`, `tomador_obrigatorio`, `cnpj_invalido` | 400 | Corrija o campo indicado na mensagem (e em `e.extras["details"]`, quando vier) |
|
|
242
|
+
| `chave_idempotencia_invalida` | 0 (conferida aqui) ou 400 | Use uma referência de 8 a 64 caracteres: letras, números, `_` e `-` |
|
|
243
|
+
| `limite_notas` | 402 | O limite do plano no mês acabou; veja os [planos](https://emissaoja.com.br/#precos) |
|
|
244
|
+
| `tomador_nao_encontrado`, `servico_nao_encontrado`, `nota_nao_encontrada`, `pedido_nao_encontrado` | 404 | Confira o id (e o tipo `pj`/`pf` ou a origem `local`/`importada`) |
|
|
245
|
+
| `sem_empresa` | 409 | Conecte a empresa com `ej.empresa.conectar` |
|
|
246
|
+
| `aceite_pendente` | 409 | Aceite os termos no [app](https://emissaoja.com.br/app) |
|
|
247
|
+
| `possivel_duplicada`, `emissao_repetida_recente` | 409 | Nota igual recente: veja a seção abaixo |
|
|
248
|
+
| `chave_idempotencia_conflito` | 409 | A referência já foi usada numa nota com outros dados (`e.extras["pedido_id"]` é o pedido original): para outra nota, use outra referência |
|
|
249
|
+
| `incerta_pendente` | 409 | Há uma nota igual incerta (`e.extras["pedido_id"]`): confira com `ej.emissoes.conferir` antes de emitir de novo |
|
|
250
|
+
| `ultimo_servico_ativo` | 409 | O último serviço ativo não pode ser desativado |
|
|
251
|
+
| `nota_bloqueada` | 422 | A nota não pode sair assim: cada item de `e.bloqueios` traz `code`, `mensagem` e `acao` |
|
|
252
|
+
| `rate_limited` | 429 | Limite por minuto: espere `e.extras["retry_after"]` segundos e repita |
|
|
253
|
+
| `fila_indisponivel` | 503 | Repita `emitir` com a **mesma** referência |
|
|
254
|
+
| `motor_indisponivel`, `receita_indisponivel` | 503 | Portal ou serviço fora do ar: tente de novo mais tarde |
|
|
255
|
+
| `rede`, `tempo_esgotado` | 0 | Sem resposta da API: repita (em `emitir`, com a mesma referência). Em `aguardar`, o pedido continua: consulte depois com `ej.emissoes.obter(e.extras["pedido_id"])` |
|
|
256
|
+
|
|
257
|
+
**A biblioteca não repete chamadas sozinha.** Emitir tem efeito fiscal: quem decide repetir é o seu código, sempre com a mesma referência, e a API garante que a mesma referência nunca emite duas vezes.
|
|
258
|
+
|
|
259
|
+
## Idempotência e nota em dobro
|
|
260
|
+
|
|
261
|
+
- **Referência.** Cada nota que você quer emitir tem uma referência sua (o id do pedido de venda, por exemplo), de 8 a 64 caracteres: letras, números, `_` e `-`. A gem confere o formato antes de chamar a API e a envia no cabeçalho `Idempotency-Key`. Repetir `emitir` com a mesma referência devolve o mesmo pedido, com `"repetido" => true`, e nunca emite duas vezes. Por isso, depois de falha de rede, `tempo_esgotado` ou `503 fila_indisponivel`, repita com a **mesma** referência.
|
|
262
|
+
- **`possivel_duplicada`.** Já saiu hoje uma nota igual (mesmo tomador, valor e competência), descrita em `e.extras["nota_igual_recente"]`. Se for mesmo outra nota, repita com `permitir_repetida_de:` igual ao `pedido_id` informado.
|
|
263
|
+
- **`emissao_repetida_recente`.** A mesma nota foi pedida há menos de 2 minutos. Se for mesmo outra, repita com `confirmo_repeticao: true`.
|
|
264
|
+
|
|
265
|
+
```ruby
|
|
266
|
+
referencia = format("venda-%08d", venda.id) # a mesma venda gera sempre a mesma referência
|
|
267
|
+
campos = { tomador_tipo: "pj", tomador_id: tomador_id, valor: venda.total, descricao: venda.descricao }
|
|
268
|
+
|
|
269
|
+
tentativas = 0
|
|
270
|
+
begin
|
|
271
|
+
r = ej.notas.emitir(referencia, **campos)
|
|
272
|
+
rescue Emissaoja::Erro => e
|
|
273
|
+
tentativas += 1
|
|
274
|
+
raise unless %w[rede tempo_esgotado fila_indisponivel].include?(e.code) && tentativas < 3
|
|
275
|
+
|
|
276
|
+
sleep(2 * tentativas)
|
|
277
|
+
retry # mesma referência: se o pedido já tinha sido criado, volta o mesmo
|
|
278
|
+
end
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Quando a API avisa de nota igual e a pessoa confirma que é mesmo outra nota:
|
|
282
|
+
|
|
283
|
+
```ruby
|
|
284
|
+
begin
|
|
285
|
+
r = ej.notas.emitir(referencia, **campos)
|
|
286
|
+
rescue Emissaoja::Erro => e
|
|
287
|
+
raise unless e.code == "possivel_duplicada" && confirmado_pela_pessoa?(e.extras["nota_igual_recente"])
|
|
288
|
+
|
|
289
|
+
r = ej.notas.emitir(referencia, **campos, permitir_repetida_de: e.extras["nota_igual_recente"]["pedido_id"])
|
|
290
|
+
end
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
## Rails
|
|
294
|
+
|
|
295
|
+
```ruby
|
|
296
|
+
# config/initializers/emissaoja.rb
|
|
297
|
+
EMISSAOJA = Emissaoja::Cliente.new(
|
|
298
|
+
chave: Rails.application.credentials.dig(:emissaoja, :chave), # nil: lê EMISSAOJA_KEY na primeira chamada
|
|
299
|
+
base_url: Rails.env.production? ? Emissaoja::BASE_PRODUCAO : Emissaoja::BASE_SANDBOX
|
|
300
|
+
)
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
A chave fica nas credentials (`bin/rails credentials:edit`):
|
|
304
|
+
|
|
305
|
+
```yaml
|
|
306
|
+
emissaoja:
|
|
307
|
+
chave: ej_live_...
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Em desenvolvimento e teste, use uma chave `ej_test_` do sandbox (credentials por ambiente ou `EMISSAOJA_KEY`). Como a chave só é lida na primeira chamada, subir a aplicação sem ela (por exemplo, no `assets:precompile`) não falha. O cliente não guarda conexão nem estado mutável: a mesma instância serve todas as threads do Puma e do Sidekiq.
|
|
311
|
+
|
|
312
|
+
Emitir num job, repetindo só o que é passageiro:
|
|
313
|
+
|
|
314
|
+
```ruby
|
|
315
|
+
# app/jobs/emitir_nota_job.rb
|
|
316
|
+
class EmitirNotaJob < ApplicationJob
|
|
317
|
+
PASSAGEIROS = %w[rede tempo_esgotado rate_limited fila_indisponivel motor_indisponivel].freeze
|
|
318
|
+
|
|
319
|
+
# Só os erros passageiros chegam aqui (veja o rescue): o job repete com a MESMA referência
|
|
320
|
+
retry_on Emissaoja::Erro, wait: 30.seconds, attempts: 5
|
|
321
|
+
|
|
322
|
+
def perform(venda_id)
|
|
323
|
+
venda = Venda.find(venda_id)
|
|
324
|
+
r = EMISSAOJA.notas.emitir(
|
|
325
|
+
format("venda-%08d", venda.id),
|
|
326
|
+
tomador_tipo: venda.tomador_tipo,
|
|
327
|
+
tomador_id: venda.tomador_id,
|
|
328
|
+
valor: venda.total, # BigDecimal vai como número
|
|
329
|
+
descricao: venda.descricao
|
|
330
|
+
)
|
|
331
|
+
pedido = EMISSAOJA.notas.aguardar(r["pedido"]["id"])["pedido"]
|
|
332
|
+
venda.update!(nfse_estado: pedido["estado"], nfse_numero: pedido["numero"])
|
|
333
|
+
rescue Emissaoja::Erro => e
|
|
334
|
+
raise if PASSAGEIROS.include?(e.code)
|
|
335
|
+
|
|
336
|
+
venda.update!(nfse_estado: "erro", nfse_erro: e.code) # nota_bloqueada, limite_notas...: precisa de alguém
|
|
337
|
+
end
|
|
338
|
+
end
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
`aguardar` ocupa o worker até o pedido terminar (no máximo `timeout:`, padrão 180 s). Com muitas notas, você pode emitir num job e consultar `EMISSAOJA.emissoes.obter(id)` em outro, agendado com `proxima_consulta_ms`.
|
|
342
|
+
|
|
343
|
+
## Testes no seu projeto
|
|
344
|
+
|
|
345
|
+
Troque o transporte HTTP por um lambda e nada sai da máquina:
|
|
346
|
+
|
|
347
|
+
```ruby
|
|
348
|
+
falso = lambda do |metodo, url, cabecalhos, corpo, timeout|
|
|
349
|
+
[202, { "content-type" => "application/json" }, '{"pedido":{"id":"p1","estado":"na_fila"}}']
|
|
350
|
+
end
|
|
351
|
+
ej = Emissaoja::Cliente.new(chave: "ej_test_falsa", transporte: falso, dormir: ->(_segundos) {})
|
|
352
|
+
ej.notas.emitir("pedido-0001", tomador_tipo: "pj", tomador_id: "t1", valor: 10)["pedido"]["estado"] # "na_fila"
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
O transporte recebe `(metodo, url, cabecalhos, corpo, timeout)` e devolve `[status, cabecalhos, corpo]`; `dormir` recebe os segundos de espera dos métodos `aguardar`. Para testar contra a API de verdade, use o sandbox.
|
|
356
|
+
|
|
357
|
+
## Limites
|
|
358
|
+
|
|
359
|
+
- 60 chamadas por minuto por chave; emissões, 10 por minuto; buscas e catálogo, 120 por minuto; consulta de CNPJ, 30 por minuto. Acima disso, `429 rate_limited`.
|
|
360
|
+
- Plano Grátis: 1 nota por mês. A nota conta quando o Emissor Nacional aceita o pedido; recusada não conta. Planos em [emissaoja.com.br/#precos](https://emissaoja.com.br/#precos).
|
|
361
|
+
- Uma conta tem uma empresa. Para várias empresas, uma conta e uma chave por empresa.
|
|
362
|
+
|
|
363
|
+
## Perguntas frequentes
|
|
364
|
+
|
|
365
|
+
**Precisa de certificado digital?** Não. O emissaoja entra no Emissor Nacional com o CNPJ e a senha do próprio portal.
|
|
366
|
+
|
|
367
|
+
**Funciona para MEI?** Sim. Atende MEI, ME e EPP optantes pelo Simples Nacional. O CNPJ da empresa vai só com números (o CNPJ alfanumérico ainda não é aceito para a empresa).
|
|
368
|
+
|
|
369
|
+
**Tem ambiente de testes?** Sim: o sandbox (`Emissaoja::BASE_SANDBOX`), com o Emissor Nacional simulado, empresas e tomadores de exemplo e chaves `ej_test_`. Nada vai ao fisco e nada é cobrado.
|
|
370
|
+
|
|
371
|
+
**Quanto custa?** A gem é gratuita (licença MIT). A API tem o plano Grátis, com 1 nota por mês, e planos pagos em [emissaoja.com.br/#precos](https://emissaoja.com.br/#precos). O sandbox não tem custo.
|
|
372
|
+
|
|
373
|
+
**Tem webhook?** Ainda não. Acompanhe o pedido com `ej.notas.aguardar`, que consulta `GET /v1/emissoes/{id}` no ritmo de `proxima_consulta_ms`.
|
|
374
|
+
|
|
375
|
+
## Links
|
|
376
|
+
|
|
377
|
+
- Documentação: [emissaoja.com.br/docs](https://emissaoja.com.br/docs/) (também em Markdown: [docs.md](https://emissaoja.com.br/docs.md))
|
|
378
|
+
- OpenAPI 3.1: [emissaoja.com.br/v1/openapi.json](https://emissaoja.com.br/v1/openapi.json)
|
|
379
|
+
- Para IAs: [emissaoja.com.br/llms.txt](https://emissaoja.com.br/llms.txt)
|
|
380
|
+
- MCP (emitir pelo seu assistente de IA): `https://emissaoja.com.br/mcp`
|
|
381
|
+
- Status da API: [emissaoja.com.br/v1/status](https://emissaoja.com.br/v1/status)
|
|
382
|
+
- Suporte: [suporte@emissaoja.com.br](mailto:suporte@emissaoja.com.br)
|
|
383
|
+
- Código-fonte, issues e changelog: [github.com/Easymovel/emissaoja-ruby](https://github.com/Easymovel/emissaoja-ruby)
|
|
384
|
+
|
|
385
|
+
Bibliotecas oficiais em outras linguagens:
|
|
386
|
+
|
|
387
|
+
- JavaScript e TypeScript: npm [`emissaoja`](https://www.npmjs.com/package/emissaoja)
|
|
388
|
+
- Python: PyPI [`emissaoja`](https://pypi.org/project/emissaoja/)
|
|
389
|
+
- PHP: Packagist [`emissaoja/emissaoja`](https://packagist.org/packages/emissaoja/emissaoja)
|
|
390
|
+
- .NET: NuGet [`Emissaoja`](https://www.nuget.org/packages/Emissaoja)
|
|
391
|
+
- Go: [`emissaoja.com.br/go`](https://pkg.go.dev/emissaoja.com.br/go)
|
|
392
|
+
- Ruby: RubyGems [`emissaoja`](https://rubygems.org/gems/emissaoja) (esta gem)
|
|
393
|
+
- n8n: [`n8n-nodes-emissaoja`](https://www.npmjs.com/package/n8n-nodes-emissaoja)
|
|
394
|
+
|
|
395
|
+
## Licença
|
|
396
|
+
|
|
397
|
+
[MIT](LICENSE). Copyright (c) 2026 BINOBO LTDA (CNPJ 68.649.497/0001-07), Belo Horizonte (MG).
|
|
398
|
+
|
|
399
|
+
## In English
|
|
400
|
+
|
|
401
|
+
**emissaoja** is a Brazilian NFS-e (service invoice) API, and this is its official Ruby gem. It issues invoices through the national Emissor Nacional using the company's CNPJ and portal password, with no digital certificate, for MEI and Simples Nacional companies. It has no runtime dependencies (Net::HTTP and JSON from the standard library), runs on Ruby 3.0+ and Rails, sends an idempotency key with every invoice and downloads the PDF and XML. Try it for free in the sandbox at [sandbox.emissaoja.com.br](https://sandbox.emissaoja.com.br); the documentation (in Portuguese) is at [emissaoja.com.br/docs](https://emissaoja.com.br/docs/).
|
|
402
|
+
|
|
403
|
+
---
|
|
404
|
+
|
|
405
|
+
O emissaoja é um serviço privado e não tem vínculo com a Receita Federal nem com o Emissor Nacional.
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
require "uri"
|
|
5
|
+
|
|
6
|
+
module Emissaoja
|
|
7
|
+
# Cliente da API do emissaoja (https://emissaoja.com.br/docs/).
|
|
8
|
+
#
|
|
9
|
+
# ej = Emissaoja::Cliente.new(chave: ENV["EMISSAOJA_KEY"], base_url: Emissaoja::BASE_SANDBOX)
|
|
10
|
+
# r = ej.notas.emitir("pedido-0001", tomador_tipo: "pj", tomador_id: id, valor: 1500, descricao: "Consultoria")
|
|
11
|
+
# ej.notas.aguardar(r["pedido"]["id"])
|
|
12
|
+
#
|
|
13
|
+
# Recursos: empresa, tomadores, servicos, notas, emissoes, operacoes e cnpj. As respostas são Hash com chaves
|
|
14
|
+
# String (o JSON da API, em snake_case) e os erros viram Emissaoja::Erro. O cliente não guarda conexão aberta
|
|
15
|
+
# nem estado além da chave: uma instância pode ser compartilhada entre threads (Puma, Sidekiq).
|
|
16
|
+
class Cliente
|
|
17
|
+
# @return [String] URL base da API, sem barra no fim
|
|
18
|
+
attr_reader :base_url
|
|
19
|
+
|
|
20
|
+
# @return [Numeric] segundos para conectar, para enviar e para cada leitura
|
|
21
|
+
attr_reader :timeout
|
|
22
|
+
|
|
23
|
+
# @return [Recursos::Empresa] conexão com o Emissor Nacional e configuração fiscal
|
|
24
|
+
attr_reader :empresa
|
|
25
|
+
|
|
26
|
+
# @return [Recursos::Tomadores] clientes da nota (pj e pf)
|
|
27
|
+
attr_reader :tomadores
|
|
28
|
+
|
|
29
|
+
# @return [Recursos::Servicos] serviços da empresa e catálogo nacional
|
|
30
|
+
attr_reader :servicos
|
|
31
|
+
|
|
32
|
+
# @return [Recursos::Notas] emitir, aguardar, listar, PDF, XML e cancelar
|
|
33
|
+
attr_reader :notas
|
|
34
|
+
|
|
35
|
+
# @return [Recursos::Emissoes] pedidos de emissão
|
|
36
|
+
attr_reader :emissoes
|
|
37
|
+
|
|
38
|
+
# @return [Recursos::Operacoes] operações assíncronas (cancelamento)
|
|
39
|
+
attr_reader :operacoes
|
|
40
|
+
|
|
41
|
+
# @return [Recursos::Cnpj] consulta de CNPJ
|
|
42
|
+
attr_reader :cnpj
|
|
43
|
+
|
|
44
|
+
# @param chave [String, nil] chave da API (ej_live_ em produção, ej_test_ no sandbox). Sem ela, o cliente lê
|
|
45
|
+
# a variável de ambiente EMISSAOJA_KEY na primeira chamada que precisa da chave (não aqui no construtor).
|
|
46
|
+
# @param base_url [String, nil] BASE_PRODUCAO (padrão) ou BASE_SANDBOX
|
|
47
|
+
# @param timeout [Numeric, nil] segundos (padrão 30)
|
|
48
|
+
# @param transporte [#call, nil] objeto com call(metodo, url, cabecalhos, corpo, timeout) que devolve
|
|
49
|
+
# [status, cabecalhos, corpo]; padrão TransporteNetHTTP. Útil nos testes.
|
|
50
|
+
# @param dormir [#call, nil] objeto com call(segundos), usado entre as consultas dos métodos aguardar;
|
|
51
|
+
# padrão Kernel.sleep. Nos testes, um lambda que não dorme.
|
|
52
|
+
def initialize(chave: nil, base_url: BASE_PRODUCAO, timeout: 30, transporte: nil, dormir: nil)
|
|
53
|
+
@chave = chave
|
|
54
|
+
@base_url = (base_url || BASE_PRODUCAO).to_s.sub(%r{/+\z}, "")
|
|
55
|
+
@timeout = timeout || 30
|
|
56
|
+
@transporte = transporte || TransporteNetHTTP.new
|
|
57
|
+
@dormir = dormir || ->(segundos) { Kernel.sleep(segundos) }
|
|
58
|
+
unless %r{\Ahttps?://[^/]}i.match?(@base_url)
|
|
59
|
+
raise ArgumentError, "base_url precisa começar com https:// (ou http://): #{@base_url.inspect}"
|
|
60
|
+
end
|
|
61
|
+
raise ArgumentError, "transporte precisa responder a call(metodo, url, cabecalhos, corpo, timeout)" unless @transporte.respond_to?(:call)
|
|
62
|
+
raise ArgumentError, "dormir precisa responder a call(segundos)" unless @dormir.respond_to?(:call)
|
|
63
|
+
|
|
64
|
+
@empresa = Recursos::Empresa.new(self)
|
|
65
|
+
@tomadores = Recursos::Tomadores.new(self)
|
|
66
|
+
@servicos = Recursos::Servicos.new(self)
|
|
67
|
+
@notas = Recursos::Notas.new(self)
|
|
68
|
+
@emissoes = Recursos::Emissoes.new(self)
|
|
69
|
+
@operacoes = Recursos::Operacoes.new(self)
|
|
70
|
+
@cnpj = Recursos::Cnpj.new(self)
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
# A chave em uso. Sem chave no construtor, lê EMISSAOJA_KEY agora (na primeira chamada que precisa dela).
|
|
74
|
+
# @return [String]
|
|
75
|
+
# @raise [Erro] code "chave_invalida" (status 0) sem chave e sem EMISSAOJA_KEY; nada é enviado à API
|
|
76
|
+
def chave
|
|
77
|
+
@chave = texto_ou_nil(@chave) || texto_ou_nil(ENV["EMISSAOJA_KEY"])
|
|
78
|
+
return @chave if @chave
|
|
79
|
+
|
|
80
|
+
raise Erro.new(0, { "code" => "chave_invalida",
|
|
81
|
+
"message" => "Informe a chave: Emissaoja::Cliente.new(chave: ...) ou a variável de ambiente EMISSAOJA_KEY." })
|
|
82
|
+
end
|
|
83
|
+
|
|
84
|
+
# GET /v1/status: versão, estado do motor e ambiente ("producao" ou "sandbox"). Não usa a chave.
|
|
85
|
+
# @return [Hash] {"ok" => true, "versao" => "...", "motor" => "ok", "ambiente" => "producao", "tempo" => "..."}
|
|
86
|
+
def status
|
|
87
|
+
requisitar_json("GET", "/v1/status", sem_chave: true)
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
# Não mostra a chave: inspect aparece em logs, no console e em mensagens de erro.
|
|
91
|
+
def inspect
|
|
92
|
+
"#<#{self.class.name} base_url=#{@base_url.inspect}>"
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
# Chamada que responde JSON. Uso interno dos recursos.
|
|
96
|
+
# @api private
|
|
97
|
+
# @return [Hash] o corpo da resposta ({} quando vazio ou quando não é um objeto JSON)
|
|
98
|
+
# @raise [Erro] resposta fora de 2xx, falha de rede ou tempo esgotado
|
|
99
|
+
def requisitar_json(metodo, caminho, corpo: nil, query: nil, cabecalhos: nil, sem_chave: false)
|
|
100
|
+
status, cabecalhos_resposta, bruto = requisitar(metodo, caminho, corpo: corpo, query: query,
|
|
101
|
+
cabecalhos: cabecalhos, sem_chave: sem_chave)
|
|
102
|
+
texto = texto_utf8(bruto)
|
|
103
|
+
dados = ler_json(texto)
|
|
104
|
+
raise erro_http(status, cabecalhos_resposta, texto, dados) unless sucesso?(status)
|
|
105
|
+
|
|
106
|
+
dados.is_a?(Hash) ? dados : {}
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
# GET que responde bytes (PDF, XML). Uso interno dos recursos.
|
|
110
|
+
# @api private
|
|
111
|
+
# @return [String] o corpo, em ASCII-8BIT
|
|
112
|
+
# @raise [Erro] resposta fora de 2xx, falha de rede ou tempo esgotado
|
|
113
|
+
def requisitar_bytes(caminho)
|
|
114
|
+
status, cabecalhos_resposta, bruto = requisitar("GET", caminho)
|
|
115
|
+
unless sucesso?(status)
|
|
116
|
+
texto = texto_utf8(bruto)
|
|
117
|
+
raise erro_http(status, cabecalhos_resposta, texto, ler_json(texto))
|
|
118
|
+
end
|
|
119
|
+
bruto.b
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
# Espera entre as consultas dos métodos aguardar. Uso interno dos recursos.
|
|
123
|
+
# @api private
|
|
124
|
+
def esperar(segundos)
|
|
125
|
+
@dormir.call(segundos)
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
private
|
|
129
|
+
|
|
130
|
+
def requisitar(metodo, caminho, corpo: nil, query: nil, cabecalhos: nil, sem_chave: false)
|
|
131
|
+
h = { "Accept" => "application/json", "User-Agent" => "emissaoja-ruby/#{VERSION}" }
|
|
132
|
+
h.merge!(cabecalhos) if cabecalhos
|
|
133
|
+
h["Authorization"] = "Bearer #{chave}" unless sem_chave
|
|
134
|
+
corpo_json = nil
|
|
135
|
+
unless corpo.nil?
|
|
136
|
+
h["Content-Type"] = "application/json"
|
|
137
|
+
corpo_json = JSON.generate(para_json(corpo))
|
|
138
|
+
end
|
|
139
|
+
status, cabecalhos_resposta, bruto = @transporte.call(metodo, montar_url(caminho, query), h, corpo_json, @timeout)
|
|
140
|
+
[Integer(status), normalizar_cabecalhos(cabecalhos_resposta), bruto.to_s]
|
|
141
|
+
end
|
|
142
|
+
|
|
143
|
+
def montar_url(caminho, query)
|
|
144
|
+
url = @base_url + caminho
|
|
145
|
+
pares = pares_da_query(query)
|
|
146
|
+
pares.empty? ? url : "#{url}?#{URI.encode_www_form(pares)}"
|
|
147
|
+
end
|
|
148
|
+
|
|
149
|
+
# Omite nil e vazios. Lista vira texto separado por vírgula (ex.: estados: %w[na_fila emitindo]).
|
|
150
|
+
def pares_da_query(query)
|
|
151
|
+
(query || {}).each_with_object([]) do |(nome, valor), pares|
|
|
152
|
+
valor = valor.join(",") if valor.is_a?(Array)
|
|
153
|
+
next if valor.nil? || valor.to_s.empty?
|
|
154
|
+
|
|
155
|
+
pares << [nome.to_s, valor.to_s]
|
|
156
|
+
end
|
|
157
|
+
end
|
|
158
|
+
|
|
159
|
+
# Chaves viram String; BigDecimal e Rational viram Float (sem isso o JSON levaria texto, como "0.15e4").
|
|
160
|
+
def para_json(valor)
|
|
161
|
+
case valor
|
|
162
|
+
when Hash then valor.each_with_object({}) { |(nome, item), h| h[nome.to_s] = para_json(item) }
|
|
163
|
+
when Array then valor.map { |item| para_json(item) }
|
|
164
|
+
when Integer, Float then valor
|
|
165
|
+
when Numeric then valor.to_f
|
|
166
|
+
else valor
|
|
167
|
+
end
|
|
168
|
+
end
|
|
169
|
+
|
|
170
|
+
def normalizar_cabecalhos(cabecalhos)
|
|
171
|
+
(cabecalhos || {}).each_with_object({}) do |(nome, valor), h|
|
|
172
|
+
h[nome.to_s.downcase] = valor.is_a?(Array) ? valor.join(", ") : valor
|
|
173
|
+
end
|
|
174
|
+
end
|
|
175
|
+
|
|
176
|
+
def texto_utf8(bruto)
|
|
177
|
+
String.new(bruto, encoding: Encoding::UTF_8).scrub
|
|
178
|
+
end
|
|
179
|
+
|
|
180
|
+
def ler_json(texto)
|
|
181
|
+
return nil if texto.strip.empty?
|
|
182
|
+
|
|
183
|
+
JSON.parse(texto)
|
|
184
|
+
rescue JSON::ParserError
|
|
185
|
+
nil
|
|
186
|
+
end
|
|
187
|
+
|
|
188
|
+
def erro_http(status, cabecalhos, texto, dados)
|
|
189
|
+
corpo = dados.is_a?(Hash) ? dados : { "message" => resumo(texto, status) }
|
|
190
|
+
Erro.new(status, corpo, request_id: cabecalhos["x-request-id"])
|
|
191
|
+
end
|
|
192
|
+
|
|
193
|
+
# Corpo que não é JSON (página de proxy, por exemplo): até 200 caracteres do texto.
|
|
194
|
+
def resumo(texto, status)
|
|
195
|
+
limpo = texto.strip
|
|
196
|
+
limpo.empty? ? "HTTP #{status}" : limpo[0, 200]
|
|
197
|
+
end
|
|
198
|
+
|
|
199
|
+
def sucesso?(status)
|
|
200
|
+
status >= 200 && status <= 299
|
|
201
|
+
end
|
|
202
|
+
|
|
203
|
+
def texto_ou_nil(valor)
|
|
204
|
+
texto = valor.to_s.strip
|
|
205
|
+
texto.empty? ? nil : texto
|
|
206
|
+
end
|
|
207
|
+
end
|
|
208
|
+
end
|