Exemplos em Python
Setup
pip install requests python-dotenvMYSE_API_BASE=https://api.mysebr.com.br/nfemyse-v3/restMYSE_API_TOKEN=seu_token_aquiCliente HTTP centralizado
import osimport timefrom dataclasses import dataclassfrom typing import Any, Optionalimport requestsfrom dotenv import load_dotenv
load_dotenv()
BASE = os.environ["MYSE_API_BASE"]TOKEN = os.environ["MYSE_API_TOKEN"]
@dataclassclass ApiError(Exception): http_status: int message: str payload: Any request_id: Optional[str] = None
def __str__(self): return f"[{self.http_status}] {self.message} (request_id={self.request_id})"
def m_api(method: str, path: str, body: dict | None = None, timeout: int = 30) -> dict: headers = { "Authorization": f"Token {TOKEN}", "Content-Type": "application/json", } res = requests.request( method, f"{BASE}{path}", json=body, headers=headers, timeout=timeout )
request_id = res.headers.get("X-Request-Id")
# Erros HTTP duros if not res.ok: try: payload = res.json() msg = payload.get("error", {}).get("message", f"HTTP {res.status_code}") except Exception: payload = {} msg = f"HTTP {res.status_code}" raise ApiError(res.status_code, msg, payload, request_id)
json = res.json()
# Erro de domínio if json.get("status") == "999": raise ApiError( 200, json.get("data", {}).get("erro") or json.get("descricao", "erro"), json, (json.get("meta") or {}).get("request_id") or request_id, )
return jsonCenário: emitir NFCe com polling
import time
def emitir_nfce(pedido: dict) -> dict: # 1. Emissão body = { "serie": "65", "cfop": "5102", "numero-origem": f"PED-{pedido['id']}", "tp_pagamento": pedido["forma_pagamento"], "cliente": pedido["cpf_cnpj_cliente"], "itens": [ { "produto": i["sku"], "quantidade": str(i["qtd"]), "valor-unitario": str(i["preco"]), } for i in pedido["itens"] ], }
emissao = m_api("POST", "/nfce/emissao", body) if emissao["status"] not in ("001", "050"): raise RuntimeError(f"Emissão falhou: {emissao['descricao']}")
recibo = emissao["data"]["recibo"] print(f"[emissao] recibo={recibo} request_id={emissao['meta']['request_id']}")
# 2. Polling TERMINAIS = {"004", "010", "900", "999"} wait = 5.0 inicio = time.time()
while time.time() - inicio < 5 * 60: time.sleep(wait) consulta = m_api("GET", f"/nfce/cupom/{recibo}") print(f"[polling] status={consulta['status']}")
if consulta["status"] in TERMINAIS: if consulta["status"] == "004": return consulta["data"] raise RuntimeError(f"Status terminal não-sucesso: {consulta['status']}")
wait = min(wait * 1.5, 30)
raise TimeoutError(f"Timeout aguardando recibo {recibo}")Retry em erros transitórios
def com_retry(fn, max_tentativas=3): for i in range(1, max_tentativas + 1): try: return fn() except ApiError as e: if e.payload and e.payload.get("status") == "999": raise # Validação: não retentar if i == max_tentativas: raise time.sleep(2 ** (i - 1)) # 1s, 2s, 4s except (requests.Timeout, requests.ConnectionError): if i == max_tentativas: raise time.sleep(2 ** (i - 1))
# Usonfce = com_retry(lambda: emitir_nfce(pedido))Helper de polling reutilizável
TERMINAIS = {"004", "010", "900", "999"}
def aguardar_recibo(path_base: str, recibo: str, timeout: int = 300) -> dict: """Polling com backoff exponencial até status terminal.""" wait = 5.0 inicio = time.time()
while time.time() - inicio < timeout: time.sleep(wait) resp = m_api("GET", f"{path_base}/{recibo}") if resp["status"] in TERMINAIS: return resp wait = min(wait * 1.5, 30)
raise TimeoutError(f"Timeout aguardando recibo {recibo}")Emitir NF-e (com transporte completo)
def emitir_nfe(pedido: dict) -> dict: body = { "serie": "1", "cfop": "5102", "numero-origem": f"PED-{pedido['id']}", "tipo": "S", "finalidade": "N", "valor-despesas": "0.00", "cliente": pedido["cpf_cnpj_cliente"], "transporte": { "modalidade": "0", "transportadora": pedido["transportadora"], "placa-veiculo": pedido["placa"], "valor-frete": pedido.get("frete", "0.00"), "valor-seguro": "0.00", "peso-bruto": pedido["peso_bruto"], "peso-liquido": pedido["peso_liquido"], "quantidade-volume": "1", "especie-volume": "Caixa", "marca-volume": "Embalagem", }, "itens": [ { "produto": i["sku"], "quantidade": str(i["qtd"]), "valor-unitario": str(i["preco"]), } for i in pedido["itens"] ], "faturas": [ {"valor": str(f["valor"]), "data": f["data"]} for f in pedido.get("faturas", []) ], }
emissao = m_api("POST", "/nfe/emissao", body) if emissao["status"] not in ("001", "050"): raise RuntimeError(f"Emissão falhou: {emissao['descricao']}")
resultado = aguardar_recibo("/nfe/nota", emissao["data"]["recibo"]) if resultado["status"] != "004": raise RuntimeError(f"Status terminal não-sucesso: {resultado['status']}") return resultado["data"] # inclui sefaz.chave, url-danfe, url-xmlCancelar NF-e
def cancelar_nfe(chave: str, motivo: str) -> dict: assert 15 <= len(motivo) <= 255, "motivo deve ter entre 15 e 255 caracteres" cancel = m_api("POST", "/nfe/cancelamento", {"chave": chave, "motivo": motivo}) if cancel["status"] != "001": raise RuntimeError(cancel["descricao"]) return aguardar_recibo("/nfe/cancelamento", cancel["data"]["recibo"])Lançar carta de correção (CC-e)
def carta_correcao_nfe(chave: str, texto_correcao: str) -> dict: """O campo 'motivo' na CC-e é o TEXTO da correção (xCorrecao).""" # CC-e aceita de 15 a 1000 caracteres (desde a 3.15.1); o cancelamento segue em 15 a 255 if not 15 <= len(texto_correcao) <= 1000: raise ValueError("texto deve ter entre 15 e 1000 caracteres") cce = m_api("POST", "/nfe/correcao", {"chave": chave, "motivo": texto_correcao}) if cce["status"] != "001": raise RuntimeError(cce["descricao"]) return aguardar_recibo("/nfe/correcao", cce["data"]["recibo"])Cancelar NFC-e
def cancelar_nfce(chave: str, motivo: str) -> dict: assert 15 <= len(motivo) <= 255, "motivo deve ter 15-255 chars" cancel = m_api("POST", "/nfce/cancelamento", {"chave": chave, "motivo": motivo}) if cancel["status"] != "001": raise RuntimeError(cancel["descricao"]) return aguardar_recibo("/nfce/cancelamento", cancel["data"]["recibo"])Emitir NFS-e (Nota Fiscal de Serviço)
def emitir_nfse(servico: dict) -> dict: body = { "numero-origem": f"OS-{servico['id']}", "observacao": servico["observacao"], "nome-contato": servico.get("nome_contato"), "telefone-contato": servico.get("telefone_contato"), "data-fim": servico["data_fim"], "cliente": servico["cpf_cnpj_cliente"], "itens": [ { "produto": i["codigo_servico"], "quantidade": str(i["qtd"]), "valor-unitario": str(i["preco"]), } for i in servico["itens"] ], }
emissao = m_api("POST", "/nfse/emissao", body) if emissao["status"] not in ("001", "050"): raise RuntimeError(f"Emissão NFSe falhou: {emissao['descricao']}")
resultado = aguardar_recibo("/nfse/nota", emissao["data"]["recibo"]) if resultado["status"] != "004": raise RuntimeError(f"Status terminal não-sucesso: {resultado['status']}") return resultado["data"]Cancelar NFS-e
def cancelar_nfse(chave: str, motivo: str) -> dict: assert 15 <= len(motivo) <= 255, "motivo deve ter 15-255 chars" return m_api("POST", "/nfse/cancelamento", {"chave": chave, "motivo": motivo})Reconhecer nota de fornecedor (MD-e)
CODIGOS_RECONHECIMENTO = {"210200", "210210", "210220", "210240"}# 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
def reconhecer_nota_fornecedor(chave: str, codigo: str) -> dict: if codigo not in CODIGOS_RECONHECIMENTO: raise ValueError(f"Código inválido: {codigo}")
resp = m_api("POST", "/nffornecedor/reconhecimento", { "chave": chave, "codigo-reconhecimento": codigo, }) if resp["status"] != "001": raise RuntimeError(resp["descricao"]) return aguardar_recibo("/nffornecedor", resp["data"]["recibo"])Consulta completa por recibo
A consulta simples (/nfe/nota/{recibo}) serve para o polling. A completa devolve todos os dados
do documento. Veja Emitir NF-e e Paginação.
# NF-e: itens, transporte, cliente, faturas, notas referenciadas e dados da SEFAZ# (chave, protocolo, URLs do DANFE e do XML)nfe_completa = m_api("GET", f"/nfe/nota/{recibo}/completa")
# NFC-e: itens, cliente e dados da SEFAZnfce_completa = m_api("GET", f"/nfce/cupom/{recibo}/completa")# Recibo de outra operação (ex.: de um cancelamento) responde status "500".
def listar_nfces(quantidade: int = 100): """NFC-es pela paginação de path (legado). {pagina} começa em 1; quantidade até 500.""" pagina = 1 while True: resp = m_api("GET", f"/nfce/paginacao/{pagina}/{quantidade}") if resp["status"] != "005" or not isinstance(resp.get("data"), list): break yield from resp["data"] if len(resp["data"]) < quantidade: break pagina += 1Inutilizar numeração
Fecha na SEFAZ uma faixa de NF-e (/nfe/inutilizacao) ou NFC-e (/nfce/inutilizacao) que não foi
usada. Exige certificado A1. Veja Inutilizar numeração.
def inutilizar(modelo: str, serie: str, inicial: int, final: int, justificativa: str, ano: str | None = None) -> dict: """modelo: 'nfe' (55) ou 'nfce' (65). Para um número só, final = inicial.""" assert 15 <= len(justificativa) <= 255, "justificativa deve ter 15-255 chars" body = { "serie": serie, "numero-inicial": str(inicial), "numero-final": str(final), "justificativa": justificativa, } if ano: body["ano"] = ano # ano em que a numeração foi GERADA ("26" ou "2026")
pedido = m_api("POST", f"/{modelo}/inutilizacao", body) if pedido["status"] != "001": # 400: faixa com nota autorizada ou em processamento, faixa já na fila, certificado A3... raise RuntimeError((pedido.get("data") or {}).get("erro") or pedido["descricao"])
resultado = aguardar_recibo(f"/{modelo}/inutilizacao", pedido["data"]["recibo"]) sefaz = resultado["data"].get("sefaz", {}) if resultado["status"] != "004": # 900 = recusada pela SEFAZ raise RuntimeError(f"SEFAZ recusou: {sefaz.get('codigo')} {sefaz.get('mensagem')}") return sefaz # codigo "102" e protocolo
inutilizar("nfe", "1", 120, 125, "Falha no sistema pulou a numeração da série.")XML em lote por período
O ZIP com os XMLs de NF-e ou NFC-e de até 92 dias é gerado em segundo plano: solicite, consulte o protocolo e baixe o link temporário. Veja Baixar XMLs por período.
def baixar_xml_periodo(tipo: str, data_inicial: str, data_final: str, destino: str, email: str | None = None) -> str | None: """tipo: 'NFe' ou 'NFCe'. Devolve o caminho do ZIP, ou None se não havia nota.""" body = {"tipo": tipo, "data-inicial": data_inicial, "data-final": data_final} if email: body["email"] = email
sol = m_api("POST", "/xml/solicitacao", body) # 050 = já havia uma solicitação igual em andamento; o protocolo devolvido é o dela if sol["status"] not in ("001", "050"): raise RuntimeError((sol.get("data") or {}).get("erro") or sol["descricao"]) protocolo = sol["data"]["protocolo"]
wait, inicio = 5.0, time.time() # intervalo mínimo entre consultas: 2 s while True: if time.time() - inicio > 15 * 60: raise TimeoutError(f"Timeout aguardando protocolo {protocolo}") time.sleep(wait) resp = m_api("GET", f"/xml/solicitacao/{protocolo}") if resp["status"] == "005": # disponivel break if resp["status"] == "006": # sem-notas: final, reconsultar não muda return None if resp["status"] != "002": # 007 falha (faça NOVA solicitação), 500 protocolo inexistente raise RuntimeError(f"Protocolo {protocolo}: {resp['status']} {resp['descricao']}") wait = min(wait * 1.5, 30)
# url-download expira em data["expira-em"] (7 dias). Só aceita GET e NÃO leva Authorization. with requests.get(resp["data"]["url-download"], stream=True, timeout=120) as r: r.raise_for_status() with open(destino, "wb") as f: for chunk in r.iter_content(chunk_size=64 * 1024): f.write(chunk) return destino
Resumo diário
Totais por dia de NF-e e NFC-e emitidas, canceladas, denegadas e das falhas, para conciliação. Veja Resumo diário de emissões.
from urllib.parse import urlencode
def resumo_diario(data_inicial: str, data_final: str) -> dict: """Período de até 92 dias, datas AAAA-MM-DD.""" qs = urlencode({"data-inicial": data_inicial, "data-final": data_final}) resp = m_api("GET", f"/resumo?{qs}") if resp["status"] != "005": raise RuntimeError(resp["descricao"]) return resp["data"]
resumo = resumo_diario("2026-08-01", "2026-08-06")for dia in resumo["dias"]: # dias sem movimento não aparecem nfe, nfce = dia["nfe"], dia["nfce"] # canceladas é SUBCONJUNTO de emitidas: notas válidas = emitidas - canceladas print( dia["data"], f"NF-e válidas={nfe['emitidas'] - nfe['canceladas']}", f"NFC-e válidas={nfce['emitidas'] - nfce['canceladas']}", f"falhas={sum(dia['falhas'].values())}", )print("Falhas no período:", resumo["totais"]["falhas"])Classificação fiscal
Sugestão de NCM, CEST, CFOP, CST, alíquotas, IBS/CBS e ISS de um produto ou serviço, na mesma chamada (sem recibo). Só consulta: não grava nada. Confira a sugestão com o contador antes de emitir. Veja Classificação fiscal.
def classificar(produto: dict, respostas_conhecidas: dict | None = None) -> dict: """Classifica um item e reenvia com `respostas` enquanto houver pergunta que você sabe responder.""" body = dict(produto) conhecidas = respostas_conhecidas or {} while True: # Sem NCM informado, o motor identifica o item por IA: dê folga ao timeout (70 s) resp = m_api("POST", "/classificacao-fiscal", body, timeout=70) if resp["status"] != "005": # 400: motivo na descricao, campo em data.campo raise ValueError(f"{resp['descricao']} (campo={(resp.get('data') or {}).get('campo')})")
pacote = resp["data"]["pacote"] # chaves do pacote em snake_case ja_respondidas = body.get("respostas", {}) novas = { p["id"]: conhecidas[p["id"]] for p in pacote.get("perguntas_pendentes") or [] if p["id"] in conhecidas and p["id"] not in ja_respondidas } if not novas: # Sem pendência, ou só sobraram perguntas para mostrar ao usuário (p["texto"]) return pacote body["respostas"] = {**ja_respondidas, **novas} # reenvia o MESMO produto
pacote = classificar( { "referencia": "SKU-NB15", "nome": "NOTEBOOK 15 POLEGADAS 8GB RAM", "ncm": "8471.30.12", "documento": "nfe", "destinatario": "contribuinte", "destino": "interestadual", }, respostas_conhecidas={ "empresa_industrial_ou_equiparada_ipi": False, "produto_sujeito_st_na_uf": False, },)print(pacote["icms"]["cfop"]["valor"], pacote["metadados"]["requer_revisao"])
def classificar_lote(produtos: list[dict]) -> tuple[list[dict], list[dict]]: """Até 10 produtos por chamada. Devolve (resultados, produtos para reenviar).""" resultados, reenviar = [], [] for inicio in range(0, len(produtos), 10): fatia = produtos[inicio:inicio + 10] resp = m_api("POST", "/classificacao-fiscal/lote", {"produtos": fatia}, timeout=90) if resp["status"] != "005": raise ValueError(resp["descricao"]) # Cada item tem status próprio, na ordem do pedido: 005 (pacote), 400 (campo) ou 999 for item in resp["data"]["resultados"]: resultados.append(item) if item["status"] == "999": # não terminou no prazo do lote: reenvie só ele reenviar.append(fatia[item["indice"]]) return resultados, reenviarRotinas
Uma rotina emite NFS-e sozinha em cada data da agenda (recorrente, aluguel, condomínio). Todas as rotas respondem na hora; quem gera recibo é a NFS-e emitida. Veja Rotinas.
# Modelos e os campos (parametros) de cada umfor modelo in m_api("GET", "/rotinas/modelos")["data"]["modelos"]: print(modelo["codigo"], [p["nome"] for p in modelo["parametros"]])
rotina = { "modelo": "NFSE_RECORRENTE", "nome": "Suporte mensal - ACME", "periodicidade": "mensal", "dia": 10, "inicio": "2026-11-01", # As chaves de parametros são os nomes dos campos do modelo (snake_case). # Os ids vêm de GET /rotinas/clientes?busca= e GET /rotinas/servicos. "parametros": { "id_clifor": 1262804, "id_produto": 88231, "vl_servico": "3.500,50", "ds_discriminacao": "Suporte técnico de {competencia}", },}
# 1. Conferir sem gravarconferencia = m_api("POST", "/rotinas/validar", rotina)if conferencia["status"] != "005" or not conferencia["data"]["pode-ativar"]: raise RuntimeError(conferencia["descricao"], conferencia.get("data"))
# 2. Criar. Sem "ativar", já sai ATIVA e emite nota fiscal sozinha.criada = m_api("POST", "/rotinas", rotina)if criada["status"] != "001": # 400: data.campo ou data.pendencias raise RuntimeError(criada["descricao"], criada.get("data"))id_rotina = criada["data"]["rotina"]["id-rotina"]
# 3. A agenda não emite o mês da criação se o dia já passou: emita agoraagora = m_api("POST", f"/rotinas/{id_rotina}/emitir-agora", {"competencia": "2026-11"})print(agora["data"]["numero-origem"]) # ROT-<id>-2026-11: enfileirada, ainda não autorizada
# 4. Histórico: o recibo de cada NFS-e. O desfecho sai em /nfse/nota/{recibo}.for execucao in m_api("GET", f"/rotinas/{id_rotina}/execucoes")["data"]["execucoes"]: if execucao.get("recibo"): nfse = aguardar_recibo("/nfse/nota", execucao["recibo"]) print(execucao["competencia"], execucao["situacao-descricao"], nfse["status"])
# 5. Detalhe: dados, agenda, pendencias, diagnostico (por que emitiu ou não) e execucoesdetalhe = m_api("GET", f"/rotinas/{id_rotina}")if detalhe["status"] == "500": # inexistente ou excluída raise RuntimeError(detalhe["descricao"])print(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.alterada = m_api("PUT", f"/rotinas/{id_rotina}", {"dia": 5, "parametros": {"vl_servico": 3800}})if alterada["status"] != "001": # 400: data.campo ou data.pendencias raise RuntimeError(alterada["descricao"], alterada.get("data"))
# 7. Valor extra em um único mês (só rotina ativa, só nos próximos meses da agenda)extras = m_api("GET", f"/rotinas/{id_rotina}/extras")["data"]if extras["competencias-disponiveis"]: competencia = extras["competencias-disponiveis"][0] # AAAA-MM lancado = m_api("PUT", f"/rotinas/{id_rotina}/extras/{competencia}", { "valor": 250, # ou "250,50"; maior que zero "motivo": "Visita técnica extra em 02/12", # 3 a 100 caracteres, vai na descrição da nota }) if lancado["status"] != "001": # 400: ex. condomínio não aceita valor extra raise RuntimeError(lancado["descricao"]) for extra in lancado["data"]["extras"]: print(extra["competencia"], extra["valor"], extra["situacao"]) # "Programado"...
# Desistiu? Remove o extra (não vale para mês já emitido ou em emissão) m_api("DELETE", f"/rotinas/{id_rotina}/extras/{competencia}")
# 8. Pausar (só rotina ativa). Retomar: POST /rotinas/{id}/retomarpausada = m_api("POST", f"/rotinas/{id_rotina}/pausar")print(pausada["data"]["rotina"]["situacao"]) # "pausada"
# 9. Excluir: status 001 e data["id-rotina"]excluida = m_api("DELETE", f"/rotinas/{id_rotina}")if excluida["status"] != "001": raise RuntimeError(excluida["descricao"])Certificado digital A1
Instala o .pfx/.p12 da empresa da chave e acompanha a validade, sem passar pela tela do
FazNota. Desde a 3.20.0. Guarde a senha do arquivo numa variável de ambiente
(MYSE_CERT_SENHA). Veja Certificado digital A1.
import base64
def instalar_certificado_a1(caminho_pfx: str) -> dict: with open(caminho_pfx, "rb") as f: arquivo = base64.b64encode(f.read()).decode("ascii") # até 50 KB de arquivo senha = os.environ["MYSE_CERT_SENHA"] # NUNCA registre em log a senha, o arquivo nem o corpo desta requisição. resp = m_api("POST", "/certificado/a1", {"arquivo": arquivo, "senha": senha}) if resp["status"] != "001": # 400: senha errada, não é A1 ICP-Brasil, vencido, de outro CNPJ, vence antes do atual... raise RuntimeError(resp["descricao"]) return resp["data"] # já em uso: a próxima emissão sai assinada com ele
def conferir_certificado() -> dict: cert = m_api("GET", "/certificado")["data"] # VALIDO, A_VENCER (até 30 dias), VENCIDO, NAO_INSTALADO ou INDISPONIVEL if cert["situacao"] in ("A_VENCER", "VENCIDO", "NAO_INSTALADO"): print(f"Certificado {cert['situacao']}: {cert.get('dias-para-vencer')} dias para vencer") return certCIOT
Declara na ANTT a operação de transporte de uma ETC e devolve o código do CIOT. Os campos seguem o leiaute PEF da ANTT (PascalCase). Veja Emitir CIOT.
def emitir_ciot(numero_viagem: str) -> dict: # Não envie CpfCnpjContratado, RNTRCContratado nem IdOperacaoTransporte (vêm do cadastro). body = { "numero-origem": numero_viagem, # estável por viagem: reenvio após 999 usa o MESMO valor "TipoOperacao": 1, # 1 carga lotação, 2 carga fracionada "CpfCnpjContratante": "12345678000199", "CpfCnpjDestinatario": "98765432000155", "ValorFrete": 1500.00, "Veiculos": [{"Placa": "ABC1D23", "NumeroEixos": "4"}], "OrigemDestino": [{ "Origem": {"CodigoMunicipioOrigem": 4127700}, "Destino": {"CodigoMunicipioDestino": 4104808}, "DistanciaPercorrida": 45, }], "DadosCarga": {"CodigoNaturezaCarga": 9999, "CodigoTipoCarga": 5, "PesoCarga": 1000}, "InfIndicadoresOperacionais": { "IndAltoDesempenho": False, "IndRetornoVazio": False, "ComposicaoVeicular": False, }, "InfPagamento": [{ "TipoPagamento": 6, "IndPagamento": 0, "IdentificadorPix": "FRETE-2026-1021", }], } pedido = m_api("POST", "/ciot/emissao", body) if pedido["status"] != "001": # 400: TipoOperacao inválido, A3, sem RNTRC... raise RuntimeError((pedido.get("data") or {}).get("erro") or pedido["descricao"])
resultado = aguardar_recibo("/ciot", pedido["data"]["recibo"]) if resultado["status"] != "004": # 900: recusado pela ANTT ou pelo leiaute data = resultado["data"] raise RuntimeError(data.get("erro") or data.get("antt", {}).get("mensagem")) return resultado["data"] # ciot, codigo-verificador, protocolo, situacao
def encerrar_ciot(ciot: str) -> dict: """Identifique por "ciot" (o código) ou por "recibo" (o da emissão).""" pedido = m_api("POST", "/ciot/encerramento", {"ciot": ciot}) if pedido["status"] != "001": raise RuntimeError((pedido.get("data") or {}).get("erro") or pedido["descricao"]) return aguardar_recibo("/ciot", pedido["data"]["recibo"]) # 004 = encerrado
def cancelar_ciot(ciot: str, motivo: str) -> dict: """Cancela na ANTT. CIOT que a ANTT recusou (REJEITADO) só é marcado como cancelado no FazNota.""" if not motivo or len(motivo) > 500: raise ValueError("motivo é obrigatório, até 500 caracteres") pedido = m_api("POST", "/ciot/cancelamento", {"ciot": ciot, "motivo": motivo}) if pedido["status"] != "001": raise RuntimeError((pedido.get("data") or {}).get("erro") or pedido["descricao"]) resultado = aguardar_recibo("/ciot", pedido["data"]["recibo"]) if resultado["status"] != "010": # 010 = cancelado data = resultado.get("data") or {} raise RuntimeError(data.get("erro") or data.get("antt", {}).get("mensagem") or resultado["descricao"]) return resultado["data"]
def retificar_ciot(ciot: str, campos: dict) -> dict: """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.""" pedido = m_api("POST", "/ciot/retificacao", {"ciot": ciot, **campos}) if pedido["status"] != "001": raise RuntimeError((pedido.get("data") or {}).get("erro") or pedido["descricao"]) return aguardar_recibo("/ciot", pedido["data"]["recibo"]) # 004 = retificado
ciot = emitir_ciot("VIAGEM-1021")["ciot"]retificar_ciot(ciot, {"ValorFrete": 1650.00, "PesoCarga": 1200}) # só se TipoOperacao 2cancelar_ciot(ciot, "Viagem cancelada pelo contratante.")RENAVE
Registra no SERPRO a entrada e a saída de veículos do estoque da revenda, vinculadas à NF-e da operação. Os campos seguem os nomes do SERPRO (camelCase). Veja RENAVE.
def renave_entrada_compra() -> dict: body = { "chaveNFe": "35261012345678000190550010000012341000012345", # NF-e 55 da própria empresa "cpfOperadorResponsavel": "12345678901", "dataCompra": "2026-10-20", "valorCompra": 45000.00, "veiculo": { "placa": "ABC1D23", "numeroCrv": "123456789012", "renavam": "01234567890", "codigoSegurancaCrv": "12345678901", "tipoCrv": "DIGITAL", "dataHoraMedicaoHodometro": "2026-10-20T10:00:00", "quilometragemHodometro": 52000, "documentoProprietarioAtual": "98765432100", "tipoDocumentoProprietarioAtual": "CPF", }, } pedido = m_api("POST", "/renave/nota-fiscal/entrada", body) if pedido["status"] != "001": # 400: campo obrigatório ausente, sem A1 ou e-mail principal raise RuntimeError((pedido.get("data") or {}).get("erro") or pedido["descricao"])
# 002 na fila, 003 sendo enviado ao SERPRO: o helper continua consultando resultado = aguardar_recibo("/renave", pedido["data"]["recibo"]) if resultado["status"] != "004": # 900: recusado pelo SERPRO ou pela validação data = resultado["data"] raise RuntimeError(data.get("mensagem") or data.get("erro")) return resultado["data"] # guarde "id-renave": é ele que identifica o cancelamento
def renave(rota: str, body: dict, esperado: str = "004") -> dict: """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.""" pedido = m_api("POST", rota, body) if pedido["status"] != "001": raise RuntimeError((pedido.get("data") or {}).get("erro") or pedido["descricao"]) resultado = aguardar_recibo("/renave", pedido["data"]["recibo"]) if resultado["status"] != esperado: data = resultado.get("data") or {} raise RuntimeError(data.get("mensagem") or data.get("erro") or resultado["descricao"]) return resultado["data"]
# Saída do estoque (venda), vinculada à NF-e de vendasaida = renave("/renave/nota-fiscal/saida", { "chaveNFe": "35261012345678000190550010000012401000012400", "cpfOperadorResponsavel": "12345678901", "dataVenda": "2026-10-25", "valorVenda": 52000.00, "veiculo": { "placa": "ABC1D23", "numeroCrv": "123456789012", "renavam": "01234567890", "codigoSegurancaCrv": "12345678901", }, "comprador": { "nome": "Maria Compradora", "tipoDocumento": "CPF", "numeroDocumento": "11122233344", "endereco": { "logradouro": "Rua das Flores", "numero": "100", "bairro": "Centro", "cep": "01001000", "municipio": "São Paulo", "uf": "SP", }, },})
# Entrada de veículo que já é da empresa (sem compra). A chaveNFe identifica o movimento no# FazNota e não vai ao SERPRO. Aqui CRV (código e tipo) e hodômetro são obrigatórios.proprio = renave("/renave/estoque/entrada-veiculo-proprio", { "chaveNFe": "35261012345678000190550010000012411000012411", "cpfOperadorResponsavel": "12345678901", "dataEntradaEstoque": "2026-10-20", "veiculo": { "placa": "XYZ9A87", "numeroCrv": "210987654321", "renavam": "09876543210", "codigoSegurancaCrv": "10987654321", "tipoCrv": "DIGITAL", "dataHoraMedicaoHodometro": "2026-10-20T09:00:00", "quilometragemHodometro": 18000, },})
# Cancelamentos: por id-renave OU pelo recibo do registro. Os dados do veículo vêm do registro.renave("/renave/estoque/cancelamento-entrada", {"id-renave": proprio["id-renave"]}, esperado="010")renave("/renave/estoque/cancelamento-saida", {"id-renave": saida["id-renave"]}, esperado="010")Listar com paginação
def listar_todos_clientes() -> list: todos = [] page = 1 page_size = 100
while True: resp = m_api("GET", f"/clientes?page={page}&page_size={page_size}") if resp["status"] != "005" or not isinstance(resp.get("data"), list): break todos.extend(resp["data"]) if len(resp["data"]) < page_size: break page += 1 time.sleep(0.2)
return todosTratamento de erros
try: nfce = emitir_nfce(pedido) print("NFCe emitida:", nfce.get("sefaz", {}).get("chave"))except ApiError as e: print(f"API Error: {e}") # Log para suporte com request_id logger.error( "API call failed", extra={ "request_id": e.request_id, "http_status": e.http_status, "payload": e.payload, }, )except TimeoutError as e: print(f"Timeout: {e}")Variação: usando httpx (async)
import httpx
async def m_api_async(method, path, body=None): async with httpx.AsyncClient(timeout=30) as client: res = await client.request( method, f"{BASE}{path}", json=body, headers={"Authorization": f"Token {TOKEN}"}, ) # ... mesma lógica de tratamentoHealth check (sem autenticação)
import requests
def health() -> dict: res = requests.get(f"{BASE}/health", timeout=5) 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.
# requests direto, sem Authorization: o m_api levantaria ApiError no 503, que aqui é a respostadef health_deep() -> tuple[bool, dict]: res = requests.get(f"{BASE}/health/deep", timeout=5) # 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 res.status_code == 200, res.json()
def health_pool() -> dict: return requests.get(f"{BASE}/health/pool", timeout=5).json() # status "UP" ou "STARTING"
saudavel, deep = health_deep()if not saudavel: print("API DOWN", deep)elif deep["pool"]["waiting"] > 0: print(f"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.
def alterar_nota(tipo: str, id_nota: str, dados: dict) -> dict: """tipo: 'nfe' | 'nfce' | 'nfse'""" return m_api("PUT", f"/{tipo}/{id_nota}", dados)
# Uso:alterar_nota("nfe", "12345", { "serie": "1", "cfop": "5102", "cliente": "12345678000199", "itens": [{"produto": "SKU-001", "quantidade": "3", "valor-unitario": "89.90"}],})Listagens
# NF-es paginadasnfes = m_api("GET", "/nfe?page=1&page_size=20")
# NFC-esnfces = m_api("GET", "/nfce?page=1&page_size=50")
# NFS-es com filtro de datanfses = m_api("GET", "/nfse?dataInicial=2026-05-01&page=1&page_size=20")
# Notas de fornecedorfornecedor = m_api("GET", "/nffornecedor?page=1&page_size=20")
# Forma legada (path-based)nfes_legado = m_api("GET", "/nfe/paginacao/1/20")Clientes (CRUD completo)
def cadastrar_pf(dados: dict) -> dict: return m_api("POST", "/clientes", { "tipo": "F", "nome": dados["nome"], "cpf": dados["cpf"], "rg": dados.get("rg"), "consumidor-final": "1", "contato": { "email": dados.get("email"), "telefone": dados.get("telefone"), }, "endereco": dados["endereco"], })
def cadastrar_pj(dados: dict) -> dict: return m_api("POST", "/clientes", { "tipo": "J", "razao-social": dados["razao_social"], "nome-fantasia": dados.get("nome_fantasia"), "cnpj": dados["cnpj"], "inscricao-municipal": dados.get("inscricao_municipal"), "tipo-inscricao-estadual": dados.get("contribuinte", "9"), "inscricao-estadual": dados.get("inscricao_estadual", "ISENTO"), "consumidor-final": dados.get("consumidor_final", "0"), "contato": { "email": dados.get("email"), "telefone": dados.get("telefone"), }, "endereco": dados["endereco"], })
# Consultar por CPF/CNPJcliente = m_api("GET", "/clientes/12345678000199")
# Buscar por nomeencontrados = m_api("GET", "/clientes/busca/exemplo")top = m_api("GET", "/clientes/busca/top_clientes")
# Atualizarm_api("PUT", "/clientes/12345678000199", { "tipo": "J", "razao-social": "Empresa Exemplo (Novo Nome) Ltda",})
# Excluirm_api("DELETE", "/clientes/12345678000199")Produtos (CRUD completo)
def cadastrar_produto(produto: dict) -> dict: return m_api("POST", "/produtos", { "referencia": produto["sku"], "nome": produto["nome"], "valor": str(produto["valor"]), "medida": produto.get("medida", "UN"), "categoria": produto.get("categoria"), "ncm": produto["ncm"], "origem": produto.get("origem", "0"), "cfop-preferencial": produto.get("cfop", "5102"), "tipo-produto": "P", "configuracoes-fiscais": produto.get("config_fiscal", []), })
def cadastrar_servico(servico: dict) -> dict: return m_api("POST", "/produtos", { "referencia": servico["sku"], "nome": servico["nome"], "valor": str(servico["valor"]), "medida": "H", "tipo-produto": "S", "codigo-servico": servico["codigo_servico"], })
# Consultar por referênciaproduto = m_api("GET", "/produtos/SKU-001")
# Buscar por nome (1º resultado)por_nome = m_api("GET", "/produtos/nome/Camiseta")
# Listar paginado com busca (use _todos para não filtrar)todos = m_api("GET", "/produtos/paginacao/1/20/_todos")filtrados = m_api("GET", "/produtos/paginacao/1/20/Camiseta")
# Atualizarm_api("PUT", "/produtos/SKU-001", { "referencia": "SKU-001", "nome": "Camiseta Polo M (Novo)", "valor": "99.90",})
# Excluirm_api("DELETE", "/produtos/SKU-001")