# Como integrar sistemas de clínica com um backend FHIR

> Tutorial: conectar um EMR de clínica aos registos FHIR R4 de pacientes — diretório de médicos, correspondência por número de registo, uma consulta como uma transação com o médico como autor, relatórios de laboratório, dados de outros fornecedores e webhooks.

Source: https://developers.anpheros.com/pt/guides/integrate-clinic-systems-fhir

**Este tutorial conecta o software de uma clínica (um EMR, um sistema de gestão de consultório ou uma ferramenta de marcação) aos registos HL7 FHIR R4 de pacientes no Anpheros: a clínica e os seus médicos são registados no diretório, os pacientes são correspondidos pelo número de registo da clínica, uma consulta é escrita como uma transação com o médico nomeado como autor, e a clínica fica a saber sobre dados que outros fornecedores adicionam.** Cada pedido é `curl` contra a sandbox gratuita, e as respostas são as da plataforma.

A integração é executada no servidor da clínica, com uma chave API de projeto para os pacientes que a clínica regista e, para pessoas que já têm um registo Anpheros, uma concessão OAuth que elas aprovam.

## O que mapeia para o quê

| No sistema clínico | Em FHIR R4 |
|---|---|
| a clínica, os seus departamentos | `Organization` |
| um médico ou enfermeiro | `Practitioner` |
| essa pessoa a trabalhar nessa clínica, com uma especialidade | `PractitionerRole` |
| o ficheiro do paciente e o seu número | `Patient` com um `identifier` no sistema da clínica |
| uma visita | `Encounter` |
| sinais vitais, resultados medidos durante a visita | `Observation` ligados ao `Encounter` |
| um diagnóstico | `Condition` (ICD-10), com `verificationStatus` provisório ou confirmado |
| uma prescrição, tratamento atual | `MedicationStatement` (ATC) |
| uma carta, um resumo de alta, um scan | `DocumentReference` com o ficheiro |
| resultados de laboratório | o [conector de laboratório](https://developers.anpheros.com/pt/guides/lab-connector), para `Observation` |

## Passo 1: registar a clínica e os seus médicos

Os recursos do diretório não têm pacientes. Outros projetos no mesmo ambiente podem lê-los, permitindo que outros prestadores de cuidados de um paciente vejam quem escreveu o quê, mas apenas o seu projeto pode alterá-los.

```bash
export BASE=https://platform.anpheros.com/fhir/R4
export KEY=sk_test_…
H=(-H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json")

curl -X POST $BASE/Organization "${H[@]}" -d '{"resourceType": "Organization", "active": true, "name": "Clinica Cardio Nord",
  "identifier": [{"system": "https://clinic.example/org", "value": "CCN"}]}'

curl -X POST $BASE/Practitioner "${H[@]}" -d '{"resourceType": "Practitioner", "active": true,
  "name": [{"family": "Popescu", "given": ["Ana"], "prefix": ["Dr."]}]}'

curl -X POST $BASE/PractitionerRole "${H[@]}" -d '{"resourceType": "PractitionerRole", "active": true,
  "practitioner": {"reference": "Practitioner/'$PRACTITIONER'"},
  "organization": {"reference": "Organization/'$ORG'"},
  "code": [{"text": "Cardiologist"}]}'
```

Guarde os IDs retornados junto dos registos do seu pessoal. Quando alguém sair, defina o seu `PractitionerRole` para `"active": false`; as suas escritas anteriores mantêm o seu nome e já não poderão agir através do seu sistema.

## Passo 2: Correspondência de pacientes

Para os pacientes que a clínica regista, crie o `Patient` com o número de registo da clínica como identificador:

```bash
curl -X POST $BASE/Patient "${H[@]}" -d '{"resourceType": "Patient",
  "identifier": [{"system": "https://clinic.example/mrn", "value": "MRN-20981"}],
  "name": [{"family": "Dinu", "given": ["Andrei"]}], "gender": "male", "birthDate": "1968-11-05"}'
```

A partir daí, encontre o paciente por esse número, nunca por nome e data de nascimento:

```bash
curl "$BASE/Patient?identifier=https://clinic.example/mrn|MRN-20981" -H "Authorization: Bearer $KEY"
```

**Quando a pessoa já tem um registo Anpheros**, a partir da sua própria aplicação ou de outro fornecedor, a clínica não cria um segundo. Pede à pessoa acesso com OAuth, a partir de um tablet na receção ou de um link enviado antes da consulta, utilizando uma aplicação **confidencial** (o servidor da clínica guarda o segredo). A pessoa escolhe o seu registo e por quanto tempo a clínica pode aceder a ele. Os passos estão em [Como implementar o consentimento do paciente com SMART on FHIR](https://developers.anpheros.com/pt/guides/smart-on-fhir-backend); o campo `patient` do token é o id a armazenar com o seu ficheiro.

## Passo 3: escrever uma visita como uma transação

Uma visita produz vários recursos que pertencem em conjunto. Envie-os numa `transaction` para que sejam armazenados todos de uma vez ou nenhum deles, e diga quem está a trabalhar: `X-Anpheros-Acting-As` nomeia o papel do médico. Torna-se o autor em Provenance, é escrito no registo de acesso e é mostrado ao paciente pelo nome.

```bash
curl -X POST $BASE "${H[@]}" \
  -H "X-Anpheros-Acting-As: PractitionerRole/$ROLE" \
  -H "X-Anpheros-Author-Type: practitioner" \
  -H "X-Anpheros-Source-System: ccn-emr" -d '{
  "resourceType": "Bundle", "type": "transaction",
  "entry": [
    {"fullUrl": "urn:uuid:aa000000-0000-4000-8000-000000000001",
     "resource": {"resourceType": "Encounter", "status": "finished",
       "class": {"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB", "display": "ambulatory"},
       "subject": {"reference": "Patient/'$PID'"},
       "serviceProvider": {"reference": "Organization/'$ORG'"},
       "participant": [{"individual": {"reference": "PractitionerRole/'$ROLE'"}}],
       "period": {"start": "2026-10-09T10:00:00Z", "end": "2026-10-09T10:30:00Z"}},
     "request": {"method": "POST", "url": "Encounter"}},
    {"resource": {"resourceType": "Observation", "status": "final",
       "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs"}]}],
       "code": {"coding": [{"system": "http://loinc.org", "code": "8867-4", "display": "Heart rate"}]},
       "subject": {"reference": "Patient/'$PID'"},
       "encounter": {"reference": "urn:uuid:aa000000-0000-4000-8000-000000000001"},
       "effectiveDateTime": "2026-10-09T10:10:00Z",
       "valueQuantity": {"value": 92, "unit": "/min", "system": "http://unitsofmeasure.org", "code": "/min"}},
     "request": {"method": "POST", "url": "Observation"}},
    {"resource": {"resourceType": "Condition",
       "subject": {"reference": "Patient/'$PID'"},
       "encounter": {"reference": "urn:uuid:aa000000-0000-4000-8000-000000000001"},
       "clinicalStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active"}]},
       "verificationStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status", "code": "provisional"}]},
       "code": {"coding": [{"system": "http://hl7.org/fhir/sid/icd-10", "code": "I48.0", "display": "Paroxysmal atrial fibrillation"}]}},
     "request": {"method": "POST", "url": "Condition"}}
  ]}'
```

O `transaction-response` tem `201 Created` para o Encounter, o Observation e o Condition. O Observation e o Condition apontam agora para o `Encounter/0ca25459-…` real. O Provenance de cada um nomeia o papel do médico, a clínica e o sistema de origem:

```json
"agent": [{"who": {"reference": "PractitionerRole/e6d8c227-…",
                   "identifier": {"system": "https://anpheros.com/fhir/CodeSystem/author-type", "value": "practitioner"}},
           "onBehalfOf": {"reference": "Organization/c3a56a4b-…", "display": "Clinica Cardio Nord"}}],
"entity": [{"role": "source", "what": {"identifier": {"system": "ccn-emr"}}}]
```

O diagnóstico é `provisional` até ser confirmado. Atualize-o para `confirmed` mais tarde, e o histórico mantém ambos. O que cada campo significa é explicado em [Medical data provenance explained](https://developers.anpheros.com/pt/guides/medical-data-provenance).

## Passo 4: Resultados de laboratório e documentos

Os resultados do laboratório da clínica, ou relatórios que o paciente traz, passam pelo conector de laboratório num único pedido por relatório:

```bash
curl -X POST "https://platform.anpheros.com/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: x-application/hl7-v2+er7" -H "X-Anpheros-Source-System: ccn-lab" --data-binary @oru.hl7
```

Cartas e resumos de alta são documentos: crie um `DocumentReference` através de `/v1/patients/{id}/documents` e carregue o PDF. O ficheiro original nunca é modificado, e os valores extraídos dele apontam de volta para ele. Veja [Como importar resultados de laboratório para um registo FHIR](https://developers.anpheros.com/pt/guides/import-lab-results-fhir) e [API de dados médicos](https://developers.anpheros.com/pt/guides/medical-data-api).

## Passo 5: Leia o que outros fornecedores escreveram e mantenha-se na sua área

Com o consentimento do paciente, a clínica lê o registo completo dentro dos seus âmbitos, incluindo o que outras clínicas, laboratórios e o paciente adicionaram. Só pode alterar o que escreveu. Uma atualização ou eliminação de um recurso de outra organização responde `403`, e o original permanece como estava. Para corrigir algo que outro fornecedor escreveu, escreva o seu próprio recurso (por exemplo, um novo `Condition` com a sua avaliação) e deixe que o registo mostre ambos, cada um com o seu autor.

Antes de uma consulta, `GET $BASE/Patient/$PID/$summary` fornece o Resumo Internacional do Paciente do registo: problemas, medicamentos, alergias e sinais vitais recentes, de todas as fontes.

## Passo 6: ser notificado sobre novos dados

Registe um webhook uma vez para o projeto da clínica:

```bash
curl -X POST https://platform.anpheros.com/v1/webhooks -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"url": "https://ccn.example/anpheros/hook", "events": ["resource.created", "resource.updated", "consent.revoked"]}'
```

Quando outro projeto escreve num registo ao qual a sua clínica tem acesso, o evento informa disso com `data.external: true` e a origem, para que o seu EMR possa mostrar "novos resultados de outro laboratório" sem necessidade de polling. Um evento `consent.revoked` significa que a pessoa retirou o acesso da clínica: pare de sincronizar esse registo. Assinaturas, retentativas e payloads são abordados em [Webhooks](https://developers.anpheros.com/pt/guides/webhooks).

## O que o paciente vê

O paciente vê a consulta, a frequência cardíaca e o diagnóstico provisório no seu registo, cada um marcado como adicionado pela Dra. Ana Popescu na Clinica Cardio Nord. Nas suas ligações, a aplicação da clínica lista cada acesso, pelo nome quando um profissional de saúde estava a atuar. Essa transparência é o que faz com que os pacientes estejam dispostos a conceder acesso à próxima clínica.

## Checklist para ir para produção

- [ ] Organização, Praticantes e Cargos de Praticante registados; colaboradores inativos definidos como inativos
- [ ] Doentes correspondidos pelo identificador da clínica, nunca pelo nome
- [ ] Registos existentes acedidos através de consentimento OAuth, não duplicados
- [ ] Cada pedido de pessoal clínico transporta `X-Anpheros-Acting-As`
- [ ] Consultas escritas como transações; diagnósticos com o estado de verificação correto
- [ ] Sistema de origem definido em cada escrita; relatórios de laboratório através do conector
- [ ] Ponto final do webhook a verificar assinaturas; `consent.revoked` tratado
- [ ] Projeto de produção com um DPA assinado (chaves `sk_live_…`); ver [Preços](https://developers.anpheros.com/pt/guides/pricing)

## Perguntas Frequentes

### O Anpheros tem um conector pronto a usar para o meu EMR?
Não. Não existem conectores prontos a usar para EMRs ou sistemas de laboratório específicos; a integração é construída contra as APIs FHIR R4 e REST, geralmente como um pequeno serviço adjacente ao EMR. Mensagens de laboratório HL7 v2 são aceites como estão.

### Um médico pode trabalhar para duas clínicas?
Sim. Um `Practitioner` pode ter um `PractitionerRole` em cada organização. A função nomeada em `X-Anpheros-Acting-As` decide para qual clínica cada escrita é registada.

### O que acontece quando o paciente revoga o acesso da clínica?
As chamadas da clínica para esse registo respondem com `401`, e um webhook `consent.revoked` é enviado. O que a clínica escreveu permanece no registo do paciente com a sua proveniência; a clínica simplesmente já não pode lê-lo ou alterá-lo.

## Relacionados

- [Integrações de saúde](https://developers.anpheros.com/pt/guides/healthcare-integrations): todos os padrões de integração num relance
- [Proveniência de dados médicos explicada](https://developers.anpheros.com/pt/guides/medical-data-provenance)
- [Como implementar o consentimento do paciente com SMART on FHIR](https://developers.anpheros.com/pt/guides/smart-on-fhir-backend)
- [Como importar resultados de laboratório para um registo FHIR](https://developers.anpheros.com/pt/guides/import-lab-results-fhir)
- [Interoperabilidade de dados de saúde](https://developers.anpheros.com/pt/guides/interoperability)