Pular para o conteúdo

Exemplos em C# (.NET)

Setup

Requer .NET 6+.

.csproj
<PackageReference Include="DotNetEnv" Version="3.0.0" />
.env
MYSE_API_BASE=https://api.mysebr.com.br/nfemyse-v3/rest
MYSE_API_TOKEN=seu_token_aqui

Cliente 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 extra
private 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,
["email"] = "[email protected]",
}, 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
}
// Uso
var 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 respostas
var 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óprio
var 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 gravar
var 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 ativa
var 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 agora
var 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-e
var 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 encontrada
var 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.

.env
MYSE_PFX_SENHA=senha_do_pfx
public 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 validade
var cert = (await _api.CallAsync(HttpMethod.Get, "/certificado", null))["data"]!;
var situacao = cert["situacao"]?.ToString(); // VALIDO, A_VENCER, VENCIDO, NAO_INSTALADO, INDISPONIVEL
if (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
["ChavePix"] = "[email protected]",
["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,
["emailVendedor"] = "[email protected]",
["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 55
var 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",
["email"] = "[email protected]",
["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 saturado
var 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/CNPJ
var cliente = await _api.CallAsync(HttpMethod.Get, "/clientes/12345678000199", null);
// Buscar por nome
var encontrados = await _api.CallAsync(HttpMethod.Get, "/clientes/busca/exemplo", null);
var top = await _api.CallAsync(HttpMethod.Get, "/clientes/busca/top_clientes", null);
// Atualizar
await _api.CallAsync(HttpMethod.Put, "/clientes/12345678000199", new JsonObject
{
["tipo"] = "J",
["razao-social"] = "Empresa Exemplo (Novo Nome) Ltda",
});
// Excluir
await _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);
}
// Consultar
var 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);
// Atualizar
await _api.CallAsync(HttpMethod.Put, "/produtos/SKU-001", new JsonObject
{
["referencia"] = "SKU-001",
["nome"] = "Camiseta Polo M (Novo)",
["valor"] = "99.90",
});
// Excluir
await _api.CallAsync(HttpMethod.Delete, "/produtos/SKU-001", null);