API de validação TISS

Valide arquivos XML no padrão TISS programaticamente, com o mesmo motor usado no site. Tier grátis: 200 validações por mês, até 10 por minuto.

Quickstart

Envie o XML em application/xml:

curl -X POST https://tisscheck.com.br/api/v1/validate \
  -H "Authorization: Bearer tk_live_SUACHAVE" \
  -H "Content-Type: application/xml" \
  --data-binary @lote.xml

Exemplos por linguagem

Node.js

const fs = require("fs");
const xml = fs.readFileSync("lote.xml");

const res = await fetch("https://tisscheck.com.br/api/v1/validate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tk_live_SUACHAVE",
    "Content-Type": "application/xml",
  },
  body: xml,
});
const result = await res.json();
console.log(result.status, result.issues);

Python

import requests

with open("lote.xml", "rb") as f:
    xml = f.read()

res = requests.post(
    "https://tisscheck.com.br/api/v1/validate",
    headers={
        "Authorization": "Bearer tk_live_SUACHAVE",
        "Content-Type": "application/xml",
    },
    data=xml,
)
print(res.json())

PHP

$xml = file_get_contents("lote.xml");
$ch = curl_init("https://tisscheck.com.br/api/v1/validate");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $xml,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer tk_live_SUACHAVE",
        "Content-Type: application/xml",
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
echo $result["status"];

Endpoints

• POST /api/v1/validate: valida um XML. Requer chave. Query opcional ?sanitize=true inclui o XML com hash corrigido em base64.
• GET /api/v1/versions: versões TISS suportadas. Público, sem chave.
• GET /api/v1/glosas/{code}: dados públicos de um código da Tabela 38. Público, sem chave.
• GET /api/v1/usage: consumo do mês da chave autenticada.

Códigos de erro HTTP

Um XML com inconsistências é uma resposta válida, não um erro de requisição: retorna 200 com status: "invalid" e a lista de problemas. Os códigos HTTP abaixo indicam problema na requisição em si:

• 400 corpo vazio ou malformado
• 401 chave ausente, inválida ou revogada
• 413 arquivo maior que 10 MB
• 429 limite de 10 chamadas/minuto ou quota mensal excedida
• 503 serviço de validação temporariamente indisponível

Limites e política de versão

Tier dev (grátis): 200 validações por mês, até 10 por minuto por chave, arquivos de até 10 MB, timeout de 60 segundos por requisição. Esta é a v1: mudanças incompatíveis, se necessárias no futuro, virão como v2, mantendo v1 estável.

Segurança

A API é feita para uso servidor-a-servidor: não envie sua chave em requisições feitas direto do navegador (ela ficaria exposta no código-fonte da página). Não há CORS habilitado propositalmente. Guarde sua chave como segredo de aplicação; se ela vazar, revogue e crie uma nova em Chaves de API.

Nunca guardamos o conteúdo dos arquivos enviados pela API: o XML é processado em memória e descartado após a validação, igual ao fluxo do site.