Pular para o conteúdo principal

Cadastrar/atualizar

EndpointPOST /fhir/resources/Practitioner
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

Campos e comportamentos​

Este endpoint faz upsert (cria ou atualiza) de um profissional. A decisão entre criar e atualizar é feita pelos identificadores — veja a seção Identificadores na introdução do recurso.

  • identifier (obrigatório) — usado para localizar um profissional já existente. Apenas os sistemas configurados como identificadores primários (definidos junto ao time de suporte) são considerados no casamento. Se nenhum dos identificadores enviados corresponder a um sistema configurado, a requisição é recusada para evitar duplicidades. Os identificadores também carregam CPF e registro em conselho.
  • name (obrigatório) — é utilizado apenas o nome com use: "official". O valor gravado é o campo text; se text não for informado, é montado a partir de given + family.
  • telecom — quando há um contato com system: "phone", seu value é gravado como telefone do profissional.
  • gender — mapeado para o cadastro NiloCare conforme a tabela abaixo:
FHIR (gender)NiloCare
maleMasculino
femaleFeminino
otherOutro
unknown / ausenteNão informado
  • qualification — especialidades do profissional (via código CBO). Veja os exemplos de especialidades abaixo.
  • address — endereço com use: "work" é sincronizado como unidade/local de atendimento. Veja o exemplo de endereço abaixo.
  • extension — gestão de usuário (login) e vínculo com unidades de cuidado. Veja as extensões de gestão de usuário na introdução do recurso.

Exemplos de uso​

Exemplo básico​

Exemplo de requisição CURL

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Practitioner \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Practitioner",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/profissional/",
      "value": "5032932"
    }
  ],
  "name": [
    {
      "text": "Jon Doe",
      "use": "official"
    }
  ]
}'

Exemplo com CPF e registro em conselho​

Exemplo de requisição CURL com CPF e registro em conselho

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Practitioner \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Practitioner",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/profissional/",
      "value": "5032932"
    },
    {
      "system": "https://servicos.receita.fazenda.gov.br/servicos/cpf/",
      "value": "12345678900"
    },
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/NiloClassCouncil/",
      "value": "CRM-SP-11111"
    }
  ],
  "name": [
    {
      "text": "Jon Doe",
      "use": "official"
    }
  ]
}'

Sobre CPF e registro em conselho: Ambos são enviados como identifier, cada um em seu system.

  • O CPF usa o system https://servicos.receita.fazenda.gov.br/servicos/cpf/.
  • O registro em conselho usa o system https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/NiloClassCouncil/ e o valor deve seguir o padrão [Conselho]-[UF]-[número] (ex.: CRM-SP-11111). Consulte os conselhos suportados na introdução do recurso.

Exemplo com email para login​

Exemplo de requisição CURL com email para login

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Practitioner \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Practitioner",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/profissional/",
      "value": "5032932"
    }
  ],
  "name": [
    {
      "text": "Jon Doe",
      "use": "official"
    }
  ],
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/practitioner-user",
      "extension": [
        {
          "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/practitioner-user-active",
          "valueBoolean": true
        },
        {
          "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/practitioner-user-email",
          "valueString": "email@exemplo.com"
        }
      ]
    }
  ]
}'

Sobre o usuário/login: Para que o profissional seja também um usuário do NiloCare, envie a extensão practitioner-user contendo:

  • practitioner-user-active com valueBoolean: true para ativar o login;
  • practitioner-user-email com o email usado para login. Este email é obrigatório quando active é true.

Basta informar um email (pela extensão practitioner-user-email ou pelo identifier — veja a nota abaixo) para que o profissional passe a ser tratado como usuário do sistema (care_user). A ativação do login/acesso (active: true), porém, exige o email especificamente na extensão practitioner-user-email.

Email também pode ser um identificador

Além da extensão, o email pode ser informado como identifier no system urn:ietf:rfc:6530. Se o email for enviado tanto na extensão quanto no identificador, os dois valores precisam ser iguais — caso contrário a requisição é recusada. O login (active: true), porém, exige o email na extensão practitioner-user-email.

Exemplo desativando o acesso do usuário​

Exemplo de requisição CURL desativando o acesso do usuário

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Practitioner \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Practitioner",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/profissional/",
      "value": "5032932"
    }
  ],
  "name": [
    {
      "text": "Jon Doe",
      "use": "official"
    }
  ],
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/practitioner-user",
      "extension": [
        {
          "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/practitioner-user-active",
          "valueBoolean": false
        },
        {
          "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/practitioner-user-email",
          "valueString": "email@exemplo.com"
        }
      ]
    }
  ]
}'

Sobre a desativação: Enviar practitioner-user-active com valueBoolean: false remove o acesso do usuário à unidade (care provider). O email é usado para localizar o usuário a ser desativado, por isso deve ser informado.

Exemplo com endereço de trabalho​

Exemplo de requisição CURL com endereço de trabalho

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Practitioner \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Practitioner",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/profissional/",
      "value": "5032932"
    }
  ],
  "name": [
    {
      "text": "Jon Doe",
      "use": "official"
    }
  ],
  "address": [
    {
      "use": "work",
      "line": [
        "Av. Paulista",
        "1000",
        "Sala 502"
      ],
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postalCode": "01310-100"
    }
  ]
}'

Sobre o endereço: Apenas endereços com use: "work" são considerados. O campo line é posicional:

  • line[0] → logradouro (rua/avenida)
  • line[1] → número (assume S/N quando ausente)
  • line[2] → complemento

Os endereços de trabalho enviados são sincronizados como locais de atendimento do profissional. Endereços que haviam sido enviados anteriormente e não constarem mais na requisição são desvinculados.

Exemplo com especialidades​

Exemplo de requisição CURL com especialidades

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Practitioner \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Practitioner",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/profissional/",
      "value": "5032932"
    }
  ],
  "name": [
    {
      "text": "Jon Doe",
      "use": "official"
    }
  ],
  "qualification": [
    {
      "code": {
        "coding": [
          {
            "code": "225130",
            "system": "http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO"
          }
        ]
      }
    },
    {
      "code": {
        "coding": [
          {
            "code": "225175",
            "system": "http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO"
          }
        ]
      }
    }
  ]
}'

Sobre especialidades: O campo qualification é utilizado para descrever as especialidades do profissional de saúde.

  • No campo code.coding.code deve ser informado o código CBO da especialidade
  • No campo code.coding.system deve ser sempre http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO (sistema do CBO - Classificação Brasileira de Ocupações)
  • O código CBO informado precisa ser válido/existente, caso contrário a requisição é recusada
  • Para informar múltiplas especialidades, use uma entrada qualification separada para cada uma

No exemplo acima, foram utilizados os códigos CBO 225130 (Médico de Família e Comunidade) e 225175 (Médico Geneticista).

Exemplo removendo uma especialidade​

Exemplo de requisição CURL removendo uma especialidade

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Practitioner \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Practitioner",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/profissional/",
      "value": "5032932"
    }
  ],
  "name": [
    {
      "text": "Jon Doe",
      "use": "official"
    }
  ],
  "qualification": [
    {
      "code": {
        "coding": [
          {
            "code": "225130",
            "system": "http://www.saude.gov.br/fhir/r4/CodeSystem/BRCBO"
          }
        ]
      },
      "period": {
        "end": "2025-08-14T15:05:00+00:00"
      }
    }
  ]
}'

Sobre remoção de especialidades: O campo period.end é utilizado para remover uma especialidade do profissional. Para que a remoção aconteça, o valor precisa ser menor ou igual à data atual.

Exemplo adicionando às múltiplas unidades de cuidado​

Exemplo de requisição CURL vinculando a múltiplas unidades de cuidado

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Practitioner \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '{
  "resourceType": "Practitioner",
  "identifier": [
    {
      "use": "usual",
      "system": "https://www.acmesaude.com.br/integracao/profissional/",
      "value": "5032932"
    }
  ],
  "name": [
    {
      "text": "Jon Doe",
      "use": "official"
    }
  ],
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/practitioner-organization",
      "valueIdentifier": {
        "system": "https://www.acmesaude.com.br/integracao/unidade-de-cuidado/",
        "use": "usual",
        "value": "10654"
      }
    },
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/practitioner-organization",
      "valueIdentifier": {
        "system": "https://www.acmesaude.com.br/integracao/unidade-de-cuidado/",
        "use": "usual",
        "value": "9998232"
      }
    }
  ]
}'

Sobre múltiplas unidades de cuidado: As extension com url https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/practitioner-organization são utilizadas para associar as unidades de cuidado às quais o profissional de saúde está vinculado. Cada unidade de cuidado deve ser representada como uma extensão separada. O campo valueIdentifier deve ser um identifier do recurso FHIR Organization (unidades de cuidado). Você pode consultar as unidades de cuidado (Organization) disponíveis na API para obter os identifiers corretos.

Unidade de cuidado padrão

Quando nenhuma extensão practitioner-organization é enviada, o profissional é vinculado à unidade de cuidado padrão configurada para o care provider. Se não houver unidade padrão configurada, a requisição é recusada.

Exemplo de requisição CURL para obter unidades de cuidado
curl --request GET \
--url https://landing-zone-api.nilo.services/fhir/resources/Organization \
--header 'Content-Type: application/json' \
--header 'x-api-key: <inserir API Key aqui>'

A resposta do GET será um Bundle, onde o campo entry conterá as unidades de cuidado disponíveis. Conforme exemplo de resposta abaixo:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Organization",
        "id": "37c2b365-cb5a-4401-ae0a-e747ee379f09",
        "identifier": [
          {
            "system": "https://www.acmesaude.com.br/integracao/unidade-de-cuidado/",
            "value": "10654"
          }
        ],
        "name": "Unidade de Cuidado 1"
      }
    },
    {
      "resource": {
        "resourceType": "Organization",
        "id": "37c2b365-cb5a-4401-ae0a-e747ee379f66",
        "identifier": [
          {
            "system": "https://www.acmesaude.com.br/integracao/unidade-de-cuidado/",
            "value": "9998232"
          }
        ],
        "name": "Unidade de Cuidado 2"
      }
    }
  ]
}

Modelagem da API - Response​

Operação bem sucedida.
Array of Extension-Practitioner-user (object)

Pode ser usado para representar informações adicionais que não fazem parte da definição básica do recurso. Qualquer implementador pode definir uma extensão, aqui apresentamos as extensões utilizadas no contexto Nilo, extensões externas a esse contexto são ignoradas.

gender
string
Enum: "male" "female" "other" "unknown"

O sexo que o profissional de saúde é considerado para fins de administração e manutenção de registros.

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.

Array of objects (Identifier)

Um conjunto de códigos de identificação para este profissional de saúde (IDs, CPF, CRM, ...).

object (Meta)

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

required
Array of objects (HumanName)

O(s) nome(s) associado(s) ao profissional de saúde. Ao menos um nome official deve ser fornecido.

resourceType
required
string
Default: "Practitioner"

Indica o tipo do recurso transacionado.

Array of objects (ContactPoint)

Um detalhe de contato (por exemplo, um número de telefone ou um endereço de e-mail) por qual o indivíduo pode ser contatado.

{
  • "extension": [
    ],
  • "gender": "male",
  • "id": "903dAAe9-c57f-4eb3-bd1c-65XXd41exx81",
  • "identifier": [
    ],
  • "meta": {
    },
  • "name": [
    ],
  • "resourceType": "Practitioner",
  • "telecom": [
    ]
}