almztech-sdk 0.2.0.beta.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 82f60a2af5454b5669483a42bd14e79526754c05e973dd72b3917e4c78ddcc2a
+  data.tar.gz: a23ad001fc0de6a3f3f5a6bdcf371d329afcf62eccbda914813130cc8e2e2e65
+SHA512:
+  metadata.gz: ec2bff67dcf4c97f98475ae14b7ce67175dd9e5b759612d4546b9b817c8b0350285fcae97c085b9f986842147f3a8047c17433e900be3982e23143c879c7f20c
+  data.tar.gz: 51c5c64972d301c5c2321527affc69224fe81e0093baaf0cb37aaa8d241d7fc989eeffa40fe18b6432292985809308d7cb6b7dc2a433d92406de3636fe7a521c

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

data/README.md

@@ -0,0 +1,87 @@
+# almztech-sdk (Ruby)
+
+SDK oficial da [Almztech](https://almztech.com.br) para Ruby. 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
+gem install almztech-sdk --pre
+```
+
+- Ruby 3.0+.
+- **Sem dependências de runtime**: usa `net/http` e `json` da biblioteca padrão. Dá para injetar outro envio HTTP com `envio_http:`, qualquer objeto que responda a `call`.
+- Os dados são `Hash` no formato exato do JSON da API, em camelCase. Na entrada aceita chaves símbolo ou string; as respostas vêm com chaves string. Valores `nil` não são enviados.
+
+## Uso
+
+```ruby
+require "almztech"
+
+# 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 = Almztech::Client.new(ENV.fetch("ALMZTECH_API_KEY"))
+
+begin
+  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: Date.today.iso8601 },
+      destinatario: { cpfCnpj: "11222333000181", razaoSocial: "Cliente Exemplo Ltda",
+                      endereco: { cep: "50030170", codigoIBGEMunicipio: 2_611_606 } },
+      servicos: [{ codigo: "0105", descricao: "Licenciamento de software", quantidade: 1,
+                   valorUnitario: 1500.0, aliquotaISS: 2, retemISS: 2 }]
+    }]
+  )
+
+  resultado = client.notas_fiscais.aguardar_conclusao(protocolo["protocolo"])
+  resultado.fetch("notas", []).each do |nota|
+    File.binwrite("nfse-#{nota['numero']}.pdf", client.notas_fiscais.baixar_pdf(nota["codigoNota"]))
+  end
+rescue Almztech::ErroProtocoloRejeitado => e
+  puts "Rejeitada: #{e.protocolo['mensagem']}"
+rescue Almztech::ErroValidacao => e
+  puts "Recusada: #{e.mensagem}"
+end
+
+# No seu endpoint de webhook (a API não assina o payload: proteja a URL):
+evento = Almztech::Webhook.ler(request.body.read) # evento.tipo: :emissao, :cancelamento ou :rejeicao
+```
+
+Consulta com filtros e paginação automática:
+
+```ruby
+filtros = [Almztech::Filtros.periodo("2026-10-01", "2026-10-31"), Almztech::Filtros.com_status("EMITIDA")]
+client.notas_fiscais.paginas(Almztech::Filtros::PRODUCAO, filtros: filtros).each do |nota|
+  puts "#{nota['numeroNota']} #{nota['valorTotal']}"
+end
+```
+
+Exceções:
+- `Almztech::ErroValidacao` (422 e 400);
+- `ErroAutenticacao` (401);
+- `ErroAutorizacao` (403);
+- `ErroLimiteDeRequisicoes` (429, com `retry_after`);
+- `ErroServidor` (5xx);
+- `ErroRede`;
+- `ErroTempoDePollingEsgotado`;
+- `ErroProtocoloRejeitado`;
+- `ErroWebhook`.
+
+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/ruby). Os SDKs das outras linguagens (.NET, Node.js,
+  PHP, Java e Python) 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/ruby/LICENSE).

data/lib/almztech/erros.rb

@@ -0,0 +1,66 @@
+module Almztech
+  # Base de todas as exceções do SDK (DESIGN.md seção 3).
+  class Erro < StandardError; end
+
+  # Erro devolvido pela API ({"mensagem": "..."}). Não há código estruturado: +mensagem+ é texto livre.
+  class ErroApi < Erro
+    attr_reader :status_code, :mensagem, :corpo_bruto
+
+    def initialize(status_code, mensagem, corpo_bruto = nil)
+      super("A API da Almztech retornou #{status_code}: #{mensagem}")
+      @status_code = status_code
+      @mensagem = mensagem
+      @corpo_bruto = corpo_bruto
+    end
+  end
+
+  # 422 (regra de negócio, inclusive franquia do plano esgotada) ou 400 (corpo recusado, com os erros por campo).
+  class ErroValidacao < ErroApi; end
+
+  # 401 — token ausente, inválido ou revogado, ou licença inválida para produção. Só a mensagem diferencia.
+  class ErroAutenticacao < ErroApi; end
+
+  # 403 — papel sem permissão para o endpoint.
+  class ErroAutorizacao < ErroApi; end
+
+  # 429 — limite de requisições. Não é retentado sozinho: +retry_after+ (segundos) diz quanto esperar.
+  class ErroLimiteDeRequisicoes < ErroApi
+    attr_reader :retry_after
+
+    def initialize(mensagem, retry_after, corpo_bruto = nil)
+      super(429, mensagem, corpo_bruto)
+      @retry_after = retry_after
+    end
+  end
+
+  # 5xx — erro interno; em produção a mensagem pode vir genérica.
+  class ErroServidor < ErroApi; end
+
+  # Falha de rede, timeout ou DNS antes de qualquer resposta HTTP.
+  class ErroRede < Erro; end
+
+  # O polling estourou o tempo total; +ultimo_protocolo+ permite continuar manualmente.
+  class ErroTempoDePollingEsgotado < Erro
+    attr_reader :protocolo, :ultimo_protocolo
+
+    def initialize(protocolo, ultimo_protocolo)
+      status = ultimo_protocolo && ultimo_protocolo["status"] || "desconhecido"
+      super("O protocolo #{protocolo} não concluiu no tempo de espera (último status: #{status}).")
+      @protocolo = protocolo
+      @ultimo_protocolo = ultimo_protocolo
+    end
+  end
+
+  # O protocolo terminou em REJEITADO ou ERRO_INTERNO; o motivo está em +protocolo["mensagem"]+.
+  class ErroProtocoloRejeitado < Erro
+    attr_reader :protocolo
+
+    def initialize(protocolo)
+      super("O protocolo #{protocolo['protocolo']} terminou em #{protocolo['status']}: #{protocolo['mensagem'] || '(sem mensagem)'}")
+      @protocolo = protocolo
+    end
+  end
+
+  # Payload de webhook não reconhecido.
+  class ErroWebhook < Erro; end
+end

data/lib/almztech/filtros.rb

@@ -0,0 +1,55 @@
+require "date"
+
+module Almztech
+  # 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.
+  module Filtros
+    PRODUCAO = "PRD".freeze
+    HOMOLOGACAO = "HML".freeze
+
+    module Campos
+      PROTOCOLO = "protocolo".freeze
+      CODIGO_NOTA = "codigoNota".freeze
+      NOME_EMITENTE = "nomeEmitente".freeze
+      CPF_CNPJ_EMITENTE = "cpfCnpjEmitente".freeze
+      NUMERO_RPS = "numeroRps".freeze
+      SERIE_RPS = "serieRps".freeze
+      LOTE_RPS = "loteRps".freeze
+      VALOR_TOTAL = "valorTotal".freeze
+      # Data yyyy-MM-dd.
+      DATA_EMISSAO = "dataEmissao".freeze
+      # Vários status separados por |; só com Igual.
+      STATUS = "status".freeze
+    end
+
+    # Operadores (OperadorFiltro da API, pelo nome).
+    OPERADORES = %w[Igual Diferente MaiorQue MaiorOuIgual MenorQue MenorOuIgual Entre Contem IniciaCom TerminaCom].freeze
+
+    module_function
+
+    def filtro(campo, operador, valor, valor_final = nil)
+      item = { "campo" => campo, "operador" => operador, "valor" => valor }
+      item["valorFinal"] = valor_final unless valor_final.nil?
+      item
+    end
+
+    def texto(campo, operador, valor) = filtro(campo, operador, valor.to_s)
+    def numero(campo, operador, valor) = filtro(campo, operador, decimal(valor))
+    def entre_valores(campo, inicio, fim) = filtro(campo, "Entre", decimal(inicio), decimal(fim))
+    def data(operador, valor) = filtro(Campos::DATA_EMISSAO, operador, data_iso(valor))
+    def periodo(inicio, fim) = filtro(Campos::DATA_EMISSAO, "Entre", data_iso(inicio), data_iso(fim))
+    def com_status(*status) = filtro(Campos::STATUS, "Igual", status.join("|"))
+
+    # Sempre ponto decimal, independente do locale, sem notação científica.
+    def decimal(valor)
+      return valor.to_s if valor.is_a?(Integer) || valor.is_a?(String)
+
+      format("%.10f", valor).sub(/0+\z/, "").sub(/\.\z/, "")
+    end
+
+    def data_iso(valor)
+      valor.respond_to?(:strftime) ? valor.strftime("%Y-%m-%d") : valor.to_s
+    end
+  end
+end

data/lib/almztech/log.rb

@@ -0,0 +1,36 @@
+require "json"
+
+module Almztech
+  # 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.
+  module Log
+    CAMPOS_SENSIVEIS = %w[apikey senha senhacertificado senhaprefeitura base64 arquivobase64 login].freeze
+    MASCARA = "***".freeze
+
+    module_function
+
+    # Mostra só os últimos 4 caracteres da api key.
+    def mascarar_api_key(api_key)
+      return MASCARA if api_key.nil? || api_key.empty?
+
+      MASCARA + (api_key.length > 4 ? api_key[-4..] : api_key)
+    end
+
+    # Cópia do JSON com todo campo sensível mascarado. Corpo não-JSON nunca é devolvido cru.
+    def mascarar_corpo_json(corpo)
+      return "" if corpo.nil? || corpo.strip.empty?
+
+      JSON.generate(mascarar(JSON.parse(corpo)))
+    rescue JSON::ParserError
+      "<corpo não-JSON omitido da sanitização de log>"
+    end
+
+    def mascarar(valor)
+      case valor
+      when Array then valor.map { |item| mascarar(item) }
+      when Hash then valor.to_h { |chave, item| [chave, CAMPOS_SENSIVEIS.include?(chave.to_s.downcase) ? MASCARA : mascarar(item)] }
+      else valor
+      end
+    end
+  end
+end

data/lib/almztech/recursos.rb

@@ -0,0 +1,190 @@
+require "erb"
+require "uri"
+
+module Almztech
+  # Conteúdo de .pfx/.xlsx: caminho de arquivo (Pathname), String binária ou IO aberto. Uso interno.
+  module Arquivo
+    module_function
+
+    def base64(arquivo)
+      conteudo =
+        if arquivo.respond_to?(:read) then arquivo.read
+        elsif arquivo.is_a?(Pathname) then File.binread(arquivo)
+        else arquivo.to_s
+        end
+      [conteudo].pack("m0")
+    end
+  end
+
+  def self.segmento(valor) = ERB::Util.url_encode(valor.to_s)
+
+  # Emissão, consulta, reconsulta, cancelamento, planilha e downloads de NFS-e (rota NFSe/*). Os dados são Hash com as
+  # chaves camelCase do JSON da API; chaves com nil não são enviadas.
+  class NotasFiscais
+    def initialize(transporte)
+      @t = transporte
+    end
+
+    # POST /NFSe/Emitir. Devolve só o protocolo em fila: acompanhe com +aguardar_conclusao+ ou pelo 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.
+    def emitir(lote) = @t.json("POST", "NFSe/Emitir", lote)
+
+    # Consulta o protocolo com intervalos crescentes até um status terminal. REJEITADO/ERRO_INTERNO lançam
+    # ErroProtocoloRejeitado; estourar +timeout_total+ (segundos) lança ErroTempoDePollingEsgotado com o último protocolo.
+    def aguardar_conclusao(protocolo, intervalo_inicial: 2.0, multiplicador: 1.5, intervalo_maximo: 30.0, timeout_total: 300.0, &a_cada_tentativa)
+      inicio = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      atraso = intervalo_inicial
+      loop do
+        ultimo = consultar_protocolo(protocolo)
+        a_cada_tentativa&.call(ultimo)
+
+        case ultimo["status"]
+        when "PROCESSADO_COM_SUCESSO", "CANCELADO" then return ultimo
+        when "REJEITADO", "ERRO_INTERNO" then raise ErroProtocoloRejeitado.new(ultimo)
+        end
+        raise ErroTempoDePollingEsgotado.new(protocolo, ultimo) if Process.clock_gettime(Process::CLOCK_MONOTONIC) - inicio >= timeout_total
+
+        sleep(atraso)
+        atraso = [atraso * multiplicador, intervalo_maximo].min
+      end
+    end
+
+    def consultar_protocolo(protocolo) = ler("NFSe/Consultar/Protocolo/#{Almztech.segmento(protocolo)}")
+    def consultar_por_codigo(codigo_nota) = ler("NFSe/Consultar/#{Integer(codigo_nota)}")
+
+    # Pelo número da NFS-e na prefeitura; havendo mais de uma entre os seus emitentes, vem a mais recente.
+    def consultar_por_numero(numero_nota) = ler("NFSe/Consultar/Numero/#{Almztech.segmento(numero_nota)}")
+
+    # As 50 notas mais recentes do ambiente (Filtros::PRODUCAO/HOMOLOGACAO).
+    def consultar_lista(ambiente) = ler("NFSe/ConsultarLista/#{Almztech.segmento(ambiente)}")
+
+    # Busca por CNPJ, código, número, razão social, nome fantasia ou protocolo (até 50).
+    def consultar_lista_por_termo(ambiente, termo)
+      ler("NFSe/ConsultarListaPorTermo/#{Almztech.segmento(ambiente)}/#{Almztech.segmento(termo)}")
+    end
+
+    # 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".
+    def consultar_com_filtros(ambiente, filtros: nil, filtro_rapido: nil, pagina: 1, limite_da_pagina: 50)
+      corpo = { "ambiente" => ambiente, "filtroRapido" => filtro_rapido, "filtros" => filtros, "pagina" => pagina, "limiteDaPagina" => limite_da_pagina }
+      @t.json("POST", "NFSe/ConsultarComFiltros", corpo, permite_retry: true)
+    end
+
+    # Percorre todas as páginas de +consultar_com_filtros+, nota a nota (Enumerator sem bloco).
+    def paginas(ambiente, filtros: nil, filtro_rapido: nil, limite_da_pagina: 50)
+      return enum_for(:paginas, ambiente, filtros: filtros, filtro_rapido: filtro_rapido, limite_da_pagina: limite_da_pagina) unless block_given?
+
+      pagina = 1
+      loop do
+        resultado = consultar_com_filtros(ambiente, filtros: filtros, filtro_rapido: filtro_rapido, pagina: pagina, limite_da_pagina: limite_da_pagina)
+        notas = resultado["notas"] || []
+        notas.each { |nota| yield nota }
+        break if notas.empty? || pagina >= (resultado["totalDeRegistros"].to_i / [1, limite_da_pagina].max.to_f).ceil
+
+        pagina += 1
+      end
+    end
+
+    # Consulta a nota de novo na prefeitura e atualiza a situação local. Repetir é seguro.
+    def reconsultar(codigo_nota) = ler("NFSe/Reconsultar/#{Integer(codigo_nota)}")
+
+    # Reconsulta pela chave de acesso do Emissor Nacional; atualiza a nota local de mesmo número.
+    def reconsultar_por_chave_acesso(chave_acesso, enviar_para_producao)
+      @t.json("POST", "NFSe/Reconsultar/ChaveAcesso/#{Almztech.segmento(chave_acesso)}", { "enviarParaProducao" => enviar_para_producao }, permite_retry: true)
+    end
+
+    # POST /NFSe/Cancelar/{codigo}. Assíncrono como a emissão; não retentado.
+    def cancelar(codigo_nota, url_webhook: nil) = @t.json("POST", "NFSe/Cancelar/#{Integer(codigo_nota)}", { "urlWebhook" => url_webhook })
+
+    # Bytes do XML; gravar em disco fica com você.
+    def baixar_xml(codigo_nota) = @t.bytes("NFSe/XML/#{Integer(codigo_nota)}")
+    def baixar_pdf(codigo_nota) = @t.bytes("NFSe/PDF/#{Integer(codigo_nota)}")
+
+    # O .xlsx modelo de +importar_planilha+.
+    def baixar_modelo_planilha = @t.bytes("NFSe/ModeloPlanilha")
+
+    # Emite as notas de uma planilha no formato do modelo, com os padrões fiscais do emitente (que precisa do controle
+    # automático de RPS). Devolve "protocolos" (um por lote) e "erros" por linha. Não retentado (emite notas).
+    # +planilha+: Pathname, String binária ou IO aberto.
+    def importar_planilha(identificacao_emitente, planilha, enviar_para_producao, url_webhook: nil)
+      corpo = {
+        "arquivoBase64" => Arquivo.base64(planilha),
+        "identificacaoEmitente" => identificacao_emitente,
+        "enviarParaProducao" => enviar_para_producao,
+        "urlWebhook" => url_webhook
+      }
+      @t.json("POST", "NFSe/ImportarPlanilha", corpo)
+    end
+
+    private
+
+    def ler(caminho) = @t.json("GET", caminho, permite_retry: true)
+  end
+
+  # 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 hashes.
+  class Emitentes
+    def initialize(transporte)
+      @t = transporte
+    end
+
+    # Até 50 emitentes da conta.
+    def consultar = @t.json("GET", "Emitente/Consultar", permite_retry: true)
+    def consultar_por_codigo(codigo) = @t.json("GET", "Emitente/Consultar/#{Integer(codigo)}", permite_retry: true)
+    def consultar_por_cpf_cnpj(cpf_cnpj) = @t.json("GET", "Emitente/ConsultarCpfCnpj/#{Almztech.segmento(cpf_cnpj)}", permite_retry: true)
+    def consultar_por_termo(termo) = @t.json("GET", "Emitente/ConsultaPorTermo/#{Almztech.segmento(termo)}", permite_retry: true)
+
+    # Devolve "mensagem", "cpfCnpj" e o "codigo" do emitente criado.
+    def cadastrar(emitente) = @t.json("POST", "Emitente/Cadastrar", emitente)
+    def atualizar(emitente) = @t.json("PUT", "Emitente/Atualizar", emitente)
+    def excluir(codigo) = @t.json("DELETE", "Emitente/Excluir/#{Integer(codigo)}")
+
+    # Envia o .pfx (Pathname, String binária ou IO), convertido para Base64 aqui. Devolve "chaveCertificado",
+    # "vencimento" e "aviso".
+    def upload_certificado(cnpj_emissor, certificado_pfx, senha)
+      @t.json("POST", "Emitente/UploadCertificado", { "cnpjEmissor" => cnpj_emissor, "base64" => Arquivo.base64(certificado_pfx), "senha" => senha })
+    end
+  end
+
+  # CRUD e teste de webhook (fisicamente em Emitente/Webhook*). Um registro = um evento.
+  class Webhooks
+    # Eventos: a API os serializa como número.
+    EMISSAO = 0
+    CANCELAMENTO = 1
+    REJEICAO = 2
+
+    def initialize(transporte)
+      @t = transporte
+    end
+
+    def obter(codigo) = @t.json("GET", "Emitente/Webhook/#{Almztech.segmento(codigo)}", permite_retry: true)
+    def listar_por_emitente(codigo_emitente) = @t.json("GET", "Emitente/Webhooks/#{Integer(codigo_emitente)}", permite_retry: true)
+
+    # Não retentado: a API não barra URL duplicada, e um retry cego criaria dois registros.
+    def criar(codigo_emitente:, evento:, url:, ativo: true)
+      @t.json("POST", "Emitente/Webhook", { "codigoEmitente" => codigo_emitente, "evento" => evento, "url" => url, "ativo" => ativo })
+    end
+
+    def atualizar(webhook) = @t.json("PUT", "Emitente/Webhook", webhook)
+    def excluir(codigo) = @t.json("DELETE", "Emitente/Webhook/#{Almztech.segmento(codigo)}")
+
+    # Dispara um payload de exemplo do evento para a URL, sem precisar de webhook cadastrado.
+    def testar(url:, evento:) = @t.json("POST", "Emitente/Webhook/Teste", { "url" => url, "evento" => evento })
+  end
+
+  # Municípios já homologados (CoberturaNacional/MunicipiosHomologados).
+  class Municipios
+    def initialize(transporte)
+      @t = transporte
+    end
+
+    # Pelo código IBGE e/ou por um termo; sem nenhum dos dois vem vazio. Até 20 {"id" => <IBGE>, "text" => ...}.
+    def homologados(codigo_ibge: nil, termo_de_busca: nil)
+      parametros = { "codigo" => codigo_ibge, "termoDeBusca" => termo_de_busca }.reject { |_, valor| valor.nil? || valor.to_s.empty? }
+      sufixo = parametros.empty? ? "" : "?#{URI.encode_www_form(parametros)}"
+      @t.json("GET", "CoberturaNacional/MunicipiosHomologados#{sufixo}", permite_retry: true)
+    end
+  end
+end

data/lib/almztech/transporte.rb

@@ -0,0 +1,146 @@
+require "json"
+require "net/http"
+require "openssl"
+require "time"
+require "uri"
+
+module Almztech
+  # Envio HTTP padrão, com net/http. Um envio injetável é qualquer objeto com
+  # +call(metodo, url, headers, corpo, timeout)+ que devolve +[status, headers, corpo]+ inclusive em 4xx/5xx e só
+  # lança exceção em falha de rede (proxy corporativo, instrumentação, testes).
+  ENVIO_NET_HTTP = lambda do |metodo, url, headers, corpo, timeout|
+    uri = URI(url)
+    Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: timeout, read_timeout: timeout) do |http|
+      requisicao = Net::HTTPGenericRequest.new(metodo, !corpo.nil?, true, uri.request_uri, headers)
+      requisicao.body = corpo if corpo
+      resposta = http.request(requisicao)
+      [resposta.code.to_i, resposta.each_header.to_h, resposta.body.to_s]
+    end
+  end
+
+  # HTTP do SDK: header x-api-key, retry só em leituras (falha de rede ou 5xx), mapeamento de erros e JSON sem nulos.
+  class Transporte
+    ERROS_DE_REDE = [IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError].freeze
+
+    # +base_url+: padrão de produção (o ambiente fiscal é por chamada, +enviarParaProducao+). +timeout+: segundos de
+    # rede por chamada, não o tempo de processamento da prefeitura. +logger+: recebe só mensagens já mascaradas.
+    def initialize(api_key, base_url: "https://api.almztech.com.br", timeout: 30, tentativas: 3, intervalo_inicial: 0.5,
+                   multiplicador: 2.0, intervalo_maximo: 10.0, envio_http: nil, logger: nil)
+      raise ArgumentError, "api_key é obrigatório." if api_key.nil? || api_key.strip.empty?
+
+      @api_key = api_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @tentativas = tentativas
+      @intervalo_inicial = intervalo_inicial
+      @multiplicador = multiplicador
+      @intervalo_maximo = intervalo_maximo
+      @envio = envio_http || ENVIO_NET_HTTP
+      @logger = logger
+      log("AlmztechClient configurado (apiKey=#{Log.mascarar_api_key(api_key)}, baseUrl=#{@base_url})")
+    end
+
+    def json(metodo, caminho, corpo = nil, permite_retry: false)
+      status, headers, texto = enviar(metodo, caminho, corpo, permite_retry)
+      texto = texto.to_s.dup.force_encoding(Encoding::UTF_8)
+      log("<- #{status} #{metodo} #{caminho} #{Log.mascarar_corpo_json(texto)}")
+      raise mapear_erro(status, headers, texto) if status >= 400
+
+      texto.strip.empty? ? nil : JSON.parse(texto)
+    end
+
+    def bytes(caminho)
+      status, headers, corpo = enviar("GET", caminho, nil, true)
+      raise mapear_erro(status, headers, corpo.to_s.dup.force_encoding(Encoding::UTF_8)) if status >= 400
+
+      corpo.to_s.b
+    end
+
+    private
+
+    def enviar(metodo, caminho, corpo, permite_retry)
+      tentativas = permite_retry ? [1, @tentativas].max : 1
+      json = corpo.nil? ? nil : JSON.generate(sem_nulos(corpo))
+      headers = { "x-api-key" => @api_key, "User-Agent" => "almztech-ruby-sdk/#{VERSAO_SDK}", "Accept" => "application/json" }
+      headers["Content-Type"] = "application/json" if json
+
+      tentativa = 1
+      loop do
+        log("-> #{metodo} #{caminho} #{Log.mascarar_corpo_json(json)}") if json
+        begin
+          resposta = @envio.call(metodo, "#{@base_url}/#{caminho}", headers, json, @timeout)
+        rescue *ERROS_DE_REDE => erro
+          raise ErroRede, "Falha de rede chamando #{metodo} #{caminho}: #{erro.message}" if tentativa >= tentativas
+
+          sleep(atraso(tentativa))
+          tentativa += 1
+          next
+        end
+
+        if resposta[0] >= 500 && tentativa < tentativas
+          sleep(atraso(tentativa))
+          tentativa += 1
+          next
+        end
+        return resposta
+      end
+    end
+
+    def atraso(tentativa)
+      base = [@intervalo_inicial * (@multiplicador**(tentativa - 1)), @intervalo_maximo].min
+      base + rand * base * 0.2
+    end
+
+    # Campo numérico da API (tipo não anulável) recusa null com 400: omitir deixa valer o padrão dela.
+    def sem_nulos(valor)
+      case valor
+      when Hash then valor.each_with_object({}) { |(chave, item), saida| saida[chave] = sem_nulos(item) unless item.nil? }
+      when Array then valor.map { |item| sem_nulos(item) }
+      else valor
+      end
+    end
+
+    def log(mensagem)
+      @logger&.call(mensagem)
+    end
+
+    def mapear_erro(status, headers, corpo)
+      mensagem = extrair_mensagem(corpo)
+      case status
+      when 400, 422 then ErroValidacao.new(status, mensagem, corpo)
+      when 401 then ErroAutenticacao.new(status, mensagem, corpo)
+      when 403 then ErroAutorizacao.new(status, mensagem, corpo)
+      when 429 then ErroLimiteDeRequisicoes.new(mensagem, ler_retry_after(headers), corpo)
+      else status >= 500 ? ErroServidor.new(status, mensagem, corpo) : ErroApi.new(status, mensagem, corpo)
+      end
+    end
+
+    def ler_retry_after(headers)
+      valor = headers.find { |nome, _| nome.to_s.casecmp?("retry-after") }&.last
+      valor = valor.first if valor.is_a?(Array)
+      return nil if valor.nil? || valor.to_s.strip.empty?
+      return valor.to_i if valor.to_s.match?(/\A\d+\z/)
+
+      [(Time.httpdate(valor) - Time.now).to_i, 0].max
+    rescue ArgumentError
+      nil
+    end
+
+    # {mensagem} é o formato de erro da API; o 400 do ASP.NET vem como ProblemDetails, com +errors+ por campo.
+    def extrair_mensagem(corpo)
+      return "(sem corpo de resposta)" if corpo.strip.empty?
+
+      dados = JSON.parse(corpo)
+      if dados.is_a?(Hash)
+        return dados["mensagem"] if dados["mensagem"].is_a?(String)
+
+        if dados["errors"].is_a?(Hash)
+          return dados["errors"].flat_map { |campo, erros| Array(erros).map { |erro| "#{campo}: #{erro}" } }.join("; ")
+        end
+      end
+      corpo
+    rescue JSON::ParserError
+      corpo
+    end
+  end
+end

data/lib/almztech/versao.rb

@@ -0,0 +1,5 @@
+module Almztech
+  VERSAO_SDK = "0.2.0-beta.1"
+  # RubyGems não aceita o hífen do pré-lançamento.
+  VERSAO_GEM = "0.2.0.beta.1"
+end

data/lib/almztech/webhook.rb

@@ -0,0 +1,42 @@
+require "json"
+
+module Almztech
+  # Leitura do payload recebido no seu endpoint de webhook (DESIGN.md seção 5). 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.
+  module Webhook
+    EMISSAO = :emissao
+    CANCELAMENTO = :cancelamento
+    REJEICAO = :rejeicao
+
+    # Evento classificado: +tipo+ (EMISSAO, CANCELAMENTO ou REJEICAO) e o payload completo (mesmo schema do polling).
+    Evento = Struct.new(:tipo, :protocolo, keyword_init: true)
+
+    module_function
+
+    # "notas" não vazio → Emissão; senão "dadosCancelamento" → Cancelamento; senão status REJEITADO → Rejeição (motivo
+    # em "mensagem"); senão lança ErroWebhook. +corpo+: o corpo cru do POST ou um Hash já decodificado.
+    def ler(corpo)
+      protocolo =
+        if corpo.is_a?(Hash)
+          corpo
+        else
+          raise ErroWebhook, "Corpo do webhook vazio." if corpo.nil? || corpo.strip.empty?
+
+          begin
+            JSON.parse(corpo)
+          rescue JSON::ParserError
+            raise ErroWebhook, "Corpo do webhook não é um JSON válido."
+          end
+        end
+      raise ErroWebhook, "Corpo do webhook não é um objeto." unless protocolo.is_a?(Hash)
+
+      return Evento.new(tipo: EMISSAO, protocolo: protocolo) if protocolo["notas"].is_a?(Array) && !protocolo["notas"].empty?
+      return Evento.new(tipo: CANCELAMENTO, protocolo: protocolo) if protocolo["dadosCancelamento"]
+      return Evento.new(tipo: REJEICAO, protocolo: protocolo) if protocolo["status"] == "REJEITADO"
+
+      raise ErroWebhook, "Payload de webhook não reconhecido (protocolo='#{protocolo['protocolo']}', status='#{protocolo['status']}'): " \
+                         "sem 'notas', sem 'dadosCancelamento' e status diferente de REJEITADO."
+    end
+  end
+end

data/lib/almztech.rb

@@ -0,0 +1,30 @@
+require "pathname"
+require_relative "almztech/versao"
+require_relative "almztech/erros"
+require_relative "almztech/log"
+require_relative "almztech/transporte"
+require_relative "almztech/filtros"
+require_relative "almztech/recursos"
+require_relative "almztech/webhook"
+
+# SDK oficial Ruby da Almztech (DESIGN.md).
+#
+#   client = Almztech::Client.new(ENV.fetch("ALMZTECH_API_KEY"))
+#   protocolo = client.notas_fiscais.emitir(lote)
+#   resultado = client.notas_fiscais.aguardar_conclusao(protocolo["protocolo"])
+module Almztech
+  # 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. As opções (+base_url+, +timeout+, +tentativas+, +envio_http+, +logger+...) são as
+  # de Transporte.
+  class Client
+    attr_reader :notas_fiscais, :emitentes, :webhooks, :municipios
+
+    def initialize(api_key, **opcoes)
+      transporte = Transporte.new(api_key, **opcoes)
+      @notas_fiscais = NotasFiscais.new(transporte)
+      @emitentes = Emitentes.new(transporte)
+      @webhooks = Webhooks.new(transporte)
+      @municipios = Municipios.new(transporte)
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: almztech-sdk
+version: !ruby/object:Gem::Version
+  version: 0.2.0.beta.1
+platform: ruby
+authors:
+- ALMZTECH SOFTWARES LTDA
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-08 00:00:00.000000000 Z
+dependencies: []
+description: Emissão, consulta, reconsulta e cancelamento de NFS-e, importação por
+  planilha, Emitente e Webhook.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/almztech.rb
+- lib/almztech/erros.rb
+- lib/almztech/filtros.rb
+- lib/almztech/log.rb
+- lib/almztech/recursos.rb
+- lib/almztech/transporte.rb
+- lib/almztech/versao.rb
+- lib/almztech/webhook.rb
+homepage: https://docs.almztech.com.br
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://docs.almztech.com.br
+  documentation_uri: https://docs.almztech.com.br
+  source_code_uri: https://gitlab.com/almztech/sdks/-/tree/main/ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: SDK oficial Ruby para a API da Almztech
+test_files: []