Começando

Introdução

A API de interoperabilidade da Nilo expõe recursos FHIR R4 sobre HTTP. Cada cliente escreve e lê no seu próprio FHIR store, isolado dos demais.

Autenticação

Todas as requisições exigem o header x-api-key:

$curl --request GET \
>  --url https://landing-zone-api.nilo.services/fhir/resources/Patient \
>  --header 'Content-Type: application/json' \
>  --header 'x-api-key: SUA_API_KEY'

A API key é vinculada a um care provider. É esse vínculo que decide em qual FHIR store a requisição vai cair — não existe parâmetro para escolher o store, e uma key nunca enxerga os dados de outro care provider.

Uma API key de homologação não funciona em produção, e vice-versa. Recursos que carreguem identificadores apontando para um ambiente diferente do ambiente da requisição são rejeitados na validação.

Ambientes

AmbienteHost
Produçãohttps://landing-zone-api.nilo.services
Homologaçãohttps://landing-zone-api.stg.nilo.services

Métodos suportados

O endpoint de recursos aceita apenas GET e POST. Não há PUT, PATCH nem DELETE.

OperaçãoRequisição
Buscar por parâmetrosGET /fhir/resources/{tipo}
Buscar por IDGET /fhir/resources/{tipo}/{id}
Ler uma versão anteriorGET /fhir/resources/{tipo}/{id}/_history/{versionId}
Criar ou atualizarPOST /fhir/resources/{tipo}

Atualização é feita pelo mesmo POST da criação — veja Escritas.

Paginação

As buscas devolvem um Bundle do tipo searchset. A navegação é por cursor, não por número de página:

  • _count — quantidade de registros por página.
  • _page_token — cursor da próxima página.

Quando existe uma próxima página, ela vem pronta em link, com relation: "next". Siga essa URL em vez de montar o cursor à mão.

1{
2  "resourceType": "Bundle",
3  "type": "searchset",
4  "link": [
5    {
6      "relation": "next",
7      "url": "https://landing-zone-api.nilo.services/fhir/resources/Patient?_page_token=Cjj3YopYuf..."
8    }
9  ],
10  "entry": [
11    {
12      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4",
13      "resource": { "resourceType": "Patient" },
14      "search": { "mode": "match" }
15    }
16  ]
17}

Erros

Erros de validação retornam 400 com um OperationOutcome, em que cada issue aponta o campo problemático em expression:

1{
2  "resourceType": "OperationOutcome",
3  "issue": [
4    {
5      "severity": "error",
6      "code": "structure",
7      "details": { "text": "Parâmetro enviado inválido" },
8      "expression": ["Patient.birthDate"]
9    }
10  ]
11}

Um 429 indica que o limite de escrita daquele tipo de recurso foi atingido. Ele é configurado por recurso e por janela de tempo — aguarde e repita a requisição.