Pular para o conteúdo

Exemplos em JavaScript / TypeScript

Setup

Requer Node.js 18+ (que tem fetch nativo).

Terminal window
# .env (use dotenv ou similar)
MYSE_API_BASE=https://api.mysebr.com.br/nfemyse-v3/rest
MYSE_API_TOKEN=seu_token_aqui

Cliente HTTP centralizado

myse-api.js
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);
}
}

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
}
}
}
// Uso
const 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 SEFAZ
const nfeCompleta = await mApi('GET', `/nfe/nota/${recibo}/completa`);
// NFC-e completa: itens, cliente e dados da SEFAZ
const nfceCompleta = await mApi('GET', `/nfce/cupom/${recibo}/completa`);
// NFC-es por path (legado): {pagina} começa em 1, {quantidade} até 500
async 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,
email: '[email protected]', // opcional: sem ele, vale o e-mail cadastrado da empresa
});
// 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 chamada
const 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 item
for (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-case
const 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 gravar
const 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.campo
const 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-e
const { data: { execucoes } } = await mApi('GET', `/rotinas/${id}/execucoes`);
const ultima = execucoes[0]; // da mais recente para a mais antiga
if (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 execucoes
const detalhe = await mApi('GET', `/rotinas/${id}`);
if (detalhe.status === '500') throw new Error(detalhe.descricao); // inexistente ou excluída
console.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-MM
if (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}/retomar
const 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
ChavePix: '[email protected]',
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ão
async 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 2
await 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,
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',
},
});
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 venda
const 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 resposta
async 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 paginadas
const nfes = await mApi('GET', '/nfe?page=1&page_size=20');
// NFC-es
const nfces = await mApi('GET', '/nfce?page=1&page_size=50');
// NFS-es com filtro de data
const nfses = await mApi(
'GET',
'/nfse?dataInicial=2026-05-01&page=1&page_size=20'
);
// Notas de fornecedor
const 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ísica
async 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ídica
async 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/CNPJ
const cliente = await mApi('GET', '/clientes/12345678000199');
// Buscar por nome (parcial)
const encontrados = await mApi('GET', '/clientes/busca/exemplo');
// Top 20 clientes mais relevantes
const top = await mApi('GET', '/clientes/busca/top_clientes');
// Atualizar
await mApi('PUT', '/clientes/12345678000199', {
tipo: 'J',
'razao-social': 'Empresa Exemplo (Novo Nome) Ltda',
});
// Excluir
await mApi('DELETE', '/clientes/12345678000199');

Produtos (CRUD completo)

// Cadastrar produto com configuração fiscal
async 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ço
async 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ência
const 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');
// Atualizar
await mApi('PUT', '/produtos/SKU-001', {
referencia: 'SKU-001',
nome: 'Camiseta Polo M (Novo)',
valor: '99.90',
});
// Excluir
await mApi('DELETE', '/produtos/SKU-001');