Exemplos em Ruby
Setup
Requer Ruby 3+. Sem dependências externas (stdlib).
export MYSE_API_BASE="https://api.mysebr.com.br/nfemyse-v3/rest"export MYSE_API_TOKEN="seu_token_aqui"Cliente HTTP centralizado
require 'net/http'require 'json'require 'uri'
module Myse class ApiError < StandardError attr_reader :http_status, :payload, :request_id
def initialize(http_status, message, payload = nil, request_id = nil) @http_status = http_status @payload = payload @request_id = request_id super(message) end end
class Client BASE = ENV.fetch('MYSE_API_BASE') TOKEN = ENV.fetch('MYSE_API_TOKEN')
def call(method, path, body = nil, timeout: 30) uri = URI.parse("#{BASE}#{path}") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = (uri.scheme == 'https') http.read_timeout = timeout
req_class = { 'GET' => Net::HTTP::Get, 'POST' => Net::HTTP::Post, 'PUT' => Net::HTTP::Put, 'DELETE' => Net::HTTP::Delete, }.fetch(method.upcase)
req = req_class.new(uri.request_uri) req['Authorization'] = "Token #{TOKEN}" req['Content-Type'] = 'application/json' req.body = body.to_json if body
res = http.request(req) request_id = res['x-request-id'] json = JSON.parse(res.body) rescue {}
if res.code.to_i >= 400 msg = json.dig('error', 'message') || "HTTP #{res.code}" raise ApiError.new(res.code.to_i, msg, json, request_id) end
if json['status'] == '999' msg = json.dig('data', 'erro') || json['descricao'] || 'erro' rid = json.dig('meta', 'request_id') || request_id raise ApiError.new(200, msg, json, rid) end
json end endendCenário: emitir NFCe com polling
require_relative 'myse_api'
TERMINAIS = %w[004 010 900 999].freeze
def emitir_nfce(client, pedido) body = { serie: '65', cfop: '5102', 'numero-origem' => "PED-#{pedido[:id]}", tp_pagamento: pedido[:forma_pagamento], cliente: pedido[:cpf_cnpj_cliente], itens: pedido[:itens].map do |i| { produto: i[:sku], quantidade: i[:qtd].to_s, 'valor-unitario' => i[:preco].to_s, } end, }
emissao = client.call('POST', '/nfce/emissao', body)
unless %w[001 050].include?(emissao['status']) raise "Emissão falhou: #{emissao['descricao']}" end
recibo = emissao.dig('data', 'recibo') puts "[emissao] recibo=#{recibo} request_id=#{emissao.dig('meta', 'request_id')}"
wait = 5.0 inicio = Time.now
while Time.now - inicio < 5 * 60 sleep(wait) consulta = client.call('GET', "/nfce/cupom/#{recibo}") puts "[polling] status=#{consulta['status']}"
if TERMINAIS.include?(consulta['status']) return consulta['data'] if consulta['status'] == '004' raise "Status terminal não-sucesso: #{consulta['status']}" end
wait = [wait * 1.5, 30].min end
raise "Timeout aguardando recibo #{recibo}"endRetry com backoff
def com_retry(max_tentativas: 3) (1..max_tentativas).each do |i| begin return yield rescue Myse::ApiError => e raise if e.payload&.dig('status') == '999' raise if i == max_tentativas sleep(2 ** (i - 1)) # 1s, 2s, 4s end endend
# Usonfce = com_retry { emitir_nfce(client, pedido) }Helper de polling reutilizável
TERMINAIS = %w[004 010 900 999].freeze
def aguardar_recibo(client, path_base, recibo, timeout_sec: 300) wait = 5.0 inicio = Time.now
while Time.now - inicio < timeout_sec sleep(wait) resp = client.call('GET', "#{path_base}/#{recibo}") return resp if TERMINAIS.include?(resp['status']) wait = [wait * 1.5, 30].min end raise "Timeout aguardando recibo #{recibo}"end
# Cancelamento: 15 a 255 caracteres. Carta de correção da NF-e: 15 a 1000 (desde a 3.15.1).def validar_motivo!(motivo, max: 255) unless (15..max).include?(motivo.length) raise ArgumentError, "motivo deve ter entre 15 e #{max} caracteres" endendEmitir NF-e (com transporte completo)
def emitir_nfe(client, pedido) body = { 'serie' => '1', 'cfop' => '5102', 'numero-origem' => "PED-#{pedido[:id]}", 'tipo' => 'S', 'finalidade' => 'N', 'valor-despesas' => '0.00', 'cliente' => pedido[:cpf_cnpj_cliente], 'transporte' => { 'modalidade' => '0', 'transportadora' => pedido[:transportadora], 'placa-veiculo' => pedido[:placa], 'valor-frete' => pedido[:frete] || '0.00', 'valor-seguro' => '0.00', 'peso-bruto' => pedido[:peso_bruto], 'peso-liquido' => pedido[:peso_liquido], 'quantidade-volume' => '1', 'especie-volume' => 'Caixa', 'marca-volume' => 'Embalagem', }, 'itens' => pedido[:itens].map do |i| { 'produto' => i[:sku], 'quantidade' => i[:qtd].to_s, 'valor-unitario' => i[:preco].to_s, } end, 'faturas' => (pedido[:faturas] || []).map do |f| { 'valor' => f[:valor].to_s, 'data' => f[:data] } end, }
emissao = client.call('POST', '/nfe/emissao', body) unless %w[001 050].include?(emissao['status']) raise "Emissão falhou: #{emissao['descricao']}" end
resultado = aguardar_recibo(client, '/nfe/nota', emissao.dig('data', 'recibo')) unless resultado['status'] == '004' raise "Status terminal não-sucesso: #{resultado['status']}" end resultado['data'] # inclui sefaz.chave, url-danfe, url-xmlendCancelar NF-e
def cancelar_nfe(client, chave, motivo) validar_motivo!(motivo) cancel = client.call('POST', '/nfe/cancelamento', { chave: chave, motivo: motivo }) raise cancel['descricao'] unless cancel['status'] == '001' aguardar_recibo(client, '/nfe/cancelamento', cancel.dig('data', 'recibo'))endLançar carta de correção (CC-e)
# O campo 'motivo' na CC-e é o TEXTO da correção (xCorrecao).def carta_correcao_nfe(client, chave, texto_correcao) validar_motivo!(texto_correcao, max: 1000) # CC-e aceita até 1000 caracteres cce = client.call('POST', '/nfe/correcao', { chave: chave, motivo: texto_correcao }) raise cce['descricao'] unless cce['status'] == '001' aguardar_recibo(client, '/nfe/correcao', cce.dig('data', 'recibo'))endCancelar NFC-e
def cancelar_nfce(client, chave, motivo) validar_motivo!(motivo) cancel = client.call('POST', '/nfce/cancelamento', { chave: chave, motivo: motivo }) raise cancel['descricao'] unless cancel['status'] == '001' aguardar_recibo(client, '/nfce/cancelamento', cancel.dig('data', 'recibo'))endEmitir NFS-e (Nota Fiscal de Serviço)
def emitir_nfse(client, servico) body = { 'numero-origem' => "OS-#{servico[:id]}", 'observacao' => servico[:observacao], 'nome-contato' => servico[:nome_contato], 'telefone-contato' => servico[:telefone_contato], 'data-fim' => servico[:data_fim], 'cliente' => servico[:cpf_cnpj_cliente], 'itens' => servico[:itens].map do |i| { 'produto' => i[:codigo_servico], 'quantidade' => i[:qtd].to_s, 'valor-unitario' => i[:preco].to_s, } end, }
emissao = client.call('POST', '/nfse/emissao', body) unless %w[001 050].include?(emissao['status']) raise "Emissão NFSe falhou: #{emissao['descricao']}" end
resultado = aguardar_recibo(client, '/nfse/nota', emissao.dig('data', 'recibo')) unless resultado['status'] == '004' raise "Status terminal não-sucesso: #{resultado['status']}" end resultado['data']endCancelar NFS-e
def cancelar_nfse(client, chave, motivo) validar_motivo!(motivo) client.call('POST', '/nfse/cancelamento', { chave: chave, motivo: motivo })endReconhecer nota de fornecedor (MD-e)
# Códigos de reconhecimento:# '210200' — Confirmação da operação (terminal, irreversível)# '210210' — Ciência da operação (provisório, 15 dias)# '210220' — Desconhecimento da operação# '210240' — Operação não realizadaCODIGOS_RECONHECIMENTO = %w[210200 210210 210220 210240].freeze
def reconhecer_nota_fornecedor(client, chave, codigo) unless CODIGOS_RECONHECIMENTO.include?(codigo) raise ArgumentError, "Código inválido: #{codigo}" end
resp = client.call('POST', '/nffornecedor/reconhecimento', { chave: chave, 'codigo-reconhecimento' => codigo, }) raise resp['descricao'] unless resp['status'] == '001' aguardar_recibo(client, '/nffornecedor', resp.dig('data', 'recibo'))endConsulta completa por recibo
A consulta simples (/nfe/nota/{recibo}) serve para o polling. A completa devolve todos os dados
do documento. Veja Emitir NF-e e Paginação.
# NF-e: itens, transporte, cliente, faturas, notas referenciadas e dados da SEFAZ# (chave, protocolo, URLs do DANFE e do XML)nfe_completa = client.call('GET', "/nfe/nota/#{recibo}/completa")
# NFC-e: itens, cliente e dados da SEFAZnfce_completa = client.call('GET', "/nfce/cupom/#{recibo}/completa")# Recibo de outra operação (ex.: de um cancelamento) responde status "500".
# NFC-es pela paginação de path (legado). {pagina} começa em 1; quantidade até 500.def listar_nfces(client, quantidade: 100) return enum_for(:listar_nfces, client, quantidade: quantidade) unless block_given?
(1..).each do |pagina| resp = client.call('GET', "/nfce/paginacao/#{pagina}/#{quantidade}") break unless resp['status'] == '005' && resp['data'].is_a?(Array) resp['data'].each { |nfce| yield nfce } break if resp['data'].size < quantidade endendInutilizar numeração
Fecha na SEFAZ uma faixa de NF-e (/nfe/inutilizacao) ou NFC-e (/nfce/inutilizacao) que não foi
usada. Exige certificado A1. Veja Inutilizar numeração.
# modelo: 'nfe' (55) ou 'nfce' (65). Para um número só, final = inicial.def inutilizar(client, modelo, serie, inicial, final, justificativa, ano: nil) unless (15..255).include?(justificativa.length) raise ArgumentError, 'justificativa deve ter entre 15 e 255 caracteres' end
body = { 'serie' => serie, 'numero-inicial' => inicial.to_s, 'numero-final' => final.to_s, 'justificativa' => justificativa, } body['ano'] = ano if ano # ano em que a numeração foi GERADA ("26" ou "2026")
pedido = client.call('POST', "/#{modelo}/inutilizacao", body) unless pedido['status'] == '001' # 400: faixa com nota autorizada ou em processamento, faixa já na fila, certificado A3... raise pedido.dig('data', 'erro') || pedido['descricao'] end
resultado = aguardar_recibo(client, "/#{modelo}/inutilizacao", pedido.dig('data', 'recibo')) sefaz = resultado.dig('data', 'sefaz') || {} unless resultado['status'] == '004' # 900 = recusada pela SEFAZ raise "SEFAZ recusou: #{sefaz['codigo']} #{sefaz['mensagem']}" end sefaz # codigo "102" e protocoloend
inutilizar(client, 'nfe', '1', 120, 125, 'Falha no sistema pulou a numeração da série.')XML em lote por período
O ZIP com os XMLs de NF-e ou NFC-e de até 92 dias é gerado em segundo plano: solicite, consulte o protocolo e baixe o link temporário. Veja Baixar XMLs por período.
# tipo: 'NFe' ou 'NFCe'. Devolve o caminho do ZIP, ou nil se não havia nota.def baixar_xml_periodo(client, tipo, data_inicial, data_final, destino, email: nil) body = { 'tipo' => tipo, 'data-inicial' => data_inicial, 'data-final' => data_final } body['email'] = email if email
sol = client.call('POST', '/xml/solicitacao', body) # 050 = já havia uma solicitação igual em andamento; o protocolo devolvido é o dela unless %w[001 050].include?(sol['status']) raise sol.dig('data', 'erro') || sol['descricao'] end protocolo = sol.dig('data', 'protocolo')
wait = 5.0 # intervalo mínimo entre consultas: 2 s inicio = Time.now resp = nil loop do raise "Timeout aguardando protocolo #{protocolo}" if Time.now - inicio > 15 * 60 sleep(wait) resp = client.call('GET', "/xml/solicitacao/#{protocolo}") case resp['status'] when '005' then break # disponivel when '006' then return nil # sem-notas: final, reconsultar não muda when '002' then wait = [wait * 1.5, 30].min else # 007 falha (faça NOVA solicitação), 500 protocolo inexistente raise "Protocolo #{protocolo}: #{resp['status']} #{resp['descricao']}" end end
# url-download expira em data['expira-em'] (7 dias). Só aceita GET e NÃO leva Authorization. uri = URI.parse(resp.dig('data', 'url-download')) Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 120) do |http| http.request_get(uri.request_uri) do |res| raise "Download falhou: HTTP #{res.code}" unless res.is_a?(Net::HTTPSuccess) File.open(destino, 'wb') { |f| res.read_body { |chunk| f.write(chunk) } } end end destinoend
baixar_xml_periodo(client, 'NFe', '2026-04-01', '2026-04-30', 'nfe-2026-04.zip',Resumo diário
Totais por dia de NF-e e NFC-e emitidas, canceladas, denegadas e das falhas, para conciliação. Veja Resumo diário de emissões.
# Período de até 92 dias, datas AAAA-MM-DD.def resumo_diario(client, data_inicial, data_final) qs = URI.encode_www_form('data-inicial' => data_inicial, 'data-final' => data_final) resp = client.call('GET', "/resumo?#{qs}") raise resp['descricao'] unless resp['status'] == '005' resp['data']end
resumo = resumo_diario(client, '2026-08-01', '2026-08-06')resumo['dias'].each do |dia| # dias sem movimento não aparecem nfe, nfce = dia['nfe'], dia['nfce'] # canceladas é SUBCONJUNTO de emitidas: notas válidas = emitidas - canceladas puts "#{dia['data']} NF-e válidas=#{nfe['emitidas'] - nfe['canceladas']} " \ "NFC-e válidas=#{nfce['emitidas'] - nfce['canceladas']} falhas=#{dia['falhas'].values.sum}"endputs "Falhas no período: #{resumo.dig('totais', 'falhas')}"Classificação fiscal
Sugestão de NCM, CEST, CFOP, CST, alíquotas, IBS/CBS e ISS de um produto ou serviço, na mesma chamada (sem recibo). Só consulta: não grava nada. Confira a sugestão com o contador antes de emitir. Veja Classificação fiscal.
# Classifica um item e reenvia com `respostas` enquanto houver pergunta que você sabe responder.def classificar(client, produto, respostas_conhecidas = {}) body = produto.dup loop do # Sem NCM informado, o motor identifica o item por IA: dê folga ao timeout (70 s) resp = client.call('POST', '/classificacao-fiscal', body, timeout: 70) unless resp['status'] == '005' # 400: motivo na descricao, campo em data.campo raise ArgumentError, "#{resp['descricao']} (campo=#{resp.dig('data', 'campo')})" end
pacote = resp.dig('data', 'pacote') # chaves do pacote em snake_case ja_respondidas = body['respostas'] || {} novas = (pacote['perguntas_pendentes'] || []) .map { |p| p['id'] } .select { |id| respostas_conhecidas.key?(id) && !ja_respondidas.key?(id) } .to_h { |id| [id, respostas_conhecidas[id]] } # Sem pendência, ou só sobraram perguntas para mostrar ao usuário (p['texto']) return pacote if novas.empty?
body['respostas'] = ja_respondidas.merge(novas) # reenvia o MESMO produto endend
pacote = classificar(client, { 'referencia' => 'SKU-NB15', 'nome' => 'NOTEBOOK 15 POLEGADAS 8GB RAM', 'ncm' => '8471.30.12', 'documento' => 'nfe', 'destinatario' => 'contribuinte', 'destino' => 'interestadual',}, { 'empresa_industrial_ou_equiparada_ipi' => false, 'produto_sujeito_st_na_uf' => false,})puts pacote.dig('icms', 'cfop', 'valor')
# Até 10 produtos por chamada. Devolve [resultados, produtos para reenviar].def classificar_lote(client, produtos) resultados = [] reenviar = [] produtos.each_slice(10) do |fatia| resp = client.call('POST', '/classificacao-fiscal/lote', { 'produtos' => fatia }, timeout: 90) raise ArgumentError, resp['descricao'] unless resp['status'] == '005' # Cada item tem status próprio, na ordem do pedido: 005 (pacote), 400 (campo) ou 999 resp.dig('data', 'resultados').each do |item| resultados << item # não terminou no prazo do lote: reenvie só ele reenviar << fatia[item['indice']] if item['status'] == '999' end end [resultados, reenviar]endRotinas
Uma rotina emite NFS-e sozinha em cada data da agenda (recorrente, aluguel, condomínio). Todas as rotas respondem na hora; quem gera recibo é a NFS-e emitida. Veja Rotinas.
# Modelos e os campos (parametros) de cada umclient.call('GET', '/rotinas/modelos').dig('data', 'modelos').each do |modelo| puts "#{modelo['codigo']}: #{modelo['parametros'].map { |p| p['nome'] }.join(', ')}"end
rotina = { 'modelo' => 'NFSE_RECORRENTE', 'nome' => 'Suporte mensal - ACME', 'periodicidade' => 'mensal', 'dia' => 10, 'inicio' => '2026-11-01', # As chaves de parametros são os nomes dos campos do modelo (snake_case). # Os ids vêm de GET /rotinas/clientes?busca= e GET /rotinas/servicos. 'parametros' => { 'id_clifor' => 1262804, 'id_produto' => 88231, 'vl_servico' => '3.500,50', 'ds_discriminacao' => 'Suporte técnico de {competencia}', },}
# 1. Conferir sem gravarconferencia = client.call('POST', '/rotinas/validar', rotina)unless conferencia['status'] == '005' && conferencia.dig('data', 'pode-ativar') raise "#{conferencia['descricao']} #{conferencia['data'].to_json}"end
# 2. Criar. Sem "ativar", já sai ATIVA e emite nota fiscal sozinha.criada = client.call('POST', '/rotinas', rotina)unless criada['status'] == '001' # 400: data.campo ou data.pendencias raise "#{criada['descricao']} #{criada['data'].to_json}"endid_rotina = criada.dig('data', 'rotina', 'id-rotina')
# 3. A agenda não emite o mês da criação se o dia já passou: emita agoraagora = client.call('POST', "/rotinas/#{id_rotina}/emitir-agora", { 'competencia' => '2026-11' })puts agora.dig('data', 'numero-origem') # ROT-<id>-2026-11: enfileirada, ainda não autorizada
# 4. Histórico: o recibo de cada NFS-e. O desfecho sai em /nfse/nota/{recibo}.client.call('GET', "/rotinas/#{id_rotina}/execucoes").dig('data', 'execucoes').each do |execucao| next unless execucao['recibo'] nfse = aguardar_recibo(client, '/nfse/nota', execucao['recibo']) puts "#{execucao['competencia']} #{execucao['situacao-descricao']} #{nfse['status']}"end
# 5. Detalhe: dados, agenda, pendencias, diagnostico (por que emitiu ou não) e execucoesdetalhe = client.call('GET', "/rotinas/#{id_rotina}")raise detalhe['descricao'] if detalhe['status'] == '500' # inexistente ou excluídaputs detalhe.dig('data', 'rotina', 'diagnostico')
# 6. Alterar: os campos da criação, todos opcionais. Parâmetros parciais (o que não vier fica# como está) e o modelo não muda. Rotina pausada continua pausada, salvo 'ativar' => true.alterada = client.call('PUT', "/rotinas/#{id_rotina}", { 'dia' => 5, 'parametros' => { 'vl_servico' => 3800 } })unless alterada['status'] == '001' # 400: data.campo ou data.pendencias raise "#{alterada['descricao']} #{alterada['data'].to_json}"end
# 7. Valor extra em um único mês (só rotina ativa, só nos próximos meses da agenda)extras = client.call('GET', "/rotinas/#{id_rotina}/extras")['data']competencia = extras['competencias-disponiveis'].first # AAAA-MMif competencia lancado = client.call('PUT', "/rotinas/#{id_rotina}/extras/#{competencia}", { 'valor' => 250, # ou '250,50'; maior que zero 'motivo' => 'Visita técnica extra em 02/12', # 3 a 100 caracteres, vai na descrição da nota }) raise lancado['descricao'] unless lancado['status'] == '001' # 400: ex. condomínio não aceita extra lancado.dig('data', 'extras').each do |extra| puts "#{extra['competencia']} #{extra['valor']} #{extra['situacao']}" # Programado... end
# Desistiu? Remove o extra (não vale para mês já emitido ou em emissão) client.call('DELETE', "/rotinas/#{id_rotina}/extras/#{competencia}")end
# 8. Pausar (só rotina ativa). Retomar: POST /rotinas/{id}/retomarpausada = client.call('POST', "/rotinas/#{id_rotina}/pausar")puts pausada.dig('data', 'rotina', 'situacao') # "pausada"
# 9. Excluir: status 001 e data.id-rotinaexcluida = client.call('DELETE', "/rotinas/#{id_rotina}")raise excluida['descricao'] unless excluida['status'] == '001'Certificado digital A1
Instala o .pfx/.p12 da empresa da chave e acompanha a validade, sem passar pela tela do
FazNota. Desde a 3.20.0. Guarde a senha do arquivo numa variável de ambiente
(MYSE_CERT_SENHA). Veja Certificado digital A1.
def instalar_certificado_a1(client, caminho_pfx) # pack('m0') = base64 estrito, sem quebras de linha (sem depender da gem base64) arquivo = [File.binread(caminho_pfx)].pack('m0') # até 50 KB de arquivo senha = ENV.fetch('MYSE_CERT_SENHA') # NUNCA registre em log a senha, o arquivo nem o corpo desta requisição. resp = client.call('POST', '/certificado/a1', { 'arquivo' => arquivo, 'senha' => senha }) unless resp['status'] == '001' # 400: senha errada, não é A1 ICP-Brasil, vencido, de outro CNPJ, vence antes do atual... raise resp['descricao'] end resp['data'] # já em uso: a próxima emissão sai assinada com eleend
def conferir_certificado(client) cert = client.call('GET', '/certificado')['data'] # VALIDO, A_VENCER (até 30 dias), VENCIDO, NAO_INSTALADO ou INDISPONIVEL if %w[A_VENCER VENCIDO NAO_INSTALADO].include?(cert['situacao']) warn "Certificado #{cert['situacao']}: #{cert['dias-para-vencer']} dias para vencer" end certendCIOT
Declara na ANTT a operação de transporte de uma ETC e devolve o código do CIOT. Os campos seguem o leiaute PEF da ANTT (PascalCase). Veja Emitir CIOT.
def emitir_ciot(client, numero_viagem) # Não envie CpfCnpjContratado, RNTRCContratado nem IdOperacaoTransporte (vêm do cadastro). body = { 'numero-origem' => numero_viagem, # estável por viagem: reenvio após 999 usa o MESMO valor 'TipoOperacao' => 1, # 1 carga lotação, 2 carga fracionada 'CpfCnpjContratante' => '12345678000199', 'CpfCnpjDestinatario' => '98765432000155', 'ValorFrete' => 1500.00, 'Veiculos' => [{ 'Placa' => 'ABC1D23', 'NumeroEixos' => '4' }], 'OrigemDestino' => [{ 'Origem' => { 'CodigoMunicipioOrigem' => 4127700 }, 'Destino' => { 'CodigoMunicipioDestino' => 4104808 }, 'DistanciaPercorrida' => 45, }], 'DadosCarga' => { 'CodigoNaturezaCarga' => 9999, 'CodigoTipoCarga' => 5, 'PesoCarga' => 1000 }, 'InfIndicadoresOperacionais' => { 'IndAltoDesempenho' => false, 'IndRetornoVazio' => false, 'ComposicaoVeicular' => false, }, 'InfPagamento' => [{ 'TipoPagamento' => 6, 'IndPagamento' => 0, 'IdentificadorPix' => 'FRETE-2026-1021', }], } pedido = client.call('POST', '/ciot/emissao', body) unless pedido['status'] == '001' # 400: TipoOperacao inválido, A3, sem RNTRC... raise pedido.dig('data', 'erro') || pedido['descricao'] end
resultado = aguardar_recibo(client, '/ciot', pedido.dig('data', 'recibo')) unless resultado['status'] == '004' # 900: recusado pela ANTT ou pelo leiaute raise resultado.dig('data', 'erro') || resultado.dig('data', 'antt', 'mensagem') || resultado['descricao'] end resultado['data'] # ciot, codigo-verificador, protocolo, situacaoend
# Identifique por 'ciot' (o código) ou por 'recibo' (o da emissão).def encerrar_ciot(client, ciot) pedido = client.call('POST', '/ciot/encerramento', { 'ciot' => ciot }) raise pedido.dig('data', 'erro') || pedido['descricao'] unless pedido['status'] == '001' aguardar_recibo(client, '/ciot', pedido.dig('data', 'recibo')) # 004 = encerradoend
# Cancela na ANTT. CIOT que a ANTT recusou (REJEITADO) só é marcado como cancelado no FazNota.def cancelar_ciot(client, ciot, motivo) if motivo.to_s.empty? || motivo.length > 500 raise ArgumentError, 'motivo é obrigatório, até 500 caracteres' end pedido = client.call('POST', '/ciot/cancelamento', { 'ciot' => ciot, 'motivo' => motivo }) raise pedido.dig('data', 'erro') || pedido['descricao'] unless pedido['status'] == '001' resultado = aguardar_recibo(client, '/ciot', pedido.dig('data', 'recibo')) unless resultado['status'] == '010' # 010 = cancelado raise resultado.dig('data', 'erro') || resultado.dig('data', 'antt', 'mensagem') || resultado['descricao'] end resultado['data']end
# Só carga fracionada (TipoOperacao 2): lotação não se retifica, cancele e emita outro.# Informe ao menos um campo; CodigoMunicipioOrigem e CodigoMunicipioDestino vão juntos.def retificar_ciot(client, ciot, campos) pedido = client.call('POST', '/ciot/retificacao', { 'ciot' => ciot }.merge(campos)) raise pedido.dig('data', 'erro') || pedido['descricao'] unless pedido['status'] == '001' aguardar_recibo(client, '/ciot', pedido.dig('data', 'recibo')) # 004 = retificadoend
ciot = emitir_ciot(client, 'VIAGEM-1021')['ciot']retificar_ciot(client, ciot, { 'ValorFrete' => 1650.00, 'PesoCarga' => 1200 }) # só se TipoOperacao 2cancelar_ciot(client, ciot, 'Viagem cancelada pelo contratante.')RENAVE
Registra no SERPRO a entrada e a saída de veículos do estoque da revenda, vinculadas à NF-e da operação. Os campos seguem os nomes do SERPRO (camelCase). Veja RENAVE.
def renave_entrada_compra(client) body = { 'chaveNFe' => '35261012345678000190550010000012341000012345', # NF-e 55 da própria empresa 'cpfOperadorResponsavel' => '12345678901', 'dataCompra' => '2026-10-20', 'valorCompra' => 45000.00, 'veiculo' => { 'placa' => 'ABC1D23', 'numeroCrv' => '123456789012', 'renavam' => '01234567890', 'codigoSegurancaCrv' => '12345678901', 'tipoCrv' => 'DIGITAL', 'dataHoraMedicaoHodometro' => '2026-10-20T10:00:00', 'quilometragemHodometro' => 52000, 'documentoProprietarioAtual' => '98765432100', 'tipoDocumentoProprietarioAtual' => 'CPF', }, } pedido = client.call('POST', '/renave/nota-fiscal/entrada', body) unless pedido['status'] == '001' # 400: campo obrigatório ausente, sem A1 ou e-mail principal raise pedido.dig('data', 'erro') || pedido['descricao'] end
# 002 na fila, 003 sendo enviado ao SERPRO: o helper continua consultando resultado = aguardar_recibo(client, '/renave', pedido.dig('data', 'recibo')) unless resultado['status'] == '004' # 900: recusado pelo SERPRO ou pela validação raise resultado.dig('data', 'mensagem') || resultado.dig('data', 'erro') || resultado['descricao'] end resultado['data'] # guarde 'id-renave': é ele que identifica o cancelamentoend
# As outras operações seguem o mesmo fluxo: POST, recibo e GET /renave/{recibo}.# 004 registrado (id-renave, id-estoque), 010 cancelado, 900 recusado, 999 reenvie o MESMO pedido.# Os corpos levam CPF, CRV e endereço do comprador: não registre em log o corpo nem a resposta.def renave(client, rota, body, esperado: '004') pedido = client.call('POST', rota, body) raise pedido.dig('data', 'erro') || pedido['descricao'] unless pedido['status'] == '001' resultado = aguardar_recibo(client, '/renave', pedido.dig('data', 'recibo')) unless resultado['status'] == esperado raise resultado.dig('data', 'mensagem') || resultado.dig('data', 'erro') || resultado['descricao'] end resultado['data']end
# Saída do estoque (venda), vinculada à NF-e de vendasaida = renave(client, '/renave/nota-fiscal/saida', { 'chaveNFe' => '35261012345678000190550010000012401000012400', 'cpfOperadorResponsavel' => '12345678901', 'dataVenda' => '2026-10-25', 'valorVenda' => 52000.00, 'veiculo' => { 'placa' => 'ABC1D23', 'numeroCrv' => '123456789012', 'renavam' => '01234567890', 'codigoSegurancaCrv' => '12345678901', }, 'comprador' => { 'nome' => 'Maria Compradora', 'tipoDocumento' => 'CPF', 'numeroDocumento' => '11122233344', 'endereco' => { 'logradouro' => 'Rua das Flores', 'numero' => '100', 'bairro' => 'Centro', 'cep' => '01001000', 'municipio' => 'São Paulo', 'uf' => 'SP', }, },})
# Entrada de veículo que já é da empresa (sem compra). A chaveNFe identifica o movimento no# FazNota e não vai ao SERPRO. Aqui CRV (código e tipo) e hodômetro são obrigatórios.proprio = renave(client, '/renave/estoque/entrada-veiculo-proprio', { 'chaveNFe' => '35261012345678000190550010000012411000012411', 'cpfOperadorResponsavel' => '12345678901', 'dataEntradaEstoque' => '2026-10-20', 'veiculo' => { 'placa' => 'XYZ9A87', 'numeroCrv' => '210987654321', 'renavam' => '09876543210', 'codigoSegurancaCrv' => '10987654321', 'tipoCrv' => 'DIGITAL', 'dataHoraMedicaoHodometro' => '2026-10-20T09:00:00', 'quilometragemHodometro' => 18000, },})
# Cancelamentos: por id-renave OU pelo recibo do registro. Os dados do veículo vêm do registro.renave(client, '/renave/estoque/cancelamento-entrada', { 'id-renave' => proprio['id-renave'] }, esperado: '010')renave(client, '/renave/estoque/cancelamento-saida', { 'id-renave' => saida['id-renave'] }, esperado: '010')Listar com paginação
def listar_todos_clientes(client) todos = [] page = 1 page_size = 100
loop do resp = client.call('GET', "/clientes?page=#{page}&page_size=#{page_size}") break unless resp['status'] == '005' && resp['data'].is_a?(Array) todos.concat(resp['data']) break if resp['data'].size < page_size page += 1 sleep(0.2) end
todosendTratamento de erros
require 'logger'logger = Logger.new($stdout)client = Myse::Client.new
begin nfce = emitir_nfce(client, pedido) logger.info("NFCe emitida: #{nfce.dig('sefaz', 'chave')}")rescue Myse::ApiError => e logger.error({ event: 'api_error', http_status: e.http_status, request_id: e.request_id, message: e.message, }.to_json) raiseendHealth check (sem autenticação)
uri = URI.parse("#{Myse::Client::BASE}/health")res = Net::HTTP.get_response(uri)health = JSON.parse(res.body)# {"status" => "ok", "database" => "ok", "timestamp" => "..."}/health/deep faz um SELECT 1 no banco e traz as métricas do pool de conexões: 200 saudável,
503 com banco fora ou pool saturado. /health/pool traz só o pool, sem tocar no banco, e sempre
responde 200 (status STARTING enquanto o pool inicializa). Nenhum dos três exige token.
# Net::HTTP direto, sem Authorization: o Client levantaria ApiError no 503, que aqui é a respostares = Net::HTTP.get_response(URI.parse("#{Myse::Client::BASE}/health/deep"))deep = JSON.parse(res.body)# 200: {"status" => "UP", "check" => "deep", "total_ms", "db" => {"ok", "latency_ms"},# "pool" => {"active", "idle", "waiting", "total", "max", "connection_timeout_ms"}}# 503: {"status" => "DOWN", "check" => "deep", "timestamp"}if res.code == '503' warn "API DOWN: #{deep.to_json}"elsif deep.dig('pool', 'waiting').to_i > 0 warn "pool #{deep.dig('pool', 'active')}/#{deep.dig('pool', 'max')}, #{deep.dig('pool', 'waiting')} aguardando"end
pool = JSON.parse(Net::HTTP.get(URI.parse("#{Myse::Client::BASE}/health/pool")))puts "#{pool['status']} ativas=#{pool.dig('pool', 'active')} ociosas=#{pool.dig('pool', 'idle')}"Alterar nota antes da emissão (PUT)
Disponível em NF-e (/nfe/{id}), NFC-e (/nfce/{id}) e NFS-e (/nfse/{id}).
Só funciona enquanto a nota ainda não foi submetida para emissão.
def alterar_nota(client, tipo, id, dados) # tipo: 'nfe' | 'nfce' | 'nfse' client.call('PUT', "/#{tipo}/#{id}", dados)end
# Uso:alterar_nota(client, 'nfe', '12345', { serie: '1', cfop: '5102', cliente: '12345678000199', itens: [{ produto: 'SKU-001', quantidade: '3', 'valor-unitario' => '89.90' }],})Listagens
nfes = client.call('GET', '/nfe?page=1&page_size=20')nfces = client.call('GET', '/nfce?page=1&page_size=50')nfses = client.call('GET', '/nfse?dataInicial=2026-05-01&page=1&page_size=20')fornecedor = client.call('GET', '/nffornecedor?page=1&page_size=20')
# Forma legada (path-based)nfes_legado = client.call('GET', '/nfe/paginacao/1/20')Clientes (CRUD completo)
def cadastrar_pf(client, dados) client.call('POST', '/clientes', { tipo: 'F', nome: dados[:nome], cpf: dados[:cpf], rg: dados[:rg], 'consumidor-final' => '1', contato: { email: dados[:email], telefone: dados[:telefone] }, endereco: dados[:endereco], })end
def cadastrar_pj(client, dados) client.call('POST', '/clientes', { tipo: 'J', 'razao-social' => dados[:razao_social], 'nome-fantasia' => dados[:nome_fantasia], cnpj: dados[:cnpj], 'inscricao-municipal' => dados[:inscricao_municipal], 'tipo-inscricao-estadual' => dados[:contribuinte] || '9', 'inscricao-estadual' => dados[:inscricao_estadual] || 'ISENTO', 'consumidor-final' => '0', contato: { email: dados[:email], telefone: dados[:telefone] }, endereco: dados[:endereco], })end
# Consultar por CPF/CNPJcliente = client.call('GET', '/clientes/12345678000199')
# Buscar por nomeencontrados = client.call('GET', '/clientes/busca/exemplo')top = client.call('GET', '/clientes/busca/top_clientes')
# Atualizarclient.call('PUT', '/clientes/12345678000199', { tipo: 'J', 'razao-social' => 'Empresa Exemplo (Novo Nome) Ltda',})
# Excluirclient.call('DELETE', '/clientes/12345678000199')Produtos (CRUD completo)
def cadastrar_produto(client, produto) client.call('POST', '/produtos', { referencia: produto[:sku], nome: produto[:nome], valor: produto[:valor].to_s, medida: produto[:medida] || 'UN', categoria: produto[:categoria], ncm: produto[:ncm], origem: produto[:origem] || '0', 'cfop-preferencial' => produto[:cfop] || '5102', 'tipo-produto' => 'P', 'configuracoes-fiscais' => produto[:config_fiscal] || [], })end
def cadastrar_servico(client, servico) client.call('POST', '/produtos', { referencia: servico[:sku], nome: servico[:nome], valor: servico[:valor].to_s, medida: 'H', 'tipo-produto' => 'S', 'codigo-servico' => servico[:codigo_servico], })end
# Consultarproduto = client.call('GET', '/produtos/SKU-001')por_nome = client.call('GET', '/produtos/nome/Camiseta')
# Listar paginado com busca (use _todos para não filtrar)todos = client.call('GET', '/produtos/paginacao/1/20/_todos')filtrados = client.call('GET', '/produtos/paginacao/1/20/Camiseta')
# Atualizarclient.call('PUT', '/produtos/SKU-001', { referencia: 'SKU-001', nome: 'Camiseta Polo M (Novo)', valor: '99.90',})
# Excluirclient.call('DELETE', '/produtos/SKU-001')