Exemplos em C# (.NET)
Setup
Requer .NET 6+.
<PackageReference Include="DotNetEnv" Version="3.0.0" />MYSE_API_BASE=https://api.mysebr.com.br/nfemyse-v3/restMYSE_API_TOKEN=seu_token_aquiCliente HTTP centralizado
using System.Net.Http.Json;using System.Text.Json;using System.Text.Json.Nodes;
namespace Myse;
public class ApiError : Exception{ public int HttpStatus { get; } public JsonNode? Payload { get; } public string? RequestId { get; }
public ApiError(int httpStatus, string message, JsonNode? payload, string? requestId) : base(message) { HttpStatus = httpStatus; Payload = payload; RequestId = requestId; }}
public class MyseApi{ private readonly HttpClient _http;
// timeout opcional: a classificação fiscal pede 70 a 90 s public MyseApi(string baseUrl, string token, TimeSpan? timeout = null) { _http = new HttpClient { BaseAddress = new Uri(baseUrl), Timeout = timeout ?? TimeSpan.FromSeconds(30), }; _http.DefaultRequestHeaders.Add("Authorization", $"Token {token}"); }
public async Task<JsonNode> CallAsync( HttpMethod method, string path, object? body = null, CancellationToken ct = default) { var req = new HttpRequestMessage(method, path); if (body != null) { req.Content = JsonContent.Create(body); }
var res = await _http.SendAsync(req, ct); var requestId = res.Headers.TryGetValues("X-Request-Id", out var v) ? v.FirstOrDefault() : null;
var bodyStr = await res.Content.ReadAsStringAsync(ct); var json = JsonNode.Parse(bodyStr);
if (!res.IsSuccessStatusCode) { var msg = json?["error"]?["message"]?.ToString() ?? $"HTTP {(int)res.StatusCode}"; throw new ApiError((int)res.StatusCode, msg, json, requestId); }
if (json?["status"]?.ToString() == "999") { var msg = json["data"]?["erro"]?.ToString() ?? json["descricao"]?.ToString() ?? "erro"; var rid = json["meta"]?["request_id"]?.ToString() ?? requestId; throw new ApiError(200, msg, json, rid); }
return json ?? throw new InvalidOperationException("Resposta vazia"); }}Cenário: emitir NFCe com polling
public class EmissorNFCe{ private readonly MyseApi _api; private static readonly HashSet<string> Terminais = new() { "004", "010", "900", "999" };
public EmissorNFCe(MyseApi api) => _api = api;
public async Task<JsonNode> EmitirAsync(Pedido p, CancellationToken ct = default) { // JsonObject: as chaves saem exatamente como no contrato (kebab-case). // tp_pagamento é a exceção documentada da NFC-e e fica com sublinhado. var body = new JsonObject { ["serie"] = "65", ["cfop"] = "5102", ["numero-origem"] = $"PED-{p.Id}", ["tp_pagamento"] = p.FormaPagamento, ["cliente"] = p.CpfCnpjCliente, ["itens"] = new JsonArray(p.Itens.Select(i => new JsonObject { ["produto"] = i.Sku, ["quantidade"] = i.Qtd.ToString(), ["valor-unitario"] = i.Preco.ToString("F2"), }).ToArray()), };
var emissao = await _api.CallAsync(HttpMethod.Post, "/nfce/emissao", body, ct); var status = emissao["status"]?.ToString();
if (status != "001" && status != "050") { throw new InvalidOperationException( $"Emissão falhou: {emissao["descricao"]}" ); }
var recibo = emissao["data"]!["recibo"]!.ToString(); Console.WriteLine($"[emissao] recibo={recibo} request_id={emissao["meta"]?["request_id"]}");
// Polling var wait = TimeSpan.FromSeconds(5); var inicio = DateTime.UtcNow;
while (DateTime.UtcNow - inicio < TimeSpan.FromMinutes(5)) { await Task.Delay(wait, ct); var consulta = await _api.CallAsync(HttpMethod.Get, $"/nfce/cupom/{recibo}", null, ct); var st = consulta["status"]?.ToString(); Console.WriteLine($"[polling] status={st}");
if (Terminais.Contains(st!)) { if (st == "004") return consulta["data"]!; throw new InvalidOperationException($"Status terminal não-sucesso: {st}"); }
wait = TimeSpan.FromMilliseconds(Math.Min(wait.TotalMilliseconds * 1.5, 30_000)); }
throw new TimeoutException($"Timeout aguardando recibo {recibo}"); }}Retry com backoff
public static async Task<T> ComRetryAsync<T>(Func<Task<T>> fn, int maxTentativas = 3){ Exception? last = null; for (int i = 1; i <= maxTentativas; i++) { try { return await fn(); } catch (ApiError e) when (e.Payload?["status"]?.ToString() == "999") { throw; // validação, não retentar } catch (Exception e) { last = e; if (i == maxTentativas) throw; await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, i - 1))); } } throw last!;}
// Uso:var nfce = await ComRetryAsync(() => emissor.EmitirAsync(pedido));Helper de polling reutilizável
public static class FiscalHelpers{ private static readonly HashSet<string> Terminais = new() { "004", "010", "900", "999" };
public static async Task<JsonNode> AguardarReciboAsync( MyseApi api, string pathBase, string recibo, TimeSpan? timeout = null, CancellationToken ct = default) { var max = timeout ?? TimeSpan.FromMinutes(5); var wait = TimeSpan.FromSeconds(5); var inicio = DateTime.UtcNow;
while (DateTime.UtcNow - inicio < max) { await Task.Delay(wait, ct); var resp = await api.CallAsync(HttpMethod.Get, $"{pathBase}/{recibo}", null, ct); if (Terminais.Contains(resp["status"]?.ToString() ?? "")) return resp; wait = TimeSpan.FromMilliseconds(Math.Min(wait.TotalMilliseconds * 1.5, 30_000)); } throw new TimeoutException($"Timeout aguardando recibo {recibo}"); }
public static void ValidarMotivo(string motivo) { if (motivo.Length < 15 || motivo.Length > 255) throw new ArgumentException("motivo deve ter entre 15 e 255 caracteres"); }
/// <summary>Texto da carta de correção (POST /nfe/correcao): 15 a 1000 caracteres desde a 3.15.1.</summary> public static void ValidarTextoCorrecao(string texto) { var n = new System.Globalization.StringInfo(texto).LengthInTextElements; if (n < 15 || n > 1000) throw new ArgumentException("texto da correção deve ter entre 15 e 1000 caracteres"); }}Emitir NF-e (com transporte completo)
public async Task<JsonNode> EmitirNFeAsync(Pedido p, CancellationToken ct = default){ var body = new JsonObject { ["serie"] = "1", ["cfop"] = "5102", ["numero-origem"] = $"PED-{p.Id}", ["tipo"] = "S", ["finalidade"] = "N", ["valor-despesas"] = "0.00", ["cliente"] = p.CpfCnpjCliente, ["transporte"] = new JsonObject { ["modalidade"] = "0", ["transportadora"] = p.Transportadora, ["placa-veiculo"] = p.Placa, ["valor-frete"] = p.Frete ?? "0.00", ["valor-seguro"] = "0.00", ["peso-bruto"] = p.PesoBruto, ["peso-liquido"] = p.PesoLiquido, ["quantidade-volume"] = "1", ["especie-volume"] = "Caixa", ["marca-volume"] = "Embalagem", }, ["itens"] = new JsonArray(p.Itens.Select(i => new JsonObject { ["produto"] = i.Sku, ["quantidade"] = i.Qtd.ToString(), ["valor-unitario"] = i.Preco.ToString("F2"), }).ToArray()), ["faturas"] = new JsonArray(p.Faturas?.Select(f => new JsonObject { ["valor"] = f.Valor.ToString("F2"), ["data"] = f.Data, }).ToArray() ?? Array.Empty<JsonNode?>()), };
var emissao = await _api.CallAsync(HttpMethod.Post, "/nfe/emissao", body, ct); var status = emissao["status"]?.ToString(); if (status != "001" && status != "050") throw new InvalidOperationException($"Emissão falhou: {emissao["descricao"]}");
var recibo = emissao["data"]!["recibo"]!.ToString(); var resultado = await FiscalHelpers.AguardarReciboAsync(_api, "/nfe/nota", recibo, ct: ct); if (resultado["status"]?.ToString() != "004") throw new InvalidOperationException($"Status terminal não-sucesso: {resultado["status"]}"); return resultado["data"]!;}Cancelar NF-e
public async Task<JsonNode> CancelarNFeAsync(string chave, string motivo, CancellationToken ct = default){ FiscalHelpers.ValidarMotivo(motivo); var cancel = await _api.CallAsync(HttpMethod.Post, "/nfe/cancelamento", new JsonObject { ["chave"] = chave, ["motivo"] = motivo }, ct); if (cancel["status"]?.ToString() != "001") throw new InvalidOperationException(cancel["descricao"]?.ToString()); return await FiscalHelpers.AguardarReciboAsync(_api, "/nfe/cancelamento", cancel["data"]!["recibo"]!.ToString(), ct: ct);}Lançar carta de correção (CC-e)
/// <summary>/// O campo "motivo" na CC-e é o TEXTO da correção (xCorrecao): 15 a 1000 caracteres./// (O motivo do cancelamento continua entre 15 e 255.)/// </summary>public async Task<JsonNode> CartaCorrecaoAsync(string chave, string textoCorrecao, CancellationToken ct = default){ FiscalHelpers.ValidarTextoCorrecao(textoCorrecao); var cce = await _api.CallAsync(HttpMethod.Post, "/nfe/correcao", new JsonObject { ["chave"] = chave, ["motivo"] = textoCorrecao }, ct); if (cce["status"]?.ToString() != "001") throw new InvalidOperationException(cce["descricao"]?.ToString()); return await FiscalHelpers.AguardarReciboAsync(_api, "/nfe/correcao", cce["data"]!["recibo"]!.ToString(), ct: ct);}Cancelar NFC-e
public async Task<JsonNode> CancelarNFCeAsync(string chave, string motivo, CancellationToken ct = default){ FiscalHelpers.ValidarMotivo(motivo); var cancel = await _api.CallAsync(HttpMethod.Post, "/nfce/cancelamento", new JsonObject { ["chave"] = chave, ["motivo"] = motivo }, ct); if (cancel["status"]?.ToString() != "001") throw new InvalidOperationException(cancel["descricao"]?.ToString()); return await FiscalHelpers.AguardarReciboAsync(_api, "/nfce/cancelamento", cancel["data"]!["recibo"]!.ToString(), ct: ct);}Emitir NFS-e (Nota Fiscal de Serviço)
public async Task<JsonNode> EmitirNFSeAsync(Servico s, CancellationToken ct = default){ var body = new JsonObject { ["numero-origem"] = $"OS-{s.Id}", ["observacao"] = s.Observacao, ["nome-contato"] = s.NomeContato, ["telefone-contato"] = s.TelefoneContato, ["data-fim"] = s.DataFim, ["cliente"] = s.CpfCnpjCliente, ["itens"] = new JsonArray(s.Itens.Select(i => new JsonObject { ["produto"] = i.CodigoServico, ["quantidade"] = i.Qtd.ToString(), ["valor-unitario"] = i.Preco.ToString("F2"), }).ToArray()), };
var emissao = await _api.CallAsync(HttpMethod.Post, "/nfse/emissao", body, ct); var status = emissao["status"]?.ToString(); if (status != "001" && status != "050") throw new InvalidOperationException($"Emissão NFSe falhou: {emissao["descricao"]}");
var recibo = emissao["data"]!["recibo"]!.ToString(); var resultado = await FiscalHelpers.AguardarReciboAsync(_api, "/nfse/nota", recibo, ct: ct); if (resultado["status"]?.ToString() != "004") throw new InvalidOperationException($"Status terminal não-sucesso: {resultado["status"]}"); return resultado["data"]!;}Cancelar NFS-e
public async Task<JsonNode> CancelarNFSeAsync(string chave, string motivo, CancellationToken ct = default){ FiscalHelpers.ValidarMotivo(motivo); return await _api.CallAsync(HttpMethod.Post, "/nfse/cancelamento", new JsonObject { ["chave"] = chave, ["motivo"] = motivo }, ct);}Reconhecer nota de fornecedor (MD-e)
/// <summary>/// 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/// </summary>public async Task<JsonNode> ReconhecerNotaFornecedorAsync( string chave, string codigo, CancellationToken ct = default){ var validos = new HashSet<string> { "210200", "210210", "210220", "210240" }; if (!validos.Contains(codigo)) throw new ArgumentException($"Código inválido: {codigo}");
var resp = await _api.CallAsync(HttpMethod.Post, "/nffornecedor/reconhecimento", new JsonObject { ["chave"] = chave, ["codigo-reconhecimento"] = codigo }, ct); if (resp["status"]?.ToString() != "001") throw new InvalidOperationException(resp["descricao"]?.ToString());
return await FiscalHelpers.AguardarReciboAsync(_api, "/nffornecedor", resp["data"]!["recibo"]!.ToString(), ct: ct);}Consulta completa por recibo
Para o polling, a consulta simples (/nfe/nota/{recibo}, /nfce/cupom/{recibo}) basta. A versão
/completa traz o documento inteiro: itens, cliente e dados da SEFAZ e, na NF-e, também transporte,
faturas e notas referenciadas. Veja Emitir NF-e e
Emitir NFC-e.
var nfeCompleta = await _api.CallAsync(HttpMethod.Get, $"/nfe/nota/{recibo}/completa", null);var nfceCompleta = await _api.CallAsync(HttpMethod.Get, $"/nfce/cupom/{recibo}/completa", null);
// NFC-e paginadas pelo path (forma legada): página 1, 50 por página (máximo 500)var cupons = await _api.CallAsync(HttpMethod.Get, "/nfce/paginacao/1/50", null);Inutilizar numeração
Fecha na SEFAZ um buraco na numeração de NF-e ou NFC-e. É assíncrona, como a emissão. Veja Inutilizar numeração.
/// <summary>tipo: "nfe" (modelo 55) ou "nfce" (modelo 65). O corpo é o mesmo.</summary>public async Task<JsonNode> InutilizarAsync(string tipo, string serie, string numeroInicial, string numeroFinal, string justificativa, CancellationToken ct = default){ FiscalHelpers.ValidarMotivo(justificativa); // mesma regra: 15 a 255 caracteres var pedido = await _api.CallAsync(HttpMethod.Post, $"/{tipo}/inutilizacao", new JsonObject { ["serie"] = serie, ["numero-inicial"] = numeroInicial, ["numero-final"] = numeroFinal, // igual ao inicial para um número só ["justificativa"] = justificativa, // ["ano"] = "2025": informe quando a numeração foi gerada em outro ano }, ct); if (pedido["status"]?.ToString() != "001") // 400: recusado na hora (número autorizado na faixa, faixa já na fila, certificado A3...) throw new InvalidOperationException( pedido["data"]?["erro"]?.ToString() ?? pedido["descricao"]?.ToString());
var resultado = await FiscalHelpers.AguardarReciboAsync(_api, $"/{tipo}/inutilizacao", pedido["data"]!["recibo"]!.ToString(), ct: ct); var sefaz = resultado["data"]?["sefaz"]; if (resultado["status"]?.ToString() != "004") // 900: a SEFAZ recusou (ex.: 241 = número já usado) throw new InvalidOperationException($"Inutilização recusada: {sefaz?["codigo"]} {sefaz?["mensagem"]}"); return sefaz!; // codigo 102 e protocolo da homologação}XML em lote por período
Pede o ZIP com os XMLs de NF-e ou NFC-e de um período (até 92 dias), consulta o protocolo e baixa o arquivo do link temporário. Veja Baixar XMLs por período.
// Cliente SEM o header Authorization: o link temporário não aceita autenticação extraprivate static readonly HttpClient Download = new();
/// <summary>Devolve o caminho do ZIP, ou null quando não havia nota no período.</summary>public async Task<string?> BaixarXmlPeriodoAsync(string tipo, string dataInicial, string dataFinal, string destino, CancellationToken ct = default){ var pedido = await _api.CallAsync(HttpMethod.Post, "/xml/solicitacao", new JsonObject { ["tipo"] = tipo, // "NFe" ou "NFCe" ["data-inicial"] = dataInicial, // AAAA-MM-DD ["data-final"] = dataFinal, }, ct); var st = pedido["status"]?.ToString(); if (st != "001" && st != "050") // 050 = já havia uma solicitação igual em andamento throw new InvalidOperationException( pedido["data"]?["erro"]?.ToString() ?? pedido["descricao"]?.ToString()); var protocolo = pedido["data"]!["protocolo"]!.ToString();
// Os status aqui não são os da nota: 005 pronto; 006 (sem notas) e 007 (falha) são finais var wait = TimeSpan.FromSeconds(2); var limite = DateTime.UtcNow.AddMinutes(15); while (DateTime.UtcNow < limite) { await Task.Delay(wait, ct); var consulta = await _api.CallAsync(HttpMethod.Get, $"/xml/solicitacao/{protocolo}", null, ct); switch (consulta["status"]?.ToString()) { case "002": break; // processando case "005": // Só GET: um HEAD no link devolve 403 var zip = await Download.GetByteArrayAsync(consulta["data"]!["url-download"]!.ToString(), ct); await File.WriteAllBytesAsync(destino, zip, ct); return destino; case "006": return null; default: // 007 falha (faça nova solicitação), 500 protocolo inexistente throw new InvalidOperationException($"Solicitação {protocolo}: {consulta["descricao"]}"); } wait = TimeSpan.FromMilliseconds(Math.Min(wait.TotalMilliseconds * 1.5, 30_000)); } throw new TimeoutException($"Timeout aguardando protocolo {protocolo}");}Resumo diário
Totais por dia de NF-e e NFC-e emitidas, canceladas e denegadas, mais as falhas de emissão, para conciliação. Veja Resumo diário de emissões.
var resumo = await _api.CallAsync(HttpMethod.Get, "/resumo?data-inicial=2026-08-01&data-final=2026-08-06", null);
foreach (var dia in resumo["data"]!["dias"]!.AsArray()) // dias sem movimento não aparecem{ var nfe = dia!["nfe"]!; // canceladas está DENTRO de emitidas: válidas = emitidas - canceladas (nunca some os dois) var nfeValidas = nfe["emitidas"]!.GetValue<int>() - nfe["canceladas"]!.GetValue<int>(); Console.WriteLine($"{dia["data"]} NF-e válidas={nfeValidas} " + $"NFC-e emitidas={dia["nfce"]?["emitidas"]} falhas NFC-e={dia["falhas"]?["nfce"]}");}var falhasNoPeriodo = resumo["data"]!["totais"]!["falhas"]!.GetValue<int>();Classificação fiscal
Sugestão de NCM, CFOP, CST, alíquotas e IBS/CBS de um produto ou serviço, na mesma chamada (sem recibo). É uma sugestão: confira com o contador antes de emitir. Veja Classificação fiscal.
// Timeout com folga: 70 s no individual, 90 s no lote (o padrão do cliente é 30 s)private readonly MyseApi _apiLenta = new( Environment.GetEnvironmentVariable("MYSE_API_BASE")!, Environment.GetEnvironmentVariable("MYSE_API_TOKEN")!, TimeSpan.FromSeconds(90));
public async Task<JsonNode> ClassificarAsync(JsonObject produto, CancellationToken ct = default){ var resp = await _apiLenta.CallAsync(HttpMethod.Post, "/classificacao-fiscal", produto, ct); if (resp["status"]?.ToString() != "005") // 400: corrija o campo indicado; repetir igual não resolve throw new ArgumentException($"{resp["descricao"]} (campo: {resp["data"]?["campo"]})"); return resp["data"]!["pacote"]!; // chaves do pacote em snake_case}
// Usovar produto = new JsonObject{ ["referencia"] = "SKU-NB15", ["nome"] = "NOTEBOOK 15 POLEGADAS 8GB RAM", ["ncm"] = "8471.30.12", // com o NCM a resposta é bem mais rápida ["documento"] = "nfe", ["destinatario"] = "contribuinte", ["destino"] = "interestadual",};var pacote = await ClassificarAsync(produto);
// Perguntas que só a empresa sabe: responda e reenvie o MESMO produto, com todas as respostasvar respostas = new JsonObject();produto["respostas"] = respostas;for (var rodada = 0; rodada < 3 && pacote["perguntas_pendentes"] is JsonArray { Count: > 0 } pendentes; rodada++){ foreach (var p in pendentes) respostas[p!["id"]!.ToString()] = PerguntarAoUsuario(p); // booleano, escolha ou texto pacote = await ClassificarAsync(produto);}Console.WriteLine($"CFOP sugerido: {pacote["icms"]?["cfop"]?["valor"]}");
// Lote: de 1 a 10 por chamada; cada item tem status própriovar lote = await _apiLenta.CallAsync(HttpMethod.Post, "/classificacao-fiscal/lote", new JsonObject{ ["produtos"] = new JsonArray( new JsonObject { ["referencia"] = "SKU-1", ["nome"] = "ARROZ BRANCO TIPO 1 5KG", ["ncm"] = "1006.30.21", ["documento"] = "nfce" }, new JsonObject { ["referencia"] = "SRV-1", ["natureza"] = "servico", ["nome"] = "CORTE DE CABELO MASCULINO" }),});foreach (var item in lote["data"]!["resultados"]!.AsArray()){ if (item!["status"]?.ToString() == "005") Revisar(item["referencia"]!.ToString(), item["pacote"]!); else // 400: corrija item["campo"]; 999: reenvie só este produto Console.WriteLine($"{item["referencia"]}: {item["descricao"]}");}Rotinas
Uma rotina emite a mesma NFS-e sozinha em cada data da agenda (mensalidade, aluguel, condomínio). Depois de ativa, ela emite nota fiscal sem ninguém olhando: confira antes de criar. Veja Rotinas de emissão automática.
// 1. Modelos e campos: o "nome" de cada campo é a chave a usar em "parametros"var modelos = await _api.CallAsync(HttpMethod.Get, "/rotinas/modelos", null);
var rotina = new JsonObject{ ["modelo"] = "NFSE_RECORRENTE", ["nome"] = "Suporte mensal - ACME", ["periodicidade"] = "mensal", ["dia"] = 10, ["inicio"] = "2026-11-01", // Exceção ao kebab-case: as chaves de parametros são os nomes do modelo (snake_case) ["parametros"] = new JsonObject { ["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}", },};
// 2. Conferir sem gravarvar conferida = await _api.CallAsync(HttpMethod.Post, "/rotinas/validar", rotina);if (conferida["data"]?["pode-ativar"]?.GetValue<bool>() != true) throw new InvalidOperationException( $"{conferida["descricao"]} {conferida["data"]?["pendencias"]?.ToJsonString()}");
// 3. Criar: sem "ativar", a rotina já sai ativavar criada = await _api.CallAsync(HttpMethod.Post, "/rotinas", rotina);if (criada["status"]?.ToString() != "001") throw new InvalidOperationException(criada["descricao"]?.ToString());var id = criada["data"]!["rotina"]!["id-rotina"]!.GetValue<int>();
// 4. A agenda não emite o mês da criação se o dia já passou: emita agoravar agora = await _api.CallAsync(HttpMethod.Post, $"/rotinas/{id}/emitir-agora", new JsonObject { ["competencia"] = "2026-11" });if (agora["status"]?.ToString() != "001") // ex.: competência já processada throw new InvalidOperationException(agora["descricao"]?.ToString());
// 5. Histórico: "Enviada para emissão" não é "autorizada"; o desfecho sai no recibo da NFS-evar execucoes = await _api.CallAsync(HttpMethod.Get, $"/rotinas/{id}/execucoes", null);foreach (var e in execucoes["data"]!["execucoes"]!.AsArray()){ var recibo = e?["recibo"]?.ToString(); if (string.IsNullOrEmpty(recibo)) continue; var nfse = await FiscalHelpers.AguardarReciboAsync(_api, "/nfse/nota", recibo); Console.WriteLine($"{e!["competencia"]}: {nfse["status"]}");}
// 6. Parar de emitir (só rotina ativa; retome com POST /rotinas/{id}/retomar)await _api.CallAsync(HttpMethod.Post, $"/rotinas/{id}/pausar", null);// Detalhe: agenda, pendências e o diagnóstico (por que emitiu ou não). 005; 500 = não encontradavar det = (await _api.CallAsync(HttpMethod.Get, $"/rotinas/{id}", null))["data"]?["rotina"];Console.WriteLine($"{det?["situacao"]} | próxima: {det?["proxima-emissao"]} | {det?["diagnostico"]}");
// Alterar: todos os campos opcionais, parcial nos parâmetros (o que não vier fica como estava).// Em rotina PAUSADA, alterar não a religa (mande "ativar": true ou use /retomar).var alterada = await _api.CallAsync(HttpMethod.Put, $"/rotinas/{id}", new JsonObject{ ["dia"] = 5, ["parametros"] = new JsonObject { ["vl_servico"] = 3800 },});if (alterada["status"]?.ToString() != "001") // 400: data.campo e/ou data.pendencias throw new InvalidOperationException($"{alterada["descricao"]} {alterada["data"]?["campo"]}");
// Valor extra num mês: soma à nota e ao boleto só daquela competência (rotina ativa,// próximos meses da agenda). Os meses possíveis vêm em competencias-disponiveis.var extras = (await _api.CallAsync(HttpMethod.Get, $"/rotinas/{id}/extras", null))["data"];Console.WriteLine($"Meses possíveis: {extras?["competencias-disponiveis"]?.ToJsonString()}");
var extra = await _api.CallAsync(HttpMethod.Put, $"/rotinas/{id}/extras/2026-12", new JsonObject{ ["valor"] = 250, ["motivo"] = "Visita técnica extra em 02/12", // 3 a 100 caracteres; aparece na nota});if (extra["status"]?.ToString() != "001") // 400: modelo sem extra (ex.: condomínio), mês fechado throw new InvalidOperationException(extra["descricao"]?.ToString());
// Remover o extra (não vale para mês já emitido ou em emissão)await _api.CallAsync(HttpMethod.Delete, $"/rotinas/{id}/extras/2026-12", null);
// Excluir a rotina: 001 "Rotina excluída."var excluida = await _api.CallAsync(HttpMethod.Delete, $"/rotinas/{id}", null);Certificado digital A1
Instala o .pfx da empresa e acompanha a validade, sem passar pela tela do FazNota. Responde na
hora, sem recibo. Desde a 3.20.0. Veja Certificado digital A1.
MYSE_PFX_SENHA=senha_do_pfxpublic async Task<JsonNode> InstalarCertificadoA1Async(string caminhoPfx, CancellationToken ct = default){ var arquivo = Convert.ToBase64String(await File.ReadAllBytesAsync(caminhoPfx, ct)); // A senha vem do ambiente (ou de um cofre). NUNCA registre em log a senha, o arquivo // ou o corpo desta requisição: com os dois, qualquer um assina em nome da empresa. var senha = Environment.GetEnvironmentVariable("MYSE_PFX_SENHA") ?? throw new InvalidOperationException("Defina MYSE_PFX_SENHA");
var resp = await _api.CallAsync(HttpMethod.Post, "/certificado/a1", new JsonObject { ["arquivo"] = arquivo, ["senha"] = senha, }, ct); if (resp["status"]?.ToString() != "001") // 400: senha errada, não é ICP-Brasil, vencido, de outro CNPJ, vence antes do atual... throw new InvalidOperationException(resp["descricao"]?.ToString()); return resp["data"]!; // situacao, valido-ate, dias-para-vencer}
// Monitoramento diário da validadevar cert = (await _api.CallAsync(HttpMethod.Get, "/certificado", null))["data"]!;var situacao = cert["situacao"]?.ToString(); // VALIDO, A_VENCER, VENCIDO, NAO_INSTALADO, INDISPONIVELif (situacao is "A_VENCER" or "VENCIDO") AvisarCliente($"Certificado vence em {cert["dias-para-vencer"]} dias ({cert["dt-validade"]})");CIOT
Declara na ANTT a operação de transporte e devolve o código do CIOT. É para ETC com RNTRC ativo e certificado A1. Veja Emitir CIOT.
public async Task<JsonNode> EmitirCiotAsync(string numeroViagem, CancellationToken ct = default){ // Os campos seguem o leiaute PEF da ANTT (PascalCase), não o kebab-case da v3 var body = new JsonObject { ["numero-origem"] = numeroViagem, // estável por viagem: o reenvio devolve o recibo original ["TipoOperacao"] = 1, // 1 carga lotação, 2 carga fracionada ["CpfCnpjContratante"] = "12345678000199", ["CpfCnpjDestinatario"] = "98765432000155", ["ValorFrete"] = 1500.00m, ["Veiculos"] = new JsonArray(new JsonObject { ["Placa"] = "ABC1D23", ["NumeroEixos"] = "4" }), ["OrigemDestino"] = new JsonArray(new JsonObject { ["Origem"] = new JsonObject { ["CodigoMunicipioOrigem"] = 4127700 }, ["Destino"] = new JsonObject { ["CodigoMunicipioDestino"] = 4104808 }, ["DistanciaPercorrida"] = 45, }), ["DadosCarga"] = new JsonObject { ["CodigoNaturezaCarga"] = 9999, ["CodigoTipoCarga"] = 5, ["PesoCarga"] = 1000, }, ["InfIndicadoresOperacionais"] = new JsonObject { ["IndAltoDesempenho"] = false, ["IndRetornoVazio"] = false, ["ComposicaoVeicular"] = false, }, ["InfPagamento"] = new JsonArray(new JsonObject { ["TipoPagamento"] = 6, ["IndPagamento"] = 0, // Pix, à vista ["IdentificadorPix"] = "FRETE-2026-1021", }), };
var pedido = await _api.CallAsync(HttpMethod.Post, "/ciot/emissao", body, ct); if (pedido["status"]?.ToString() != "001") // 400: A3, sem RNTRC, TipoOperacao inválido... throw new InvalidOperationException( pedido["data"]?["erro"]?.ToString() ?? pedido["descricao"]?.ToString());
// Se der 999 (falha com a ANTT), reenvie com o MESMO numero-origem: não gera um segundo CIOT var resultado = await FiscalHelpers.AguardarReciboAsync(_api, "/ciot", pedido["data"]!["recibo"]!.ToString(), ct: ct); if (resultado["status"]?.ToString() != "004") // 900: motivo em data.erro ou data.antt throw new InvalidOperationException($"CIOT recusado: {resultado["data"]?.ToJsonString()}"); return resultado["data"]!; // ciot, codigo-verificador, protocolo, situacao}
// Encerrar ao fim da viagem (pelo código do CIOT ou pelo recibo da emissão)var enc = await _api.CallAsync(HttpMethod.Post, "/ciot/encerramento", new JsonObject { ["ciot"] = "123456789012" });var encerrado = await FiscalHelpers.AguardarReciboAsync(_api, "/ciot", enc["data"]!["recibo"]!.ToString());
// Retificar: só carga FRACIONADA (TipoOperacao 2); lotação não admite (cancele e emita outro).// Informe ao menos um campo; CodigoMunicipioOrigem e CodigoMunicipioDestino vão juntos.var ret = await _api.CallAsync(HttpMethod.Post, "/ciot/retificacao", new JsonObject{ ["ciot"] = "123456789012", ["ValorFrete"] = 1650.00m, ["PesoCarga"] = 1200,});var retificado = await FiscalHelpers.AguardarReciboAsync(_api, "/ciot", ret["data"]!["recibo"]!.ToString()); // 004
// Cancelar (por "ciot" ou "recibo" da emissão). motivo obrigatório, até 500 caracteres.// CIOT REJEITADO pela ANTT só é marcado como cancelado no FazNota, sem chamar a ANTT.var canc = await _api.CallAsync(HttpMethod.Post, "/ciot/cancelamento", new JsonObject{ ["ciot"] = "123456789012", ["motivo"] = "Viagem cancelada pelo contratante.",});var cancelado = await FiscalHelpers.AguardarReciboAsync(_api, "/ciot", canc["data"]!["recibo"]!.ToString());if (cancelado["status"]?.ToString() != "010") throw new InvalidOperationException($"Cancelamento recusado: {cancelado["data"]?["erro"]}");RENAVE
Registra no RENAVE (SERPRO) a entrada e a saída de veículos do estoque da revenda, vinculadas à NF-e da operação. Veja RENAVE.
public async Task<string> EntradaRenaveAsync(string chaveNFe, CancellationToken ct = default){ // Os campos do RENAVE são camelCase (chaveNFe, valorCompra), não kebab-case var pedido = await _api.CallAsync(HttpMethod.Post, "/renave/nota-fiscal/entrada", new JsonObject { ["chaveNFe"] = chaveNFe, // NF-e modelo 55 de entrada, emitida pela própria empresa ["cpfOperadorResponsavel"] = "12345678901", ["dataCompra"] = "2026-10-20", ["valorCompra"] = 45000.00m, ["veiculo"] = new JsonObject { ["placa"] = "ABC1D23", ["numeroCrv"] = "123456789012", ["renavam"] = "01234567890", ["codigoSegurancaCrv"] = "12345678901", ["tipoCrv"] = "DIGITAL", ["dataHoraMedicaoHodometro"] = "2026-10-20T10:00:00", ["quilometragemHodometro"] = 52000, ["documentoProprietarioAtual"] = "98765432100", ["tipoDocumentoProprietarioAtual"] = "CPF", }, }, ct); if (pedido["status"]?.ToString() != "001") // 400: campo fora da regra, sem A1... throw new InvalidOperationException( pedido["data"]?["erro"]?.ToString() ?? pedido["descricao"]?.ToString());
var resultado = await FiscalHelpers.AguardarReciboAsync(_api, "/renave", pedido["data"]!["recibo"]!.ToString(), ct: ct); if (resultado["status"]?.ToString() != "004") // 900: motivo em data.mensagem ou data.erro throw new InvalidOperationException($"RENAVE recusou: {MotivoRenave(resultado)}"); // Guarde o id-renave: ele identifica o registro no cancelamento return resultado["data"]!["id-renave"]!.ToString();}
// A resposta do RENAVE traz dados pessoais (CPF, endereço do comprador): nunca registre o// "data" inteiro em log nem em exceção. Leia só o motivo.static string MotivoRenave(JsonNode resp) => $"{resp["status"]} {resp["data"]?["mensagem"] ?? resp["data"]?["erro"]}";
// Envia, confere o 001 e aguarda o desfecho em GET /renave/{recibo}.async Task<JsonNode> OperacaoRenaveAsync(string path, JsonObject body, CancellationToken ct = default){ var pedido = await _api.CallAsync(HttpMethod.Post, path, body, ct); if (pedido["status"]?.ToString() != "001") // 400: recusado na hora throw new InvalidOperationException( pedido["data"]?["erro"]?.ToString() ?? pedido["descricao"]?.ToString()); // 004 registrado · 010 cancelado · 900 recusado · 999 erro técnico (reenvie o MESMO pedido) return await FiscalHelpers.AguardarReciboAsync(_api, "/renave", pedido["data"]!["recibo"]!.ToString(), ct: ct);}// Saída do estoque (venda), vinculada à NF-e de venda modelo 55var saida = await OperacaoRenaveAsync("/renave/nota-fiscal/saida", new JsonObject{ ["chaveNFe"] = "35261012345678000190550010000012351000012356", ["cpfOperadorResponsavel"] = "12345678901", ["dataVenda"] = "2026-10-25", ["valorVenda"] = 52000.00m, ["veiculo"] = new JsonObject { ["placa"] = "ABC1D23", ["numeroCrv"] = "123456789012", ["renavam"] = "01234567890", }, ["comprador"] = new JsonObject { ["nome"] = "Maria Souza", ["tipoDocumento"] = "CPF", ["numeroDocumento"] = "98765432100", ["endereco"] = new JsonObject { ["logradouro"] = "Av. Paulista", ["numero"] = "1000", ["bairro"] = "Bela Vista", ["cep"] = "01310100", ["municipio"] = "São Paulo", ["uf"] = "SP", }, },});var idRenaveSaida = saida["data"]?["id-renave"]?.ToString();
// Entrada de veículo PRÓPRIO (sem compra). A chaveNFe identifica o movimento no FazNota e não// vai ao SERPRO. Aqui codigoSegurancaCrv, tipoCrv e o hodômetro também são obrigatórios.var proprio = await OperacaoRenaveAsync("/renave/estoque/entrada-veiculo-proprio", new JsonObject{ ["chaveNFe"] = "35261012345678000190550010000012361000012367", ["cpfOperadorResponsavel"] = "12345678901", ["dataEntradaEstoque"] = "2026-10-20", ["veiculo"] = new JsonObject { ["placa"] = "DEF4G56", ["numeroCrv"] = "223456789012", ["renavam"] = "11234567890", ["codigoSegurancaCrv"] = "22345678901", ["tipoCrv"] = "DIGITAL", ["dataHoraMedicaoHodometro"] = "2026-10-20T09:00:00", ["quilometragemHodometro"] = 18000, },});
// Cancelar uma entrada (compra ou veículo próprio) ou uma saída registrada com sucesso.// Identifique por "id-renave" OU pelo "recibo" do registro; os dados do veículo vêm do registro.var cancEntrada = await OperacaoRenaveAsync("/renave/estoque/cancelamento-entrada", new JsonObject { ["id-renave"] = proprio["data"]?["id-renave"]?.ToString() });var cancSaida = await OperacaoRenaveAsync("/renave/estoque/cancelamento-saida", new JsonObject { ["id-renave"] = idRenaveSaida });if (cancSaida["status"]?.ToString() != "010") throw new InvalidOperationException($"Cancelamento recusado: {MotivoRenave(cancSaida)}");Listar com paginação
public async Task<List<JsonNode>> ListarTodosClientesAsync(CancellationToken ct = default){ var todos = new List<JsonNode>(); int page = 1; int pageSize = 100;
while (true) { var resp = await _api.CallAsync(HttpMethod.Get, $"/clientes?page={page}&page_size={pageSize}", null, ct);
if (resp["status"]?.ToString() != "005") break; if (resp["data"] is not JsonArray arr || arr.Count == 0) break;
todos.AddRange(arr.Select(x => x!));
if (arr.Count < pageSize) break; page++; await Task.Delay(200, ct); }
return todos;}Tratamento de erros + logging estruturado
try{ var nfce = await emissor.EmitirAsync(pedido); _logger.LogInformation("NFCe emitida: {Chave}", nfce["sefaz"]?["chave"]);}catch (ApiError e){ _logger.LogError( "API Error httpStatus={Status} requestId={RequestId} msg={Message}", e.HttpStatus, e.RequestId, e.Message ); throw;}Health check (sem autenticação)
using var http = new HttpClient();var res = await http.GetAsync($"{baseUrl}/health");var health = await res.Content.ReadFromJsonAsync<JsonNode>();// { status: "ok", database: "ok", timestamp: "..." }
// Profundo: SELECT 1 no banco + pool de conexões. 200 = UP; 503 = banco falhou ou pool saturadovar deepRes = await http.GetAsync($"{baseUrl}/health/deep");var deep = JsonNode.Parse(await deepRes.Content.ReadAsStringAsync());var saudavel = deepRes.IsSuccessStatusCode && deep?["status"]?.ToString() == "UP";// deep.db.ok, deep.db.latency_ms, deep.pool.active/idle/waiting/total/max, deep.total_ms
// Só as métricas do pool, sem tocar no banco (sempre 200; status STARTING enquanto inicializa)var pool = (await http.GetFromJsonAsync<JsonNode>($"{baseUrl}/health/pool"))?["pool"];Console.WriteLine($"ativas={pool?["active"]} ociosas={pool?["idle"]} esperando={pool?["waiting"]} max={pool?["max"]}");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.
public async Task<JsonNode> AlterarNotaAsync(string tipo, string id, object dados, CancellationToken ct = default){ // tipo: "nfe" | "nfce" | "nfse" return await _api.CallAsync(HttpMethod.Put, $"/{tipo}/{id}", dados, ct);}
// Uso:await AlterarNotaAsync("nfe", "12345", new JsonObject{ ["serie"] = "1", ["cfop"] = "5102", ["cliente"] = "12345678000199", ["itens"] = new JsonArray(new JsonObject { ["produto"] = "SKU-001", ["quantidade"] = "3", ["valor-unitario"] = "89.90", }),});Listagens
var nfes = await _api.CallAsync(HttpMethod.Get, "/nfe?page=1&page_size=20", null);var nfces = await _api.CallAsync(HttpMethod.Get, "/nfce?page=1&page_size=50", null);var nfses = await _api.CallAsync(HttpMethod.Get, "/nfse?dataInicial=2026-05-01&page=1&page_size=20", null);var fornecedor = await _api.CallAsync(HttpMethod.Get, "/nffornecedor?page=1&page_size=20", null);
// Forma legada (path-based)var nfesLegado = await _api.CallAsync(HttpMethod.Get, "/nfe/paginacao/1/20", null);Clientes (CRUD completo)
private static JsonObject EnderecoJson(Endereco e) => new(){ ["cep"] = e.Cep, ["rua"] = e.Rua, ["numero"] = e.Numero, ["complemento"] = e.Complemento, ["bairro"] = e.Bairro, ["cidade"] = e.Cidade, ["estado"] = e.Estado,};
public async Task<JsonNode> CadastrarPFAsync(PessoaFisica pf, CancellationToken ct = default){ return await _api.CallAsync(HttpMethod.Post, "/clientes", new JsonObject { ["tipo"] = "F", ["nome"] = pf.Nome, ["cpf"] = pf.Cpf, ["rg"] = pf.Rg, ["consumidor-final"] = "1", ["contato"] = new JsonObject { ["email"] = pf.Email, ["telefone"] = pf.Telefone }, ["endereco"] = EnderecoJson(pf.Endereco), }, ct);}
public async Task<JsonNode> CadastrarPJAsync(PessoaJuridica pj, CancellationToken ct = default){ return await _api.CallAsync(HttpMethod.Post, "/clientes", new JsonObject { ["tipo"] = "J", ["razao-social"] = pj.RazaoSocial, ["nome-fantasia"] = pj.NomeFantasia, ["cnpj"] = pj.Cnpj, ["inscricao-municipal"] = pj.InscricaoMunicipal, ["tipo-inscricao-estadual"] = pj.Contribuinte ?? "9", ["inscricao-estadual"] = pj.InscricaoEstadual ?? "ISENTO", ["consumidor-final"] = "0", ["contato"] = new JsonObject { ["email"] = pj.Email, ["telefone"] = pj.Telefone }, ["endereco"] = EnderecoJson(pj.Endereco), }, ct);}
// Consultar por CPF/CNPJvar cliente = await _api.CallAsync(HttpMethod.Get, "/clientes/12345678000199", null);
// Buscar por nomevar encontrados = await _api.CallAsync(HttpMethod.Get, "/clientes/busca/exemplo", null);var top = await _api.CallAsync(HttpMethod.Get, "/clientes/busca/top_clientes", null);
// Atualizarawait _api.CallAsync(HttpMethod.Put, "/clientes/12345678000199", new JsonObject{ ["tipo"] = "J", ["razao-social"] = "Empresa Exemplo (Novo Nome) Ltda",});
// Excluirawait _api.CallAsync(HttpMethod.Delete, "/clientes/12345678000199", null);Produtos (CRUD completo)
public async Task<JsonNode> CadastrarProdutoAsync(Produto p, CancellationToken ct = default){ var body = new JsonObject { ["referencia"] = p.Sku, ["nome"] = p.Nome, ["valor"] = p.Valor.ToString("F2"), ["medida"] = p.Medida ?? "UN", ["categoria"] = p.Categoria, ["ncm"] = p.Ncm, ["origem"] = p.Origem ?? "0", ["cfop-preferencial"] = p.Cfop ?? "5102", ["tipo-produto"] = "P", }; // p.ConfiguracoesFiscais: JsonArray já com as chaves do contrato. O Parse faz uma cópia, // porque um nó JSON só pode estar em um pai. if (p.ConfiguracoesFiscais is not null) body["configuracoes-fiscais"] = JsonNode.Parse(p.ConfiguracoesFiscais.ToJsonString()); return await _api.CallAsync(HttpMethod.Post, "/produtos", body, ct);}
public async Task<JsonNode> CadastrarServicoAsync(Servico s, CancellationToken ct = default){ return await _api.CallAsync(HttpMethod.Post, "/produtos", new JsonObject { ["referencia"] = s.Sku, ["nome"] = s.Nome, ["valor"] = s.Valor.ToString("F2"), ["medida"] = "H", ["tipo-produto"] = "S", ["codigo-servico"] = s.CodigoServico, }, ct);}
// Consultarvar produto = await _api.CallAsync(HttpMethod.Get, "/produtos/SKU-001", null);var porNome = await _api.CallAsync(HttpMethod.Get, "/produtos/nome/Camiseta", null);
// Listar paginado com busca (use _todos para não filtrar)var todos = await _api.CallAsync(HttpMethod.Get, "/produtos/paginacao/1/20/_todos", null);var filtrados = await _api.CallAsync(HttpMethod.Get, "/produtos/paginacao/1/20/Camiseta", null);
// Atualizarawait _api.CallAsync(HttpMethod.Put, "/produtos/SKU-001", new JsonObject{ ["referencia"] = "SKU-001", ["nome"] = "Camiseta Polo M (Novo)", ["valor"] = "99.90",});
// Excluirawait _api.CallAsync(HttpMethod.Delete, "/produtos/SKU-001", null);