Usando identificadores

Consultando Recursos com Identificadores

A forma mais comum de consultar um recurso específico utilizando seu identificador é através de uma requisição HTTP GET. A URL de consulta geralmente segue o padrão:

[URL Base da API FHIR]/[Tipo do Recurso]?identifier=[system]|[value]

Onde:

• [URL Base da API FHIR] é o endpoint da API FHIR da API Nilo (e.g., https://landing-zone-api.stg.nilo.services/fhir/).
• [Tipo do Recurso] é o nome do recurso FHIR que você deseja consultar (e.g., Patient, Organization, Condition).
• identifier é o parâmetro de busca para identificadores.
• [system] é o URI que define o sistema do identificador.
• [value] é o valor do identificador.
• | é um separador entre o system e o value.

Exemplo 1: Consultando um Paciente pelo CPF

Suponha que no Sistema Fictício, desejamos consultar um paciente com o CPF 12345678901. Utilizaremos o system padronizado para CPF no Brasil: https://servicos.receita.fazenda.gov.br/servicos/cpf/.

A URL da requisição GET seria:

https://landing-zone-api.stg.nilo.services/fhir/Patient?identifier=https://servicos.receita.fazenda.gov.br/servicos/cpf/|12345678901

Se o paciente for encontrado, a API FHIR retornará um Bundle contendo o recurso Patient.

Exemplo 2: Consultando uma Organização pelo ID Interno

Digamos que a Acme Saúde utiliza um ID interno para suas organizações, com o system definido como https://sistemaficticio.acmesaude.com.br/organizacao/id-interno e desejamos buscar a organização com o valor ORG-001.

A URL da requisição GET seria:

https://landing-zone-api.stg.nilo.services/fhir/Organization?identifier=https://sistemaficticio.acmesaude.com.br/organizacao/id-interno|ORG-001

Novamente, um Bundle contendo o recurso Organization seria retornado em caso de sucesso.

Atualizando Recursos com Identificadores

Para atualizar um recurso existente, geralmente utilizamos o método HTTP PUT na URL do recurso específico. No entanto, para garantir a integridade dos dados, podemos utilizar o identificador para realizar uma atualização condicional. Isso permite atualizar um recurso somente se ele existir com um determinado identificador.

A URL para uma atualização condicional:

[URL Base da API FHIR]/[Tipo do Recurso]

No corpo da requisição PUT, você enviará o recurso FHIR atualizado no formato JSON. O servidor FHIR irá procurar por um recurso do [Tipo do Recurso] que possua um identifier com o [system] e [value] especificados. Se encontrar um único recurso correspondente, ele será atualizado com os dados fornecidos no corpo da requisição.

Exemplo 3: Atualizando o Nome de um Paciente pelo CPF

Vamos supor que precisamos atualizar o nome do paciente com CPF 12345678901. Primeiro, construímos a URL de atualização condicional:

https://landing-zone-api.stg.nilo.services/fhir/Patient

O corpo da requisição PUT conterá o recurso Patient atualizado:

{
  "resourceType": "Patient",
  "identifier": [
    {
      "system": "https://servicos.receita.fazenda.gov.br/servicos/cpf/",
      "value": "12345678901"
    }
  ],
  "name": [
    {
      "use": "official",
      "text": "Pernalonga da Silva"
    }
  ],
  "gender": "male",
  "birthDate": "1970-01-01"
}

Ao enviar esta requisição PUT, o servidor FHIR buscará o paciente com o CPF 12345678901 e atualizará seu nome para "Pernalonga da Silva".

Importante: Ao realizar atualizações, certifique-se de que o recurso enviado no corpo da requisição contenha o mesmo identifier utilizado na criação do recurso.

Exemplo 4: Criando um Recurso se Não Existir (Upsert) usando ifNoneExist

Em alguns casos, pode ser necessário criar um recurso se ele não existir com um determinado identificador. Isso pode ser feito utilizando o cabeçalho HTTP If-None-Exist com o valor do critério de busca pelo identificador durante uma requisição POST.

A URL para a requisição POST seria o endpoint do tipo de recurso:

https://landing-zone-api.stg.nilo.services/fhir/Patient

E o cabeçalho HTTP seria:

If-None-Exist: identifier=https://servicos.receita.fazenda.gov.br/servicos/cpf/|98765432109

O corpo da requisição POST conterá o recurso Patient a ser criado:

{
  "resourceType": "Patient",
  "identifier": [
    {
      "system": "https://servicos.receita.fazenda.gov.br/servicos/cpf/",
      "value": "98765432109"
    }
  ],
  "name": [
    {
      "use": "official",
      "text": "Patolino Oliveira"
    }
  ],
  "gender": "male",
  "birthDate": "1985-05-10"
}

Se nenhum paciente com o CPF 98765432109 for encontrado, um novo recurso Patient será criado. Caso contrário, a requisição poderá retornar um código de status informando que o recurso já existe.

A utilização eficiente de identificadores é fundamental para garantir a interoperabilidade e a integridade dos dados no Sistema Fictício da Acme Saúde. Ao seguir estas diretrizes, os desenvolvedores poderão consultar e atualizar recursos de forma precisa e confiável.