emissaoja 0.1.0__tar.gz

emissaoja-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.env

emissaoja-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-11-05
+
+Primeira versão pública do cliente oficial da API do emissaoja para Python.
+
+- Recursos `empresa`, `tomadores`, `servicos`, `notas`, `emissoes`, `operacoes`, `cnpj` e `status()`.
+- `notas.emitir` exige `referencia` (vira o cabeçalho `Idempotency-Key`) e valida o formato antes de chamar a API.
+- `notas.aguardar`, `empresa.aguardar_credencial` e `operacoes.aguardar` respeitam `proxima_consulta_ms`.
+- Erros da API viram `EmissaojaErro` com `status`, `code`, `extras` e `request_id`; timeout e falha de conexão viram
+  `tempo_esgotado` e `rede`.
+- Constantes `BASE_PRODUCAO` e `BASE_SANDBOX`. Só biblioteca padrão, Python 3.9+.

emissaoja-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BINOBO LTDA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

emissaoja-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.5
+Name: emissaoja
+Version: 0.1.0
+Summary: API de NFS-e nacional para Python: emita nota fiscal de serviço eletrônica no Emissor Nacional sem certificado digital (MEI e Simples Nacional). PDF, XML, tomadores. Cliente oficial do emissaoja.
+Project-URL: Homepage, https://emissaoja.com.br
+Project-URL: Documentation, https://emissaoja.com.br/docs/
+Project-URL: Source, https://github.com/Easymovel/emissaoja-py
+Project-URL: Changelog, https://github.com/Easymovel/emissaoja-py/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Easymovel/emissaoja-py/issues
+Author: BINOBO LTDA
+License: MIT
+License-File: LICENSE
+Keywords: api nfse,brasil,brazil,danfse,emissaoja,emissor nacional,emitir nfse,invoice,iss,mei,nfs-e,nfse,nfse nacional,nota fiscal,nota fiscal de servico,nota fiscal eletronica,sem certificado digital,simples nacional
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Portuguese (Brazilian)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# emissaoja: API de NFS-e nacional para Python
+
+[![PyPI](https://img.shields.io/pypi/v/emissaoja)](https://pypi.org/project/emissaoja/) [![CI](https://github.com/Easymovel/emissaoja-py/actions/workflows/ci.yml/badge.svg)](https://github.com/Easymovel/emissaoja-py/actions/workflows/ci.yml) [![Licença MIT](https://img.shields.io/badge/licen%C3%A7a-MIT-blue)](LICENSE)
+
+Cliente oficial da **[API do emissaoja](https://emissaoja.com.br/docs/)** para emitir **NFS-e (Nota Fiscal de Serviço eletrônica) no Emissor Nacional** (nfse.gov.br) a partir do seu sistema em Python, **sem certificado digital**: o emissaoja entra no portal com o CNPJ e a senha da própria empresa. Feito para **MEI e empresas do Simples Nacional**. Cadastre tomadores pelo CNPJ (nome e endereço vêm da Receita Federal), emita, acompanhe a autorização, baixe o **PDF (DANFSe) e o XML** e cancele notas.
+
+- **Só biblioteca padrão** (urllib), Python 3.9+, com `py.typed`.
+- **Idempotência embutida:** toda emissão leva uma `referencia` sua, que vira o cabeçalho `Idempotency-Key`. Repetir a mesma referência nunca emite duas notas.
+- `notas.aguardar()` acompanha o pedido até `autorizada`, `recusada` ou `incerta`, no ritmo que a API indica (`proxima_consulta_ms`).
+- Erros com `code` estável (`nota_bloqueada`, `limite_notas`, `possivel_duplicada`…) e o que falta resolver em `extras["bloqueios"]`.
+- **Sandbox grátis** com Emissor Nacional simulado: teste o fluxo inteiro sem efeito fiscal.
+
+## Instalação
+
+```bash
+pip install emissaoja
+```
+
+Crie a conta com o Google em [emissaoja.com.br](https://emissaoja.com.br/?origem=lib-pypi) e gere a chave em **Conta → API** (ela aparece uma vez; prefixo `ej_live_`). Guarde a chave no servidor:
+
+```bash
+export EMISSAOJA_KEY=ej_live_...
+```
+
+## Teste no sandbox em 2 minutos
+
+O sandbox (`https://sandbox.emissaoja.com.br`) é o mesmo emissaoja com um **Emissor Nacional simulado**: nada ali existe no fisco e nada é cobrado. Entre com o Google, crie uma chave `ej_test_` em Conta → API e rode:
+
+```python
+from emissaoja import BASE_SANDBOX, Emissaoja
+
+ej = Emissaoja(base_url=BASE_SANDBOX)  # lê a chave de EMISSAOJA_KEY; ou Emissaoja("ej_test_...", base_url=...)
+
+# 1. Conectar a empresa (uma vez). 11111111000191 é um MEI de exemplo pronto para emitir; qualquer senha serve.
+ej.empresa.conectar("11111111000191", "senha-de-teste")
+ej.empresa.aguardar_credencial()
+
+# 2. Tomador pelo CNPJ: nome e endereço vêm da Receita Federal
+tomador = ej.tomadores.criar("12345678000195")["tomador"]
+
+# 3. Emitir (prévia + emissão num passo). A referência é o seu id da nota.
+pedido = ej.notas.emitir(
+    "pedido-2026-11-0001",
+    tomador["tipo"],
+    tomador["id"],
+    1500,
+    descricao="Consultoria em marketing digital - novembro/2026",
+)["pedido"]
+
+# 4. Acompanhar até autorizada | recusada | incerta
+final = ej.notas.aguardar(pedido["id"])["pedido"]
+print(final["estado"], final.get("numero"), final.get("chave_acesso"))
+
+# 5. PDF (DANFSe) e XML
+if final["estado"] == "autorizada":
+    pdf = ej.notas.pdf(final["nota"]["origem"], final["nota"]["id"])  # bytes
+    xml = ej.notas.xml(final["nota"]["origem"], final["nota"]["id"])  # str
+```
+
+Valores com significado no sandbox: `13.13` gera uma nota **incerta** que `ej.emissoes.conferir(id)` resolve como autorizada, `77.77` uma incerta que não saiu, `66.66` uma **recusada** pelo fisco e `99.99` um **bloqueio** já na prévia (`422 nota_bloqueada`). Outras empresas de exemplo: `22222222000191` (ME que pede a alíquota do Simples antes de emitir), `33333333000191` (MEI sem notas anteriores) e `44444444000191` (bloqueada). A senha `errada` simula senha recusada pelo portal. Exemplo completo em [`exemplos/emitir_nfse_sandbox.py`](exemplos/emitir_nfse_sandbox.py).
+
+## Em produção
+
+`Emissaoja()` usa `https://emissaoja.com.br` e lê `EMISSAOJA_KEY`. A chave `ej_live_` vale para a empresa e o plano da conta que a criou; chaves `ej_test_` só valem no sandbox.
+
+> **A chave é secreta.** Use o cliente só no servidor (Django, Flask, FastAPI, filas, scripts). Quem tiver a chave emite notas em nome da empresa.
+
+Com Django ou FastAPI, crie um cliente por processo e reutilize (ele não guarda estado entre chamadas):
+
+```python
+# settings.py / config.py
+from emissaoja import Emissaoja
+
+EMISSAOJA = Emissaoja()  # chave de EMISSAOJA_KEY, lida na primeira chamada
+```
+
+## Empresa: conectar ao Emissor Nacional
+
+```python
+ej.empresa.conectar("11222333000181", "senha-do-emissor-nacional")  # 202, verificação em segundo plano
+tentativa = ej.empresa.aguardar_credencial()["tentativa"]
+# tentativa["proximo_passo"]: configurando | pronto | corrigir_senha | tentar_mais_tarde | redefinir_no_portal | suporte
+
+empresa = ej.empresa.obter()  # empresa["onboarding"]["estado"]: configurando → perguntas → pronto
+if empresa["onboarding"]["estado"] == "perguntas":
+    print(ej.empresa.onboarding())  # o que o cadastro fiscal não respondeu sozinho
+    ej.empresa.fiscal(aliquota_simples=6)  # só com o valor que a empresa informou
+```
+
+A senha é conferida no portal e nunca volta em resposta. O portal bloqueia a conta da empresa depois de algumas senhas erradas: a API limita a 3 tentativas erradas por CNPJ em 24 h.
+
+## Tomadores e serviços
+
+```python
+ej.tomadores.criar("52998224725", nome="Maria da Silva")  # CPF precisa do nome
+ej.tomadores.listar(busca="alfa", ordem="recentes")
+ej.tomadores.buscar("12.345.678")
+
+itens = ej.servicos.catalogo("consultoria")["itens"]  # código nacional (cTribNac) por texto
+ej.servicos.criar(descricao="Consultoria", c_trib_nac=itens[0]["c_trib_nac"], trib_issqn="tributavel", retem_iss=False)
+ej.servicos.listar()  # emitir sem servico_id usa o principal
+```
+
+## Notas
+
+```python
+notas = ej.notas.listar(periodo="mes_atual", situacao="emitidas")["notas"]
+operacao = ej.notas.cancelar("local", nota_id, "1", justificativa="Valor digitado errado.")["operacao"]
+ej.operacoes.aguardar(operacao["id"])  # processando → concluida | falhou
+```
+
+Nota não se altera: para corrigir, cancele e emita outra. Nota autorizada e depois cancelada conta no plano; recusada não conta.
+
+## Idempotência e nota em dobro
+
+- Use uma `referencia` por nota que você quer emitir (o id do seu pedido serve; 8 a 64 caracteres: letras, números, `_` e `-`). Repetir a mesma devolve o mesmo `pedido` com `repetido: True`.
+- `503 fila_indisponivel`: repita **com a mesma referência**.
+- `409 possivel_duplicada`: já existe nota igual (tomador, valor e competência) no mesmo dia. Se for mesmo outra nota, repita com `permitir_repetida_de=e.extras["nota_igual_recente"]["pedido_id"]`.
+- `409 emissao_repetida_recente`: mesma nota há menos de 2 minutos. Se for intencional, repita com `confirmo_repeticao=True`.
+- A biblioteca não repete chamadas sozinha: emitir tem efeito fiscal, e quem decide repetir é você.
+
+## Erros
+
+```python
+from emissaoja import EmissaojaErro
+
+try:
+    ej.notas.emitir("pedido-0002", "pj", tomador_id, 100)
+except EmissaojaErro as e:
+    if e.code == "nota_bloqueada":
+        print(e.extras["bloqueios"])  # [{"code", "mensagem", "acao"}]
+    elif e.code == "limite_notas":
+        print("limite do plano no mês")
+    else:
+        print(e.status, e.code, e, e.request_id)
+```
+
+| HTTP | `code` | O que fazer |
+| --- | --- | --- |
+| 400 | `validation_error`, `valor_invalido`, `cnpj_invalido`, `chave_idempotencia_invalida` | Corrigir o campo |
+| 401 | `chave_invalida` | Conferir a chave (ou o ambiente: `ej_test_` só no sandbox) |
+| 402 | `limite_notas` | Limite do plano no mês |
+| 404 | `tomador_nao_encontrado`, `servico_nao_encontrado`, `nota_nao_encontrada`, `pedido_nao_encontrado` | Conferir o id |
+| 409 | `sem_empresa` | Conectar a empresa (`empresa.conectar`) |
+| 409 | `aceite_pendente` | Termos ou Política mudaram: entre no [app](https://emissaoja.com.br/app) e aceite a versão nova; a chave volta a funcionar |
+| 409 | `possivel_duplicada`, `emissao_repetida_recente`, `incerta_pendente` | Ver "Idempotência e nota em dobro" |
+| 422 | `nota_bloqueada` | Resolver `extras["bloqueios"]` |
+| 429 | `rate_limited` | Esperar `Retry-After` |
+| 503 | `motor_indisponivel`, `fila_indisponivel`, `receita_indisponivel` | Tentar de novo (com a mesma referência) |
+| 0 | `rede`, `tempo_esgotado` | Falha de rede ou tempo esgotado no seu lado |
+
+Limites: 60 chamadas por minuto por chave, 10 emissões por minuto e 120 por minuto em buscas e catálogo.
+
+## Referência
+
+| Recurso | Métodos |
+| --- | --- |
+| `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` (dados da Receita Federal) |
+| — | `status()` (sem chave) |
+
+`Emissaoja(chave=None, base_url=BASE_PRODUCAO, timeout=30.0)`. Referência completa da API: [emissaoja.com.br/docs](https://emissaoja.com.br/docs/) e [OpenAPI 3.1](https://emissaoja.com.br/v1/openapi.json).
+
+## Perguntas frequentes
+
+**Precisa de certificado digital?** Não. O emissaoja entra no Emissor Nacional com o CNPJ e a senha do portal da própria empresa, o acesso que o portal oferece a MEI e empresas do Simples Nacional.
+
+**Funciona para MEI?** Sim. O público é MEI, ME e EPP optantes pelo Simples Nacional, em um município que emite pelo Emissor Nacional.
+
+**Tem ambiente de testes?** Sim, o sandbox em `https://sandbox.emissaoja.com.br`, com o Emissor Nacional simulado e empresas de exemplo.
+
+**Quanto custa?** O plano Grátis emite 1 nota por mês; os planos pagos estão em [emissaoja.com.br/#precos](https://emissaoja.com.br/#precos). O sandbox é grátis. Nota recusada não conta.
+
+**Tem webhook?** Ainda não. Acompanhe o pedido com `notas.aguardar()` ou `emissoes.obter()`, que trazem `proxima_consulta_ms`.
+
+## Outras formas de integrar
+
+- Node.js/TypeScript: [`npm install emissaoja`](https://github.com/Easymovel/emissaoja-js) · PHP/Laravel: [`composer require emissaoja/emissaoja`](https://github.com/Easymovel/emissaoja-php) · .NET: [`dotnet add package Emissaoja`](https://github.com/Easymovel/emissaoja-dotnet) · Go: [`go get emissaoja.com.br/go`](https://github.com/Easymovel/emissaoja-go) · Ruby: [`gem install emissaoja`](https://github.com/Easymovel/emissaoja-ruby)
+- n8n: [`n8n-nodes-emissaoja`](https://github.com/Easymovel/n8n-nodes-emissaoja) · WooCommerce: [emissaoja NFS-e para WooCommerce](https://github.com/Easymovel/emissaoja-woocommerce)
+- Assistentes de IA (Claude, ChatGPT, Cursor, VS Code): servidor MCP em `https://emissaoja.com.br/mcp` ([emissaoja-mcp](https://github.com/Easymovel/emissaoja-mcp))
+- Documentação para IAs: [llms.txt](https://emissaoja.com.br/llms.txt) · [docs.md](https://emissaoja.com.br/docs.md)
+
+## In English
+
+Official Python client for the [emissaoja API](https://emissaoja.com.br/docs/): issue Brazilian **NFS-e** (electronic service invoices) through the national **Emissor Nacional** without a digital certificate, for MEI and Simples Nacional companies. Standard library only, typed, idempotent issuing, PDF and XML download, and a free sandbox with a simulated tax authority. The API and the docs are in Portuguese.
+
+---
+
+Suporte: [suporte@emissaoja.com.br](mailto:suporte@emissaoja.com.br). Licença MIT, © 2026 BINOBO LTDA.
+
+O emissaoja é um serviço privado e não tem vínculo com a Receita Federal nem com o Emissor Nacional.

emissaoja-0.1.0/README.md

@@ -0,0 +1,196 @@
+# emissaoja: API de NFS-e nacional para Python
+
+[![PyPI](https://img.shields.io/pypi/v/emissaoja)](https://pypi.org/project/emissaoja/) [![CI](https://github.com/Easymovel/emissaoja-py/actions/workflows/ci.yml/badge.svg)](https://github.com/Easymovel/emissaoja-py/actions/workflows/ci.yml) [![Licença MIT](https://img.shields.io/badge/licen%C3%A7a-MIT-blue)](LICENSE)
+
+Cliente oficial da **[API do emissaoja](https://emissaoja.com.br/docs/)** para emitir **NFS-e (Nota Fiscal de Serviço eletrônica) no Emissor Nacional** (nfse.gov.br) a partir do seu sistema em Python, **sem certificado digital**: o emissaoja entra no portal com o CNPJ e a senha da própria empresa. Feito para **MEI e empresas do Simples Nacional**. Cadastre tomadores pelo CNPJ (nome e endereço vêm da Receita Federal), emita, acompanhe a autorização, baixe o **PDF (DANFSe) e o XML** e cancele notas.
+
+- **Só biblioteca padrão** (urllib), Python 3.9+, com `py.typed`.
+- **Idempotência embutida:** toda emissão leva uma `referencia` sua, que vira o cabeçalho `Idempotency-Key`. Repetir a mesma referência nunca emite duas notas.
+- `notas.aguardar()` acompanha o pedido até `autorizada`, `recusada` ou `incerta`, no ritmo que a API indica (`proxima_consulta_ms`).
+- Erros com `code` estável (`nota_bloqueada`, `limite_notas`, `possivel_duplicada`…) e o que falta resolver em `extras["bloqueios"]`.
+- **Sandbox grátis** com Emissor Nacional simulado: teste o fluxo inteiro sem efeito fiscal.
+
+## Instalação
+
+```bash
+pip install emissaoja
+```
+
+Crie a conta com o Google em [emissaoja.com.br](https://emissaoja.com.br/?origem=lib-pypi) e gere a chave em **Conta → API** (ela aparece uma vez; prefixo `ej_live_`). Guarde a chave no servidor:
+
+```bash
+export EMISSAOJA_KEY=ej_live_...
+```
+
+## Teste no sandbox em 2 minutos
+
+O sandbox (`https://sandbox.emissaoja.com.br`) é o mesmo emissaoja com um **Emissor Nacional simulado**: nada ali existe no fisco e nada é cobrado. Entre com o Google, crie uma chave `ej_test_` em Conta → API e rode:
+
+```python
+from emissaoja import BASE_SANDBOX, Emissaoja
+
+ej = Emissaoja(base_url=BASE_SANDBOX)  # lê a chave de EMISSAOJA_KEY; ou Emissaoja("ej_test_...", base_url=...)
+
+# 1. Conectar a empresa (uma vez). 11111111000191 é um MEI de exemplo pronto para emitir; qualquer senha serve.
+ej.empresa.conectar("11111111000191", "senha-de-teste")
+ej.empresa.aguardar_credencial()
+
+# 2. Tomador pelo CNPJ: nome e endereço vêm da Receita Federal
+tomador = ej.tomadores.criar("12345678000195")["tomador"]
+
+# 3. Emitir (prévia + emissão num passo). A referência é o seu id da nota.
+pedido = ej.notas.emitir(
+    "pedido-2026-11-0001",
+    tomador["tipo"],
+    tomador["id"],
+    1500,
+    descricao="Consultoria em marketing digital - novembro/2026",
+)["pedido"]
+
+# 4. Acompanhar até autorizada | recusada | incerta
+final = ej.notas.aguardar(pedido["id"])["pedido"]
+print(final["estado"], final.get("numero"), final.get("chave_acesso"))
+
+# 5. PDF (DANFSe) e XML
+if final["estado"] == "autorizada":
+    pdf = ej.notas.pdf(final["nota"]["origem"], final["nota"]["id"])  # bytes
+    xml = ej.notas.xml(final["nota"]["origem"], final["nota"]["id"])  # str
+```
+
+Valores com significado no sandbox: `13.13` gera uma nota **incerta** que `ej.emissoes.conferir(id)` resolve como autorizada, `77.77` uma incerta que não saiu, `66.66` uma **recusada** pelo fisco e `99.99` um **bloqueio** já na prévia (`422 nota_bloqueada`). Outras empresas de exemplo: `22222222000191` (ME que pede a alíquota do Simples antes de emitir), `33333333000191` (MEI sem notas anteriores) e `44444444000191` (bloqueada). A senha `errada` simula senha recusada pelo portal. Exemplo completo em [`exemplos/emitir_nfse_sandbox.py`](exemplos/emitir_nfse_sandbox.py).
+
+## Em produção
+
+`Emissaoja()` usa `https://emissaoja.com.br` e lê `EMISSAOJA_KEY`. A chave `ej_live_` vale para a empresa e o plano da conta que a criou; chaves `ej_test_` só valem no sandbox.
+
+> **A chave é secreta.** Use o cliente só no servidor (Django, Flask, FastAPI, filas, scripts). Quem tiver a chave emite notas em nome da empresa.
+
+Com Django ou FastAPI, crie um cliente por processo e reutilize (ele não guarda estado entre chamadas):
+
+```python
+# settings.py / config.py
+from emissaoja import Emissaoja
+
+EMISSAOJA = Emissaoja()  # chave de EMISSAOJA_KEY, lida na primeira chamada
+```
+
+## Empresa: conectar ao Emissor Nacional
+
+```python
+ej.empresa.conectar("11222333000181", "senha-do-emissor-nacional")  # 202, verificação em segundo plano
+tentativa = ej.empresa.aguardar_credencial()["tentativa"]
+# tentativa["proximo_passo"]: configurando | pronto | corrigir_senha | tentar_mais_tarde | redefinir_no_portal | suporte
+
+empresa = ej.empresa.obter()  # empresa["onboarding"]["estado"]: configurando → perguntas → pronto
+if empresa["onboarding"]["estado"] == "perguntas":
+    print(ej.empresa.onboarding())  # o que o cadastro fiscal não respondeu sozinho
+    ej.empresa.fiscal(aliquota_simples=6)  # só com o valor que a empresa informou
+```
+
+A senha é conferida no portal e nunca volta em resposta. O portal bloqueia a conta da empresa depois de algumas senhas erradas: a API limita a 3 tentativas erradas por CNPJ em 24 h.
+
+## Tomadores e serviços
+
+```python
+ej.tomadores.criar("52998224725", nome="Maria da Silva")  # CPF precisa do nome
+ej.tomadores.listar(busca="alfa", ordem="recentes")
+ej.tomadores.buscar("12.345.678")
+
+itens = ej.servicos.catalogo("consultoria")["itens"]  # código nacional (cTribNac) por texto
+ej.servicos.criar(descricao="Consultoria", c_trib_nac=itens[0]["c_trib_nac"], trib_issqn="tributavel", retem_iss=False)
+ej.servicos.listar()  # emitir sem servico_id usa o principal
+```
+
+## Notas
+
+```python
+notas = ej.notas.listar(periodo="mes_atual", situacao="emitidas")["notas"]
+operacao = ej.notas.cancelar("local", nota_id, "1", justificativa="Valor digitado errado.")["operacao"]
+ej.operacoes.aguardar(operacao["id"])  # processando → concluida | falhou
+```
+
+Nota não se altera: para corrigir, cancele e emita outra. Nota autorizada e depois cancelada conta no plano; recusada não conta.
+
+## Idempotência e nota em dobro
+
+- Use uma `referencia` por nota que você quer emitir (o id do seu pedido serve; 8 a 64 caracteres: letras, números, `_` e `-`). Repetir a mesma devolve o mesmo `pedido` com `repetido: True`.
+- `503 fila_indisponivel`: repita **com a mesma referência**.
+- `409 possivel_duplicada`: já existe nota igual (tomador, valor e competência) no mesmo dia. Se for mesmo outra nota, repita com `permitir_repetida_de=e.extras["nota_igual_recente"]["pedido_id"]`.
+- `409 emissao_repetida_recente`: mesma nota há menos de 2 minutos. Se for intencional, repita com `confirmo_repeticao=True`.
+- A biblioteca não repete chamadas sozinha: emitir tem efeito fiscal, e quem decide repetir é você.
+
+## Erros
+
+```python
+from emissaoja import EmissaojaErro
+
+try:
+    ej.notas.emitir("pedido-0002", "pj", tomador_id, 100)
+except EmissaojaErro as e:
+    if e.code == "nota_bloqueada":
+        print(e.extras["bloqueios"])  # [{"code", "mensagem", "acao"}]
+    elif e.code == "limite_notas":
+        print("limite do plano no mês")
+    else:
+        print(e.status, e.code, e, e.request_id)
+```
+
+| HTTP | `code` | O que fazer |
+| --- | --- | --- |
+| 400 | `validation_error`, `valor_invalido`, `cnpj_invalido`, `chave_idempotencia_invalida` | Corrigir o campo |
+| 401 | `chave_invalida` | Conferir a chave (ou o ambiente: `ej_test_` só no sandbox) |
+| 402 | `limite_notas` | Limite do plano no mês |
+| 404 | `tomador_nao_encontrado`, `servico_nao_encontrado`, `nota_nao_encontrada`, `pedido_nao_encontrado` | Conferir o id |
+| 409 | `sem_empresa` | Conectar a empresa (`empresa.conectar`) |
+| 409 | `aceite_pendente` | Termos ou Política mudaram: entre no [app](https://emissaoja.com.br/app) e aceite a versão nova; a chave volta a funcionar |
+| 409 | `possivel_duplicada`, `emissao_repetida_recente`, `incerta_pendente` | Ver "Idempotência e nota em dobro" |
+| 422 | `nota_bloqueada` | Resolver `extras["bloqueios"]` |
+| 429 | `rate_limited` | Esperar `Retry-After` |
+| 503 | `motor_indisponivel`, `fila_indisponivel`, `receita_indisponivel` | Tentar de novo (com a mesma referência) |
+| 0 | `rede`, `tempo_esgotado` | Falha de rede ou tempo esgotado no seu lado |
+
+Limites: 60 chamadas por minuto por chave, 10 emissões por minuto e 120 por minuto em buscas e catálogo.
+
+## Referência
+
+| Recurso | Métodos |
+| --- | --- |
+| `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` (dados da Receita Federal) |
+| — | `status()` (sem chave) |
+
+`Emissaoja(chave=None, base_url=BASE_PRODUCAO, timeout=30.0)`. Referência completa da API: [emissaoja.com.br/docs](https://emissaoja.com.br/docs/) e [OpenAPI 3.1](https://emissaoja.com.br/v1/openapi.json).
+
+## Perguntas frequentes
+
+**Precisa de certificado digital?** Não. O emissaoja entra no Emissor Nacional com o CNPJ e a senha do portal da própria empresa, o acesso que o portal oferece a MEI e empresas do Simples Nacional.
+
+**Funciona para MEI?** Sim. O público é MEI, ME e EPP optantes pelo Simples Nacional, em um município que emite pelo Emissor Nacional.
+
+**Tem ambiente de testes?** Sim, o sandbox em `https://sandbox.emissaoja.com.br`, com o Emissor Nacional simulado e empresas de exemplo.
+
+**Quanto custa?** O plano Grátis emite 1 nota por mês; os planos pagos estão em [emissaoja.com.br/#precos](https://emissaoja.com.br/#precos). O sandbox é grátis. Nota recusada não conta.
+
+**Tem webhook?** Ainda não. Acompanhe o pedido com `notas.aguardar()` ou `emissoes.obter()`, que trazem `proxima_consulta_ms`.
+
+## Outras formas de integrar
+
+- Node.js/TypeScript: [`npm install emissaoja`](https://github.com/Easymovel/emissaoja-js) · PHP/Laravel: [`composer require emissaoja/emissaoja`](https://github.com/Easymovel/emissaoja-php) · .NET: [`dotnet add package Emissaoja`](https://github.com/Easymovel/emissaoja-dotnet) · Go: [`go get emissaoja.com.br/go`](https://github.com/Easymovel/emissaoja-go) · Ruby: [`gem install emissaoja`](https://github.com/Easymovel/emissaoja-ruby)
+- n8n: [`n8n-nodes-emissaoja`](https://github.com/Easymovel/n8n-nodes-emissaoja) · WooCommerce: [emissaoja NFS-e para WooCommerce](https://github.com/Easymovel/emissaoja-woocommerce)
+- Assistentes de IA (Claude, ChatGPT, Cursor, VS Code): servidor MCP em `https://emissaoja.com.br/mcp` ([emissaoja-mcp](https://github.com/Easymovel/emissaoja-mcp))
+- Documentação para IAs: [llms.txt](https://emissaoja.com.br/llms.txt) · [docs.md](https://emissaoja.com.br/docs.md)
+
+## In English
+
+Official Python client for the [emissaoja API](https://emissaoja.com.br/docs/): issue Brazilian **NFS-e** (electronic service invoices) through the national **Emissor Nacional** without a digital certificate, for MEI and Simples Nacional companies. Standard library only, typed, idempotent issuing, PDF and XML download, and a free sandbox with a simulated tax authority. The API and the docs are in Portuguese.
+
+---
+
+Suporte: [suporte@emissaoja.com.br](mailto:suporte@emissaoja.com.br). Licença MIT, © 2026 BINOBO LTDA.
+
+O emissaoja é um serviço privado e não tem vínculo com a Receita Federal nem com o Emissor Nacional.

emissaoja-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "emissaoja"
+version = "0.1.0"
+description = "API de NFS-e nacional para Python: emita nota fiscal de serviço eletrônica no Emissor Nacional sem certificado digital (MEI e Simples Nacional). PDF, XML, tomadores. Cliente oficial do emissaoja."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "BINOBO LTDA" }]
+keywords = [
+  "nfse",
+  "nfs-e",
+  "nfse nacional",
+  "api nfse",
+  "emitir nfse",
+  "nota fiscal",
+  "nota fiscal de servico",
+  "nota fiscal eletronica",
+  "emissor nacional",
+  "danfse",
+  "sem certificado digital",
+  "mei",
+  "simples nacional",
+  "iss",
+  "brasil",
+  "brazil",
+  "invoice",
+  "emissaoja",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Natural Language :: Portuguese (Brazilian)",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Office/Business :: Financial :: Accounting",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://emissaoja.com.br"
+Documentation = "https://emissaoja.com.br/docs/"
+Source = "https://github.com/Easymovel/emissaoja-py"
+Changelog = "https://github.com/Easymovel/emissaoja-py/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Easymovel/emissaoja-py/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/emissaoja"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/emissaoja",
+  "/tests",
+  "/README.md",
+  "/CHANGELOG.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]

emissaoja-0.1.0/src/emissaoja/__init__.py

@@ -0,0 +1,301 @@
+"""emissaoja: cliente oficial da API de NFS-e do emissaoja (https://emissaoja.com.br/docs/).
+
+Emite Nota Fiscal de Serviço eletrônica (NFS-e) no Emissor Nacional (nfse.gov.br) com o CNPJ e a senha do
+portal, sem certificado digital, para MEI e empresas do Simples Nacional.
+
+Só biblioteca padrão (urllib). Mesma forma do cliente JavaScript: ``Emissaoja(chave)`` e os
+recursos ``empresa``, ``tomadores``, ``servicos``, ``notas``, ``emissoes``, ``operacoes`` e ``cnpj``.
+Erros da API viram ``EmissaojaErro`` com ``code`` (a lista fechada da API), ``status`` e ``extras``.
+
+Exemplo no sandbox (Emissor Nacional simulado)::
+
+    from emissaoja import Emissaoja, BASE_SANDBOX
+
+    ej = Emissaoja(base_url=BASE_SANDBOX)  # chave em EMISSAOJA_KEY (ej_test_...)
+    tomador = ej.tomadores.criar("12345678000195")["tomador"]
+    pedido = ej.notas.emitir("pedido-0001", tomador["tipo"], tomador["id"], 150, descricao="Consultoria")["pedido"]
+    final = ej.notas.aguardar(pedido["id"])["pedido"]
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import re
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Optional
+
+__all__ = ["Emissaoja", "EmissaojaErro", "BASE_PRODUCAO", "BASE_SANDBOX", "__version__"]
+__version__ = "0.1.0"
+
+BASE_PRODUCAO = "https://emissaoja.com.br"
+BASE_SANDBOX = "https://sandbox.emissaoja.com.br"
+_BASE_PADRAO = BASE_PRODUCAO
+_TERMINAIS = {"autorizada", "recusada", "incerta"}
+_RE_REFERENCIA = re.compile(r"^[A-Za-z0-9_-]{8,64}$")
+
+
+class EmissaojaErro(Exception):
+    """Erro da API (``status`` HTTP, ``code`` da lista fechada, ``extras`` com bloqueios etc.)."""
+
+    def __init__(self, status: int, corpo: Optional[dict] = None, request_id: Optional[str] = None):
+        c = corpo if isinstance(corpo, dict) else {}
+        super().__init__(c.get("message") or f"HTTP {status}")
+        self.status = status
+        self.code: str = c.get("code") or "erro_desconhecido"
+        self.extras: Dict[str, Any] = {k: v for k, v in c.items() if k not in ("status", "message", "code")}
+        self.request_id = request_id
+
+
+# Transporte: (metodo, url, cabecalhos, corpo_bytes, timeout) -> (status, cabecalhos, bytes). Injetável nos testes.
+Transporte = Callable[[str, str, Dict[str, str], Optional[bytes], float], "tuple[int, Dict[str, str], bytes]"]
+
+
+def _transporte_urllib(metodo: str, url: str, cabecalhos: Dict[str, str], corpo: Optional[bytes], timeout: float):
+    req = urllib.request.Request(url, data=corpo, method=metodo, headers=cabecalhos)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:  # noqa: S310 (URL é a da API)
+            return res.status, {k.lower(): v for k, v in res.headers.items()}, res.read()
+    except urllib.error.HTTPError as e:
+        cabecalhos_erro = {k.lower(): v for k, v in e.headers.items()} if e.headers is not None else {}
+        return e.code, cabecalhos_erro, e.read()
+    except urllib.error.URLError as e:
+        if isinstance(e.reason, (TimeoutError, socket.timeout)):
+            raise EmissaojaErro(0, {"code": "tempo_esgotado", "message": "A API não respondeu a tempo."}) from e
+        raise EmissaojaErro(0, {"code": "rede", "message": str(e.reason)}) from e
+    except (TimeoutError, socket.timeout) as e:  # no 3.9, socket.timeout ainda não é TimeoutError
+        raise EmissaojaErro(0, {"code": "tempo_esgotado", "message": "A API não respondeu a tempo."}) from e
+    except (OSError, http.client.HTTPException) as e:
+        raise EmissaojaErro(0, {"code": "rede", "message": str(e) or e.__class__.__name__}) from e
+
+
+class _Recurso:
+    def __init__(self, cliente: "Emissaoja"):
+        self._c = cliente
+
+
+class _Empresa(_Recurso):
+    def obter(self) -> dict:
+        return self._c._json("GET", "/v1/empresa")
+
+    def conectar(self, cnpj: str, senha: str, ciente_ultima_tentativa: bool = False) -> dict:
+        """``PUT /v1/empresa/credencial``: CNPJ e senha do Emissor Nacional → ``{"tentativa": …}``."""
+        return self._c._json("PUT", "/v1/empresa/credencial", {"cnpj": cnpj, "senha": senha, "ciente_ultima_tentativa": bool(ciente_ultima_tentativa)})
+
+    def credencial(self) -> dict:
+        return self._c._json("GET", "/v1/empresa/credencial")
+
+    def aguardar_credencial(self, intervalo: float = 2.0, timeout: float = 120.0) -> dict:
+        """Consulta até ``tentativa.proximo_passo`` sair de ``aguardar``."""
+        fim = time.monotonic() + timeout
+        while True:
+            r = self.credencial()
+            t = r.get("tentativa")
+            if not t or t.get("proximo_passo") != "aguardar":
+                return r
+            if time.monotonic() > fim:
+                raise EmissaojaErro(0, {"code": "tempo_esgotado", "message": "A verificação da senha não terminou a tempo."})
+            self._c._dormir(intervalo)
+
+    def onboarding(self) -> dict:
+        return self._c._json("GET", "/v1/empresa/onboarding")
+
+    def fiscal(self, aliquota_simples: Optional[float] = None, reg_ap_trib_sn: Optional[int] = None) -> dict:
+        corpo: Dict[str, Any] = {}
+        if aliquota_simples is not None:
+            corpo["aliquota_simples"] = aliquota_simples
+        if reg_ap_trib_sn is not None:
+            corpo["reg_ap_trib_sn"] = reg_ap_trib_sn
+        return self._c._json("PUT", "/v1/empresa/fiscal", corpo)
+
+    def reler_fisco(self) -> dict:
+        return self._c._json("POST", "/v1/empresa/reler-fisco")
+
+
+class _Tomadores(_Recurso):
+    def listar(self, busca: Optional[str] = None, pagina: int = 1, limite: Optional[int] = None, ordem: Optional[str] = None) -> dict:
+        return self._c._json("GET", "/v1/tomadores", query={"busca": busca, "pagina": pagina, "limite": limite, "ordem": ordem})
+
+    def buscar(self, q: str) -> dict:
+        return self._c._json("GET", "/v1/tomadores/busca", query={"q": q})
+
+    def criar(self, documento: str, nome: Optional[str] = None) -> dict:
+        corpo: Dict[str, Any] = {"documento": documento}
+        if nome:
+            corpo["nome"] = nome
+        return self._c._json("POST", "/v1/tomadores", corpo)
+
+    def obter(self, tipo: str, id: str) -> dict:
+        return self._c._json("GET", f"/v1/tomadores/{_q(tipo)}/{_q(id)}")
+
+    def atualizar(self, tipo: str, id: str, **campos: Any) -> dict:
+        return self._c._json("PUT", f"/v1/tomadores/{_q(tipo)}/{_q(id)}", campos)
+
+
+class _Servicos(_Recurso):
+    def listar(self, ativos: str = "1") -> dict:
+        return self._c._json("GET", "/v1/servicos", query={"ativos": ativos})
+
+    def criar(self, **campos: Any) -> dict:
+        return self._c._json("POST", "/v1/servicos", campos)
+
+    def atualizar(self, id: str, **campos: Any) -> dict:
+        return self._c._json("PUT", f"/v1/servicos/{_q(id)}", campos)
+
+    def desativar(self, id: str) -> dict:
+        return self._c._json("DELETE", f"/v1/servicos/{_q(id)}")
+
+    def catalogo(self, q: str, limite: Optional[int] = None) -> dict:
+        return self._c._json("GET", "/v1/catalogo/servicos", query={"q": q, "limite": limite})
+
+
+class _Notas(_Recurso):
+    def emitir(self, referencia: str, tomador_tipo: str, tomador_id: str, valor: float, **campos: Any) -> dict:
+        """``POST /v1/notas`` com ``Idempotency-Key`` = ``referencia`` (um id seu por nota).
+
+        Devolve ``{"pedido": …, "previa": …}`` (202) ou ``{"pedido": …, "repetido": True}`` (mesma referência).
+        """
+        if not isinstance(referencia, str) or not _RE_REFERENCIA.match(referencia):
+            raise EmissaojaErro(0, {"code": "chave_idempotencia_invalida", "message": "Informe `referencia` (8 a 64 caracteres: letras, números, _ e -), única por nota."})
+        corpo = {"tomador_tipo": tomador_tipo, "tomador_id": tomador_id, "valor": valor, **{k: v for k, v in campos.items() if v is not None}}
+        return self._c._json("POST", "/v1/notas", corpo, cabecalhos={"Idempotency-Key": referencia})
+
+    def aguardar(self, pedido_id: str, timeout: float = 180.0, intervalo_minimo: float = 1.0) -> dict:
+        """Consulta o pedido até ``autorizada``, ``recusada`` ou ``incerta``, respeitando ``proxima_consulta_ms``."""
+        fim = time.monotonic() + timeout
+        while True:
+            r = self._c.emissoes.obter(pedido_id)
+            p = r.get("pedido") or {}
+            if p.get("estado") in _TERMINAIS:
+                return r
+            if time.monotonic() > fim:
+                raise EmissaojaErro(0, {"code": "tempo_esgotado", "message": "O pedido não terminou a tempo; consulte de novo mais tarde.", "pedido_id": pedido_id})
+            self._c._dormir(max(intervalo_minimo, (p.get("proxima_consulta_ms") or 3000) / 1000))
+
+    def listar(self, **query: Any) -> dict:
+        return self._c._json("GET", "/v1/notas", query=query)
+
+    def pdf(self, origem: str, id: str) -> bytes:
+        return self._c._bytes(f"/v1/notas/{_q(origem)}/{_q(id)}/pdf")
+
+    def xml(self, origem: str, id: str) -> str:
+        return self._c._bytes(f"/v1/notas/{_q(origem)}/{_q(id)}/xml").decode("utf-8")
+
+    def cancelar(self, origem: str, id: str, motivo: str, justificativa: Optional[str] = None) -> dict:
+        corpo: Dict[str, Any] = {"motivo": str(motivo)}
+        if justificativa:
+            corpo["justificativa"] = justificativa
+        return self._c._json("POST", f"/v1/notas/{_q(origem)}/{_q(id)}/cancelar", corpo)
+
+
+class _Emissoes(_Recurso):
+    def obter(self, id: str) -> dict:
+        return self._c._json("GET", f"/v1/emissoes/{_q(id)}")
+
+    def listar(self, estados: Optional[str] = None) -> dict:
+        return self._c._json("GET", "/v1/emissoes", query={"estados": estados})
+
+    def conferir(self, id: str) -> dict:
+        return self._c._json("POST", f"/v1/emissoes/{_q(id)}/conferir")
+
+
+class _Operacoes(_Recurso):
+    def obter(self, id: str) -> dict:
+        return self._c._json("GET", f"/v1/operacoes/{_q(id)}")
+
+    def aguardar(self, id: str, intervalo: float = 2.0, timeout: float = 180.0) -> dict:
+        fim = time.monotonic() + timeout
+        while True:
+            r = self.obter(id)
+            if (r.get("operacao") or {}).get("estado") != "processando":
+                return r
+            if time.monotonic() > fim:
+                raise EmissaojaErro(0, {"code": "tempo_esgotado", "message": "A operação não terminou a tempo."})
+            self._c._dormir(intervalo)
+
+
+class _Cnpj(_Recurso):
+    def consultar(self, cnpj: str) -> dict:
+        return self._c._json("GET", f"/v1/cnpj/{re.sub(r'[^0-9]', '', str(cnpj))}")
+
+
+class Emissaoja:
+    """``Emissaoja(chave)``; ``chave`` omitida lê ``EMISSAOJA_KEY`` na primeira chamada."""
+
+    def __init__(
+        self,
+        chave: Optional[str] = None,
+        base_url: str = _BASE_PADRAO,
+        timeout: float = 30.0,
+        transporte: Optional[Transporte] = None,
+        dormir: Optional[Callable[[float], None]] = None,
+    ):
+        self._chave = chave
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._transporte = transporte or _transporte_urllib
+        self._dormir: Callable[[float], None] = dormir or time.sleep
+        self.empresa = _Empresa(self)
+        self.tomadores = _Tomadores(self)
+        self.servicos = _Servicos(self)
+        self.notas = _Notas(self)
+        self.emissoes = _Emissoes(self)
+        self.operacoes = _Operacoes(self)
+        self.cnpj = _Cnpj(self)
+
+    @property
+    def chave(self) -> str:
+        if self._chave is None:
+            env = os.environ.get("EMISSAOJA_KEY")
+            if not env:
+                raise EmissaojaErro(0, {"code": "chave_invalida", "message": "Informe a chave: Emissaoja(chave) ou a variável EMISSAOJA_KEY."})
+            self._chave = env
+        return self._chave
+
+    def status(self) -> dict:
+        return self._json("GET", "/v1/status", sem_chave=True)
+
+    # ---- transporte ----
+    def _req(self, metodo: str, caminho: str, corpo: Any = None, query: Optional[dict] = None, cabecalhos: Optional[dict] = None, sem_chave: bool = False):
+        url = self.base_url + caminho
+        q = {k: v for k, v in (query or {}).items() if v is not None and v != ""}
+        if q:
+            url += "?" + urllib.parse.urlencode(q)
+        h = {"Accept": "application/json", "User-Agent": f"emissaoja-py/{__version__}", **(cabecalhos or {})}
+        if not sem_chave:
+            h["Authorization"] = f"Bearer {self.chave}"
+        dados = None
+        if corpo is not None:
+            h["Content-Type"] = "application/json"
+            dados = json.dumps(corpo).encode("utf-8")
+        return self._transporte(metodo, url, h, dados, self.timeout)
+
+    def _json(self, metodo: str, caminho: str, corpo: Any = None, query: Optional[dict] = None, cabecalhos: Optional[dict] = None, sem_chave: bool = False) -> dict:
+        status, h, bytes_ = self._req(metodo, caminho, corpo, query, cabecalhos, sem_chave)
+        texto = bytes_.decode("utf-8") if bytes_ else ""
+        try:
+            dados = json.loads(texto) if texto else None
+        except ValueError:
+            dados = None
+        if status >= 400:
+            raise EmissaojaErro(status, dados if isinstance(dados, dict) else {"message": texto[:200] or f"HTTP {status}"}, h.get("x-request-id"))
+        return dados if isinstance(dados, dict) else {}
+
+    def _bytes(self, caminho: str) -> bytes:
+        status, h, bytes_ = self._req("GET", caminho)
+        if status >= 400:
+            try:
+                dados = json.loads(bytes_.decode("utf-8"))
+            except ValueError:
+                dados = None
+            raise EmissaojaErro(status, dados if isinstance(dados, dict) else None, h.get("x-request-id"))
+        return bytes_
+
+
+def _q(v: Any) -> str:
+    return urllib.parse.quote(str(v), safe="")

emissaoja-0.1.0/tests/test_cliente.py

@@ -0,0 +1,105 @@
+"""Testes do cliente com um transporte falso (sem rede). Rodar: python -m unittest discover -s tests -v"""
+
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+from emissaoja import Emissaoja, EmissaojaErro  # noqa: E402
+
+
+class Transporte:
+    """Guarda as chamadas e responde pelo caminho."""
+
+    def __init__(self):
+        self.chamadas = []
+        self.respostas = {}
+
+    def __call__(self, metodo, url, cabecalhos, corpo, timeout):
+        self.chamadas.append((metodo, url, cabecalhos, corpo))
+        caminho = url.split("emissaoja.test", 1)[1].split("?")[0]
+        status, dados = self.respostas.get((metodo, caminho), (404, {"status": "ERROR", "code": "not_found", "message": "Rota não encontrada."}))
+        if isinstance(dados, (bytes, bytearray)):
+            return status, {"content-type": "application/pdf"}, bytes(dados)
+        return status, {"content-type": "application/json", "x-request-id": "r_teste"}, json.dumps(dados).encode("utf-8")
+
+
+class ClienteTest(unittest.TestCase):
+    def setUp(self):
+        self.t = Transporte()
+        self.ej = Emissaoja("ej_live_" + "a" * 43, base_url="https://emissaoja.test", transporte=self.t)
+
+    def test_cabecalhos_e_status_sem_chave(self):
+        self.t.respostas[("GET", "/v1/status")] = (200, {"ok": True, "motor": "ok"})
+        self.assertEqual(self.ej.status()["motor"], "ok")
+        _, _, h, _ = self.t.chamadas[0]
+        self.assertNotIn("Authorization", h)
+        self.t.respostas[("GET", "/v1/empresa")] = (200, {"empresa": None})
+        self.ej.empresa.obter()
+        self.assertEqual(self.t.chamadas[1][2]["Authorization"], "Bearer ej_live_" + "a" * 43)
+        self.assertTrue(self.t.chamadas[1][2]["User-Agent"].startswith("emissaoja-py/"))
+
+    def test_emitir_exige_referencia_e_manda_idempotency_key(self):
+        with self.assertRaises(EmissaojaErro) as cm:
+            self.ej.notas.emitir("curta", "pj", "id", 10)
+        self.assertEqual(cm.exception.code, "chave_idempotencia_invalida")
+        self.t.respostas[("POST", "/v1/notas")] = (202, {"pedido": {"id": "p1", "estado": "na_fila"}})
+        r = self.ej.notas.emitir("pedido-0001", "pj", "11111111-1111-1111-1111-111111111111", 150.0, descricao="x", competencia=None)
+        self.assertEqual(r["pedido"]["id"], "p1")
+        metodo, url, h, corpo = self.t.chamadas[-1]
+        self.assertEqual(h["Idempotency-Key"], "pedido-0001")
+        self.assertEqual(json.loads(corpo), {"tomador_tipo": "pj", "tomador_id": "11111111-1111-1111-1111-111111111111", "valor": 150.0, "descricao": "x"})
+
+    def test_erro_da_api_vira_excecao_com_code_e_extras(self):
+        self.t.respostas[("POST", "/v1/notas")] = (422, {"status": "ERROR", "code": "nota_bloqueada", "message": "Antes de emitir, resolva:", "bloqueios": [{"code": "tomador_incompleto", "mensagem": "…", "acao": "completar_tomador"}]})
+        with self.assertRaises(EmissaojaErro) as cm:
+            self.ej.notas.emitir("pedido-0002", "pj", "11111111-1111-1111-1111-111111111111", 10)
+        e = cm.exception
+        self.assertEqual((e.status, e.code, e.request_id), (422, "nota_bloqueada", "r_teste"))
+        self.assertEqual(e.extras["bloqueios"][0]["acao"], "completar_tomador")
+
+    def test_aguardar_respeita_proxima_consulta(self):
+        estados = iter([{"estado": "emitindo", "proxima_consulta_ms": 1}, {"estado": "autorizada", "numero": "7"}])
+        self.t.respostas[("GET", "/v1/emissoes/p1")] = (200, {})
+        original = self.t.__call__
+
+        def responder(metodo, url, h, corpo, timeout):
+            status, hh, _ = original(metodo, url, h, corpo, timeout)
+            return 200, hh, json.dumps({"pedido": next(estados)}).encode()
+
+        self.ej._transporte = responder
+        r = self.ej.notas.aguardar("p1", intervalo_minimo=0.001)
+        self.assertEqual(r["pedido"]["numero"], "7")
+
+    def test_query_e_bytes(self):
+        self.t.respostas[("GET", "/v1/tomadores")] = (200, {"tomadores": [], "total": 0})
+        self.ej.tomadores.listar(busca="alfa", pagina=2)
+        self.assertIn("busca=alfa&pagina=2", self.t.chamadas[-1][1])
+        self.t.respostas[("GET", "/v1/notas/local/abc/pdf")] = (200, b"%PDF-1.4 teste")
+        self.assertTrue(self.ej.notas.pdf("local", "abc").startswith(b"%PDF"))
+        self.t.respostas[("GET", "/v1/cnpj/11222333000181")] = (200, {"cnpj": "11222333000181"})
+        self.assertEqual(self.ej.cnpj.consultar("11.222.333/0001-81")["cnpj"], "11222333000181")
+
+    def test_dormir_injetavel_recebe_proxima_consulta(self):
+        estados = iter([
+            {"estado": "na_fila", "proxima_consulta_ms": 2500},
+            {"estado": "emitindo", "proxima_consulta_ms": 10},
+            {"estado": "recusada", "motivo_code": "E0001"},
+        ])
+        esperas = []
+        ej = Emissaoja("ej_live_" + "a" * 43, base_url="https://emissaoja.test", transporte=lambda m, u, h, c, t: (200, {}, json.dumps({"pedido": next(estados)}).encode()), dormir=esperas.append)
+        r = ej.notas.aguardar("p2")
+        self.assertEqual(r["pedido"]["estado"], "recusada")
+        self.assertEqual(esperas, [2.5, 1.0])
+
+    def test_sem_chave_le_env(self):
+        os.environ.pop("EMISSAOJA_KEY", None)
+        ej = Emissaoja(base_url="https://emissaoja.test", transporte=self.t)
+        with self.assertRaises(EmissaojaErro) as cm:
+            ej.empresa.obter()
+        self.assertEqual(cm.exception.code, "chave_invalida")
+
+
+if __name__ == "__main__":
+    unittest.main()

emissaoja-0.1.0/tests/test_integracao.py

@@ -0,0 +1,32 @@
+"""Integração com o sandbox público (Emissor Nacional simulado). Só roda com EMISSAOJA_TEST_KEY (chave ej_test_)."""
+
+import os
+import random
+import sys
+import time
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+from emissaoja import BASE_SANDBOX, Emissaoja  # noqa: E402
+
+CHAVE = os.environ.get("EMISSAOJA_TEST_KEY")
+
+
+@unittest.skipUnless(CHAVE, "defina EMISSAOJA_TEST_KEY para rodar")
+class SandboxTest(unittest.TestCase):
+    def test_fluxo_no_sandbox(self):
+        ej = Emissaoja(CHAVE, base_url=BASE_SANDBOX)
+        self.assertEqual(ej.status()["motor"], "simulado")
+        if ej.empresa.obter()["credencial"]["estado"] != "ativa":
+            ej.empresa.conectar("11111111000191", "qualquer")
+            ej.empresa.aguardar_credencial(timeout=60)
+        tomador = ej.tomadores.criar("12345678000195")["tomador"]
+        pedido = ej.notas.emitir(f"sdk-py-{int(time.time())}", tomador["tipo"], tomador["id"], random.randint(10001, 19999) / 100, descricao="Teste do cliente Python")["pedido"]
+        final = ej.notas.aguardar(pedido["id"], timeout=120)["pedido"]
+        self.assertIn(final["estado"], ("autorizada", "recusada", "incerta"))
+        if final["estado"] == "autorizada":
+            self.assertTrue(ej.notas.pdf(final["nota"]["origem"], final["nota"]["id"]).startswith(b"%PDF"))
+
+
+if __name__ == "__main__":
+    unittest.main()

emissaoja-0.1.0/tests/test_transporte.py

@@ -0,0 +1,48 @@
+"""Transporte urllib: timeouts e falhas de conexão viram EmissaojaErro (sem rede: urlopen é trocado)."""
+
+import os
+import socket
+import sys
+import unittest
+import urllib.error
+from unittest import mock
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+import emissaoja  # noqa: E402
+from emissaoja import BASE_PRODUCAO, BASE_SANDBOX, Emissaoja, EmissaojaErro  # noqa: E402
+
+
+class TransporteUrllibTest(unittest.TestCase):
+    def setUp(self):
+        self.ej = Emissaoja("ej_test_" + "b" * 43, base_url=BASE_SANDBOX)
+
+    def _codigo(self, excecao):
+        with mock.patch("urllib.request.urlopen", side_effect=excecao):
+            with self.assertRaises(EmissaojaErro) as cm:
+                self.ej.empresa.obter()
+        self.assertEqual(cm.exception.status, 0)
+        return cm.exception.code
+
+    def test_timeout_de_leitura(self):
+        self.assertEqual(self._codigo(socket.timeout("timed out")), "tempo_esgotado")
+        self.assertEqual(self._codigo(TimeoutError("timed out")), "tempo_esgotado")
+
+    def test_timeout_na_conexao(self):
+        self.assertEqual(self._codigo(urllib.error.URLError(socket.timeout("timed out"))), "tempo_esgotado")
+
+    def test_falhas_de_rede(self):
+        self.assertEqual(self._codigo(urllib.error.URLError("Name or service not known")), "rede")
+        self.assertEqual(self._codigo(ConnectionResetError("reset")), "rede")
+
+
+class ConstantesTest(unittest.TestCase):
+    def test_bases_e_versao(self):
+        self.assertEqual(BASE_PRODUCAO, "https://emissaoja.com.br")
+        self.assertEqual(BASE_SANDBOX, "https://sandbox.emissaoja.com.br")
+        self.assertEqual(Emissaoja("x" * 10).base_url, BASE_PRODUCAO)
+        self.assertEqual(Emissaoja("x" * 10, base_url=BASE_SANDBOX + "/").base_url, BASE_SANDBOX)
+        self.assertRegex(emissaoja.__version__, r"^\d+\.\d+\.\d+$")
+
+
+if __name__ == "__main__":
+    unittest.main()