Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

Como integrar sistemas de clínicas com um backend FHIR

Tutorial: conecte um EMR de clínica aos registos FHIR R4 dos 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 prestadores e webhooks.

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ê

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.

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:

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:

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; 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.

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:

"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.

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:

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 e API de dados médicos.

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:

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.

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

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: todos os padrões de integração num relance
• Proveniência de dados médicos explicada
• Como implementar o consentimento do paciente com SMART on FHIR
• Como importar resultados de laboratório para um registo FHIR
• Interoperabilidade de dados de saúde

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card