Pular para o conteúdo principal

Cadastrar

Endpoint

POST /fhir/resources/Coverage

Autenticação🔓 Chave de API
StatusImplementado

Modelagem da API - Request​

OpçãoTipoRequeridoDescriçãoExemplo
x-api-keystringSim

Chave de autenticação do cliente, fornecida durante a configuração do ambiente.

Content-TypestringSimapplication/json


Exemplo de requisição CURL

curl --request POST \
--url https://landing-zone-api.nilo.services/fhir/resources/Coverage \
--header 'Content-Type: application/json' \
--header 'x-api-key: ???' \
--data '{
  "resourceType": "Coverage",
  "identifier": [
    {
      "use": "usual",
      "system": "https://sistemadocliente.com/beneficios",
      "value": "12345"
    }
  ],
  "status": "active",
  "policyHolder": {
    "display": "Petrobras"
  },
  "class": [
    {
      "type": { "text": "plan" },
      "value": "42",
      "name": "Plano Empresarial"
    }
  ],
  "subscriberId": 1352743,
  "beneficiary": {
    "identifier": {
      "use": "usual",
      "system": "https://sistemadocliente.com/paciente",
      "value": "12346"
    }
  },
  "dependent": 1352744,
  "relationship": {
    "coding": [
      {
        "code": "spouse"
      }
    ]
  },
  "period": {
    "start": "2022-05-23",
    "end": "2023-05-23"
  },
  "order": 1
}'
Atualização de uma cobertura existente

Para atualizar um recurso já cadastrado, envie o payload com o mesmo identifier utilizado na criação.

Caso o identifier não seja informado (ou não corresponda a nenhum recurso), o sistema tenta localizar uma cobertura existente pela chave de negócio: a combinação de carteirinha (subscriberId/dependent, conforme o relationship) + paciente (beneficiary) + plano (class.value). Havendo correspondência, o recurso é atualizado; caso contrário, um novo é criado.

Plano de saúde (class)​

O plano de saúde é informado no primeiro item de class cujo type.text seja plan. O identificador do plano vai em class.value, e corresponde ao value do identifier do recurso InsurancePlan cujo system é https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2. O atributo class.name é apenas informativo e não é usado para localizar o plano.

Como consultar os planos de saúde disponíveis​

Faça uma requisição GET no endpoint /fhir/resources/InsurancePlan e utilize o value do identifier retornado (com o system acima) como class.value na cobertura.

Exemplo de requisição CURL para listar os planos de saúde

curl --request GET \
--url https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan \
--header 'Content-Type: application/json' \
--header 'x-api-key: SEU_API_KEY_AQUI'

No retorno, localize o identifier com system igual a

https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2

e use o seu value em class.value:

{
  "class": [
    {
      "type": { "text": "plan" },
      "value": "42",
      "name": "Plano Empresarial"
    }
  ]
}

Possíveis Erros​

Paciente enviado no beneficiary não existe:​

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Patient does not exist"
      }
    }
  ]
}

O paciente informado no campo beneficiary não foi encontrado.

Exemplo de payload com paciente inexistente:​

{
  "resourceType": "Coverage",
  "identifier": [
    {
      "use": "usual",
      "system": "https://sistemadocliente.com/beneficios",
      "value": "12345"
    }
  ],
  "status": "active",
  "policyHolder": {
    "display": "Petrobras"
  },
  "subscriberId": 1352743,
  "beneficiary": {
    "identifier": {
      "use": "usual",
      "system": "https://sistemadocliente.com/paciente",
      "value": "12346"
    }
  },
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  }
}

Não é possível criar carteirinha sem número dependent ou subscriberId:​

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "HTTPBadRequest: [Bad Request] 400 for https://hippocrates-api.nilo.services/v1/coverages/:id: This Coverage violates the check `coverage_invalid_null_insurance_id_and_card_number` which states (OR: ('card_number__isnull', False), ('insurance_id__isnull', False))"
      }
    }
  ]
}

É necessário informar o número do dependente ou do assinante.

Exemplo de payload com relationship.coding.code spouse, mas sem preencher o campo dependent:​

{
  "resourceType": "Coverage",
  "identifier": [
    {
      "use": "usual",
      "system": "https://sistemadocliente.com/beneficios",
      "value": "12345"
    }
  ],
  "status": "active",
  "policyHolder": {
    "display": "Petrobras"
  },
  "subscriberId": 1352743,
  "beneficiary": {
    "identifier": {
      "use": "usual",
      "system": "https://sistemadocliente.com/paciente",
      "value": "12346"
    }
  },
  "relationship": {
    "coding": [
      {
        "code": "spouse"
      }
    ]
  }
}

Nesse caso aqui é necessário preencher o campo dependent com o número do dependente.

Exemplo de payload com relationship.coding.code self, mas sem preencher o campo subscriberId:​

{
  "resourceType": "Coverage",
  "identifier": [
    {
      "use": "usual",
      "system": "https://sistemadocliente.com/beneficios",
      "value": "12345"
    }
  ],
  "status": "active",
  "policyHolder": {
    "display": "Petrobras"
  },
  "beneficiary": {
    "identifier": {
      "use": "usual",
      "system": "https://sistemadocliente.com/paciente",
      "value": "12346"
    }
  },
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  }
}


Modelagem da API - Response​

Operação bem sucedida.

required
object

Beneficiário no NiloCare.

Array of objects (Coverage_Class)

Classificações do benefício.

Array of objects (Reference)

Contrato do Benefício.

Array of objects (Coverage_CostToBeneficiary)

Co-participação financeira de responsabilidade do beneficiário.

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

Número (carteirinha) do beneficiário, quando for um dependente de um titular.

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)

Identificador(es) pelo qual este recurso é distinguido.

object (Meta)

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

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

Descrições sobre a rede de atendimento.

order
number^[1-9][0-9]*$

Ordem de prioridade de uso entre benefícios.

required
Array of objects (Reference)

Entidade pagadora dos custos de saúde (Seguradora, Operadora, ...)

object

Período de validade do benefício.

object

Contratante (Estipulante), dono da apólice do benefício.

object

Relação entre titular e beneficiário.

resourceType
required
string
Default: "Coverage"

Indica o tipo do recurso transacionado.

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

Situação atual do benefício.

subrogation
boolean^true|false$

Indica se o benefício conta com reembolso.

object

Titular do benefício no NiloCare.

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

Número (carteirinha) do titular do benefício.

object

O tipo de benefício disponibilizado, por exemplo, Plano de Saúde.

{
  • "beneficiary": {
    },
  • "class": {
    },
  • "contract": [
    ],
  • "costToBeneficiary": [
    ],
  • "dependent": 1352744,
  • "id": "903dAAe9-c57f-4eb3-bd1c-65XXd41exx81",
  • "identifier": [
    ],
  • "meta": {
    },
  • "network": "Rede de atendimento preferêncial C465 de São Paulo capital",
  • "order": 0,
  • "payor": {
    },
  • "period": {
    },
  • "policyHolder": {
    },
  • "relationship": {
    },
  • "resourceType": "Coverage",
  • "status": "active",
  • "subrogation": true,
  • "subscriber": {
    },
  • "subscriberId": 1352743,
  • "type": {
    }
}