@br-health-kit/cnes

A typed client for the CNES API, the Cadastro Nacional de Estabelecimentos de Saúde.

npm install @br-health-kit/cnes

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

await cnes.findEstablishment('2273993')
await cnes.listEstablishments({ ufCode: 33, limit: 10 })

cnes.isValidCode('2273993')   // offline, syntactic
cnes.normalizeCode(12345)     // '0012345'

Why this package is a client, not a dataset

Every other package in the kit ships its data offline, versioned and reproducible. CNES cannot: the monthly DATASUS dump is 735 MB compressed and covers roughly 380,000 establishments that change every month. Publishing that on npm would be hostile to install and stale within weeks.

So this package owns the shape of the data rather than the data. It maps the government API's 38 snake_case fields, with their nulls, their mixture of numbers and strings, and their inconsistent naming (numero_cnpj next to numero_cnpj_entidade), onto a single typed model, and handles the timeouts and retries that talking to a government server requires.

The consequence, stated plainly: results from this package are not reproducible. They reflect the API at the time of the call. When a result must be pinned, for an audit or a billing batch, record what you received.

Two details that save debugging

Municipality codes have 6 digits, not 7. DATASUS uses the IBGE code without its check digit: Rio de Janeiro is 330455, not 3304557. That is the form the API both returns and accepts as a filter.

Leading zeros are restored. Spreadsheets and JSON turn 0012345 into 12345; normalizeCode undoes that before the call.

Errors

• code absent from CNES: null, not an exception. It is a normal answer.
• input that is not a CNES code: InvalidCodeError
• API unreachable: CnesRequestError, after retry with backoff
• 404 is not retried; 5xx and network failures are

Tests and the network

The client takes an injected fetch, so your suite does not have to depend on a government server being up:

const client = cnes.client({ fetch: myStub, baseUrl: 'http://localhost:1234' })

Environment

Node 20+, and any browser, through the same entry. There is no /web subpath here because there is no local data to inject: this package is an API client.

Mind CORS, though. The Ministry of Health API is not built to be called from a browser, so in practice you usually want a proxy on your own backend, which is also where the injectable fetch and baseUrl come in handy.

Provenance

Ministry of Health data via apidadosabertos.saude.gov.br. Code under MIT.