Pular para o conteúdo principal

Manual de implementação para parceiros

Cadastro Único Betha para sistemas parceiros​

O que é o Cadastro Único?​

O Cadastro Único é uma plataforma centralizada da Betha Sistemas, projetada para sincronizar dados e permitir a comunicação e o compartilhamento de informações de forma padronizada entre diferentes sistemas, incluindo os produtos em nuvem da Betha e sistemas de parceiros.

O objetivo é garantir a consistência e a integridade dos dados, evitando duplicidade e facilitando a gestão da informação entre as aplicações integradas.

Como funciona a sincronização?​

A sincronização de dados é fundamentada em dois conceitos principais:

Templates: Representam a estrutura de dados padronizada para cada tipo de cadastro compartilhado (ex: pessoas, feriados, municípios). Um modelo define os campos, tipos de dados e regras de validação que constituem o contrato de dados entre os sistemas. (Para mais detalhes sobre a gestão de Templates e o tratamento de campos customizados, consulte o Apêndice A).

Resources: Corresponde a que tipo de Cadastro (Templates) será integrado para uma determinada entidade (município) e as suas configurações. A configuração de um vínculo permite que o sistema passe a sincronizar os dados daquele cadastro com outras aplicações que utilizem o mesmo modelo.

Conhecimentos necessários para implementar o Cadastro Único​

Criação do Projeto no Studio​

Um projeto é a aplicação ou sistema que você cria para integrar com os produtos Betha. Ele centraliza todas as configurações e credenciais necessárias para a comunicação com as APIs.

Para mais detalhes, acesse a documentação sobre Projetos.

Configuração de Credenciais e APIs​

Uma credencial possibilita o acesso a uma API. Dentro do seu projeto, você pode criar diferentes tipos de credenciais (Serviço, Aplicação no Servidor, etc.), habilitar as APIs desejadas e definir os escopos de permissão (leitura, escrita).

Para mais detalhes, acesse a documentação sobre Credenciais.

Obtenção das Chaves de Acessos​

O Access Token é a chave de autorização para suas requisições na API, enquanto o User-Access é a permissão específica para acessar os dados de uma determinada entidade (cliente). O primeiro é gerado a partir da sua credencial e o segundo depende de uma liberação em duas etapas: uma pela Betha e outra pela entidade.

Para mais detalhes, acesse a documentação sobre Conceitos.

Configuração e pré-requisitos​

Para que um sistema parceiro possa se integrar ao Cadastro Único, as seguintes configurações são indispensáveis:

Credencial no Studio Aplicações

O parceiro deve cadastrar uma credencial do tipo (serviço) no Studio Aplicações.

  1. Crie um projeto com o nome do sistema parceiro.
  2. Dentro deste projeto, adicione os escopos das APIs dos produtos Betha com os quais deseja interagir (ex: Tributos) e, obrigatoriamente, a API do Cadastro Único.
  3. Este processo irá gerar as chaves necessárias para a autenticação.

Autorização de Acesso (Token)

Com a credencial criada, é necessário obter a autorização de acesso (Token e User Access) para a entidade (município) desejada.

  1. A chave pública gerada no Studio Aplicações deve ser cadastrada no sistema Betha (ex: Tributos) dentro do contexto da entidade (ex: Prefeitura de Criciúma).
  2. Com essa configuração, o parceiro poderá gerar o access_token e o user_access necessários para realizar chamadas às APIs do Cadastro Único.

Liberação de Vínculos de Entidade

Para que a sincronização dos cadastros seja visível na interface do Cadastro Único e para que a comunicação flua corretamente, o sistema do parceiro (cadastrado no Studio) deve ser liberado para a entidade correspondente. Essa liberação é realizada no sistema Admin da Betha.

Fluxo de Integração​

Existem dois fluxos principais de comunicação para o parceiro: receber dados dos sistemas Betha e enviar dados para os sistemas Betha.

  1. Cenário 1: Receber Dados (Escutar Eventos da Betha)

Neste cenário, o parceiro deseja que seu sistema seja notificado quando um cadastro de interesse for criado ou alterado em um sistema Betha.

Passo 1: Cadastrar o Resource

Para "escutar" um cadastro, o parceiro deve fazer uma requisição POST para a API de resources, informando qual cadastro deseja sincronizar (templateId) e para onde as notificações devem ser enviadas pela URL do webhook (api do sistema parceiro).

Exemplo de Request:

{
  "templateId": "feriados",
  "resourceId": {
    "system": "Id do projeto cadastrado no Studio",
    "aggregate": "feriados-parceiro"
  },
  "name": "Feriados do Sistema Parceiro",
  "acceptCriteria": "ALWAYS",
  "callbackConfig": {
    "webhook": {
      "enabled": true,
      "url": "https://webhook.site/3b8ccbc6-0cd1-499b-801c-baa5ca1f0254",
      "secretToken": "um-segredo-para-validacao"
    }
  }
}

A partir deste momento, o sistema parceiro está inscrito no template "feriados" e receberá eventos na API configurada. Atenção: É obrigatório que o sistema parceiro armazene o recordId recebido. Este ID é o identificador único do registro no Cadastro Único e será essencial para enviar atualizações para este mesmo registro no futuro.

  1. Cenário 2: Enviar Dados (Enviar Eventos para a Betha)

Neste cenário, uma alteração ocorre no sistema do parceiro, e ele precisa comunicar essa mudança para os sistemas Betha.

Passo 1: Enviar um (Command) Como o parceiro não se comunica diretamente com a mensageria de eventos, ele deve utilizar a API de commands. Esta API permite que o parceiro envie um evento de criação (CREATE) ou atualização (UPDATE).

Exemplo de Request para ATUALIZAR um cadastro:

{
  "action": "UPDATE",
  "data": {
    "template": "feriados",
    "aggregate": "feriados-parceiro",
    "id": "1a4d93d4-68fd-4d6b-b966-79e73944d7be",
    "user": "usuario.parceiro",
    "data": {
      "descricao": "Nova Descrição do Feriado"
    }
  }
}
  • id: Aqui vai o recordId que foi armazenado quando o registro foi recebido. Isso informa ao Cadastro Único que se trata de uma atualização.
  • data: Contém os campos que foram alterados.

Para ENVIAR um novo cadastro, o processo é similar, mas a action é CREATE e um novo id (no padrão UUID) deve ser gerado pelo parceiro.

Ao receber este comando, o Cadastro Único o processa como um evento de sincronização, que aparecerá para os sistemas Betha integrados (ex: Tributos), fechando o ciclo de comunicação.

Importante

O parceiro deve ter conhecimento prévio do schema (estrutura) do template para garantir que os dados enviados em data sejam válidos. Se a estrutura de dados enviada for incompatível com o schema, a integração não funcionará, embora possa não retornar um erro explícito ao parceiro.

Exemplo de Response ao consultar o commands:

   {
"id": "ac157642-de39-11e9-8a34-2a2ae2daaa12",
"result": {
   "_class": "com.betha.services.[...].UpdateSucceededCommandResult",
   "id": "ac157642-de39-11e9-8a34-2a2ae2daaa12",
   "generatedEvent": {
      "data": {
      "source": {
         "system": "274",
         "aggregate": "feriados-parceiro"
      },
      "templateRecord": {
         "template": "feriados",
         "recordId": "1a4d93d4-68fd-4d6b-b966-79e73944d7be"
      },
      "database": "65",
      "data": {
         "descricao": "Nova Descrição do Feriado"
      },
      "patch": [
        {
          "path": "/descricao",
          "value": "Nova Descrição do Feriado",
           "op": "replace"
        }
      ],
      "user": "usuario.parceiro",
      "_id": "bba7045a-f83c-476a-a9ab-587d656359b5"
      },
      "id": "181b3f36-b66e-4d23-a74c-e8e5af821d11"
   },
   "source": {
      "system": "274",
      "aggregate": "feriado"
   },
   "templateRecord": {
     "template": "feriados",
     "recordId": "1a4d93d4-68fd-4d6b-b966-79e73944d7be"
   },
   "result": "SUCCESS"
},
"createdAt": "2025-10-27T18:41:43.287+0000"
    }
  • Tipo de Results: SUCCESS, FAILURE.

Gerenciamento da Sincronização​

A Interface do Cadastro Único​

Na tela do Cadastro Único, é possível visualizar o status dos resources configurados para a entidade/sistema e o conteúdo que está sendo sincronizado. É nesta interface que o usuário pode gerenciar o fluxo de sincronização.

Configuração e Tipos de Sincronização​

Para cada resource, é possível definir como as sincronizações de outros sistemas serão tratadas. As opções são:

  • Sempre sincronizar: A atualização é aplicada de forma automática.

  • Nunca sincronizar: A atualização vinda de outros sistemas é ignorada.

Gerar pendência: A sincronização fica pendente de uma aprovação manual do usuário.Essa configuração pode ser feita tanto para o cadastro inteiro quanto para campos específicos dentro dele.

Nota

Por padrão, se nenhuma regra for definida para um Vínculo de Sincronização, o comportamento adotado é "Nunca sincronizar". É importante que o usuário final revise essa configuração na interface do Cadastro Único para permitir o fluxo de dados.

Resolvendo Pendências Cadastrais​

Quando uma sincronização está configurada para "Gerar pendência", ela aparece na tela do Cadastro Único aguardando uma ação. O usuário deve analisar as alterações propostas e decidir se aceita ou rejeita a sincronização. Somente após a "resolução" da pendência (aceite), a sincronização é de fato concluída e, no caso do parceiro, o evento final é disparado.

Anexos e Referências Técnicas​

https://speakerdeck.com/bobbycalderwood/commander-better-distributed-applications-through-cqrs-event-sourcing-and-immutable-logs?slide=16

https://studio.ajuda.betha.cloud/aplicacoes/cadastro-unico/envio-recepcao-comandos#recep%C3%A7%C3%A3o-de-comandos

Apêndice A: Gestão de Modelos de Cadastro e Campos Adicionais​

Definição e manutenção dos Modelos de Cadastro​

Os Modelos de Cadastro (Templates) são definidos e mantidos exclusivamente pela Betha Sistemas para garantir a padronização dos dados trocados na plataforma. Aos sistemas parceiros, cabe a adesão aos modelos existentes. Não é previsto que o parceiro crie ou modifique os Modelos de Cadastro.

Tratamento de Campos Adicionais no Sistema Parceiro​

Sistemas parceiros podem possuir campos em seus cadastros que não existem nos Modelos de Cadastro da Betha. O tratamento para esses casos depende da necessidade de sincronização do campo.

  • Cenário A: Campos para Uso Interno Se o campo adicional é de uso exclusivo do sistema parceiro e sua informação não precisa ser compartilhada, ele não deve ser incluído nos dados de sincronização. A troca de informações com o Cadastro Único se restringirá aos campos definidos no Modelo de Cadastro.

  • Cenário B: Campos que Requerem Sincronização Se um campo adicional precisa ser sincronizado com os sistemas Betha, o parceiro deve formalizar uma solicitação de alteração à equipe de produto da Betha. Se aprovada, a Betha Sistemas será responsável por criar uma nova versão do Modelo de Cadastro que inclua o campo solicitado. O parceiro deverá, então, adaptar sua integração para a nova versão do modelo.

Apêndice B: Comportamento esperado do Sistema Parceiro ao receber eventos​

Para garantir uma integração segura, robusta e resiliente, o sistema parceiro deve seguir as seguintes práticas obrigatórias ao processar os eventos recebidos do Cadastro Único:

Validação de Autenticidade da Requisição​

O evento recebido virá com um cabeçalho x-betha-signature. Este cabeçalho contém uma assinatura de segurança (JWT) gerada com o secretToken informado na inscrição do Vínculo de Sincronização. É fundamental e obrigatório que o sistema parceiro valide esta assinatura para garantir que a requisição é autêntica e que sua origem é o Cadastro Único Betha. Requisições com assinatura inválida devem ser descartadas.

Confirmação de Processamento (Status HTTP 200)​

Após receber e processar um evento com sucesso, a API do parceiro deve retornar o status HTTP 200 (OK). Este retorno é a confirmação para o Cadastro Único de que a sincronização daquele evento foi concluída. Qualquer outro código de status (erros 4xx ou 5xx) ou a falta de resposta (timeout) será interpretado como falha. Em caso de falha, o Cadastro Único interromperá o envio de novas atualizações para aquele registro específico, a fim de manter a ordem cronológica e a consistência dos dados, até que o problema de processamento no sistema parceiro seja resolvido.

Garantia de Processamento Único (Idempotência)​

A plataforma garante a entrega "pelo menos uma vez", o que significa que, em certas condições de rede ou instabilidade, um mesmo evento pode ser enviado mais de uma vez. Para evitar a duplicação de dados, o sistema parceiro deve ser idempotente. Isso é alcançado utilizando o campo changesetId, presente em cada evento. O sistema deve verificar este identificador e ignorar qualquer evento cujo changesetId já tenha sido processado anteriormente.

Checklist de Integração​

Etapa 1: Configuração e Credenciamento

[ ] 1. Criar o Projeto de serviço no Studio Aplicações.
[ ] 2. Adicionar as APIs necessárias ao projeto (Cadastro Único e sistemas Betha).
[ ] 3. Solicitar a liberação do sistema parceiro para a entidade desejada.
[ ] 4. Obter os tokens de acesso (access_token e user_access) para autenticação.

Etapa 2: Implementar Recebimento de Dados

[ ] 1. Disponibilizar um endpoint (API) para o recebimento dos eventos.
[ ] 2. Realizar a chamada de cadastro do Resource, informando o templateId e a URL do endpoint.
[ ] 3. Garantir que o endpoint siga as práticas obrigatórias de processamento (ver Apêndice B).
[ ] 4. Assegurar o armazenamento do recordId recebido em cada evento.

Etapa 3: Implementar Envio de Dados

[ ] 1. Mapear as ações no sistema que devem originar um envio de dados.
[ ] 2. Estruturar os dados para envio conforme a API de commands.
[ ] 3. Realizar a chamada de envio para novos registros (CREATE) e para atualizações (UPDATE).

Etapa 4: Testes e Validação (ver Seção 4)

[ ] 1. Testar o fluxo de recebimento de dados (alteração no sistema Betha deve gerar um evento).
[ ] 2. Testar o fluxo de envio de dados (alteração no sistema parceiro deve gerar uma pendência).
[ ] 3. Validar o ciclo completo de sincronização, incluindo a aprovação de pendências na interface.

CRIAR CREDENCIAL E CONFIGURAR ENTIDADE A SER SINCRONIZADA.​

1.1 Acessar a entidade da prefeitura no Studio

parceiros

1.2 Acessar o time

parceiros

1.3 Criar o projeto em (+projeto)

parceiros

1.4 No exemplo o nome do projeto é Parceiro (Esse é o nome do sistema que vai ser integrado)

parceiros

1.5 Projeto criado, próximo passo é configuração do projeto.

parceiros

1.6 Configurações do projeto, próximo passo é credenciais

parceiros

1.7 Criar uma credencial do tipo serviço.

parceiros

1.8 Adicionar os escopos (pesquisar na betha STORE)

parceiros

1.9 Adicionar os produtos com os quais deseja interagir.

parceiros

1.10 Produto Cadastro Único é obrigatório.

parceiros

1.11 Vamos usar os tributos como exemplo.

parceiros

1.12 Projetos adicionais, próximo passo cadastrar a chave pública

parceiros

1.13 No módulo de Utilitários > Autorizações > Aplicações

parceiros

1.14 +APLICAÇÃO e cole a chave a chave pública copiada do Studio

parceiros

1.15 Continuar e obter chave de acesso

parceiros

1.16 Feito a solicitação, agora acessando o USER ACCESS vai ter a entidade cadastrada.

parceiros

FLUXO DE INTEGRAÇÃO E PAINEL DO CADASTRO ÚNICO​

2.1 Parceiro quer ser notificado quando um cadastro foi criado ou alterado em um sistema Betha (ex. Feriado no Tributos)

Após concluída a etapa 1, deve ser solicitado a Betha a liberação deste sistema para a entidade a ser integrada, com isso podemos acessar a interface do cadastro único e a configuração de acesso.

parceiros

2.2 Adicionar qual o cadastro será integrado, no exemplo vamos integrar o cadastro de feriados do tributos ao sistema parceiro. (API Resource)

parceiros

2.3 Após o envio do Resource

parceiros

2.4 Recebendo uma atualização

parceiros

2.5 Configurações

parceiros

2.6 Configurar como deseja receber os dados por campos.

parceiros

2.7 Sincronização dos dados

parceiros

parceiros

2.8 Podemos configurar como o dado será recebido, caso queira que o campo sempre fique pendente, essa configuração pode ser personalizada para sistemas também.

parceiros