Pular para o conteúdo

Exemplos em Python

Setup

Terminal window
pip install requests python-dotenv
.env
MYSE_API_BASE=https://api.mysebr.com.br/nfemyse-v3/rest
MYSE_API_TOKEN=seu_token_aqui

Cliente HTTP centralizado

myse_api.py
import os
import time
from dataclasses import dataclass
from typing import Any, Optional
import requests
from dotenv import load_dotenv
load_dotenv()
BASE = os.environ["MYSE_API_BASE"]
TOKEN = os.environ["MYSE_API_TOKEN"]
@dataclass
class 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 json

Cená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))
# Uso
nfce = 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-xml

Cancelar 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 SEFAZ
nfce_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 += 1

Inutilizar 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
baixar_xml_periodo("NFe", "2026-04-01", "2026-04-30", "nfe-2026-04.zip", "[email protected]")

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, reenviar

Rotinas

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 um
for 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 gravar
conferencia = 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 agora
agora = 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 execucoes
detalhe = 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}/retomar
pausada = 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 cert

CIOT

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,
"ChavePix": "[email protected]",
"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 2
cancelar_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,
"emailVendedor": "[email protected]",
"veiculo": {
"placa": "ABC1D23",
"numeroCrv": "123456789012",
"renavam": "01234567890",
"codigoSegurancaCrv": "12345678901",
"tipoCrv": "DIGITAL",
"dataHoraMedicaoHodometro": "2026-10-20T10:00:00",
"quilometragemHodometro": 52000,
"documentoProprietarioAtual": "98765432100",
"tipoDocumentoProprietarioAtual": "CPF",
},
}
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 venda
saida = 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",
"email": "[email protected]",
"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 todos

Tratamento 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 tratamento

Health 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 resposta
def 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 paginadas
nfes = m_api("GET", "/nfe?page=1&page_size=20")
# NFC-es
nfces = m_api("GET", "/nfce?page=1&page_size=50")
# NFS-es com filtro de data
nfses = m_api("GET", "/nfse?dataInicial=2026-05-01&page=1&page_size=20")
# Notas de fornecedor
fornecedor = 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/CNPJ
cliente = m_api("GET", "/clientes/12345678000199")
# Buscar por nome
encontrados = m_api("GET", "/clientes/busca/exemplo")
top = m_api("GET", "/clientes/busca/top_clientes")
# Atualizar
m_api("PUT", "/clientes/12345678000199", {
"tipo": "J",
"razao-social": "Empresa Exemplo (Novo Nome) Ltda",
})
# Excluir
m_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ência
produto = 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")
# Atualizar
m_api("PUT", "/produtos/SKU-001", {
"referencia": "SKU-001",
"nome": "Camiseta Polo M (Novo)",
"valor": "99.90",
})
# Excluir
m_api("DELETE", "/produtos/SKU-001")