almztech-sdk 0.2.0b1__py3-none-any.whl

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

almztech/recursos.py

@@ -0,0 +1,261 @@
+"""Sub-clients por recurso (DESIGN.md seção 1)."""
+
+from __future__ import annotations
+
+import base64
+import time
+from pathlib import Path
+from typing import Any, BinaryIO, Callable, Iterator, List, Optional, Union
+from urllib.parse import quote, urlencode
+
+from .erros import AlmztechErroProtocoloRejeitado, AlmztechErroTempoDePollingEsgotado
+from .modelos import ProtocoloNotaResponse, ProtocoloResponse, RecepcaoLote
+from .transporte import Transporte
+
+#: Caminho de arquivo, bytes ou um arquivo aberto em modo binário.
+Arquivo = Union[str, Path, bytes, bytearray, BinaryIO]
+
+
+def _base64(arquivo: Arquivo) -> str:
+    if isinstance(arquivo, (str, Path)):
+        conteudo = Path(arquivo).read_bytes()
+    elif isinstance(arquivo, (bytes, bytearray)):
+        conteudo = bytes(arquivo)
+    else:
+        conteudo = arquivo.read()
+    return base64.b64encode(conteudo).decode("ascii")
+
+
+def _seg(valor: Any) -> str:
+    return quote(str(valor), safe="")
+
+
+class NotasFiscais:
+    """Emissão, consulta, reconsulta, cancelamento, planilha e downloads de NFS-e (rota ``NFSe/*``)."""
+
+    def __init__(self, transporte: Transporte):
+        self._t = transporte
+
+    def emitir(self, lote: RecepcaoLote) -> ProtocoloResponse:
+        """``POST /NFSe/Emitir``. Devolve só o protocolo em fila; acompanhe com ``aguardar_conclusao`` ou o webhook.
+
+        Produção exige licença válida e franquia disponível; homologação não consome franquia. **Nunca retentado
+        automaticamente**: a API não tem chave de idempotência e um reenvio pode duplicar a nota.
+        """
+        return self._t.json("POST", "NFSe/Emitir", lote)
+
+    def aguardar_conclusao(
+        self,
+        protocolo: str,
+        intervalo_inicial: float = 2.0,
+        multiplicador: float = 1.5,
+        intervalo_maximo: float = 30.0,
+        timeout_total: float = 300.0,
+        a_cada_tentativa: Optional[Callable[[ProtocoloResponse], None]] = None,
+    ) -> ProtocoloResponse:
+        """Consulta o protocolo com intervalos crescentes até um status terminal.
+
+        ``REJEITADO``/``ERRO_INTERNO`` lançam ``AlmztechErroProtocoloRejeitado``; estourar ``timeout_total``
+        (segundos) lança ``AlmztechErroTempoDePollingEsgotado`` com o último protocolo.
+        """
+        inicio = time.monotonic()
+        atraso = intervalo_inicial
+        while True:
+            ultimo = self.consultar_protocolo(protocolo)
+            if a_cada_tentativa:
+                a_cada_tentativa(ultimo)
+
+            status = ultimo.get("status")
+            if status in ("PROCESSADO_COM_SUCESSO", "CANCELADO"):
+                return ultimo
+            if status in ("REJEITADO", "ERRO_INTERNO"):
+                raise AlmztechErroProtocoloRejeitado(dict(ultimo))
+            if time.monotonic() - inicio >= timeout_total:
+                raise AlmztechErroTempoDePollingEsgotado(protocolo, dict(ultimo))
+
+            time.sleep(atraso)
+            atraso = min(atraso * multiplicador, intervalo_maximo)
+
+    def consultar_protocolo(self, protocolo: str) -> ProtocoloResponse:
+        return self._ler(f"NFSe/Consultar/Protocolo/{_seg(protocolo)}")
+
+    def consultar_por_codigo(self, codigo_nota: int) -> ProtocoloNotaResponse:
+        return self._ler(f"NFSe/Consultar/{codigo_nota}")
+
+    def consultar_por_numero(self, numero_nota: str) -> ProtocoloNotaResponse:
+        """Pelo número da NFS-e na prefeitura; havendo mais de uma entre os seus emitentes, vem a mais recente."""
+        return self._ler(f"NFSe/Consultar/Numero/{_seg(numero_nota)}")
+
+    def consultar_lista(self, ambiente: str) -> List[dict]:
+        """As 50 notas mais recentes do ambiente (``PRODUCAO``/``HOMOLOGACAO`` de ``almztech.filtros``)."""
+        return self._ler(f"NFSe/ConsultarLista/{_seg(ambiente)}")
+
+    def consultar_lista_por_termo(self, ambiente: str, termo: str) -> List[dict]:
+        """Busca por CNPJ, código, número, razão social, nome fantasia ou protocolo (até 50)."""
+        return self._ler(f"NFSe/ConsultarListaPorTermo/{_seg(ambiente)}/{_seg(termo)}")
+
+    def consultar_com_filtros(
+        self,
+        ambiente: str,
+        filtros: Optional[List[dict]] = None,
+        filtro_rapido: Optional[str] = None,
+        pagina: int = 1,
+        limite_da_pagina: int = 50,
+    ) -> dict:
+        """POST por causa do corpo, mas é leitura (retentado como os GET). Limite real de 100 por página.
+
+        Devolve ``notas``, ``paginaAtual``, ``totalDeRegistros``, os totais por status e ``contagensPorAba``.
+        """
+        corpo = {
+            "ambiente": ambiente,
+            "filtroRapido": filtro_rapido,
+            "filtros": filtros,
+            "pagina": pagina,
+            "limiteDaPagina": limite_da_pagina,
+        }
+        return self._t.json("POST", "NFSe/ConsultarComFiltros", corpo, permite_retry=True)
+
+    def paginas(
+        self, ambiente: str, filtros: Optional[List[dict]] = None, filtro_rapido: Optional[str] = None, limite_da_pagina: int = 50
+    ) -> Iterator[dict]:
+        """Percorre todas as páginas de ``consultar_com_filtros``, nota a nota."""
+        pagina = 1
+        while True:
+            resultado = self.consultar_com_filtros(ambiente, filtros, filtro_rapido, pagina, limite_da_pagina)
+            notas = resultado.get("notas") or []
+            yield from notas
+            total_de_paginas = -(-resultado.get("totalDeRegistros", 0) // max(1, limite_da_pagina))
+            if not notas or pagina >= total_de_paginas:
+                return
+            pagina += 1
+
+    def reconsultar(self, codigo_nota: int) -> ProtocoloNotaResponse:
+        """Consulta a nota de novo na prefeitura e atualiza a situação local. Repetir é seguro."""
+        return self._ler(f"NFSe/Reconsultar/{codigo_nota}")
+
+    def reconsultar_por_chave_acesso(self, chave_acesso: str, enviar_para_producao: bool) -> ProtocoloNotaResponse:
+        """Reconsulta pela chave de acesso do Emissor Nacional; atualiza a nota local de mesmo número."""
+        return self._t.json(
+            "POST", f"NFSe/Reconsultar/ChaveAcesso/{_seg(chave_acesso)}", {"enviarParaProducao": enviar_para_producao}, permite_retry=True
+        )
+
+    def cancelar(self, codigo_nota: int, url_webhook: Optional[str] = None) -> ProtocoloResponse:
+        """``POST /NFSe/Cancelar/{codigo}``. Assíncrono como a emissão; não retentado."""
+        return self._t.json("POST", f"NFSe/Cancelar/{codigo_nota}", {"urlWebhook": url_webhook})
+
+    def baixar_xml(self, codigo_nota: int) -> bytes:
+        """Bytes do XML; gravar em disco fica com você."""
+        return self._t.bytes(f"NFSe/XML/{codigo_nota}")
+
+    def baixar_pdf(self, codigo_nota: int) -> bytes:
+        return self._t.bytes(f"NFSe/PDF/{codigo_nota}")
+
+    def baixar_modelo_planilha(self) -> bytes:
+        """O ``.xlsx`` modelo de ``importar_planilha``."""
+        return self._t.bytes("NFSe/ModeloPlanilha")
+
+    def importar_planilha(
+        self, identificacao_emitente: str, planilha: Arquivo, enviar_para_producao: bool, url_webhook: Optional[str] = None
+    ) -> dict:
+        """Emite as notas de uma planilha no formato do modelo, com os padrões fiscais do emitente.
+
+        O emitente precisa do controle automático de RPS. Devolve ``protocolos`` (um por lote) e ``erros`` por linha.
+        Não retentado (emite notas).
+        """
+        corpo = {
+            "arquivoBase64": _base64(planilha),
+            "identificacaoEmitente": identificacao_emitente,
+            "enviarParaProducao": enviar_para_producao,
+            "urlWebhook": url_webhook,
+        }
+        return self._t.json("POST", "NFSe/ImportarPlanilha", corpo)
+
+    def _ler(self, caminho: str) -> Any:
+        return self._t.json("GET", caminho, permite_retry=True)
+
+
+class Emitentes:
+    """CRUD de emitente e upload do certificado A1 (rota ``Emitente/*``).
+
+    ``atualizar`` grava todos os campos, inclusive os padrões fiscais: parta do emitente consultado. As leituras
+    trazem ``senhaCertificado``/``senhaPrefeitura`` em claro — nunca logue esses dicionários.
+    """
+
+    def __init__(self, transporte: Transporte):
+        self._t = transporte
+
+    def consultar(self) -> List[dict]:
+        return self._t.json("GET", "Emitente/Consultar", permite_retry=True)
+
+    def consultar_por_codigo(self, codigo: int) -> dict:
+        return self._t.json("GET", f"Emitente/Consultar/{codigo}", permite_retry=True)
+
+    def consultar_por_cpf_cnpj(self, cpf_cnpj: str) -> dict:
+        return self._t.json("GET", f"Emitente/ConsultarCpfCnpj/{_seg(cpf_cnpj)}", permite_retry=True)
+
+    def consultar_por_termo(self, termo: str) -> List[dict]:
+        return self._t.json("GET", f"Emitente/ConsultaPorTermo/{_seg(termo)}", permite_retry=True)
+
+    def cadastrar(self, emitente: dict) -> dict:
+        """Devolve ``{"mensagem", "cpfCnpj", "codigo"}``."""
+        return self._t.json("POST", "Emitente/Cadastrar", emitente)
+
+    def atualizar(self, emitente: dict) -> dict:
+        return self._t.json("PUT", "Emitente/Atualizar", emitente)
+
+    def excluir(self, codigo: int) -> dict:
+        return self._t.json("DELETE", f"Emitente/Excluir/{codigo}")
+
+    def upload_certificado(self, cnpj_emissor: str, certificado_pfx: Arquivo, senha: str) -> dict:
+        """Envia o ``.pfx``, convertido para Base64 aqui. Devolve ``chaveCertificado``, ``vencimento`` e ``aviso``."""
+        corpo = {"cnpjEmissor": cnpj_emissor, "base64": _base64(certificado_pfx), "senha": senha}
+        return self._t.json("POST", "Emitente/UploadCertificado", corpo)
+
+
+class Webhooks:
+    """CRUD e teste de webhook (fisicamente em ``Emitente/Webhook*``). Evento: 0 Emissão, 1 Cancelamento, 2 Rejeição."""
+
+    EMISSAO = 0
+    CANCELAMENTO = 1
+    REJEICAO = 2
+
+    def __init__(self, transporte: Transporte):
+        self._t = transporte
+
+    def obter(self, codigo: str) -> dict:
+        return self._t.json("GET", f"Emitente/Webhook/{_seg(codigo)}", permite_retry=True)
+
+    def listar_por_emitente(self, codigo_emitente: int) -> List[dict]:
+        return self._t.json("GET", f"Emitente/Webhooks/{codigo_emitente}", permite_retry=True)
+
+    def criar(self, codigo_emitente: int, evento: int, url: str, ativo: bool = True) -> dict:
+        """Não retentado: a API não barra URL duplicada, e um retry cego criaria dois registros."""
+        corpo = {"codigoEmitente": codigo_emitente, "evento": evento, "url": url, "ativo": ativo}
+        return self._t.json("POST", "Emitente/Webhook", corpo)
+
+    def atualizar(self, webhook: dict) -> dict:
+        return self._t.json("PUT", "Emitente/Webhook", webhook)
+
+    def excluir(self, codigo: str) -> dict:
+        return self._t.json("DELETE", f"Emitente/Webhook/{_seg(codigo)}")
+
+    def testar(self, url: str, evento: int) -> dict:
+        """Dispara um payload de exemplo do evento para a URL, sem precisar de webhook cadastrado."""
+        return self._t.json("POST", "Emitente/Webhook/Teste", {"url": url, "evento": evento})
+
+
+class Municipios:
+    """Municípios já homologados (``CoberturaNacional/MunicipiosHomologados``)."""
+
+    def __init__(self, transporte: Transporte):
+        self._t = transporte
+
+    def homologados(self, codigo_ibge: Optional[int] = None, termo_de_busca: Optional[str] = None) -> List[dict]:
+        """Pelo código IBGE ou por um termo; sem nenhum dos dois vem vazio. Até 20 ``{"id": <IBGE>, "text"}``."""
+        parametros = {}
+        if codigo_ibge is not None:
+            parametros["codigo"] = codigo_ibge
+        if termo_de_busca:
+            parametros["termoDeBusca"] = termo_de_busca
+        sufixo = f"?{urlencode(parametros)}" if parametros else ""
+        return self._t.json("GET", f"CoberturaNacional/MunicipiosHomologados{sufixo}", permite_retry=True)

almztech/transporte.py

@@ -0,0 +1,186 @@
+"""HTTP do SDK: header ``x-api-key``, retry só em leituras, mapeamento de erros e JSON sem nulos."""
+
+from __future__ import annotations
+
+import json
+import random
+import socket
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from email.utils import parsedate_to_datetime
+from typing import Any, Callable, Mapping, Optional, Tuple
+
+from .erros import (
+    AlmztechErroApi,
+    AlmztechErroAutenticacao,
+    AlmztechErroAutorizacao,
+    AlmztechErroLimiteDeRequisicoes,
+    AlmztechErroRede,
+    AlmztechErroServidor,
+    AlmztechErroValidacao,
+)
+from .log import mascarar_api_key, mascarar_corpo_json
+
+VERSAO_SDK = "0.2.0-beta.1"
+
+# (status, headers, corpo) — o que um envio HTTP devolve.
+RespostaHttp = Tuple[int, Mapping[str, str], bytes]
+
+# Envio HTTP injetável (proxy corporativo, instrumentação, testes): (método, url, headers, corpo, timeout).
+# Deve devolver a resposta inclusive em 4xx/5xx e lançar OSError só em falha de rede.
+EnvioHttp = Callable[[str, str, Mapping[str, str], Optional[bytes], float], RespostaHttp]
+
+
+@dataclass
+class OpcoesDeRetry:
+    """Só operações seguras (leituras) são retentadas, e só em falha de rede ou 5xx (DESIGN.md seção 4)."""
+
+    tentativas: int = 3
+    intervalo_inicial: float = 0.5
+    multiplicador: float = 2.0
+    intervalo_maximo: float = 10.0
+
+    def atraso(self, tentativa: int) -> float:
+        base = min(self.intervalo_inicial * self.multiplicador ** (tentativa - 1), self.intervalo_maximo)
+        return base + random.random() * base * 0.2
+
+
+@dataclass
+class OpcoesDoClient:
+    #: Padrão: produção. O ambiente fiscal é por chamada (``enviarParaProducao``), não por URL.
+    base_url: str = "https://api.almztech.com.br"
+    #: Timeout de rede por chamada, em segundos. Não é o tempo de processamento da prefeitura.
+    timeout: float = 30.0
+    retry: OpcoesDeRetry = field(default_factory=OpcoesDeRetry)
+    envio_http: Optional[EnvioHttp] = None
+    #: Recebe só mensagens já mascaradas.
+    logger: Optional[Callable[[str], None]] = None
+
+
+def _envio_urllib(metodo: str, url: str, headers: Mapping[str, str], corpo: Optional[bytes], timeout: float) -> RespostaHttp:
+    requisicao = urllib.request.Request(url, data=corpo, headers=dict(headers), method=metodo)
+    try:
+        with urllib.request.urlopen(requisicao, timeout=timeout) as resposta:
+            return resposta.status, dict(resposta.headers), resposta.read()
+    except urllib.error.HTTPError as erro:
+        return erro.code, dict(erro.headers or {}), erro.read()
+
+
+def _sem_nulos(valor: Any) -> Any:
+    """Campo numérico da API (tipo não anulável) recusa null com 400: omitir deixa valer o padrão dela."""
+    if isinstance(valor, dict):
+        return {chave: _sem_nulos(item) for chave, item in valor.items() if item is not None}
+    if isinstance(valor, (list, tuple)):
+        return [_sem_nulos(item) for item in valor]
+    return valor
+
+
+class Transporte:
+    def __init__(self, api_key: str, opcoes: Optional[OpcoesDoClient] = None):
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key é obrigatório.")
+        self._api_key = api_key
+        self._opcoes = opcoes or OpcoesDoClient()
+        self._envio = self._opcoes.envio_http or _envio_urllib
+        self._base_url = self._opcoes.base_url.rstrip("/")
+        self._log(f"AlmztechClient configurado (apiKey={mascarar_api_key(api_key)}, baseUrl={self._base_url})")
+
+    def json(self, metodo: str, caminho: str, corpo: Any = None, permite_retry: bool = False) -> Any:
+        status, headers, conteudo = self._enviar(metodo, caminho, corpo, permite_retry)
+        texto = conteudo.decode("utf-8") if conteudo else ""
+        self._log(f"<- {status} {metodo} {caminho} {mascarar_corpo_json(texto)}")
+        if status >= 400:
+            raise _mapear_erro(status, headers, texto)
+        return json.loads(texto) if texto.strip() else None
+
+    def bytes(self, caminho: str) -> bytes:
+        status, headers, conteudo = self._enviar("GET", caminho, None, True)
+        if status >= 400:
+            raise _mapear_erro(status, headers, conteudo.decode("utf-8", errors="replace"))
+        return conteudo
+
+    def _enviar(self, metodo: str, caminho: str, corpo: Any, permite_retry: bool) -> RespostaHttp:
+        retry = self._opcoes.retry
+        tentativas = max(1, retry.tentativas) if permite_retry else 1
+        dados = None if corpo is None else json.dumps(_sem_nulos(corpo), ensure_ascii=False).encode("utf-8")
+        headers = {
+            "x-api-key": self._api_key,
+            "User-Agent": f"almztech-python-sdk/{VERSAO_SDK}",
+            "Accept": "application/json",
+        }
+        if dados is not None:
+            headers["Content-Type"] = "application/json"
+
+        tentativa = 1
+        while True:
+            if dados is not None:
+                self._log(f"-> {metodo} {caminho} {mascarar_corpo_json(dados.decode('utf-8'))}")
+            try:
+                resposta = self._envio(metodo, f"{self._base_url}/{caminho}", headers, dados, self._opcoes.timeout)
+            except (OSError, socket.timeout) as erro:
+                if tentativa >= tentativas:
+                    raise AlmztechErroRede(f"Falha de rede chamando {metodo} {caminho}: {erro}") from erro
+                time.sleep(retry.atraso(tentativa))
+                tentativa += 1
+                continue
+
+            if resposta[0] >= 500 and tentativa < tentativas:
+                time.sleep(retry.atraso(tentativa))
+                tentativa += 1
+                continue
+            return resposta
+
+    def _log(self, mensagem: str) -> None:
+        if self._opcoes.logger:
+            self._opcoes.logger(mensagem)
+
+
+def _mapear_erro(status: int, headers: Mapping[str, str], corpo: str) -> AlmztechErroApi:
+    mensagem = _extrair_mensagem(corpo)
+    if status in (400, 422):
+        return AlmztechErroValidacao(status, mensagem, corpo)
+    if status == 401:
+        return AlmztechErroAutenticacao(status, mensagem, corpo)
+    if status == 403:
+        return AlmztechErroAutorizacao(status, mensagem, corpo)
+    if status == 429:
+        retry_after = next((valor for chave, valor in headers.items() if chave.lower() == "retry-after"), None)
+        return AlmztechErroLimiteDeRequisicoes(mensagem, _ler_retry_after(retry_after), corpo)
+    if status >= 500:
+        return AlmztechErroServidor(status, mensagem, corpo)
+    return AlmztechErroApi(status, mensagem, corpo)
+
+
+def _ler_retry_after(valor: Optional[str]) -> Optional[float]:
+    if not valor:
+        return None
+    try:
+        return float(valor)
+    except ValueError:
+        pass
+    try:
+        return max(0.0, parsedate_to_datetime(valor).timestamp() - time.time())
+    except (TypeError, ValueError):
+        return None
+
+
+def _extrair_mensagem(corpo: str) -> str:
+    """``{mensagem}`` é o formato de erro da API; o 400 do ASP.NET vem como ProblemDetails, com ``errors`` por campo."""
+    if not corpo.strip():
+        return "(sem corpo de resposta)"
+    try:
+        dados = json.loads(corpo)
+    except ValueError:
+        return corpo
+    if isinstance(dados, dict):
+        if isinstance(dados.get("mensagem"), str):
+            return dados["mensagem"]
+        if isinstance(dados.get("errors"), dict):
+            return "; ".join(
+                f"{campo}: {erro}"
+                for campo, erros in dados["errors"].items()
+                for erro in (erros if isinstance(erros, list) else [erros])
+            )
+    return corpo

almztech/webhook.py

@@ -0,0 +1,53 @@
+"""Leitura do payload recebido no seu endpoint de webhook (DESIGN.md seção 5)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Union
+
+from .erros import AlmztechErroWebhook
+from .modelos import ProtocoloResponse
+
+EMISSAO = "Emissao"
+CANCELAMENTO = "Cancelamento"
+REJEICAO = "Rejeicao"
+
+
+@dataclass
+class EventoWebhook:
+    #: ``EMISSAO``, ``CANCELAMENTO`` ou ``REJEICAO``.
+    tipo: str
+    #: Payload completo (mesmo schema do polling).
+    protocolo: ProtocoloResponse
+
+
+def ler_webhook(corpo: Union[str, bytes, dict]) -> EventoWebhook:
+    """Classifica o corpo: ``notas`` não vazio → Emissão; senão ``dadosCancelamento`` → Cancelamento; senão status
+    ``REJEITADO`` → Rejeição (motivo em ``mensagem``); senão lança ``AlmztechErroWebhook``.
+
+    Não verifica autenticidade: a API não assina o webhook. Proteger o endpoint (token secreto na URL, allowlist
+    de IP, mTLS) é responsabilidade de quem o recebe.
+    """
+    if isinstance(corpo, (str, bytes)):
+        if not corpo.strip():
+            raise AlmztechErroWebhook("Corpo do webhook vazio.")
+        try:
+            protocolo = json.loads(corpo)
+        except ValueError as erro:
+            raise AlmztechErroWebhook("Corpo do webhook não é um JSON válido.") from erro
+    else:
+        protocolo = corpo
+
+    if not isinstance(protocolo, dict):
+        raise AlmztechErroWebhook("Corpo do webhook não é um objeto.")
+    if protocolo.get("notas"):
+        return EventoWebhook(EMISSAO, protocolo)  # type: ignore[arg-type]
+    if protocolo.get("dadosCancelamento"):
+        return EventoWebhook(CANCELAMENTO, protocolo)  # type: ignore[arg-type]
+    if protocolo.get("status") == "REJEITADO":
+        return EventoWebhook(REJEICAO, protocolo)  # type: ignore[arg-type]
+    raise AlmztechErroWebhook(
+        f"Payload de webhook não reconhecido (protocolo='{protocolo.get('protocolo')}', status='{protocolo.get('status')}'): "
+        "sem 'notas', sem 'dadosCancelamento' e status diferente de REJEITADO."
+    )

almztech_sdk-0.2.0b1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+almztech/__init__.py,sha256=yinVEKS8gFF2iqxhfxGjoHEy-_8lsixNjPKkj1ACals,2023
+almztech/erros.py,sha256=rrX0JPnnkK6wMWCg46tHs3OmOtiHiNwacGH6Kj1VfpI,2761
+almztech/filtros.py,sha256=5HPPeKduxae8Z0qmNozyniokxZ4zBf1HJo11FWFqAjg,2350
+almztech/log.py,sha256=qCfsysu0c0yRk652fLZAmItLzh8D4wrbUT_hO5auK9U,1370
+almztech/modelos.py,sha256=RhSnKntqqVGalU5aE6DntyssSTtVjPcDBEDsXi2PaJY,3442
+almztech/recursos.py,sha256=6k-WYBBYT7tCntO6d8HYfB33GitqTJ5iQnuWbjY75VM,11681
+almztech/transporte.py,sha256=l4rAa-N5CfJWHVE8ZRnknWbwPCHc8OSo9cskas9Zr20,7525
+almztech/webhook.py,sha256=P1cZjjxqRHiR5g4ErEgBu2pFIdoHwCyxuc322kM-IxQ,2063
+almztech_sdk-0.2.0b1.dist-info/licenses/LICENSE,sha256=uqMmLTm1nVGoPA4sX-SuPVAlHqOIAOodFCmgTKlrYyM,1080
+almztech_sdk-0.2.0b1.dist-info/METADATA,sha256=Ji4EEy86vucIs80RPYEjinC4kQ7QLlRYKwuJFKEXG3s,4754
+almztech_sdk-0.2.0b1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+almztech_sdk-0.2.0b1.dist-info/top_level.txt,sha256=GvWAgq0KzS6oMP9Dsi2ijW9_HWVgzo0Cl4Zw8KkjiRo,9
+almztech_sdk-0.2.0b1.dist-info/RECORD,,

almztech_sdk-0.2.0b1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

almztech_sdk-0.2.0b1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+almztech