Integração CMP

Visão geral

A Case Management Platform (CMP) é o módulo da Suíte Guardline responsável pela gestão de casos que exigem análise humana. A integração com a CMP permite que sistemas externos abram casos programaticamente em cada mesa de análise, acompanhem o desfecho e recebam notificações sobre os eventos relevantes do ciclo de vida.

O modelo segue uma separação clara de responsabilidades: o motor da instituição detecta e abre o caso; a Guardline enfileira, distribui, analisa e decide. A instituição não precisa conhecer filas, alçadas ou SLAs para integrar: envia o alerta com o identificador de origem e recebe de volta o identificador do caso.

Mesas e portas de entrada

Cada mesa da CMP possui um endpoint próprio de ingestão. Todos recebem JSON por POST e são autenticados por um token de API com escopo restrito àquela mesa.

Mesa	Origem típica	Endpoint	Escopo do token
Fraude	Motor de prevenção a fraude (FPP ou terceiro)	/api/v1/ingest/fraude	ingest:fraude
MED	Solicitações do Mecanismo Especial de Devolução	/api/v1/ingest/med	ingest:med
PLD	Motor de monitoramento de lavagem de dinheiro	/api/v1/ingest/pld	ingest:pld
Cadastro PF e Cadastro PJ	Onboarding (ONP ou motor de decisão próprio)	/api/v1/ingest/kyc	ingest:kyc

O endpoint de onboarding atende tanto pessoas físicas (KYC, incluindo menores com representante legal) quanto pessoas jurídicas (KYB); a mesa é escolhida pelo tipo de jornada informado no payload.

Compatibilidade com motores externos

A CMP aceita casos de qualquer origem. Instituições que utilizam motor de decisão próprio (ou de terceiros) enviam os alertas diretamente para a mesa correspondente, e a CMP opera filas, alçadas, SLAs, comitê e trilha de auditoria da mesma forma que opera com os casos gerados pelos demais módulos da Suíte Guardline.

Essa característica permite que a instituição centralize a gestão de casos em um único ambiente, independentemente de quantos motores de decisão estejam em operação.

Fluxo de integração

O fluxo típico de integração com a CMP segue estas etapas:

1. O administrador da CMP cria um token de API com o escopo da mesa e o entrega ao sistema de origem.
2. O sistema de origem (motor de decisão, FPP, ONP ou outro) envia o alerta para o endpoint da mesa, informando o identificador do evento na origem e os dados do contexto.
3. A CMP valida o payload, aplica idempotência sobre o identificador de origem, calcula risco e SLA conforme a política da mesa e devolve o identificador do caso.
4. O motor de distribuição atribui o caso a um analista disponível na fila de entrada da mesa.
5. O analista revisa o dossiê e registra a decisão (aprovar, reprovar, pendenciar, escalar, transferir para outra mesa ou convocar comitê), sempre com justificativa.
6. O desfecho retorna ao sistema de origem: via ONP, para casos de onboarding; via webhook assinado, para os eventos da mesa PLD.

Autenticação

Os endpoints de ingestão exigem o header X-API-Key com um token de API no formato cmp_ seguido de 64 caracteres hexadecimais. Os tokens são criados pelo administrador da instituição no painel da CMP, com escopo por mesa, limite de requisições por janela de tempo e validade opcional. O valor do token é exibido uma única vez, na criação; a plataforma armazena apenas o hash.

Credencial ausente ou inválida responde 401; token válido com escopo de outra mesa responde 403; limite de requisições excedido responde 429. Toda rejeição fica registrada na trilha de auditoria com origem, caminho e motivo. Um token pode ser emitido com o escopo genérico ingest, que atende as quatro mesas; esse é o escopo aplicado quando nenhum outro é informado na criação.

O endpoint de onboarding pode exigir, adicionalmente, uma assinatura HMAC-SHA256 do corpo da requisição (headers X-Guardline-Timestamp e X-Guardline-Signature), habilitada por instância durante o setup da integração. É o mesmo formato de assinatura usado pelos webhooks da ONP.

Idempotência

Cada endpoint deduplica sobre uma chave natural escolhida pelo sistema de origem: external_id na mesa de Fraude, alerta_externo_id na mesa PLD e o identificador da execução de onboarding (ou case_id) nas mesas de Cadastro. A mesa MED usa o primeiro campo presente entre id, event_id, notification_id e med_id; sem nenhum deles, a chave passa a ser um hash do corpo da requisição, que não sobrevive a nenhuma variação de serialização e por isso não substitui um identificador próprio. A primeira chamada cria o caso e responde 201; reenvios respondem 200 com o identificador do caso existente, sem sobrescrever nada. Isso torna seguro repetir a chamada após um timeout de rede.

Na mesa PLD há uma regra adicional: um alerta novo para um CPF ou CNPJ que já possui caso ativo é consolidado nesse caso em vez de abrir outro. A exceção é a COE (comunicação de operação em espécie): movimentações em espécie a partir de R$ 50.000,00, quando o sistema de origem as identifica como operação em espécie, abrem sempre um caso próprio, sem consolidação, e pulam a triagem.

Retorno das decisões

O caminho pelo qual a decisão do analista chega ao sistema de origem depende da mesa:

• Cadastro PF e Cadastro PJ (onboarding): a CMP devolve à ONP as decisões terminais, de aprovação e de reprovação, e a ONP retoma a execução e emite os seus próprios eventos de onboarding para a instituição. Quem integra ONP e CMP consome um único fluxo de webhooks, o da ONP. Decisões intermediárias, como escalar ou solicitar informação adicional, permanecem na CMP e não geram evento na ONP.
• PLD: as transições do fluxo (arquivamento em triagem, deliberação do comitê, registro, erro, retificação e cancelamento da comunicação ao COAF) são publicadas por webhook assinado para os receptores configurados.
• Fraude e MED: a decisão, seus efeitos operacionais e a justificativa ficam registrados no detalhe do caso e na trilha de auditoria da CMP. A publicação por webhook para essas mesas é habilitada sob demanda no setup da integração.

Notificações

Os webhooks de saída da CMP carregam um envelope único (event, delivery_id, correlation_key, case_id, attempt, timestamp, payload), são assinados com HMAC-SHA256 sobre o corpo bruto (header X-Webhook-Signature) e identificam o evento e a entrega em headers próprios, o que permite roteamento e deduplicação sem interpretar o corpo. Entregas sem resposta 2xx em 10 segundos são repetidas duas vezes, a partir de uma caixa de saída persistente drenada a cada 60 segundos: a segunda tentativa entra na drenagem seguinte e a terceira ao menos 30 segundos depois. Esgotadas as três, a entrega é encerrada como falha, e o reenvio é feito sob demanda pela operação da Guardline.

A configuração de quais eventos receber, a URL de destino e o segredo de assinatura são definidos durante o setup da integração, conforme descrito nos conceitos de integração.

Referência da API

Os contratos completos (campos de cada endpoint, regras de derivação de risco e prioridade, exemplos, códigos de erro, administração de tokens e verificação dos webhooks) estão na referência da API da CMP.