Pular para o conteúdo principal

Envio e recepção de comandos

Envio e recepção de comandos​

O Templates implementa o Commander Pattern. Todas as operações suportadas pelo serviço são executadas mediante o envio de comandos. Um comando representa a intenção de executar uma operação que altera o estado da aplicação.

Envio de updates​

A criação ou atualização de um registro é efetuada através do envio de um comando de update. Um comando de update possui as seguintes informações:

  • id: Identificador único do comando (UUID v4), utilizado para consultar o resultado de seu processamento.
  • action: Tipo do comando enviado (UPDATE).
  • data: Dados do comando.

O campo data para o comando de update possui as seguintes informações:

  • template: O template ao qual o comando se refere.
  • aggregate: O agregado que sofreu a alteração no sistema, definido na configuração do resource.
  • id: O ID do registro enviado.
  • user: O usuário que atualizou o registro dentro do sistema.
  • data: A representação completa do registro atualizado, no formato JSON, seguindo o schema do template.

Abaixo, um exemplo de requisição de envio de comando de update:

    POST /api/v2/commands HTTP/1.1 <br/>
    Host: https://plataforma-cadastro-unico.betha.cloud 
    Authorization: Bearer <TOKEN> 
    User-Access: <USER_ACCESS>
    Content-Type: application/json
{
    "id": "ac157642-de39-11e9-8a34-2a2ae2daaa12",
    "data": {
        "template": "pessoas",
        "aggregate": "funcionario",
        "id": "ac1578ea-de39-11e9-8a34-2a2ae2dbaa11",
        "user": "meu.usuario",
        "data": {
            "nome": "João da Silva"
        }
    },
    "action": "UPDATE"
}

É possível realizar a consulta da situação de um comando enviado, utilizando a seguinte requisição:

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

Recepção de comandos​

A recepção de comandos ocorre por meio de webhooks, que devem ser configurados via resource.

Conteúdo do webhook​

O evento que será recebido no endereço configurado possui a seguinte estrutura:

  • changesetId: Identificador da pendência cadastral que gerou a alteração.
  • metadata: Metadados do evento.
    • templateRecord: Dados do template.
      • template: Template ao qual o evento se refere.
      • recordId: O ID do registro onde as alterações devem ser aplicadas.
    • database: Database do registro.
    • user: Usuário que efetuou a modificação no sistema de origem.
    • resource: Dados do resource.
      • system: O sistema de destino que deve processar o evento.
      • aggregate: A identificação do agregado que sofreu a alteração no sistema, definido na configuração do resource.
  • data: A representação completa do registro no serviço de Templates atualmente.
  • diff: As operações que devem ser aplicadas sobre o registro no sistema, no formato JSON Patch.

O evento recebido também dispõe de um cabeçalho (x-betha-signature) contendo a assinatura da requisição. Essa assinatura utiliza o padrão JWT com o algoritmo HMAC SHA-256. É utilizado como chave o secret token configurado no cadastro do resource. Com essa assinatura, é possível garantir que o comando recebido é proveniente de uma fonte segura, dado que somente o dono do resource e o Cadastro Único conhecem este token. O tamanho mínimo para o secret token é de 32 caracteres.

Retorno do processamento​

O retorno do processamento do comando precisa ser um status code HTTP 200, indicando que o registro foi processado com sucesso. O retorno de qualquer outro status code marcará o webhook como falha, ou seja, a situação do webhook será igual a ERROR. O motivo de uma falha no envio de um webhook pode ser observado no atributo processMessage.

Ordem de processamento​

Para garantir que a situação de um cadastro reflita o mesmo estado entre todos os sistemas, é fundamental que os comandos sejam processados em ordem. Sendo assim, os webhooks são enviados respeitando a ordem cronológica das alterações efetuadas nos sistemas. Caso um webhooks_seja marcado como falha, o envio de novos _webhooks para o registro em questão é interrompido até que o motivo da falha seja resolvido. Uma tentativa de envio dessas falhas é efetuada cada vez que uma nova atualização é recebida para o registro.

Apesar da garantia de ordem, não é garantida a entrega única do evento. Isso significa que um mesmo webhook pode ser enviado mais de uma vez. Sendo assim, é importante que o processamento seja idempotente, ou seja, possa ser executado mais de uma vez. Uma forma de identificar um comando já processado é utilizando o identificador changesetId.

Listagem de webhooks​

A requisição abaixo lista todos os eventos de webhooks existentes para o sistema da credencial:

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

Reenvio de webhooks​

Uma tentativa de envio dos webhooks marcados como falha é efetuada cada vez que uma nova atualização é recebida para o registro em questão. Além disso, é possível disparar uma nova tentativa de envio manualmente, através da API de gerenciamento.

A requisição abaixo demonstra como solicitar o reenvio de um webhooks com falha:

    PUT /api/v2/webhook/<ID DO WEBHOOK>/retry HTTP/1.1
    Host: https://plataforma-cadastro-unico.betha.cloud
    Authorization: Bearer <TOKEN>
    Content-Type: application/json