Exemplos em JavaScript / TypeScript
Setup
Requer Node.js 18+ (que tem fetch nativo).
# .env (use dotenv ou similar)MYSE_API_BASE=https://api.mysebr.com.br/nfemyse-v3/restMYSE_API_TOKEN=seu_token_aquiCliente HTTP centralizado
const BASE = process.env.MYSE_API_BASE;const TOKEN = process.env.MYSE_API_TOKEN;
export class ApiError extends Error { constructor(httpStatus, message, payload, requestId) { super(message); this.httpStatus = httpStatus; this.payload = payload; this.requestId = requestId; }}
export async function mApi(method, path, body, options = {}) { const url = `${BASE}${path}`; const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 30_000);
try { const res = await fetch(url, { method, headers: { Authorization: `Token ${TOKEN}`, 'Content-Type': 'application/json', }, body: body ? JSON.stringify(body) : undefined, signal: controller.signal, });
const requestId = res.headers.get('x-request-id') ?? undefined;
if (!res.ok) { const errBody = await res.json().catch(() => ({})); throw new ApiError( res.status, errBody?.error?.message ?? `HTTP ${res.status}`, errBody, requestId ); }
const json = await res.json();
if (json.status === '999') { throw new ApiError( 200, json.data?.erro ?? json.descricao, json, json.meta?.request_id ?? requestId ); }
return json; } finally { clearTimeout(timeout); }}const BASE = process.env.MYSE_API_BASE!;const TOKEN = process.env.MYSE_API_TOKEN!;
export interface Meta { request_id: string; timestamp: string;}
export interface ApiResponse<T = unknown> { status: string; descricao: string; data?: T; meta?: Meta;}
export class ApiError extends Error { constructor( public readonly httpStatus: number, message: string, public readonly payload: unknown, public readonly requestId?: string ) { super(message); this.name = 'ApiError'; }}
export async function mApi<T = unknown>( method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, body?: unknown, options: { timeoutMs?: number } = {}): Promise<ApiResponse<T>> { const controller = new AbortController(); const timeout = setTimeout( () => controller.abort(), options.timeoutMs ?? 30_000 );
try { const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Token ${TOKEN}`, 'Content-Type': 'application/json', }, body: body ? JSON.stringify(body) : undefined, signal: controller.signal, });
const requestId = res.headers.get('x-request-id') ?? undefined;
if (!res.ok) { const errBody = (await res.json().catch(() => ({}))) as { error?: { message?: string }; }; throw new ApiError( res.status, errBody?.error?.message ?? `HTTP ${res.status}`, errBody, requestId ); }
const json = (await res.json()) as ApiResponse<T>;
if (json.status === '999') { throw new ApiError( 200, (json.data as { erro?: string })?.erro ?? json.descricao, json, json.meta?.request_id ?? requestId ); }
return json; } finally { clearTimeout(timeout); }}Cenário: emitir NFCe completa
import { mApi, ApiError } from './myse-api.js';
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function emitirNFCe(pedido) { // 1. Emitir const emissao = await mApi('POST', '/nfce/emissao', { serie: '65', cfop: '5102', 'numero-origem': `PED-${pedido.id}`, tp_pagamento: pedido.formaPagamento, cliente: pedido.cpfCnpjCliente, itens: pedido.itens.map((i) => ({ produto: i.sku, quantidade: String(i.qtd), 'valor-unitario': String(i.preco), })), });
if (emissao.status !== '001' && emissao.status !== '050') { throw new Error(`Emissão falhou: ${emissao.descricao}`); }
const recibo = emissao.data.recibo; console.log(`[emissao] recibo=${recibo} request_id=${emissao.meta.request_id}`);
// 2. Polling com backoff const terminais = new Set(['004', '010', '900', '999']); let wait = 2000; const inicio = Date.now();
while (Date.now() - inicio < 5 * 60_000) { await sleep(wait); const consulta = await mApi('GET', `/nfce/cupom/${recibo}`); console.log(`[polling] status=${consulta.status}`);
if (terminais.has(consulta.status)) { if (consulta.status === '004') { return consulta.data; // Inclui sefaz.chave, url-danfe, url-xml } throw new Error(`Status terminal não-sucesso: ${consulta.status}`); }
wait = Math.min(wait * 1.5, 30_000); }
throw new Error(`Timeout aguardando recibo ${recibo}`);}Retry com backoff em erros transitórios
async function comRetry(fn, max = 3) { for (let i = 1; i <= max; i++) { try { return await fn(); } catch (err) { // Não retentar erros de validação if (err instanceof ApiError && err.payload?.status === '999') throw err; if (i === max) throw err; await sleep(1000 * Math.pow(2, i - 1)); // 1s, 2s, 4s } }}
// Usoconst nfe = await comRetry(() => emitirNFCe(pedido));Helper de polling reutilizável
const TERMINAIS = new Set(['004', '010', '900', '999']);
async function aguardarRecibo(pathBase, recibo, timeoutMs = 5 * 60_000) { let wait = 2000; const inicio = Date.now();
while (Date.now() - inicio < timeoutMs) { await sleep(wait); const resp = await mApi('GET', `${pathBase}/${recibo}`); if (TERMINAIS.has(resp.status)) return resp; wait = Math.min(wait * 1.5, 30_000); } throw new Error(`Timeout aguardando recibo ${recibo}`);}Emitir NF-e (com transporte completo)
async function emitirNFe(pedido) { const emissao = await mApi('POST', '/nfe/emissao', { serie: '1', cfop: '5102', 'numero-origem': `PED-${pedido.id}`, tipo: 'S', finalidade: 'N', 'valor-despesas': '0.00', cliente: pedido.cpfCnpjCliente, transporte: { modalidade: '0', transportadora: pedido.transportadora, 'placa-veiculo': pedido.placa, 'valor-frete': pedido.frete ?? '0.00', 'valor-seguro': '0.00', 'peso-bruto': pedido.pesoBruto, 'peso-liquido': pedido.pesoLiquido, 'quantidade-volume': '1', 'especie-volume': 'Caixa', 'marca-volume': 'Embalagem', }, itens: pedido.itens.map((i) => ({ produto: i.sku, quantidade: String(i.qtd), 'valor-unitario': String(i.preco), })), faturas: pedido.faturas?.map((f) => ({ valor: String(f.valor), data: f.data })) ?? [], });
if (!['001', '050'].includes(emissao.status)) { throw new Error(`Emissão falhou: ${emissao.descricao}`); }
const resultado = await aguardarRecibo('/nfe/nota', emissao.data.recibo); if (resultado.status !== '004') { throw new Error(`Status terminal não-sucesso: ${resultado.status}`); } return resultado.data; // inclui sefaz.chave, url-danfe, url-xml}Cancelar NF-e
async function cancelarNFe(chave, motivo) { if (motivo.length < 15 || motivo.length > 255) { throw new Error('Motivo deve ter entre 15 e 255 caracteres'); } const cancel = await mApi('POST', '/nfe/cancelamento', { chave, motivo }); if (cancel.status !== '001') throw new Error(cancel.descricao); return aguardarRecibo('/nfe/cancelamento', cancel.data.recibo);}Lançar carta de correção (CC-e)
async function cartaCorrecaoNFe(chave, textoCorrecao) { // CC-e aceita de 15 a 1000 caracteres (desde a 3.15.1); o cancelamento segue em 15 a 255 if (textoCorrecao.length < 15 || textoCorrecao.length > 1000) { throw new Error('Texto da correção deve ter entre 15 e 1000 caracteres'); } // Nota: o campo "motivo" na CC-e é o TEXTO da correção (xCorrecao). const cce = await mApi('POST', '/nfe/correcao', { chave, motivo: textoCorrecao }); if (cce.status !== '001') throw new Error(cce.descricao); return aguardarRecibo('/nfe/correcao', cce.data.recibo);}Cancelar NFC-e
async function cancelarNFCe(chave, motivo) { if (motivo.length < 15 || motivo.length > 255) { throw new Error('Motivo deve ter entre 15 e 255 caracteres'); } const cancel = await mApi('POST', '/nfce/cancelamento', { chave, motivo }); if (cancel.status !== '001') throw new Error(cancel.descricao); return aguardarRecibo('/nfce/cancelamento', cancel.data.recibo);}Emitir NFS-e (Nota Fiscal de Serviço)
async function emitirNFSe(servico) { const emissao = await mApi('POST', '/nfse/emissao', { 'numero-origem': `OS-${servico.id}`, observacao: servico.observacao, 'nome-contato': servico.nomeContato, 'telefone-contato': servico.telefoneContato, 'data-fim': servico.dataFim, cliente: servico.cpfCnpjCliente, itens: servico.itens.map((i) => ({ produto: i.codigoServico, quantidade: String(i.qtd), 'valor-unitario': String(i.preco), })), });
if (!['001', '050'].includes(emissao.status)) { throw new Error(`Emissão NFSe falhou: ${emissao.descricao}`); }
const resultado = await aguardarRecibo('/nfse/nota', emissao.data.recibo); if (resultado.status !== '004') { throw new Error(`Status terminal não-sucesso: ${resultado.status}`); } return resultado.data;}Cancelar NFS-e
async function cancelarNFSe(chave, motivo) { if (motivo.length < 15 || motivo.length > 255) { throw new Error('Motivo deve ter entre 15 e 255 caracteres'); } return mApi('POST', '/nfse/cancelamento', { chave, motivo });}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 */async function reconhecerNotaFornecedor(chave, codigoReconhecimento) { const VALIDOS = new Set(['210200', '210210', '210220', '210240']); if (!VALIDOS.has(codigoReconhecimento)) { throw new Error(`Código inválido: ${codigoReconhecimento}`); }
const resp = await mApi('POST', '/nffornecedor/reconhecimento', { chave, 'codigo-reconhecimento': codigoReconhecimento, }); if (resp.status !== '001') throw new Error(resp.descricao); return aguardarRecibo('/nffornecedor', resp.data.recibo);}Consulta completa por recibo
Diferente do polling rápido (/nfe/nota/{recibo}), a consulta completa traz todos os dados do
documento. Veja Emitir NF-e, Emitir NFC-e
e Paginação.
// NF-e completa: itens, cliente, transporte, faturas, notas referenciadas e dados da SEFAZconst nfeCompleta = await mApi('GET', `/nfe/nota/${recibo}/completa`);
// NFC-e completa: itens, cliente e dados da SEFAZconst nfceCompleta = await mApi('GET', `/nfce/cupom/${recibo}/completa`);
// NFC-es por path (legado): {pagina} começa em 1, {quantidade} até 500async function listarTodasNFCe(quantidade = 50) { const todas = []; for (let pagina = 1; ; pagina++) { const resp = await mApi('GET', `/nfce/paginacao/${pagina}/${quantidade}`); if (resp.status !== '005' || !Array.isArray(resp.data)) break; todas.push(...resp.data); if (resp.data.length < quantidade) break; await sleep(200); } return todas;}Inutilizar numeração
Fecha na SEFAZ uma faixa de numeração de NF-e ou NFC-e que não será usada. É assíncrona: recibo e polling. Veja Inutilizar numeração.
// modelo: 'nfe' (55) ou 'nfce' (65). O corpo é o mesmo nas duas rotas.async function inutilizarNumeracao(modelo, { serie, inicial, final, justificativa, ano }) { if (justificativa.length < 15 || justificativa.length > 255) { throw new Error('Justificativa deve ter entre 15 e 255 caracteres'); } const pedido = await mApi('POST', `/${modelo}/inutilizacao`, { serie: String(serie), 'numero-inicial': String(inicial), 'numero-final': String(final), // igual ao inicial para um número só; até 10.000 por pedido justificativa, ...(ano ? { ano: String(ano) } : {}), // ano em que a numeração foi GERADA (opcional) }); // 400 = recusado na hora (nota autorizada na faixa, faixa sobreposta, certificado A3...) if (pedido.status !== '001') throw new Error(pedido.data?.erro ?? pedido.descricao);
const resultado = await aguardarRecibo(`/${modelo}/inutilizacao`, pedido.data.recibo); if (resultado.status !== '004') { // 900 = a SEFAZ recusou: motivo em sefaz.codigo / sefaz.mensagem throw new Error(`Não homologada: ${resultado.data?.sefaz?.mensagem ?? resultado.descricao}`); } return resultado.data.sefaz; // { data, codigo: '102', protocolo, mensagem }}
// Uso:await inutilizarNumeracao('nfe', { serie: 1, inicial: 120, final: 125, justificativa: 'Falha no sistema pulou a numeração da série.',});XML em lote por período
Solicita o ZIP com os XMLs de NF-e ou NFC-e de um período, acompanha o protocolo e baixa o arquivo. Veja Baixar XMLs por período.
import { writeFile } from 'node:fs/promises';
// tipo: 'NFe' ou 'NFCe'. Até 92 dias por solicitação, no máximo 3 em processamento.async function baixarXmlsPeriodo(tipo, dataInicial, dataFinal, destino) { const sol = await mApi('POST', '/xml/solicitacao', { tipo, 'data-inicial': dataInicial, 'data-final': dataFinal, }); // 050 = já havia uma solicitação igual em andamento: o protocolo é o dela (não é erro) if (!['001', '050'].includes(sol.status)) throw new Error(sol.data?.erro ?? sol.descricao); const { protocolo } = sol.data;
let wait = 2000; const inicio = Date.now(); while (Date.now() - inicio < 15 * 60_000) { await sleep(wait); const resp = await mApi('GET', `/xml/solicitacao/${protocolo}`); if (resp.status === '005') { // url-download não exige o header de autenticação, só aceita GET (HEAD devolve 403) // e expira na data de expira-em (7 dias) const zip = await fetch(resp.data['url-download']); if (!zip.ok) throw new Error(`Download falhou: HTTP ${zip.status}`); await writeFile(destino, Buffer.from(await zip.arrayBuffer())); return resp.data; } if (resp.status === '006') return null; // sem-notas: estado final, não havia nota no período if (resp.status !== '002') { // 007 = falha (final: faça uma NOVA solicitação); 500 = protocolo inexistente throw new Error(`Protocolo ${protocolo}: ${resp.status} ${resp.descricao}`); } wait = Math.min(wait * 1.5, 30_000); } throw new Error(`Timeout aguardando protocolo ${protocolo}`);}
await baixarXmlsPeriodo('NFe', '2026-04-01', '2026-04-30', './xmls-2026-04.zip');Resumo diário
Totais por dia de NF-e e NFC-e emitidas, canceladas, denegadas e das falhas de emissão, para conciliação. Veja Resumo diário de emissões.
async function resumoDiario(dataInicial, dataFinal) { // Período máximo de 92 dias const qs = new URLSearchParams({ 'data-inicial': dataInicial, 'data-final': dataFinal }); const resp = await mApi('GET', `/resumo?${qs}`); if (resp.status !== '005') throw new Error(resp.descricao);
for (const dia of resp.data.dias) { // dias sem movimento não aparecem // canceladas é SUBCONJUNTO de emitidas: notas válidas = emitidas - canceladas const nfe = (dia.nfe?.emitidas ?? 0) - (dia.nfe?.canceladas ?? 0); const nfce = (dia.nfce?.emitidas ?? 0) - (dia.nfce?.canceladas ?? 0); console.log(`${dia.data}: NF-e válidas=${nfe} NFC-e válidas=${nfce}`, dia.falhas); } return resp.data.totais;}
const totais = await resumoDiario('2026-08-01', '2026-08-06');Classificação fiscal
Sugestão de NCM, CEST, CFOP, CST, alíquotas, IBS/CBS e ISS para um produto ou serviço. Responde na hora, sem recibo, e não grava nada. Veja Classificação fiscal.
// Pode levar alguns segundos: timeout com folga (70 s; 90 s no lote).async function classificar(produto, respostas) { const body = respostas ? { ...produto, respostas } : produto; const resp = await mApi('POST', '/classificacao-fiscal', body, { timeoutMs: 70_000 }); // 400 = pedido fora do formato: motivo na descricao, campo em data.campo if (resp.status !== '005') throw new Error(`${resp.descricao} (campo: ${resp.data?.campo})`); return resp.data.pacote; // chaves do pacote em snake_case (contrato do motor)}
const produto = { referencia: 'SKU-NB15', nome: 'NOTEBOOK 15 POLEGADAS 8GB RAM', documento: 'nfe', destinatario: 'contribuinte', destino: 'interestadual',};let pacote = await classificar(produto);
// O motor nunca presume fatos que só a empresa sabe: eles voltam em perguntas_pendentes.// Responda e reenvie o MESMO produto. As respostas valem só para aquela chamada.const respostas = {};for (let rodada = 0; pacote.perguntas_pendentes?.length && rodada < 3; rodada++) { for (const p of pacote.perguntas_pendentes) { // p.tipo: 'booleano' (true/false), 'escolha' (um de p.opcoes) ou 'texto' (até 80 caracteres) respostas[p.id] = await perguntarAoUsuario(p); // função da sua aplicação } pacote = await classificar(produto, respostas);}console.log(pacote.icms?.cfop?.valor, pacote.metadados.disclaimer); // confira com o contador
// Lote: de 1 a 10 produtos por chamadaconst lote = await mApi('POST', '/classificacao-fiscal/lote', { produtos: [ { referencia: 'SKU-1', nome: 'ARROZ BRANCO TIPO 1 5KG', ncm: '1006.30.21', documento: 'nfce' }, { referencia: 'SRV-1', natureza: 'servico', nome: 'CORTE DE CABELO MASCULINO' }, ],}, { timeoutMs: 90_000 });if (lote.status !== '005') throw new Error(lote.descricao); // ex.: lote vazio ou com mais de 10
// O envelope é 005 sempre que o lote foi aceito: confira o status de CADA itemfor (const r of lote.data.resultados) { if (r.status === '005') console.log(r.referencia, r.pacote.identidade?.ncm?.valor); else console.warn(`[${r.indice}] ${r.referencia}: ${r.status} ${r.descricao}`); // 400 (r.campo) ou 999 (reenvie só ele)}Rotinas
Uma rotina emite NFS-e sozinha em cada data da agenda (nota recorrente, aluguel, condomínio). Respondem na hora, sem recibo; quem gera recibo é cada NFS-e emitida. Veja Rotinas de emissão automática.
// Modelos e os campos de cada um: parametros[].nome é a chave usada em "parametros"const { data: { modelos } } = await mApi('GET', '/rotinas/modelos');console.log(modelos.map((m) => `${m.codigo}: ${m.parametros.map((p) => p.nome).join(', ')}`));
// As chaves de "parametros" são os nomes dos campos do modelo (snake_case), não kebab-caseconst rotina = { modelo: 'NFSE_RECORRENTE', nome: 'Suporte mensal - ACME', periodicidade: 'mensal', dia: 10, inicio: '2026-11-01', parametros: { id_clifor: 1262804, // id de GET /rotinas/clientes?busca= id_produto: 88231, // id de GET /rotinas/servicos vl_servico: '3.500,50', ds_discriminacao: 'Suporte técnico de {competencia}', },};
// 1. Conferir sem gravarconst conferida = await mApi('POST', '/rotinas/validar', rotina);if (conferida.status !== '005' || !conferida.data['pode-ativar']) { throw new Error((conferida.data?.pendencias ?? [conferida.descricao]).join(' '));}
// 2. Criar. Sem "ativar", ela já sai ATIVA e passa a emitir NFS-e sozinha na agenda.const criada = await mApi('POST', '/rotinas', rotina);if (criada.status !== '001') throw new Error(criada.descricao); // 400 traz data.pendencias ou data.campoconst id = criada.data.rotina['id-rotina'];
// 3. A agenda não emite o mês atual: emita a competência agora (corpo vazio = mês atual)const agora = await mApi('POST', `/rotinas/${id}/emitir-agora`, { competencia: '2026-11' });if (agora.status !== '001') throw new Error(agora.descricao); // 400 se a competência já foi processada// agora.data['numero-origem'] === `ROT-${id}-2026-11`: nota ENFILEIRADA, ainda não autorizada
// 4. Histórico: o recibo de cada competência leva ao desfecho da NFS-econst { data: { execucoes } } = await mApi('GET', `/rotinas/${id}/execucoes`);const ultima = execucoes[0]; // da mais recente para a mais antigaif (ultima?.recibo) { const nfse = await aguardarRecibo('/nfse/nota', ultima.recibo); console.log(ultima.competencia, ultima['situacao-descricao'], nfse.status);}
// 5. Detalhe: dados, agenda, pendencias, diagnostico (por que emitiu ou não) e execucoesconst detalhe = await mApi('GET', `/rotinas/${id}`);if (detalhe.status === '500') throw new Error(detalhe.descricao); // inexistente ou excluídaconsole.log(detalhe.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.const alterada = await mApi('PUT', `/rotinas/${id}`, { dia: 5, parametros: { vl_servico: 3800 } });if (alterada.status !== '001') throw new Error(alterada.descricao); // 400: data.campo ou data.pendencias
// 7. Valor extra em um único mês (só rotina ativa, só nos próximos meses da agenda)const { data: extras } = await mApi('GET', `/rotinas/${id}/extras`);const competencia = extras['competencias-disponiveis'][0]; // AAAA-MMif (competencia) { const lancado = await mApi('PUT', `/rotinas/${id}/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 }); if (lancado.status !== '001') throw new Error(lancado.descricao); // 400: ex. condomínio não aceita extra for (const e of lancado.data.extras) console.log(e.competencia, e.valor, e.situacao); // 'Programado'...
// Desistiu? Remove o extra (não vale para mês já emitido ou em emissão) await mApi('DELETE', `/rotinas/${id}/extras/${competencia}`);}
// 8. Pausar (só rotina ativa). Para religar: POST /rotinas/{id}/retomarconst pausada = await mApi('POST', `/rotinas/${id}/pausar`);console.log(pausada.data.rotina.situacao); // 'pausada'
// 9. Excluir: status 001 e data['id-rotina']const excluida = await mApi('DELETE', `/rotinas/${id}`);if (excluida.status !== '001') throw new Error(excluida.descricao);Certificado digital A1
Instala (ou troca) o certificado A1 da empresa da chave e acompanha a validade. Responde na hora, sem recibo. Desde a 3.20.0. Veja Certificado digital A1.
import { readFile } from 'node:fs/promises';
async function instalarCertificadoA1(caminhoPfx) { // O .pfx é binário: a API recebe o conteúdo em base64 (até 50 KB de arquivo) const arquivo = (await readFile(caminhoPfx)).toString('base64'); // Senha vinda do ambiente (ou do seu cofre de segredos). NUNCA logue a senha nem o arquivo: // com os dois, qualquer um assina documentos fiscais em nome da empresa. const senha = process.env.MYSE_PFX_SENHA;
const resp = await mApi('POST', '/certificado/a1', { arquivo, senha }); // 400 = senha errada, não é A1 ICP-Brasil, vencido, de outro CNPJ/CPF ou vence antes do atual if (resp.status !== '001') throw new Error(resp.descricao); return resp.data; // { tipo, titular, 'valido-ate', 'dias-para-vencer', situacao, ... }}
await instalarCertificadoA1('./certificado.pfx'); // com 001, a próxima emissão já usa o novo
// Monitorar a validade (uma vez por dia)const { data: cert } = await mApi('GET', '/certificado');if (['A_VENCER', 'VENCIDO', 'NAO_INSTALADO'].includes(cert.situacao)) { console.warn(`Certificado ${cert.situacao}: validade ${cert['dt-validade']} (${cert['dias-para-vencer']} dias)`);}CIOT
Declara na ANTT a operação de transporte e devolve o código do CIOT. É assíncrono: recibo e polling, também nos eventos. Veja Emitir CIOT.
// Os campos seguem o leiaute PEF da ANTT (PascalCase), exceção ao kebab-case da v3.// Não envie CpfCnpjContratado, RNTRCContratado nem IdOperacaoTransporte: vêm do cadastro.async function emitirCiot(viagem) { const pedido = await mApi('POST', '/ciot/emissao', { // Estável por viagem: depois de um 999, reenvie com o MESMO valor (não gera 2º CIOT) 'numero-origem': `VIAGEM-${viagem.id}`, TipoOperacao: 1, // 1 carga lotação, 2 carga fracionada CpfCnpjContratante: viagem.contratante, CpfCnpjDestinatario: viagem.destinatario, ValorFrete: viagem.valorFrete, Veiculos: [{ Placa: viagem.placa, NumeroEixos: '4' }], // exatamente um veículo OrigemDestino: [{ Origem: { CodigoMunicipioOrigem: 4127700 }, Destino: { CodigoMunicipioDestino: 4104808 }, DistanciaPercorrida: 45, }], DadosCarga: { CodigoNaturezaCarga: 9999, CodigoTipoCarga: 5, PesoCarga: 1000 }, InfIndicadoresOperacionais: { // obrigatório na carga lotação IndAltoDesempenho: false, IndRetornoVazio: false, ComposicaoVeicular: false, }, InfPagamento: [{ TipoPagamento: 6, IndPagamento: 0, // Pix, à vista IdentificadorPix: `FRETE-${viagem.id}`, }], }); // 400 = recusado na hora (TipoOperacao inválido, certificado A3, sem RNTRC...) if (pedido.status !== '001') throw new Error(pedido.data?.erro ?? pedido.descricao);
const r = await aguardarRecibo('/ciot', pedido.data.recibo); if (r.status !== '004') { throw new Error(`CIOT não emitido: ${r.data?.erro ?? r.data?.antt?.mensagem ?? r.descricao}`); } return r.data; // { ciot, 'codigo-verificador', protocolo, situacao: 'EMITIDO', ... }}
// Encerrar ao fim da viagem: identifique por ciot OU pelo recibo da emissãoasync function encerrarCiot(ciot) { const evento = await mApi('POST', '/ciot/encerramento', { ciot }); if (!evento.data?.recibo) throw new Error(evento.data?.erro ?? evento.descricao); return aguardarRecibo('/ciot', evento.data.recibo); // 004 = encerrado}
// Cancelar na ANTT (motivo obrigatório, até 500 caracteres). CIOT que a ANTT recusou// (REJEITADO) só é marcado como cancelado no FazNota.async function cancelarCiot(ciot, motivo) { if (!motivo || motivo.length > 500) throw new Error('motivo é obrigatório, até 500 caracteres'); const evento = await mApi('POST', '/ciot/cancelamento', { ciot, motivo }); if (evento.status !== '001') throw new Error(evento.data?.erro ?? evento.descricao); const r = await aguardarRecibo('/ciot', evento.data.recibo); if (r.status !== '010') { // 010 = cancelado throw new Error(`CIOT não cancelado: ${r.data?.erro ?? r.data?.antt?.mensagem ?? r.descricao}`); } return r.data;}
// Retificar: 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.async function retificarCiot(ciot, campos) { const evento = await mApi('POST', '/ciot/retificacao', { ciot, ...campos }); if (evento.status !== '001') throw new Error(evento.data?.erro ?? evento.descricao); return aguardarRecibo('/ciot', evento.data.recibo); // 004 = retificado}
const { ciot } = await emitirCiot(viagem);await retificarCiot(ciot, { ValorFrete: 1650.0, PesoCarga: 1200 }); // só se TipoOperacao 2await cancelarCiot(ciot, 'Viagem cancelada pelo contratante.');RENAVE
Registra no RENAVE (SERPRO) a entrada e a saída de veículos do estoque da revenda, vinculadas à NF-e da operação. É assíncrono. Veja RENAVE.
// Os campos seguem o leiaute do SERPRO (camelCase), exceção ao kebab-case da v3.async function renaveEntradaCompra(compra) { const pedido = await mApi('POST', '/renave/nota-fiscal/entrada', { chaveNFe: compra.chaveNFe, // NF-e modelo 55 emitida pela própria empresa cpfOperadorResponsavel: '12345678901', dataCompra: '2026-10-20', valorCompra: 45000.0, veiculo: { placa: 'ABC1D23', numeroCrv: '123456789012', renavam: '01234567890', codigoSegurancaCrv: '12345678901', tipoCrv: 'DIGITAL', dataHoraMedicaoHodometro: '2026-10-20T10:00:00', quilometragemHodometro: 52000, documentoProprietarioAtual: '98765432100', tipoDocumentoProprietarioAtual: 'CPF', }, }); if (pedido.status !== '001') throw new Error(pedido.data?.erro ?? pedido.descricao);
// 002 na fila, 003 sendo enviado. Em 999 (ApiError), reenvie o MESMO pedido. const r = await aguardarRecibo('/renave', pedido.data.recibo); if (r.status !== '004') { throw new Error(`RENAVE recusou: ${r.data?.mensagem ?? r.data?.erro ?? r.descricao}`); } return r.data['id-renave']; // guarde: identifica o registro no cancelamento}
// 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.async function renave(rota, body, esperado = '004') { const pedido = await mApi('POST', rota, body); if (pedido.status !== '001') throw new Error(pedido.data?.erro ?? pedido.descricao); const r = await aguardarRecibo('/renave', pedido.data.recibo); if (r.status !== esperado) { throw new Error(`RENAVE ${r.status}: ${r.data?.mensagem ?? r.data?.erro ?? r.descricao}`); } return r.data;}
// Saída do estoque (venda), vinculada à NF-e de vendaconst saida = await renave('/renave/nota-fiscal/saida', { chaveNFe: '35261012345678000190550010000012401000012400', cpfOperadorResponsavel: '12345678901', dataVenda: '2026-10-25', valorVenda: 52000.0, 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.const proprio = await renave('/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.await renave('/renave/estoque/cancelamento-entrada', { 'id-renave': proprio['id-renave'] }, '010');await renave('/renave/estoque/cancelamento-saida', { 'id-renave': saida['id-renave'] }, '010');Sincronizar todos os clientes
async function listarTodosClientes() { const todos = []; let page = 1; const pageSize = 100;
while (true) { const resp = await mApi('GET', `/clientes?page=${page}&page_size=${pageSize}`); if (resp.status !== '005' || !Array.isArray(resp.data)) break; todos.push(...resp.data); if (resp.data.length < pageSize) break; page++; await sleep(200); }
return todos;}Tratamento de erros completo
try { const nfe = await emitirNFCe(pedido); console.log('NFCe emitida:', nfe.sefaz?.chave);} catch (err) { if (err instanceof ApiError) { console.error( `API Error HTTP=${err.httpStatus} requestId=${err.requestId}`, err.message, err.payload ); // Logar para suporte: requestId é o que importa } else { console.error('Erro inesperado:', err); }}Health check (sem autenticação)
async function health() { const res = await fetch(`${BASE}/health`); return res.json(); // { 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.
// fetch direto, sem Authorization: o mApi lançaria ApiError no 503, que aqui é a própria respostaasync function healthDeep() { const res = await fetch(`${process.env.MYSE_API_BASE}/health/deep`); const body = await res.json(); // 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 } return { saudavel: res.status === 200, ...body };}
async function healthPool() { const res = await fetch(`${process.env.MYSE_API_BASE}/health/pool`); return res.json(); // { status: 'UP' | 'STARTING', timestamp, pool: { active, idle, waiting, total, max, ... } }}
const deep = await healthDeep();if (!deep.saudavel) console.error('API DOWN', deep);else if (deep.pool.waiting > 0) console.warn(`pool ${deep.pool.active}/${deep.pool.max}, ${deep.pool.waiting} aguardando`);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.
async function alterarNota(tipo, id, dadosAtualizados) { // tipo: 'nfe' | 'nfce' | 'nfse' return mApi('PUT', `/${tipo}/${id}`, dadosAtualizados);}
// Uso:await alterarNota('nfe', '12345', { serie: '1', cfop: '5102', cliente: '12345678000199', itens: [{ produto: 'SKU-001', quantidade: '3', 'valor-unitario': '89.90' }],});Listagens
// NF-es paginadasconst nfes = await mApi('GET', '/nfe?page=1&page_size=20');
// NFC-esconst nfces = await mApi('GET', '/nfce?page=1&page_size=50');
// NFS-es com filtro de dataconst nfses = await mApi( 'GET', '/nfse?dataInicial=2026-05-01&page=1&page_size=20');
// Notas de fornecedorconst fornecedor = await mApi('GET', '/nffornecedor?page=1&page_size=20');
// Forma legada (path-based)const nfesLegado = await mApi('GET', '/nfe/paginacao/1/20');Clientes (CRUD completo)
// Cadastrar pessoa físicaasync function cadastrarPF(dados) { return mApi('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, });}
// Cadastrar pessoa jurídicaasync function cadastrarPJ(dados) { return mApi('POST', '/clientes', { tipo: 'J', 'razao-social': dados.razaoSocial, 'nome-fantasia': dados.nomeFantasia, cnpj: dados.cnpj, 'inscricao-municipal': dados.inscricaoMunicipal, 'tipo-inscricao-estadual': dados.contribuinte ?? '9', 'inscricao-estadual': dados.inscricaoEstadual ?? 'ISENTO', 'consumidor-final': dados.consumidorFinal ?? '0', contato: { email: dados.email, telefone: dados.telefone }, endereco: dados.endereco, });}
// Consultar por CPF/CNPJconst cliente = await mApi('GET', '/clientes/12345678000199');
// Buscar por nome (parcial)const encontrados = await mApi('GET', '/clientes/busca/exemplo');
// Top 20 clientes mais relevantesconst top = await mApi('GET', '/clientes/busca/top_clientes');
// Atualizarawait mApi('PUT', '/clientes/12345678000199', { tipo: 'J', 'razao-social': 'Empresa Exemplo (Novo Nome) Ltda',});
// Excluirawait mApi('DELETE', '/clientes/12345678000199');Produtos (CRUD completo)
// Cadastrar produto com configuração fiscalasync function cadastrarProduto(produto) { return mApi('POST', '/produtos', { referencia: produto.sku, nome: produto.nome, valor: String(produto.valor), 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.configFiscal ?? [], });}
// Cadastrar serviçoasync function cadastrarServico(servico) { return mApi('POST', '/produtos', { referencia: servico.sku, nome: servico.nome, valor: String(servico.valor), medida: 'H', 'tipo-produto': 'S', 'codigo-servico': servico.codigoServico, });}
// Consultar por referênciaconst produto = await mApi('GET', '/produtos/SKU-001');
// Buscar por nome (1º resultado)const porNome = await mApi('GET', '/produtos/nome/Camiseta');
// Listar paginado com busca (use _todos para não filtrar)const todos = await mApi('GET', '/produtos/paginacao/1/20/_todos');const filtrados = await mApi('GET', '/produtos/paginacao/1/20/Camiseta');
// Atualizarawait mApi('PUT', '/produtos/SKU-001', { referencia: 'SKU-001', nome: 'Camiseta Polo M (Novo)', valor: '99.90',});
// Excluirawait mApi('DELETE', '/produtos/SKU-001');