Pular para o conteúdo principal

Configuração

Para começar a utilizar o serviço é necessário realizar algumas configurações gerenciais. Estas configurações incluem a obtenção de uma chave de acesso e a definição dos resources da aplicação.

Após realizar essas configurações, o sistema estará apto a operar o serviço.

Credenciais de Acesso​

O primeiro passo para a utilização do Cadastro Único é a obtenção de credenciais de acesso ao serviço. Os recursos da API de gerenciamento do Cadastro Único são protegidos pelo protocolo OAuth 2.

Um client com o grant type 'client credentials' deve ser configurado para cada sistema interessado em utilizar o serviço, e um token deve ser gerado.

Este token deve ser enviado nas requisições à API através do header 'Authorization', seguindo o formato abaixo:

    Authorization: Bearer <TOKEN>

O procedimento de criação do client e geração do token é realizado atualmente pela Betha Sistemas. Os parceiros interessados em utilizar o Cadastro Único devem abrir um atendimento no canal exclusivo para parceiros.

Templates​

Conforme mencionado anteriormente, um template é uma entidade de compartilhamento de dados entre os sistemas. Alguns exemplos de templates são:

  • Pessoas (id: pessoas)
  • Logradouros (id: logradouros)
  • Municípios (id: municipios)
  • Estados (id: estados)
  • Países (id: paises)

Para saber quais informações estão disponíveis em cada template, é necessário realizar uma consulta para obter as suas definições.

Consulta​

A requisição abaixo exemplifica a consulta do template de Pessoas:

    GET /api/v2/templates/pessoas HTTP/1.1
    Host: https://plataforma-cadastro-unico.betha.cloud
    Authorization: Bearer <TOKEN>
    Content-Type: application/json

Resources​

Resources são os cadastros do sistema que fazem uso de um template. O sistema Saúde, por exemplo, pode definir o resource Paciente para o template de Pessoas. Através da configuração de um resource, o sistema formaliza o vínculo do seu cadastro com um template. Esta especificação é realizada por meio do recurso /api/v2/resources da API de Gerenciamento.

Gerenciamento do resource​

A criação, atualização e exclusão de um resource é realizada em um endpoint específico (/api/v2/resources), respeitando os verbos HTTP, conforme exemplos a seguir.

Na configuração do resource, é necessário informar o comportamento padrão para aceite de pendências cadastrais (acceptCriteria), além de parametrizar se o usuário final poderá alterar essas configurações por meio do Gerenciador de Pendências Cadastrais (disableEvaluationConfig).

Deve-se informar também o endereço do serviço a ser chamado para recepção dos eventos de webhook, meio pelo qual os sistemas recebem comandos de atualização. É necessário também configurar um secret token, o qual é utilizado para assinar o corpo da requisição. Com essa assinatura, o sistema que recebe o comando consegue garantir que o comando recebido é proveniente de uma fonte segura, dado que somente o dono do resource e o próprio Cadastro Único conhecem este token. O tamanho mínimo para o secret token é de 32 caracteres.

Criação​

A requisição abaixo exemplifica a criação do resource Funcionários para um template de Pessoas:

    POST /api/v2/resources HTTP/1.1
    Host: https://plataforma-cadastro-unico.betha.cloud
    Authorization: Bearer <TOKEN>
    Content-Type: application/json
{
   "templateId":"pessoas",
   "resourceId":{
      "system":79,
      "aggregate":"funcionarios"
   },
   "name":"Funcionários",
   "acceptCriteria":"NEVER",
   "disableEvaluationConfig":false,
   "callbackConfig":{
      "webhook":{
         "enabled":true,
         "url":"https://minha-api.com.br/integracao-betha",
         "secretToken":"f7081a62-dd5c-4949-9b4b-e776b4295095"
      }
   }
}

Atualização​

A requisição abaixo exemplifica a atualização de um resource existente:

   PUT /api/v2/resources/pessoas/funcionarios HTTP/1.1
    Host: https://plataforma-cadastro-unico.betha.cloud
    Authorization: Bearer <TOKEN>
    Content-Type: application/json
{
   "templateId":"pessoas",
   "resourceId":{
      "system":79,
      "aggregate":"funcionarios"
   },
   "name":"Funcionários",
   "acceptCriteria":"ALWAYS",
   "disableEvaluationConfig":false,
   "callbackConfig":{
      "webhook":{
         "enabled":true,
         "url":"https://minha-api.com.br/integracao-betha",
         "secretToken":"f7081a62-dd5c-4949-9b4b-e776b4295095"
      }
   }
}

Exclusão​

A requisição abaixo exemplifica a exclusão de um resource existente:

    DELETE /api/v2/resources/pessoas/funcionarios HTTP/1.1
    Host: https://templates.cloud.betha.com.br
    Authorization: Bearer < TOKEN >
    Content-Type: application/json