Hyago

recent posts

APIs FHIR Interoperabilidade

Como o FHIR pode te ajudar a desenvolver APIs para dados de saúde

Se você já tentou integrar sistemas de saúde diferentes, sabe que pode ser um verdadeiro pesadelo. Cada sistema tem seu próprio formato de dados, sua própria maneira de representar um paciente, um diagnóstico ou uma prescrição médica. É como tentar encaixar peças de quebra-cabeças completamente diferentes.

Mas e se existisse uma forma padronizada e moderna de trocar informações de saúde? É aqui que entra o FHIR (Fast Healthcare Interoperability Resources, pronunciado “fire” 🔥). O FHIR é um padrão para troca eletrônica de informações de saúde, projetado para ser simples de implementar sem sacrificar a integridade das informações.

Neste artigo, vamos explorar como o FHIR funciona, seus conceitos fundamentais e, principalmente, como você pode começar a desenvolver APIs de saúde usando esse padrão. Se você trabalha com integração de sistemas de saúde ou está curioso sobre o assunto, este guia é para você.

O que é FHIR?

1. Um padrão moderno de interoperabilidade em saúde

FHIR (Fast Healthcare Interoperability Resources) é uma especificação técnica desenvolvida pela HL7 que define como sistemas de saúde devem estruturar, representar e trocar informações eletronicamente.

O FHIR foi projetado para simplificar a implementação sem sacrificar a integridade da informação, combinando as melhores práticas da web moderna com mais de 20 anos de experiência da HL7 em modelagem de dados clínicos. Na prática, isso significa que você pode consumir uma API FHIR da mesma forma que consome qualquer API REST contemporânea – com verbos HTTP padrão, endpoints intuitivos e respostas em JSON.

2. Arquitetura baseada em Resources

Um conjunto fixo de elementos de dados (resourceType, id, meta) Elementos específicos do tipo (ex: Patient tem name, gender, birthDate) Suporte a extensões para campos customizados Referências para outros Resources (relacionamentos entre entidades)

Pense nos Resources como DTOs (Data Transfer Objects) versionados e autocontidos, onde cada tipo tem sua própria especificação formal que define estrutura, cardinalidade, tipos de dados e terminologias permitidas.

2.1 Anatomia de um Resource

Todo Resource FHIR compartilha características comuns:

  1. Um identificador único: Geralmente uma URL que define onde o recurso pode ser encontrado
  2. Metadados comuns: Informações sobre versão, data de última atualização, etc.
  3. Uma narrativa legível por humanos: Resumo em XHTML do conteúdo
  4. Elementos de dados definidos: Um conjunto específico para cada tipo de recurso
  5. Framework de extensibilidade: Para suportar variações necessárias
2.2 Extensibilidade: Adaptando às Suas Necessidades

Sempre haverão cenários de necessidade específica, para isso o FHIR possui o mecanismo Extensions que permite adicionar campos customizados sem quebrar a compatibilidade.

Atualmente, a especificação define 157 tipos diferentes de recursos, cobrindo desde informações clínicas básicas (como Patient, Observation) até processos complexos (como CarePlan, MedicationRequest).

Representação dos Dados

Os recursos podem ser representados em três formatos: JSON, XML ou RDF. Veja um exemplo simplificado de um paciente em JSON:

{
  "resourceType": "Patient",
  "id": "123",
  "identifier": [{
    "system": "http://hospital.exemplo.com/pacientes",
    "value": "987654"
  }],
  "name": [{
    "family": "Silva",
    "given": ["João", "Pedro"]
  }],
  "gender": "male",
  "birthDate": "1985-03-15"
}

A API RESTful do FHIR

Uma das grandes vantagens do FHIR é que ele adota práticas RESTful modernas que desenvolvedores já conhecem. Como explicado na documentação para desenvolvedores, o FHIR “fornece uma API REST com um conjunto rico, mas simples, de interações”.

As operações principais seguem os verbos HTTP padrão:

  • POST /base/{resourceType} – Criar um recurso
  • GET /base/{resourceType}/{id} – Ler um recurso específico
  • PUT /base/{resourceType}/{id} – Atualizar um recurso
  • DELETE /base/{resourceType}/{id} – Deletar um recurso
  • GET /base/{resourceType}?parametros – Buscar recursos

Criando um Paciente

Segundo a especificação, para criar um recurso você envia uma requisição HTTP POST para o endpoint do tipo de recurso. Veja como criar um novo paciente:

Requisição:

POST /fhir/Patient HTTP/1.1
Host: servidor.exemplo.com
Content-Type: application/fhir+json
Accept: application/fhir+json

{
  "resourceType": "Patient",
  "identifier": [{
    "system": "http://hospital.exemplo.com/pacientes",
    "value": "987654"
  }],
  "name": [{
    "family": "Silva",
    "given": ["João", "Pedro"]
  }],
  "gender": "male",
  "birthDate": "1985-03-15",
  "active": true
}

Resposta:

HTTP/1.1 201 Created
Location: http://servidor.exemplo.com/fhir/Patient/347
ETag: W/"1"
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Operação realizada com sucesso</div>"
  }
}

Note que o servidor retorna um código 201 Created e o cabeçalho Location indica onde o recurso foi criado, com o ID atribuído pelo servidor (347 neste caso).

Buscando um Paciente específico

A leitura é feita através de uma requisição GET simples:

Requisição:

GET /fhir/Patient/347 HTTP/1.1
Host: servidor.exemplo.com
Accept: application/fhir+json

Resposta:

HTTP/1.1 200 OK
Content-Type: application/fhir+json
ETag: W/"1"
Last-Modified: Mon, 18 Aug 2014 15:43:30 GMT

{
  "resourceType": "Patient",
  "id": "347",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2014-08-18T15:43:30Z"
  },
  "identifier": [{
    "system": "http://hospital.exemplo.com/pacientes",
    "value": "987654"
  }],
  "name": [{
    "family": "Silva",
    "given": ["João", "Pedro"]
  }],
  "gender": "male",
  "birthDate": "1985-03-15",
  "active": true
}

Buscando pacientes por parâmetros

A busca é uma das operações mais poderosas do FHIR. Você pode encontrar recursos usando diversos critérios através de parâmetros na URL:

Requisição – Buscar pacientes por nome de família:

GET /fhir/Patient?family=Silva HTTP/1.1
Host: servidor.exemplo.com
Accept: application/fhir+json

Resposta:

HTTP/1.1 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "link": [{
    "relation": "self",
    "url": "http://servidor.exemplo.com/fhir/Patient?family=Silva"
  }],
  "entry": [{
    "fullUrl": "http://servidor.exemplo.com/fhir/Patient/347",
    "resource": {
      "resourceType": "Patient",
      "id": "347",
      "name": [{
        "family": "Silva",
        "given": ["João", "Pedro"]
      }],
      "gender": "male",
      "birthDate": "1985-03-15"
    }
  }, {
    "fullUrl": "http://servidor.exemplo.com/fhir/Patient/891",
    "resource": {
      "resourceType": "Patient",
      "id": "891",
      "name": [{
        "family": "Silva",
        "given": ["Maria"]
      }],
      "gender": "female",
      "birthDate": "1992-07-22"
    }
  }]
}

Como explicado na especificação, “o resultado de uma busca é sempre um bundle do tipo ‘searchset’” – uma coleção de recursos que correspondem aos critérios.

Busca com Múltiplos Parâmetros

Você pode combinar vários critérios de busca:

Requisição – Buscar prescrições de um paciente específico:

GET /fhir/MedicationRequest?patient=347&status=active HTTP/1.1
Host: servidor.exemplo.com
Accept: application/fhir+json

Atualizando Paciente

Para atualizar um recurso você envia uma requisição HTTP PUT para o endpoint do tipo de recurso.

Requisição:

PUT /fhir/Patient/347 HTTP/1.1
Host: servidor.exemplo.com
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "id": "347",
  "meta": {
    "versionId": "1"
  },
  "identifier": [{
    "system": "http://hospital.exemplo.com/pacientes",
    "value": "987654"
  }],
  "name": [{
    "family": "Silva",
    "given": ["João", "Pedro"]
  }],
  "gender": "male",
  "birthDate": "1985-03-15",
  "active": true,
  "telecom": [{
    "system": "phone",
    "value": "(85) 98765-4321",
    "use": "mobile"
  }]
}

Resposta:

HTTP/1.1 200 OK
Location: http://servidor.exemplo.com/fhir/Patient/347/_history/2
ETag: W/"2"
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Recurso atualizado com sucesso</div>"
  }
}

Removendo um Paciente

Requisição:

DELETE /fhir/Patient/347 HTTP/1.1
Host: servidor.exemplo.com

Resposta:

HTTP/1.1 204 No Content

Conclusão

O HL7 FHIR representa uma mudança de paradigma no desenvolvimento de sistemas de saúde interoperáveis. Ao adotar padrões RESTful modernos e fornecer recursos bem definidos, ele simplifica drasticamente a integração entre sistemas diferentes.

Principais benefícios:

  • Facilidade de implementação: API REST padrão, sem necessidade de bibliotecas especializadas
  • Agnóstico à tecnologia: Funciona com qualquer linguagem que suporte HTTP
  • Flexibilidade: Extensões permitem adaptação a necessidades específicas
  • Padrão maduro: Baseado em décadas de experiência do HL7
  • Ampla adoção: Crescente suporte de fornecedores e instituições

Trade-offs a considerar:

  • Curva de aprendizado inicial para entender a especificação
  • Necessidade de compreender o domínio de saúde além da parte técnica
  • Complexidade em cenários muito específicos pode exigir extensões

Próximos passos:

  1. Explore a documentação oficial do FHIR
  2. Experimente com um servidor público como o HAPI FHIR para testar requisições
  3. Comece com recursos simples (Patient, Observation) antes de avançar
  4. Use ferramentas como Postman ou cURL para experimentar com a API
  5. Participe da comunidade FHIR para aprender com outros desenvolvedores

O FHIR está transformando a forma como sistemas de saúde se comunicam. Como você viu, trabalhar com FHIR é tão simples quanto fazer requisições HTTP REST – uma habilidade que praticamente todo desenvolvedor já possui. Se você trabalha nessa área, este é definitivamente um padrão que vale a pena dominar.

Referências

HL7 International. Official FHIR website: http://www.hl7.org

HL7 FHIR Specification v5.0.0 – FHIR Overview. Disponível em: http://hl7.org/fhir/overview.html

HL7 FHIR Specification v5.0.0 – FHIR Overview for Developers. Disponível em: http://hl7.org/fhir/overview-dev.html

Posted in ,