Formação e Estabilidade do ID

Dentro desses padrões, a serem melhor especificados a partir da Fase 2 do Open Insurance no Brasil, os IDs de recursos são necessários para atender ao seguinte:

• O ID de um recurso deve ser especificado no endpoint de uma API apenas para obter detalhes do recurso ou para realizar alterações no mesmo.

• Se o ID for especificado nos padrões do Open Insurance, então ele é obrigatório e deverá ser fornecido pela entidade implementadora da API de acordo com o padrão definido.

• Se um ID for especificado, o mesmo deverá ser totalmente desconectado de significados com outras entidades. Por exemplo, um ID não deve ser uma combinação de outros campos ou uma string que possa ter conteúdo sensível que possa ser extraído.

• Os identificadores (IDs) devem ser únicos, e a sua unicidade deve estar dentro de um contexto, conforme abaixo:​

  1. Identificadores de contrato: esses IDs devem se manter estáveis sob o contexto do contrato, de modo que o valor do ID não varie entre consentimentos/jornadas que compartilham o mesmo recurso. Logo deve haver uma relação 1:1 entre o contrato e o seu identificador.​

     1. Contrato: o “contrato” citado no paragrafo acima deve ser interpretado como “contrato”, “apólice”, “certificado” ou “plano”.

• Nos payloads o nome de campo "id" nunca deverá ser utilizado. Cada campo ID deverá ter um nome significativo, dessa forma independentemente de onde o ID for utilizado entre múltiplos endpoints, ele sempre irá se referir ao seu objeto principal. Por exemplo, IDs para apólices deverão ser representados no JSON como "policyId".

Princípios para a formação de IDs (identificadores) de recursos nas APIs

• O ID DEVE ser uma string com limitação de 100 caracteres - limite que poderá ser revisitado em caso de necessidade apresentada por quaisquer dos participantes do Open Insurance Brasil e - aderente aos padrões apresentados na seção 2.1 da RFC 2141;

• Uma vez que será trafegado nas chamadas de interface, o ID NÃO DEVE conter dados classificados como PII - Personally identifiable information (Informação Pessoalmente Identificável) ou Informação de Identificação Pessoal, dessa maneira o ID deve ser um valor genérico/mascarado que não apresente relação com qualquer PII.

• DEVE ser garantida a unicidade do ID dentro do contexto da API assim como a estabilidade do mesmo, sendo a estabilidade condicionada à manutenção das características de identificação natural do recurso em questão. A alteração das características de identificação natural implica na geração de um novo identificador associado ao recurso;

• A utilização de meios técnicos razoáveis e disponíveis para a formação do ID é de livre implementação por parte da instituição transmissora dos dados, de forma que apenas a aderência aos princípios elencados nesta documentação é mandatória.