> For the complete documentation index, see [llms.txt](https://docs.voa.health/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voa.health/integracao/fhir.md).

# FHIR

A Voa oferece uma API FHIR R5 para integração com outros sistemas de saúde.

```
https://api.voa.health/api/v2/org/{org_id}/fhir/
```

Cada recurso tem a própria rota com o nome FHIR (`Patient/`, `Encounter/`, `Appointment/`…): `{Entidade}/` para buscar e `{Entidade}/{id}/` para ler. As ações vêm em kebab, sem `$` (`Patient/lookup/`, `Appointment/{id}/hold/`).

### Autenticação

Envie a chave de API da organização em `Authorization: Bearer sk_org_...` (chave de sistema) ou `Bearer sk_user_...` (chave de membro); veja [Chaves de API](https://docs.voa.health/api-reference/chaves-de-api.md). Cada chave vale para uma organização: o `{org_id}` da URL tem que ser o dela.

Recusas voltam com `error_code` e `detail`:

```json
{"error_code": "organization_mismatch", "detail": "Este acesso foi liberado para outra organização e não vale nesta."}
```

| `error_code`               | HTTP  | Significado                                                                              |
| -------------------------- | ----- | ---------------------------------------------------------------------------------------- |
| `not_authenticated`        | `401` | Nenhuma chave enviada                                                                    |
| `invalid_credential`       | `401` | Chave inválida ou revogada, ou organização inativa                                       |
| `credential_not_supported` | `401` | Credencial que a API clínica não aceita, como a chave de produto (`sk_voa_`, `sk_tiss_`) |
| `api_key_member_inactive`  | `401` | Chave de membro (`sk_user_`) cujo dono não está mais ativo na organização                |
| `organization_mismatch`    | `403` | O `{org_id}` da URL não é a organização da chave                                         |
| `not_a_member`             | `404` | A chave não tem vínculo ativo na organização da URL                                      |
| `scope_denied`             | `403` | A chave não permite essa ação                                                            |

### Resumo do paciente

O resumo clínico do paciente pode ser exportado como documento FHIR (`Bundle` com `type=document`), pronto para ser enviado a outro sistema: `GET Patient/{patient_id}/ips/?document=true`.

### Terminologia

A terminologia fica fora da API clínica, em `https://terminologia.voa.health/api/v2/terminology/fhir`, com uma chave de produto `sk_voa_` de escopo `terminology:read`. Detalhes em [API FHIR da terminologia](https://docs.voa.health/integracao/terminologia/api.md).

| Operação                                               | Uso                              |
| ------------------------------------------------------ | -------------------------------- |
| `CodeSystem/$lookup`                                   | Consultar um código              |
| `CodeSystem/$validate-code`, `ValueSet/$validate-code` | Validar um código                |
| `ValueSet/$expand`                                     | Listar os códigos de um conjunto |
| `ConceptMap/$translate`                                | Traduzir entre terminologias     |

Inclui as terminologias brasileiras, como os códigos oficiais da RNDS, CID-10, CIAP-2, LOINC e TUSS.

Cliente Python e MCP local: [terminologia](https://docs.voa.health/integracao/terminologia.md).

{% hint style="info" %}
O acesso à API FHIR é liberado sob demanda. Solicite em <integration@voahealth.com>.
{% endhint %}
