> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.nilo.services/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.nilo.services/_mcp/server.

# Introdução

> Autenticação, ambientes e o formato das requisições da API de interoperabilidade da Nilo.

A API de interoperabilidade da Nilo expõe recursos [FHIR R4](https://hl7.org/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`:

```bash
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.

> **Warning**
>
> 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

| Ambiente    | Host                                         |
| ----------- | -------------------------------------------- |
| Produção    | `https://landing-zone-api.nilo.services`     |
| Homologação | `https://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ção              | Requisição                        |
| --------------------- | --------------------------------- |
| Buscar por parâmetros | `GET /fhir/resources/{tipo}`      |
| Buscar por ID         | `GET /fhir/resources/{tipo}/{id}` |
| Criar ou atualizar    | `POST /fhir/resources/{tipo}`     |

Atualização é feita pelo mesmo `POST` da criação — veja [Escritas](/guia/comecando/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.

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "next",
      "url": "https://landing-zone-api.nilo.services/fhir/resources/Patient?_page_token=Cjj3YopYuf..."
    }
  ],
  "entry": [
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4",
      "resource": { "resourceType": "Patient" },
      "search": { "mode": "match" }
    }
  ]
}
```

## Erros

Erros de validação retornam `400` com um [`OperationOutcome`](https://hl7.org/fhir/R4/operationoutcome.html),
em que cada `issue` aponta o campo problemático em `expression`:

```json
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "structure",
      "details": { "text": "Parâmetro enviado inválido" },
      "expression": ["Patient.birthDate"]
    }
  ]
}
```

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.