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".

• 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.

Conforme comunicado OPIN 26/2025, fica estabelecido que, para a Fase 2, as participantes devem obrigatoriamente utilizar o número do recurso nas URLs e nos payloads dessas APIs. Para fins de padronização, entende-se por número do recurso:

• Número da apólice do cliente, quando a variável da URL for policyId;

• Número do plano do cliente, quando a variável da URL for planId;

• Número do certificado do cliente, quando a variável da URL for certificateId;

• Número da pensão do cliente, quando a variável da URL for pensionIdentificationId;

• Número do contrato do cliente, quando a variável da URL for contractId.

Pontos importantes:

• Na API Resources, o campo resourceId deve obrigatoriamente conter o número do recurso, conforme a lista acima.

• Não devem ser utilizados outros dados como identificador do recurso além dos especificados.

• O número do recurso informado na URL da API não deve ser criptografado nem submetido a qualquer forma de mascaramento.

• Essa medida é temporária e permanecerá vigente até a implementação, pelo GT de Dados, de um novo formato de identificador (UUID) a ser utilizado nas URLs da Fase 2.

As participantes devem garantir que as respostas aos endpoints de listagem de contratos e informações de contrato nas APIs de Fase 2 incluam o número do recurso, conforme a seguir: