Guia Funcional e Operacional

1. Contexto e Objetivo

O módulo Bluebonus do sistema Blueopex é utilizado para registro e calculo de remunerações extras devidas aos colaboradores ao longo do mês. Ao final de cada ciclo, é gerado um relatório com todas as atividades registradas, e o sistema calcula o valor que cada pessoa deverá receber com base nas parametrizações sindicais e contratuais vigentes.

A funcionalidade de Webhook foi desenvolvida a partir de uma demanda da Oceanpact, que necessitava de integração entre o BlueBonus e o sistema de pagamento RM (Totvs RM Labore). O BlueBonus passa a ser responsável por enviar as informações de pagamento de gratificações para o sistema RM, utilizado para gerenciar a folha de pagamento da organização..

2. O que é um Webhook

Webhook e um mecanismo amplamente utilizado em plataformas de software para comunicar sistemas de terceiros sobre determinados eventos em tempo real. Em vez de o sistema externo consultar periodicamente o Bluebonus em busca de atualizações (modelo pull), o Bluebonus envia automaticamente as informações para o sistema configurado no momento em que o evento ocorre (modelo push).

3. Fluxo Operacional

Abaixo está descrito o fluxo completo, desde o trabalho operacional dos embarcadores até o disparo das informações via Webhook:

• Os embarcadores e analistas de logística operam o sistema ao longo do mês, registrando embarques, desembarques e atividades que gerem remuneração extra.
• Ao final do mês (ou início do período de pagamento), o time de pagamento acessa o sistema e inicia o fluxo de avaliação e aprovação do relatório de bonus.
• Quando o relatório e aprovado dentro do modulo de Bonus, o sistema verifica se existe uma configuração de Webhook habilitada.
• Caso habilitado, o sistema adiciona automaticamente o relatório na fila de envio e dispara os dados de pagamento para o endpoint (URL) configurado do sistema externo.
• Caso desabilitado o envio automático, o usuário precisara clicar manualmente no botão de envio para integrações disponível no relatório aprovado.

4. Configuração do Webhook

A área de configuração do Webhook permite cadastrar os sistemas externos que devem ser notificados. Os principais parâmetros de configuração são descritos a seguir.

4.1 Autenticação

O sistema oferece 3 padrões de autenticação reconhecidos no mercado. Para a integração com RM, será utilizado o padrão Basic Authentication (usuário e senha).

4.2 URL de Destino (Endpoint)

E o endereço (URL) do sistema receptor, ou seja, para onde os dados de pagamento serão enviados assim que o relatório for aprovado. Esse campo deve ser preenchido com o endpoint fornecido pelo sistema externo (no caso da Oceanpact, o endpoint do RM).

4.3 Envio Automatico

Checkbox que determina o comportamento do sistema após a aprovação do relatório:

• Habilitado: o relatório e adicionado automaticamente na fila de envio e os dados são disparados sem intervenção manual.
• Desabilitado: o envio não ocorre automaticamente. O usuário precisara clicar explicitamente no botão de envio para integrações na tela do relatório aprovado.

4.4 Modo de Envio (Linha a Linha ou Lote)

Um colaborador embarcado pode acumular múltiplas gratificações em um mesmo período, como dias embarcados, dobras, entre outras. Isso significa que um único relatório pode gerar dezenas, centenas ou até mais de 10.000 registros.

O sistema oferece dois modos de envio para lidar com esse volume:

4.5 Formato de Envio

Define o formato do corpo da requisição. Atualmente o formato JSON está implementado e disponível para uso. O formato XML e tecnicamente possível, mas não foi desenvolvido nesta primeira etapa por não ser necessário para o cenário atual.

4.6 Método HTTP

Define qual método HTTP será utilizado para disparar a requisição ao endpoint configurado. Os métodos disponíveis são os mais comuns em integrações via API REST: GET, POST, PUT. Para a grande maioria dos cenários de integração, o método utilizado será POST, pois o sistema receptor espera receber os dados de pagamento como um novo registro a ser processado

4.7 Ativar Webhook

Checkbox que determina se a configuração de Webhook está ativa e disponível para uso. Quando habilitado, o Webhook está apto a realizar envios conforme os gatilhos configurados. Quando desabilitado, a configuração fica inativa e nenhum envio será realizado, mesmo que o relatório seja aprovado. Esse controle é útil para pausar temporariamente uma integração sem precisar excluir toda a configuração.

4.8 Autenticações de Webhook

Lista as autenticações já cadastradas no submenu "Autenticação Webhook" e vincula uma delas à configuração atual. Ou seja, antes de configurar um Webhook, o usuário deve primeiro cadastrar as credenciais de acesso na área de autenticação (usuário e senha, por exemplo), e aqui ele seleciona qual dessas autenticações será utilizada para assinar as requisições disparadas por esta configuração.

5. Mapeamento de Campos

O mapeamento de campos e a parte central da configuração do Webhook. E aqui que o usuário define quais informações do Bluebonus serão enviadas para o sistema externo e com quais nomes esses campos devem aparecer no payload.

A lógica funciona da seguinte forma:

• Campo de destino: nome do campo esperado pelo sistema receptor (ex: company_code, chapa, mes_inicio).
• Valor de origem: propriedade do sistema Bluebonus que será utilizada para preencher aquele campo (ex: matrícula do colaborador, data inicial do relatório formatada como mes).

É possível também aplicar formatações nos valores antes do envio. Por exemplo, a data inicial do relatório pode ser enviada formatada apenas com o ano, ou apenas com o mês, dependendo do que o sistema receptor espera.

Ao final do mapeamento, o sistema exibe um preview do payload que será enviado, permitindo que o usuário valide o formato e os valores antes de realizar o primeiro envio.

6. Envio Manual pelo Relatório

Quando o envio automático está desabilitado, ou em casos em que seja necessário reenviar os dados, o usuário pode acionar o envio diretamente pela tela do relatório aprovado.

No relatório aprovado, existe um botão específico de envio para integração. Ao clicar nesse botão, o sistema processa o relatório e dispara os dados para o endpoint configurado, seguindo todas as configurações de autenticação, formato e modo de envio definidas anteriormente.

O sistema também registra um log de envio, que permite acompanhar o histórico de requisitos realizadas para aquele relatório.

7. Observações Técnicas e Limitações Atuais

Pontos de atenção que a equipe deve ter conhecimento ao apresentar ou configurar a funcionalidade:

• O formato XML não está disponível nesta versão. Se um cliente solicitar envio em XML, e tecnicamente viável desenvolver, mas não foi implementado ainda.
• O envio linha a linha pode ser mais demorado em relatórios com alto volume de registros (acima de 10.000 linhas). Isso e esperado e alinhado com o funcionamento do sistema receptor do cliente.

8. Glossario

Blue Bonus - Documentacao Interna | Uso Restrito