Navegar na documentação

Entender o resultado

Conferência de notas

Confira os grupos CBS/IBS/IS da nota na data de emissão e receba o grupo esperado para o ERP.

O que é conferido

  • Base de cálculo, alíquotas e valores de CBS, IBS estadual, IBS municipal e IS por item; valores e base nos totais.
  • Compatibilidade CST × cClassTrib e validade da classificação para o tipo de documento e a data nas tabelas oficiais. Sem classificação, o problema é “cClassTrib ausente”.
  • Indicador de operação da NFS-e nacional quando informado, junto com NBS e cClassTrib.
  • Estrutura do recorte XML declarado pelo validador oficial, com suas mensagens. Em JSON, informe grupoDeclaradoXml para esta etapa.

A tolerância monetária é de R$ 0,01 por campo/item e por campo do total, sem multiplicação pelo número de itens. Alíquotas admitem 0,0001 ponto percentual; códigos exigem igualdade. O cálculo reutiliza a montagem de bases do simulador, com os valores atuais da nota, sem projeção ou cenário.

Enviar XMLs

Na plataforma, abra Notas → Conferir notas. Pela API, use POST /v1/conferencias com chave, até 5.000 arquivos de 2 MB em arquivos, ou JSON canônico. Cada documento enviado, inclusive rejeitado, consome a mesma cota mensal das simulações.

curl -X POST "https://app.marco33.com.br/v1/conferencias" \
  -H "Authorization: Bearer m33_SUA_CHAVE" \
  -F "[email protected]"

Formato JSON canônico

Os valores declarados são números, códigos são textos para preservar zeros. cClassTribNota tem prioridade sobre cClassTrib. O destino informado define o município do cálculo; na falta, usa o emitente. As bases são recalculadas pelos componentes da operação.

POST /v1/conferencias · application/json
{
  "documentos": [
    {
      "id": "NOTA-EXEMPLO",
      "tipo": "NFe",
      "dataEmissao": "2026-11-10",
      "emitente": {
        "uf": "RS",
        "municipio": 4314902
      },
      "itens": [
        {
          "numero": 1,
          "ncm": "84713012",
          "valores": {
            "vProd": 1000
          },
          "tributosAtuais": {},
          "cClassTribNota": "000001",
          "cstNota": "000",
          "ibsCbsDeclarado": {
            "baseCalculo": 1000,
            "aliquotaCbs": 0.9,
            "aliquotaIbsEstadual": 0.1,
            "aliquotaIbsMunicipal": 0,
            "cbs": 9,
            "ibsEstadual": 1,
            "ibsMunicipal": 0,
            "ibs": 1
          }
        }
      ],
      "totaisDeclarados": {
        "baseCalculo": 1000,
        "cbs": 9,
        "ibsEstadual": 1,
        "ibsMunicipal": 0,
        "ibs": 1
      }
    }
  ]
}

Exemplo ilustrativo; os valores esperados dependem da versão e da base oficial em uso. Para IS, o item aceita isDeclarado: cst, cClassTrib, baseCalculo, aliquota, aliquotaEspecifica e valor. Na NFS-e, use nbs e, quando houver, cIndOp; codigo é o cTribNac.

Resposta

201 Created · exemplo de divergência
{
  "id": "id-da-conferencia",
  "criadaEm": "2026-11-10T15:00:00Z",
  "origem": "api",
  "resumo": {
    "documentos": 1,
    "ok": 0,
    "divergentes": 1,
    "erros": 0
  },
  "documentos": [
    {
      "id": "NOTA-EXEMPLO",
      "tipo": "NFe",
      "status": "DIVERGENTE",
      "problemas": [
        {
          "item": 1,
          "campo": "vCBS",
          "declarado": 8,
          "esperado": 9,
          "mensagem": "Valor declarado difere do cálculo oficial ou está ausente"
        }
      ],
      "grupoEsperado": "<infNFe xmlns=\"http://www.portalfiscal.inf.br/nfe\">…</infNFe>",
      "avisos": []
    }
  ],
  "rejeitados": []
}

OK: sem divergências nos campos conferidos. DIVERGENTE: valor, código ou estrutura declarada diverge. ERRO: cálculo ou consulta não pôde ser concluído. Campo ausente aparece como null. Problemas de total usam total. no campo e não têm item. XMLs ilegíveis ficam em rejeitados, fora do resumo de notas processadas.

O grupoEsperado é o XML oficial completo de grupos por item e totais, dentro de infNFe. Só é devolvido quando todos os itens podem ser calculados. Ele pode existir mesmo com divergências nos valores declarados. Guarde a correspondência de nItem ao aplicar ao ERP.

Webhook por modo

Em Integrações, escolha simulacao (padrão de links existentes), conferencia ou ambos. O parâmetro ?modo= sobrescreve a escolha apenas naquela requisição. Envie após autorização.

No modo conferência, o corpo da resposta é a conferência completa. No modo ambos, a resposta de simulação contém uma propriedade conferencia com esse resultado. Ambos executa duas operações e consome duas unidades por nota. As operações são persistidas separadamente: se a segunda falhar, a primeira pode já estar salva.

Endpoints oficiais usados

  • /calculadora/regime-geral recalcula e retorna o ROC completo; /calculadora/xml/generate?tipo=nfe|nfce gera o grupo diretamente desse ROC.
  • /calculadora/dados-abertos/situacoes-tributarias/cbs-ibs e /calculadora/dados-abertos/classificacoes-tributarias/cbs-ibs/… conferem códigos por documento e data.
  • /calculadora/nfse/indicador-operacao/validate confere o indicador informado.
  • /calculadora/xml/validate?tipo=…&subtipo=grupo verifica o recorte fiscal. Responde true ou erro com mensagem oficial.

Limitações e guarda

Disponível para regime regular, NF-e/NFC-e e NFS-e nacional. A calculadora oficial não oferece geração XML para NFS-e; nesse caso não há grupoEsperado. Alíquotas futuras e IS dependem da disponibilidade oficial: sem elas a nota retorna ERRO, sem assumir alíquotas de cenário.

Operações especiais que exigem grupos adicionais (monofasia, diferimento, compras governamentais, reduções de base e ressarcimentos) podem não ter todos os parâmetros no modelo canônico. Revise as mensagens e o leiaute. Não há validação de assinatura digital, autorização ou enquadramento material do produto na classificação: a classificação vem da nota. O destino usa o local declarado; os endpoints de locais NFS-e foram consultados no código oficial, mas não substituem a identificação do local pelo ERP.

O XML original é lido em memória e nunca guardado. DTD e entidades são recusados. Resultado e grupo esperado seguem o prazo da empresa, aparecem na exportação JSON e são eliminados no encerramento da conta. Uma nota já autorizada não é alterada automaticamente.

PróximoAPI REST