Validar uma DPS antes de transmitir

POST/v1/validate

Recebe o XML da DPS (ou o objeto JSON) e devolve o que seria rejeitado, por severidade, com o código oficial, o caminho no XML, a correção sugerida e a fonte.

TypeScript

const r = await nfse.validate(xmlDaDps);
for (const issue of r.issues) {
  console.log(issue.severity, issue.code, issue.message, "→", issue.fix);
}
// lote de até 50 notas numa chamada só:
const lote = await nfse.validateMany([xml1, xml2, { DPS: objeto }]);

Python

r = requests.post(
    "https://api.kalvi.com.br/v1/validate",
    headers={
        "Authorization": f"Bearer {os.environ['KALVI_API_KEY']}",
        "Content-Type": "application/xml",
    },
    data=xml_da_dps.encode("utf-8"),
    timeout=20,
)
for i in r.json()["issues"]:
    print(i["severity"], i["code"], i["message"], "->", i["fix"])

bash

curl -s -X POST https://api.kalvi.com.br/v1/validate \
  -H "Authorization: Bearer $KALVI_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @nota.xml

Resposta

Capturada da API, recortada para caber na tela.

JSON

{
  "api_version": "1",
  "tables_version": "2026-11-03",
  "summary": { "blocking": 1, "likely_rejection": 0, "warning": 1 },
  "issues": [
    {
      "severity": "blocking",
      "code": "E0958",
      "official": true,
      "path": "/DPS/infDPS/IBSCBS/valores/trib/gIBSCBS/cClassTrib",
      "message": "cClassTrib para IBS/CBS incorreto para operação de prestação de serviços.",
      "fix": "O cClassTrib 200999 não consta da tabela oficial (IT 2025.002, publicação 2026-10-01). Use /v1/classify para o candidato do seu item."
    }
  ],
  "suggestion": {
    "cst": "200",
    "cClassTrib": "200029",
    "short_name": "Fornecimento dos serviços de saúde humana (Anexo III)",
    "confidence": "high"
  }
}

O que saber antes de usar

Três severidades: blocking (a nota não passa), likely_rejection (deve ser rejeitada) e warning.
official: true marca o código do ambiente nacional; false é conferência nossa, feita antes.
Lote: mande {"notes": [...]} com até 50 itens; cada um volta com o seu próprio resultado ou erro.
Corpo de até 2 MB. XML com DTD é recusado (DTD_NOT_ALLOWED); XML quebrado volta com linha e coluna.
Nada da nota é guardado: o processamento é em memória e a resposta só traz o que você precisa para corrigir.

Lista de erros · Voltar à referência

Apoio técnico, não consultoria tributária. A responsabilidade pela nota é do emissor.