almztech-sdk 0.2.0b1__tar.gz

almztech_sdk-0.2.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ALMZTECH SOFTWARES 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.

almztech_sdk-0.2.0b1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: almztech-sdk
+Version: 0.2.0b1
+Summary: SDK oficial Python para a API da Almztech (emissão, consulta, reconsulta e cancelamento de NFS-e, importação por planilha, Emitente, Webhook).
+Author: ALMZTECH SOFTWARES LTDA
+License-Expression: MIT
+Project-URL: Homepage, https://docs.almztech.com.br
+Project-URL: Documentation, https://docs.almztech.com.br
+Project-URL: Source, https://gitlab.com/almztech/sdks
+Keywords: nfse,nfs-e,nota-fiscal,nota-fiscal-de-servico,almztech,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Portuguese (Brazilian)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# almztech-sdk (Python)
+
+SDK oficial da [Almztech](https://almztech.com.br) para Python. Ele cobre a API de NFS-e:
+- emissão, consulta, reconsulta e cancelamento de notas, inclusive por planilha;
+- emitentes e certificados;
+- webhooks;
+- municípios homologados.
+
+> Versão beta: a API pública do SDK ainda pode mudar até a 1.0.
+
+## Instalação
+
+```bash
+pip install --pre almztech-sdk
+```
+
+- Python 3.9+.
+- **Sem dependências de runtime**: usa `urllib` e `json` da biblioteca padrão (dá para injetar outro envio HTTP em `OpcoesDoClient.envio_http`).
+- Os dados são `dict` no formato exato do JSON da API, em camelCase, com `TypedDict` em `almztech.modelos` para o editor. Chaves com `None` não são enviadas.
+
+## Uso
+
+```python
+import os
+from almztech import AlmztechClient, AlmztechErroProtocoloRejeitado, AlmztechErroValidacao, filtros, ler_webhook
+
+# A api key está no Portal (portal.almztech.com.br), em Primeiros passos. Guarde-a na configuração do seu
+# sistema, nunca no código.
+client = AlmztechClient(os.environ["ALMZTECH_API_KEY"])
+
+try:
+    protocolo = client.notas_fiscais.emitir({
+        "identificacaoEmitente": "12345678000190",
+        "enviarParaProducao": False,  # homologação (HML-...): não consome a franquia
+        "notas": [{
+            "rps": {"numeroRPS": "1001", "serie": "1", "tipo": "1", "dataEmissao": "2026-10-31"},
+            "destinatario": {
+                "cpfCnpj": "11222333000181",
+                "razaoSocial": "Cliente Exemplo Ltda",
+                "endereco": {"cep": "50030170", "codigoIBGEMunicipio": 2611606},
+            },
+            "servicos": [{"codigo": "0105", "descricao": "Licenciamento de software", "quantidade": 1,
+                          "valorUnitario": 1500, "aliquotaISS": 2, "retemISS": 2}],
+        }],
+    })
+
+    resultado = client.notas_fiscais.aguardar_conclusao(protocolo["protocolo"])
+    for nota in resultado.get("notas", []):
+        pdf = client.notas_fiscais.baixar_pdf(nota["codigoNota"])  # bytes
+except AlmztechErroProtocoloRejeitado as erro:
+    print("Rejeitada:", erro.protocolo.get("mensagem"))
+except AlmztechErroValidacao as erro:
+    print("Recusada:", erro.mensagem)
+
+# No seu endpoint de webhook (a API não assina o payload: proteja a URL):
+evento = ler_webhook(corpo_recebido)  # evento.tipo: "Emissao" | "Cancelamento" | "Rejeicao"
+```
+
+Consulta com filtros e paginação automática:
+
+```python
+for nota in client.notas_fiscais.paginas(
+    filtros.PRODUCAO,
+    [filtros.periodo("2026-10-01", "2026-10-31"), filtros.com_status("EMITIDA")],
+):
+    print(nota["numeroNota"], nota["valorTotal"])
+```
+
+Também estão disponíveis:
+- **Notas:** `consultar_por_numero`, `reconsultar`, `reconsultar_por_chave_acesso`, `cancelar`, `baixar_xml`, `baixar_modelo_planilha` e `importar_planilha` (aceita caminho, bytes ou arquivo aberto).
+- **Emitentes:** `client.emitentes`, inclusive `upload_certificado`.
+- **Webhooks e municípios:** `client.webhooks` e `client.municipios`.
+
+Exceções:
+- `AlmztechErroValidacao` (422 e 400);
+- `AlmztechErroAutenticacao` (401);
+- `AlmztechErroAutorizacao` (403);
+- `AlmztechErroLimiteDeRequisicoes` (429, com `retry_after`);
+- `AlmztechErroServidor` (5xx);
+- `AlmztechErroRede`;
+- `AlmztechErroTempoDePollingEsgotado`;
+- `AlmztechErroProtocoloRejeitado`;
+- `AlmztechErroWebhook`.
+
+Só as leituras são retentadas automaticamente. `emitir`, `cancelar` e `importar_planilha` nunca são.
+
+## Links
+
+- [Documentação da API](https://docs.almztech.com.br)
+- [Código-fonte](https://gitlab.com/almztech/sdks/-/tree/main/python). Os SDKs das outras linguagens (.NET, Node.js,
+  PHP, Java e Ruby) seguem o mesmo [contrato](https://gitlab.com/almztech/sdks/-/blob/main/DESIGN.md).
+
+## Licença
+
+MIT, © 2026 ALMZTECH SOFTWARES LTDA. Veja [LICENSE](https://gitlab.com/almztech/sdks/-/blob/main/python/LICENSE).

almztech_sdk-0.2.0b1/README.md

@@ -0,0 +1,95 @@
+# almztech-sdk (Python)
+
+SDK oficial da [Almztech](https://almztech.com.br) para Python. Ele cobre a API de NFS-e:
+- emissão, consulta, reconsulta e cancelamento de notas, inclusive por planilha;
+- emitentes e certificados;
+- webhooks;
+- municípios homologados.
+
+> Versão beta: a API pública do SDK ainda pode mudar até a 1.0.
+
+## Instalação
+
+```bash
+pip install --pre almztech-sdk
+```
+
+- Python 3.9+.
+- **Sem dependências de runtime**: usa `urllib` e `json` da biblioteca padrão (dá para injetar outro envio HTTP em `OpcoesDoClient.envio_http`).
+- Os dados são `dict` no formato exato do JSON da API, em camelCase, com `TypedDict` em `almztech.modelos` para o editor. Chaves com `None` não são enviadas.
+
+## Uso
+
+```python
+import os
+from almztech import AlmztechClient, AlmztechErroProtocoloRejeitado, AlmztechErroValidacao, filtros, ler_webhook
+
+# A api key está no Portal (portal.almztech.com.br), em Primeiros passos. Guarde-a na configuração do seu
+# sistema, nunca no código.
+client = AlmztechClient(os.environ["ALMZTECH_API_KEY"])
+
+try:
+    protocolo = client.notas_fiscais.emitir({
+        "identificacaoEmitente": "12345678000190",
+        "enviarParaProducao": False,  # homologação (HML-...): não consome a franquia
+        "notas": [{
+            "rps": {"numeroRPS": "1001", "serie": "1", "tipo": "1", "dataEmissao": "2026-10-31"},
+            "destinatario": {
+                "cpfCnpj": "11222333000181",
+                "razaoSocial": "Cliente Exemplo Ltda",
+                "endereco": {"cep": "50030170", "codigoIBGEMunicipio": 2611606},
+            },
+            "servicos": [{"codigo": "0105", "descricao": "Licenciamento de software", "quantidade": 1,
+                          "valorUnitario": 1500, "aliquotaISS": 2, "retemISS": 2}],
+        }],
+    })
+
+    resultado = client.notas_fiscais.aguardar_conclusao(protocolo["protocolo"])
+    for nota in resultado.get("notas", []):
+        pdf = client.notas_fiscais.baixar_pdf(nota["codigoNota"])  # bytes
+except AlmztechErroProtocoloRejeitado as erro:
+    print("Rejeitada:", erro.protocolo.get("mensagem"))
+except AlmztechErroValidacao as erro:
+    print("Recusada:", erro.mensagem)
+
+# No seu endpoint de webhook (a API não assina o payload: proteja a URL):
+evento = ler_webhook(corpo_recebido)  # evento.tipo: "Emissao" | "Cancelamento" | "Rejeicao"
+```
+
+Consulta com filtros e paginação automática:
+
+```python
+for nota in client.notas_fiscais.paginas(
+    filtros.PRODUCAO,
+    [filtros.periodo("2026-10-01", "2026-10-31"), filtros.com_status("EMITIDA")],
+):
+    print(nota["numeroNota"], nota["valorTotal"])
+```
+
+Também estão disponíveis:
+- **Notas:** `consultar_por_numero`, `reconsultar`, `reconsultar_por_chave_acesso`, `cancelar`, `baixar_xml`, `baixar_modelo_planilha` e `importar_planilha` (aceita caminho, bytes ou arquivo aberto).
+- **Emitentes:** `client.emitentes`, inclusive `upload_certificado`.
+- **Webhooks e municípios:** `client.webhooks` e `client.municipios`.
+
+Exceções:
+- `AlmztechErroValidacao` (422 e 400);
+- `AlmztechErroAutenticacao` (401);
+- `AlmztechErroAutorizacao` (403);
+- `AlmztechErroLimiteDeRequisicoes` (429, com `retry_after`);
+- `AlmztechErroServidor` (5xx);
+- `AlmztechErroRede`;
+- `AlmztechErroTempoDePollingEsgotado`;
+- `AlmztechErroProtocoloRejeitado`;
+- `AlmztechErroWebhook`.
+
+Só as leituras são retentadas automaticamente. `emitir`, `cancelar` e `importar_planilha` nunca são.
+
+## Links
+
+- [Documentação da API](https://docs.almztech.com.br)
+- [Código-fonte](https://gitlab.com/almztech/sdks/-/tree/main/python). Os SDKs das outras linguagens (.NET, Node.js,
+  PHP, Java e Ruby) seguem o mesmo [contrato](https://gitlab.com/almztech/sdks/-/blob/main/DESIGN.md).
+
+## Licença
+
+MIT, © 2026 ALMZTECH SOFTWARES LTDA. Veja [LICENSE](https://gitlab.com/almztech/sdks/-/blob/main/python/LICENSE).

almztech_sdk-0.2.0b1/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "almztech-sdk"
+version = "0.2.0b1"
+description = "SDK oficial Python para a API da Almztech (emissão, consulta, reconsulta e cancelamento de NFS-e, importação por planilha, Emitente, Webhook)."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "ALMZTECH SOFTWARES LTDA" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["nfse", "nfs-e", "nota-fiscal", "nota-fiscal-de-servico", "almztech", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Natural Language :: Portuguese (Brazilian)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+# Sem dependências de runtime: HTTP e JSON da biblioteca padrão (DESIGN.md seção 2).
+dependencies = []
+
+[project.urls]
+Homepage = "https://docs.almztech.com.br"
+Documentation = "https://docs.almztech.com.br"
+Source = "https://gitlab.com/almztech/sdks"
+
+[tool.setuptools.packages.find]
+where = ["src"]

almztech_sdk-0.2.0b1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

almztech_sdk-0.2.0b1/src/almztech/__init__.py

@@ -0,0 +1,72 @@
+"""SDK oficial Python da Almztech (DESIGN.md).
+
+Exemplo::
+
+    from almztech import AlmztechClient
+
+    client = AlmztechClient(os.environ["ALMZTECH_API_KEY"])
+    protocolo = client.notas_fiscais.emitir(lote)
+    resultado = client.notas_fiscais.aguardar_conclusao(protocolo["protocolo"])
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from . import filtros
+from .erros import (
+    AlmztechErro,
+    AlmztechErroApi,
+    AlmztechErroAutenticacao,
+    AlmztechErroAutorizacao,
+    AlmztechErroLimiteDeRequisicoes,
+    AlmztechErroProtocoloRejeitado,
+    AlmztechErroRede,
+    AlmztechErroServidor,
+    AlmztechErroTempoDePollingEsgotado,
+    AlmztechErroValidacao,
+    AlmztechErroWebhook,
+)
+from .log import mascarar_api_key, mascarar_corpo_json
+from .recursos import Emitentes, Municipios, NotasFiscais, Webhooks
+from .transporte import VERSAO_SDK, OpcoesDeRetry, OpcoesDoClient, Transporte
+from .webhook import EventoWebhook, ler_webhook
+
+__version__ = VERSAO_SDK
+
+
+class AlmztechClient:
+    """Client raiz. Crie um por aplicação e reaproveite.
+
+    A api key está em "Primeiros passos" no Portal; nunca guarde login e senha no seu sistema.
+    """
+
+    def __init__(self, api_key: str, opcoes: Optional[OpcoesDoClient] = None):
+        transporte = Transporte(api_key, opcoes)
+        self.notas_fiscais = NotasFiscais(transporte)
+        self.emitentes = Emitentes(transporte)
+        self.webhooks = Webhooks(transporte)
+        self.municipios = Municipios(transporte)
+
+
+__all__ = [
+    "AlmztechClient",
+    "OpcoesDoClient",
+    "OpcoesDeRetry",
+    "filtros",
+    "ler_webhook",
+    "EventoWebhook",
+    "mascarar_api_key",
+    "mascarar_corpo_json",
+    "AlmztechErro",
+    "AlmztechErroApi",
+    "AlmztechErroValidacao",
+    "AlmztechErroAutenticacao",
+    "AlmztechErroAutorizacao",
+    "AlmztechErroLimiteDeRequisicoes",
+    "AlmztechErroServidor",
+    "AlmztechErroRede",
+    "AlmztechErroTempoDePollingEsgotado",
+    "AlmztechErroProtocoloRejeitado",
+    "AlmztechErroWebhook",
+]

almztech_sdk-0.2.0b1/src/almztech/erros.py

@@ -0,0 +1,72 @@
+"""Hierarquia de exceções do SDK (DESIGN.md seção 3)."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class AlmztechErro(Exception):
+    """Base de todas as exceções do SDK."""
+
+
+class AlmztechErroApi(AlmztechErro):
+    """Erro devolvido pela API (``{"mensagem": "..."}``). Não há código estruturado: ``mensagem`` é texto livre."""
+
+    def __init__(self, status_code: int, mensagem: str, corpo_bruto: Optional[str] = None):
+        super().__init__(f"A API da Almztech retornou {status_code}: {mensagem}")
+        self.status_code = status_code
+        self.mensagem = mensagem
+        self.corpo_bruto = corpo_bruto
+
+
+class AlmztechErroValidacao(AlmztechErroApi):
+    """422 (regra de negócio, inclusive franquia do plano esgotada) ou 400 (corpo recusado, com os erros por campo)."""
+
+
+class AlmztechErroAutenticacao(AlmztechErroApi):
+    """401 — token ausente, inválido ou revogado, ou licença inválida para produção. Só a mensagem diferencia."""
+
+
+class AlmztechErroAutorizacao(AlmztechErroApi):
+    """403 — papel sem permissão para o endpoint."""
+
+
+class AlmztechErroLimiteDeRequisicoes(AlmztechErroApi):
+    """429 — limite de requisições. Não é retentado sozinho: ``retry_after`` (segundos) diz quanto esperar."""
+
+    def __init__(self, mensagem: str, retry_after: Optional[float], corpo_bruto: Optional[str] = None):
+        super().__init__(429, mensagem, corpo_bruto)
+        self.retry_after = retry_after
+
+
+class AlmztechErroServidor(AlmztechErroApi):
+    """5xx — erro interno; em produção a mensagem pode vir genérica."""
+
+
+class AlmztechErroRede(AlmztechErro):
+    """Falha de rede, timeout ou DNS antes de qualquer resposta HTTP."""
+
+
+class AlmztechErroTempoDePollingEsgotado(AlmztechErro):
+    """O polling estourou o tempo total; ``ultimo_protocolo`` permite continuar manualmente."""
+
+    def __init__(self, protocolo: str, ultimo_protocolo: Optional[dict[str, Any]]):
+        status = (ultimo_protocolo or {}).get("status", "desconhecido")
+        super().__init__(f"O protocolo {protocolo} não concluiu no tempo de espera (último status: {status}).")
+        self.protocolo = protocolo
+        self.ultimo_protocolo = ultimo_protocolo
+
+
+class AlmztechErroProtocoloRejeitado(AlmztechErro):
+    """O protocolo terminou em ``REJEITADO`` ou ``ERRO_INTERNO``; o motivo está em ``protocolo["mensagem"]``."""
+
+    def __init__(self, protocolo: dict[str, Any]):
+        super().__init__(
+            f"O protocolo {protocolo.get('protocolo')} terminou em {protocolo.get('status')}: "
+            f"{protocolo.get('mensagem') or '(sem mensagem)'}"
+        )
+        self.protocolo = protocolo
+
+
+class AlmztechErroWebhook(AlmztechErro):
+    """Payload de webhook não reconhecido."""

almztech_sdk-0.2.0b1/src/almztech/filtros.py

@@ -0,0 +1,81 @@
+"""Filtros de ``consultar_com_filtros`` (DESIGN.md seção 7).
+
+O valor vai sempre como texto: datas ``yyyy-MM-dd`` e decimais com ponto. Campo desconhecido ou valor vazio é
+ignorado pela API (não filtra), por isso prefira as constantes e os construtores daqui.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from decimal import Decimal
+from typing import Optional, Union
+
+PRODUCAO = "PRD"
+HOMOLOGACAO = "HML"
+
+
+class CamposFiltro:
+    PROTOCOLO = "protocolo"
+    CODIGO_NOTA = "codigoNota"
+    NOME_EMITENTE = "nomeEmitente"
+    CPF_CNPJ_EMITENTE = "cpfCnpjEmitente"
+    NUMERO_RPS = "numeroRps"
+    SERIE_RPS = "serieRps"
+    LOTE_RPS = "loteRps"
+    VALOR_TOTAL = "valorTotal"
+    #: Data ``yyyy-MM-dd``.
+    DATA_EMISSAO = "dataEmissao"
+    #: Vários status separados por ``|``; só com ``Igual``.
+    STATUS = "status"
+
+
+class Operador:
+    IGUAL = "Igual"
+    DIFERENTE = "Diferente"
+    MAIOR_QUE = "MaiorQue"
+    MAIOR_OU_IGUAL = "MaiorOuIgual"
+    MENOR_QUE = "MenorQue"
+    MENOR_OU_IGUAL = "MenorOuIgual"
+    ENTRE = "Entre"
+    CONTEM = "Contem"
+    INICIA_COM = "IniciaCom"
+    TERMINA_COM = "TerminaCom"
+
+
+Numero = Union[int, float, Decimal]
+Data = Union[dt.date, str]
+
+
+def _texto_numero(valor: Numero) -> str:
+    return format(Decimal(str(valor)), "f") if not isinstance(valor, int) else str(valor)
+
+
+def _texto_data(valor: Data) -> str:
+    return valor if isinstance(valor, str) else valor.isoformat()
+
+
+def filtro(campo: str, operador: str, valor: str, valor_final: Optional[str] = None) -> dict:
+    item = {"campo": campo, "operador": operador, "valor": valor}
+    if valor_final is not None:
+        item["valorFinal"] = valor_final
+    return item
+
+
+def numero(campo: str, operador: str, valor: Numero) -> dict:
+    return filtro(campo, operador, _texto_numero(valor))
+
+
+def entre_valores(campo: str, inicio: Numero, fim: Numero) -> dict:
+    return filtro(campo, Operador.ENTRE, _texto_numero(inicio), _texto_numero(fim))
+
+
+def data(operador: str, valor: Data) -> dict:
+    return filtro(CamposFiltro.DATA_EMISSAO, operador, _texto_data(valor))
+
+
+def periodo(inicio: Data, fim: Data) -> dict:
+    return filtro(CamposFiltro.DATA_EMISSAO, Operador.ENTRE, _texto_data(inicio), _texto_data(fim))
+
+
+def com_status(*status: str) -> dict:
+    return filtro(CamposFiltro.STATUS, Operador.IGUAL, "|".join(status))

almztech_sdk-0.2.0b1/src/almztech/log.py

@@ -0,0 +1,41 @@
+"""Mascaramento central de log (DESIGN.md seção 6).
+
+Cobre request e response: ``senhaCertificado`` e ``senhaPrefeitura`` vêm em claro inclusive nas leituras de
+emitente. Todo log automático do SDK passa por aqui.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+_CAMPOS_SENSIVEIS = {"apikey", "senha", "senhacertificado", "senhaprefeitura", "base64", "arquivobase64", "login"}
+_MASCARA = "***"
+
+
+def mascarar_api_key(api_key: str) -> str:
+    """Mostra só os últimos 4 caracteres da api key."""
+    if not api_key:
+        return _MASCARA
+    return _MASCARA + (api_key[-4:] if len(api_key) > 4 else api_key)
+
+
+def mascarar_corpo_json(corpo: Optional[str]) -> str:
+    """Cópia do JSON com todo campo sensível mascarado. Corpo não-JSON nunca é devolvido cru."""
+    if not corpo or not corpo.strip():
+        return ""
+    try:
+        return json.dumps(_mascarar(json.loads(corpo)), ensure_ascii=False)
+    except ValueError:
+        return "<corpo não-JSON omitido da sanitização de log>"
+
+
+def _mascarar(valor: Any) -> Any:
+    if isinstance(valor, list):
+        return [_mascarar(item) for item in valor]
+    if isinstance(valor, dict):
+        return {
+            chave: _MASCARA if chave.lower() in _CAMPOS_SENSIVEIS else _mascarar(item)
+            for chave, item in valor.items()
+        }
+    return valor

almztech_sdk-0.2.0b1/src/almztech/modelos.py

@@ -0,0 +1,121 @@
+"""Tipos do wire format (``TypedDict``): os dados são ``dict`` em camelCase, exatamente como o JSON da API.
+
+Servem para o editor e o mypy; em runtime são dicionários comuns. Chaves com valor ``None`` não são enviadas
+(a API aplica o padrão dela, e null num campo numérico seria recusado com 400).
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+try:
+    from typing import Literal, TypedDict
+except ImportError:  # pragma: no cover
+    from typing_extensions import Literal, TypedDict  # type: ignore
+
+StatusProtocolo = Literal[
+    "EM_FILA", "EM_PROCESSAMENTO", "PENDENTE_PREFEITURA", "PROCESSADO_COM_SUCESSO", "REJEITADO", "CANCELADO", "ERRO_INTERNO"
+]
+StatusNota = Literal["EM_PROCESSAMENTO", "EMITIDA", "CANCELADA", "DENEGADA", "REJEITADA", "PENDENTE_PREFEITURA"]
+
+
+class Endereco(TypedDict, total=False):
+    logradouro: str
+    numero: str
+    complemento: str
+    bairro: str
+    cep: str
+    codigoPais: int
+    codigoIBGEUF: int
+    #: Obrigatório para o tomador: sem ele a nota falha depois, no processamento assíncrono.
+    codigoIBGEMunicipio: int
+    siglaUF: str
+
+
+class Destinatario(TypedDict, total=False):
+    cpfCnpj: str
+    razaoSocial: str
+    nomeFantasia: str
+    inscricaoEstadual: str
+    inscricaoMunicipal: str
+    telefone: str
+    endereco: Endereco
+
+
+class Servico(TypedDict, total=False):
+    codigo: str
+    descricao: str
+    codigoTributacao: str
+    localPrestacao: str
+    responsavelPelaRetencao: int
+    #: ABRASF: 1 Exigível, 2 Não incidência, 3 Isenção, 4 Exportação, 5 Imunidade, 6/7 Suspensa.
+    exigibilidadeISS: int
+    tipoTributacao: int
+    municipioIncidencia: int
+    aliquotaISS: float
+    #: 1 = retido pelo tomador, 2 = não retido.
+    retemISS: int
+    quantidade: float
+    valorUnitario: float
+    valorDesconto: float
+    valorAcrescimo: float
+    codigoCnae: str
+    numeroProcesso: str
+    nbs: str
+    ibsCbs: dict
+    pisCofins: dict
+    totaisDosTributos: dict
+
+
+class IdentificacaoDaNota(TypedDict, total=False):
+    #: Opcional com o controle automático de RPS do emitente: a API numera.
+    numeroRPS: str
+    serie: str
+    tipo: str
+    status: int
+    #: ``yyyy-MM-dd``.
+    dataEmissao: str
+    dataCompetencia: str
+
+
+class NotaFiscalResumida(TypedDict, total=False):
+    rps: IdentificacaoDaNota
+    destinatario: Destinatario
+    servicos: List[Servico]
+    #: ``[{"condicao": ..., "pagamentos": [{"parcela": 1, "dataPagamento": "yyyy-MM-dd", "valor": ...}]}]``.
+    condicoesPagamentos: List[dict]
+    observacao: str
+    #: Nome com o typo do schema real (``Subtituicao``): numeroRPS, numeroNota, serie, tipo, chaveNota, codigoMotivo, motivo.
+    subtituicaoRps: dict
+
+
+class RecepcaoLote(TypedDict, total=False):
+    identificacaoEmitente: str
+    notas: List[NotaFiscalResumida]
+    #: ``False`` = homologação (``HML-``), ``True`` = produção (``PRD-``). É por lote.
+    enviarParaProducao: bool
+    urlWebhook: str
+
+
+class ProtocoloNotaResponse(TypedDict, total=False):
+    codigoNota: int
+    tipoNota: str
+    numero: str
+    rps: str
+    serie: str
+    dataEmissao: str
+    situacao: StatusNota
+    codigoVerificacao: str
+    chaveAcesso: str
+    xml: str
+    pdf: str
+    dataHoraCancelamento: str
+    protocolo: str
+
+
+class ProtocoloResponse(TypedDict, total=False):
+    protocolo: str
+    status: StatusProtocolo
+    mensagem: Optional[str]
+    notas: List[ProtocoloNotaResponse]
+    dadosCancelamento: dict