@br-health-kit/tiss

The TISS standard (Padrão para Troca de Informação de Saúde Suplementar) as typed data extracted from the official ANS XSD schemas: 14 versions, from 3.02.00 to 4.03.00.

npm install @br-health-kit/tiss

import { tiss } from '@br-health-kit/tiss'

tiss.values('caraterAtendimento')
// [{ value: '1', label: 'Eletiva' }, { value: '2', label: 'Urgência/Emergência' }]

tiss.isValidValue('caraterAtendimento', '3')   // false
tiss.label('conselhoProfissional', '06')       // 'CRM Conselho Regional de Medicina'
tiss.load('3.05.00')                           // pin your partner's version

The problem it solves

Today every healthtech copies these tables out of PDFs and into their own code: professional council codes, care character, consultation type, rejection reason, participation degree. That is 89 vocabularies and over 2,000 values in version 4.03.00. Copied by hand, they age and drift.

Version matters

Trading partners run different TISS versions. Pin the one you exchange:

tiss.versions()      // '3.02.00' ... '4.03.00'
tiss.load('4.01.00')

The vocabulary grew from 1,273 values in 3.02.00 to 2,090 in 4.03.00.

What is verified and what is not

This distinction is taken seriously:

| | Origin | Reliability | | --- | --- | --- | | Values | enumeration elements in the official XSD | They are the schema. Authoritative. | | Labels | XML comments beside the values | Best-effort, about 88% coverage |

When the schema carries no comment for a value, the label is null, never inferred. A wrong label on a billing field is worse than a missing one.

Label extraction is driven by the values themselves: a comment line only becomes a label if it starts with a real value of that enumeration. That handles the several styles ANS uses without prose paragraphs becoming labels by accident.

Guide structure and validation

The package also carries the structure of every guide and message: 126 types, 36 of them message level (ctm_ for medical, cto_ for dental):

tiss.messages()                       // the standard's guides and messages
tiss.complexType('ctm_consultaGuia')  // elements, types and cardinality

tiss.validate('ctm_consultaGuia', myGuide)
// { valid: false, issues: [{ path: 'dadosBeneficiario.numeroCarteira',
//                            code: 'missing', ... }] }

Validation checks required elements, cardinality, unknown elements and each leaf value against its domain, recursively, reporting a dotted path.

The limit of that validation

It verifies what the schema states. It does not verify business semantics: whether the procedure is covered by the plan, whether the dates are coherent, whether that operator accepts that combination of fields. Those rules live in ANS manuals and in each operator's own rulebook, not in the XSD.

A guide that passes here can still be rejected. That line is drawn on purpose and stated, not blurred.

XML in schema order

const xml = tiss.toXml('ctm_consultaGuia', guide)
const object = tiss.fromXml('ctm_consultaGuia', xml)

Element order comes from the schema, not from your object. That is the point: an XSD sequence is ordered, and an operator's validator rejects a guide with shuffled elements even when every value is correct. It is the most common failure in hand-written TISS integrations, and it disappears by construction here.

Other guarantees:

• zero-padded codes stay strings: 00012345 never becomes 12345
• a key the schema does not declare throws instead of vanishing from the XML; silently dropping billing data would be the worst possible outcome
• when reading, unknown elements are preserved so validate() can report them
• toXml does not require a complete guide, since building one incrementally is normal; validate() is the gate

What this package does not do

Digital signature (ds:Signature) is out of scope. The ANS schema defines it as optional, and signing requires the provider's ICP-Brasil certificate: a data library should not handle private keys. See ROADMAP.md.

Environment

Node 20+ through the default entry. For a client bundle use @br-health-kit/tiss/web. See docs/browser.md.

Provenance

Public ANS schemas (ans.gov.br/padroes/tiss/schemas), redistributed without content modification. Code under MIT.