Conceitos de integração
Visão geral
Seção intitulada “Visão geral”A Suíte Guardline expõe APIs REST para integração com os sistemas internos da instituição (core banking, ERP, CRM, sistemas legados). A comunicação entre a instituição e a plataforma segue padrões bem definidos que garantem segurança, rastreabilidade e consistência em todas as operações.
Esta seção descreve os conceitos que se aplicam a todas as integrações da suíte.
Padrões de comunicação
Seção intitulada “Padrões de comunicação”A integração com a Guardline utiliza dois padrões de comunicação complementares:
- Requisições da instituição para a Guardline: chamadas REST autenticadas, com payloads em JSON. A instituição envia dados (criação de onboardings, envio de transações, abertura de casos) e consulta resultados.
- Notificações da Guardline para a instituição: webhooks disparados pela plataforma quando eventos relevantes ocorrem (conclusão de verificação, decisão de caso, alerta de fraude). A instituição cadastra URLs de callback e seleciona quais eventos deseja receber.
Esses dois padrões se complementam. As chamadas REST são usadas para operações iniciadas pela instituição, enquanto os webhooks eliminam a necessidade de polling e garantem que a instituição seja informada de eventos em tempo real.
Autenticação
Seção intitulada “Autenticação”Todas as chamadas à API requerem autenticação via token Bearer obtido por meio do fluxo OAuth2 client credentials. A instituição recebe credenciais (client ID e client secret) durante o processo de contratação e as utiliza para obter tokens de acesso com escopo e validade definidos.
Os tokens devem ser renovados antes da expiração. A plataforma rejeita requisições com tokens inválidos ou expirados.
Ambientes
Seção intitulada “Ambientes”A plataforma disponibiliza dois ambientes isolados:
- Sandbox: ambiente de testes com dados sintéticos, disponibilizado após a assinatura do contrato. Replica a configuração de produção e permite validação da integração antes do go-live.
- Produção: ambiente operacional com dados reais.
Cada ambiente possui URLs e credenciais próprias. Dados criados em sandbox não afetam produção e vice-versa.
Formato de dados
Seção intitulada “Formato de dados”- Todas as requisições e respostas utilizam JSON (Content-Type
application/json, encoding UTF-8). - Datas seguem o formato ISO 8601 (exemplo:
2025-01-15T14:30:00Z). - Identificadores são strings opacas geradas pela plataforma.
Versionamento
Seção intitulada “Versionamento”A API segue versionamento por path. Mudanças que quebram compatibilidade são introduzidas em novas versões. A versão anterior permanece disponível por um período de transição comunicado com antecedência.
Webhooks
Seção intitulada “Webhooks”A Guardline notifica eventos relevantes via webhooks configuráveis. Cada notificação inclui uma assinatura HMAC que permite à instituição validar a autenticidade e integridade da mensagem antes de processá-la.
A configuração de webhooks envolve três elementos:
- URL de callback: endpoint da instituição que receberá as notificações.
- Eventos assinados: seleção dos tipos de evento que a instituição deseja receber.
- Segredo HMAC: chave compartilhada usada para gerar e validar a assinatura de cada notificação.
Cada módulo da suíte (ONP, FPP, CMP) possui seu próprio conjunto de eventos. Os detalhes de cada módulo estão nas respectivas páginas de integração.