Navegar na documentação

Enviar notas

API REST

Tudo o que a plataforma faz com as notas, a API também faz. JSON na entrada e na saída, autenticação por chave.

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:

cabeçalho
Authorization: Bearer m33_SUA_CHAVE
# ou
X-API-Key: m33_SUA_CHAVE

URL base: https://app.marco33.com.br. A referência completa está em OpenAPI (Swagger).

Endpoints

Método e caminhoPara quê
POST /v1/simulacoesSimula 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/conferenciasConfere CBS/IBS/IS em XMLs ou JSON e guarda o resultado. Formato e exemplos.
GET /v1/cenariosLista os cenários da empresa (o padrão vem primeiro).
POST /v1/diagnosticos/cadastroDiagnó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 · JSON canônico
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-Limit e X-RateLimit-Remaining vêm em toda resposta.
  • Por mês: cada documento enviado conta, inclusive os rejeitados. O uso aparece na plataforma.
  • Ao estourar, a resposta é 429 com Retry-After em segundos.

Erros

Todo erro vem em JSON com message e, quando há várias causas, erros:

400 Bad Request
{
  "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).
PróximoCenários e alíquotas