Navegar na documentação
Enviar notas
API REST
Autenticação
Crie uma chave em Integrações → Chaves de API. Ela começa com m33_ e aparece uma única vez. Envie em todas as chamadas:
Authorization: Bearer m33_SUA_CHAVE
# ou
X-API-Key: m33_SUA_CHAVEURL base: https://app.marco33.com.br. A referência completa está em OpenAPI (Swagger).
Endpoints
| Método e caminho | Para quê |
|---|---|
POST /v1/simulacoes | Simula XMLs (multipart) ou documentos em JSON e guarda o resultado. |
GET /v1/simulacoes/{id} | Busca uma simulação feita por API, webhook ou plataforma. |
POST /v1/conferencias | Confere CBS/IBS/IS em XMLs ou JSON e guarda o resultado. Formato e exemplos. |
GET /v1/cenarios | Lista os cenários da empresa (o padrão vem primeiro). |
POST /v1/diagnosticos/cadastro | Diagnóstico do cadastro de produtos e serviços. |
POST /w/{token} | Webhook de entrada (o link é a credencial). Ver Webhook. |
Simular XMLs
Envie até 5.000 XMLs no campo arquivos. Para escolher o cenário, inclua cenarioId(de GET /v1/cenarios) ou um cenario avulso em JSON. Sem nenhum dos dois, vale o padrão da empresa.
curl -X POST "https://app.marco33.com.br/v1/simulacoes" \
-H "Authorization: Bearer m33_SUA_CHAVE" \
-F "[email protected]" \
-F "[email protected]"Simular documentos em JSON
Para quem gera os dados direto do ERP, sem XML. O formato canônico tem o emitente, o destino (para o IBS) e os itens com os tributos de hoje. Se você já sabe o cClassTrib do item, informe: ele tem prioridade sobre o cenário.
curl -X POST "https://app.marco33.com.br/v1/simulacoes" \
-H "Authorization: Bearer m33_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"documentos": [{
"id": "pedido-123",
"tipo": "NFe",
"dataEmissao": "2026-03-10",
"emitente": { "uf": "SP", "municipio": 3550308 },
"destino": { "uf": "RJ", "municipio": 3304557 },
"itens": [{
"numero": 1, "codigo": "SKU-1", "ncm": "84713012",
"valores": { "vProd": 1000 },
"tributosAtuais": { "icms": 120, "pis": 16.5, "cofins": 76 }
}]
}]
}'Resposta
201 Created com a simulação: id, totais (incluindo porAno),documentos (com itens e, por item, porAno), rejeitados e aspremissas usadas. Cada documento traz efeito (soma, subtrai ouignora), e eventos de cancelamento enviados no lote voltam em eventos ecancelamentos. Veja Resultados e premissas.
Limites e cota
- Por minuto: depende do plano. Os cabeçalhos
X-RateLimit-LimiteX-RateLimit-Remainingvêm em toda resposta. - Por mês: cada documento enviado conta, inclusive os rejeitados. O uso aparece na plataforma.
- Ao estourar, a resposta é
429comRetry-Afterem segundos.
Erros
Todo erro vem em JSON com message e, quando há várias causas, erros:
{
"statusCode": 400,
"message": "cenário inválido",
"erros": ["cenario.aliquotas.2027: obrigatório a partir de 2027 (a calculadora oficial só tem alíquotas de referência para 2026)"]
}401: chave ausente, inválida ou revogada. 404: recurso de outra empresa ou inexistente.503: motor de cálculo indisponível (repita em instantes).