Pular para o conteúdo principal

Associar/atualizar

EndpointPOST /fhir/resources/CarePlan
Autenticação🔓 Chave de API
StatusImplementado

Modelagem da API - Request​

OpçãoTipoRequeridoDescriçãoExemplo
x-api-keystringSimChave de autenticação do cliente, fornecida durante a configuração do ambiente.
Content-TypestringSimapplication/json

Exemplos de uso​

Inserir paciente em uma linha de cuidado (modo assíncrono)​

Exemplo com status=draft (processamento assíncrono)

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/CarePlan \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "CarePlan",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/careplan",
      "value": "349223"
    }
  ],
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "status": "draft",
  "intent": "order",
  "subject": {
    "identifier": {
      "use": "official",
      "system": "https://www.acmesaude.com.br/integracao/paciente",
      "value": "43927194050"
    },
    "type": "Patient"
  }
}'

Neste exemplo, o paciente será associado a uma linha de cuidado (PlanDefinition) através do campo instantiatesCanonical. O status=draft indica que o CarePlan será aplicado em um processo assíncrono, podendo levar até 24 horas para ser aplicado. Este modo respeita a capacidade da equipe de cuidado, garantindo que não haja sobrecarga de atividades.

Inserir paciente em uma linha de cuidado (modo em tempo real)​

Exemplo com status=active (processamento em tempo real)

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/CarePlan \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "CarePlan",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/careplan",
      "value": "349223"
    }
  ],
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "status": "active",
  "intent": "order",
  "subject": {
    "identifier": {
      "use": "official",
      "system": "https://www.acmesaude.com.br/integracao/paciente",
      "value": "43927194050"
    },
    "type": "Patient"
  }
}'

Quando status=active, o CarePlan é processado em tempo real e o paciente é imediatamente associado à linha de cuidado. Este modo é recomendado quando:

  • É necessária confirmação imediata da associação
  • O sistema precisa reagir instantaneamente à criação do CarePlan
  • A linha de cuidado deve ser aplicada sem delay

Remover paciente de uma linha de cuidado​

Exemplo de remoção com status=completed

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/CarePlan \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "CarePlan",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/careplan",
      "value": "349223"
    }
  ],
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "status": "completed",
  "intent": "order",
  "subject": {
    "identifier": {
      "use": "official",
      "system": "https://www.acmesaude.com.br/integracao/paciente",
      "value": "43927194050"
    },
    "type": "Patient"
  }
}'

Para remover um paciente de uma linha de cuidado, basta atualizar o CarePlan existente mudando o status para um dos seguintes valores:

  • completed: Indica que o plano de cuidado foi concluído. Usado para indicar que o paciente finalizou o tratamento.
  • revoked: Indica que o plano foi revogado. Use quando há necessidade de reverter uma associação indevida.
Identificação do CarePlan

Caso não envie o campo identifier, será usado os campos subject e instantiatesCanonical para identificar o CarePlan ativo correspondente e atualizará seu status.

Não é possível remover CarePlan em draft

Se o CarePlan ainda estiver com status=draft (aguardando processamento), não será possível removê-lo diretamente. Neste caso, aguarde o processamento ser concluído ou crie um novo CarePlan com status=active que sobrescreverá o draft.

Possíveis erros​

Os erros são retornados no formato de OperationOutcome.

Exemplo:

{
  "issue": [
    {
      "code": "structure",
      "details": {
        "text": "Field subject is required."
      },
      "severity": "error",
      "expression": [
        "CarePlan.subject"
      ]
    }
  ],
  "resourceType": "OperationOutcome"
}

Os principais campos são:

  • details: Descrição do erro.
  • expression: Caminho do recurso onde o erro ocorreu.

Erros conhecidos​

Erros de validação de campos obrigatórios​
subject.type inválido

Campo: subject
Mensagem: "Only Patient type is supported."
Causa: O campo subject.type deve ser "Patient".

author.type inválido

Campo: author
Mensagem: "Only Practitioner type is supported."
Causa: O campo author.type deve ser "Practitioner" quando fornecido.

instantiatesCanonical ausente

Campo: instantiatesCanonical
Mensagem: "instantiatesCanonical is required."
Causa: O campo instantiatesCanonical é obrigatório para associar o paciente a uma linha de cuidado (PlanDefinition).

instantiatesCanonical com URL inválida

Campo: instantiatesCanonical
Mensagem: "Invalid URL. It should start with https://landing-zone-api.nilo.services"
Causa: A URL no instantiatesCanonical deve apontar para um PlanDefinition no sistema Nilo.

Erros de status​
Status inválido para criação

Campo: status
Mensagem: "CarePlan can only be created with status draft or active"
Causa: Ao criar um CarePlan, apenas os status "draft" (processamento assíncrono) ou "active" (processamento em tempo real) são permitidos.

Erros de recursos não encontrados​
Paciente não encontrado

Campo: subject
Mensagem: "Patient with identifier system|value does not exist or is not active"
Causa: O paciente referenciado em subject.identifier não foi encontrado no sistema ou não está ativo.

Múltiplos pacientes encontrados

Campo: subject
Mensagem: "Multiple Patient with identifier system|value found"
Causa: O identificador fornecido corresponde a mais de um paciente no sistema. Use um identificador mais específico.

PlanDefinition não encontrado

Campo: instantiatesCanonical
Mensagem: "PlanDefinition with id {id} does not exist or is not active"
Causa: A linha de cuidado (PlanDefinition) referenciada não existe ou não está ativa.

PlanDefinition sem linha de cuidado ativa

Campo: instantiatesCanonical
Mensagem: "PlanDefinition with id {id} does not point to an active care line"
Causa: O PlanDefinition existe mas não aponta para uma linha de cuidado ativa no sistema Nilo.

PlanDefinition sem configuração de alocação (apenas status=draft)

Campo: instantiatesCanonical
Mensagem: "PlanDefinition with id {id} does not have an allocation config"
Causa: Para processar um CarePlan com status=draft, a linha de cuidado deve ter uma configuração de alocação (mass_guideline_config) configurada.

Erros de duplicação​
Paciente já associado à linha de cuidado

Campo: instantiatesCanonical, subject
Mensagem: "Subject with identifier value {value} and instantiatesCanonical {canonical} already exists"
Causa: Já existe um CarePlan ativo para este paciente nesta linha de cuidado. Um paciente não pode ter múltiplos CarePlans ativos para a mesma linha.

Paciente já na fila de processamento

Campo: instantiatesCanonical, subject
Mensagem: "Subject with identifier value {value} is already in the processing queue for instantiatesCanonical {canonical}"
Causa: Já existe um CarePlan com status=draft aguardando processamento para este paciente nesta linha de cuidado.

Sobrescrita de CarePlan draft para active

Se já existir um CarePlan com status=draft para o paciente/linha de cuidado, é possível criar um novo CarePlan com status=active que sobrescreverá o draft, processando a associação imediatamente.

Modelagem da API - Response​

Operação bem sucedida.
Array of objects (CarePlan_Activity)

Identifica uma ação planejada para ocorrer como parte do plano. Por exemplo, um medicamento a ser usado, exames laboratoriais a realizar, automonitoramento, educação, etc.

Array of objects (CodeableConcept)

Identifica qual o tipo do plano de cuidado para apoiar a diferenciação entre vários planos coexistentes; Por exemplo "Linha de cuidado", "Protocolo", ...

created
string^([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-...

Data em que o plano foi criado.

id
string (id) ^[A-Za-z0-9\-\.]{{1,64}}$

Qualquer combinação de letras, números, "-" e ".", com um limite de 64 caracteres. (Pode ser um número inteiro, um OID não prefixado, UUID ou qualquer outro padrão de identificador que atenda a essas restrições.) Os IDs não diferenciam maiúsculas de minúsculas.

object (Meta)

Os metadados sobre um recurso. Este conteúdo do recurso é normalmente mantido pelo sistema gestor do registro.

object

O período onde esse plano esta em execução.

title
string^[ \r\n\t\S]+$

Nome amigável para o plano de cuidado.

Array of objects (Identifier)

Identificador(es) pelo qual este recurso é distinguido.

instantiatesCanonical
required
Array of strings

Lista de URLs completas referenciando os PlanDefinitions usados como base para plano de cuidado. (No momento é possível instanciar apenas um PlanDefinition)

intent
required
string^[^\s]+(\s[^\s]+)*$
Value: "order"

Indica o nível de autoridade/intencionalidade associada ao plano de cuidados. No momento só é suportado o intent order, que significa aplicação imediata.

resourceType
required
string
Default: "CarePlan"

Indica o tipo do recurso transacionado.

status
required
string^[^\s]+(\s[^\s]+)*$
Enum: "draft" "active" "revoked" "completed" "entered-in-error"

Indica a situação do plano de cuidado.
draft: plano está na fila para que o paciente seja alocado; (padrão para novas escritas)
active: o plano está sendo executado no momento;
revoked: plano suspenso, atividades futuras canceladas;
completed: a plano foi encerrado dentro do prazo previsto;
entered-in-error: houve erro na aplicação do plano (verificar na UI do Nilo Care).

required
object

Paciente para o qual esse plano de cuidado foi planejado.

{
  • "activity": [
    ],
  • "category": {
    },
  • "created": "2022-05-23T19:00:00+00:00",
  • "id": "903dAAe9-c57f-4eb3-bd1c-65XXd41exx81",
  • "meta": {
    },
  • "period": {
    },
  • "title": "Baixo Risco",
  • "identifier": [
    ],
  • "instantiatesCanonical": [
    ],
  • "intent": "order",
  • "resourceType": "CarePlan",
  • "status": "active",
  • "subject": {
    }
}