Pular para o conteúdo

Exemplos em Ruby

Setup

Requer Ruby 3+. Sem dependências externas (stdlib).

Terminal window
export MYSE_API_BASE="https://api.mysebr.com.br/nfemyse-v3/rest"
export MYSE_API_TOKEN="seu_token_aqui"

Cliente HTTP centralizado

myse_api.rb
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
end
end

Cená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}"
end

Retry 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
end
end
# Uso
nfce = 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"
end
end

Emitir 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-xml
end

Cancelar 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'))
end

Lanç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'))
end

Cancelar 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'))
end

Emitir 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']
end

Cancelar NFS-e

def cancelar_nfse(client, chave, motivo)
validar_motivo!(motivo)
client.call('POST', '/nfse/cancelamento', { chave: chave, motivo: motivo })
end

Reconhecer 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 realizada
CODIGOS_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'))
end

Consulta 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 SEFAZ
nfce_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
end
end

Inutilizar 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 protocolo
end
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
destino
end
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}"
end
puts "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
end
end
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]
end

Rotinas

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 um
client.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 gravar
conferencia = 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}"
end
id_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 agora
agora = 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 execucoes
detalhe = client.call('GET', "/rotinas/#{id_rotina}")
raise detalhe['descricao'] if detalhe['status'] == '500' # inexistente ou excluída
puts 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-MM
if 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}/retomar
pausada = client.call('POST', "/rotinas/#{id_rotina}/pausar")
puts pausada.dig('data', 'rotina', 'situacao') # "pausada"
# 9. Excluir: status 001 e data.id-rotina
excluida = 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 ele
end
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
cert
end

CIOT

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,
'ChavePix' => '[email protected]',
'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, situacao
end
# 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 = encerrado
end
# 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 = retificado
end
ciot = emitir_ciot(client, 'VIAGEM-1021')['ciot']
retificar_ciot(client, ciot, { 'ValorFrete' => 1650.00, 'PesoCarga' => 1200 }) # só se TipoOperacao 2
cancelar_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,
'emailVendedor' => '[email protected]',
'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 cancelamento
end
# 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 venda
saida = 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',
'email' => '[email protected]',
'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
todos
end

Tratamento 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)
raise
end

Health 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 resposta
res = 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/CNPJ
cliente = client.call('GET', '/clientes/12345678000199')
# Buscar por nome
encontrados = client.call('GET', '/clientes/busca/exemplo')
top = client.call('GET', '/clientes/busca/top_clientes')
# Atualizar
client.call('PUT', '/clientes/12345678000199', {
tipo: 'J',
'razao-social' => 'Empresa Exemplo (Novo Nome) Ltda',
})
# Excluir
client.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
# Consultar
produto = 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')
# Atualizar
client.call('PUT', '/produtos/SKU-001', {
referencia: 'SKU-001',
nome: 'Camiseta Polo M (Novo)',
valor: '99.90',
})
# Excluir
client.call('DELETE', '/produtos/SKU-001')