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 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