Integração Embedded

Integre o fluxo de empréstimo consignado diretamente no seu site ou aplicativo. O widget embedded oferece uma experiência nativa para o seu usuário sem redirecionamentos externos.

---

Como funciona

Ao integrar o widget, o fluxo completo de empréstimo consignado é renderizado dentro do seu ambiente — seja em uma página web via iframe ou dentro de um app nativo via WebView.

O widget:

• Exibe apenas o fluxo de originação (sem menus, headers ou footers extras)

• Comunica eventos de ciclo de vida ao seu sistema (conclusão, erro, expiração)

• Delega a abertura de URLs externas (assinatura digital, termos) ao seu app

---

Pré-requisitos

Item	Descrição
baseUrl	URL base do webapp fornecida durante o onboarding (ex: https://cliente.consignado.giro.tech). Cada originador possui uma URL dedicada com sua identidade visual.
publicId (opcional)	Identificador público do colaborador. Se informado, o widget inicia o fluxo direto para o colaborador. Se omitido, o widget exibe o formulário de cadastro.
Domínio autorizado	Seu domínio precisa estar liberado no CSP do servidor — solicite à equipe de integração

Como funciona a identificação

• Originador — cada originador possui um deploy exclusivo com URL, logotipo, cores e marca próprios. O originador é identificado automaticamente pela baseUrl.

• Colaborador (publicId) — identificador único do colaborador no sistema.

Recomendado: cadastre o colaborador previamente via API server-to-server (POST /v1/origination/employees) e abra o widget já com o publicId. Isso oferece a melhor experiência ao usuário — ele entra direto no fluxo sem precisar preencher cadastro.

Se não for possível obter o publicId antecipadamente, o widget também funciona sem ele. Nesse caso, o próprio widget exibirá o formulário de cadastro (CPF, nome, telefone) e, após o registro, seguirá o fluxo normalmente.

---

Integração Web (iframe)

Opção 1 — Usando o SDK (recomendado)

O SDK gt-embed.js abstrai a criação do iframe e o gerenciamento de eventos.

1. Adicione um container na sua página:

<div id="gt-container" style="width: 100%; min-height: 600px;"></div>

2. Carregue o SDK e inicialize o widget:

<script src="https://cliente.consignado.giro.tech/gt-embed.js"></script>
<script>
  var widget = GTEmbed.init({
    containerId: 'gt-container',
    baseUrl: 'https://cliente.consignado.giro.tech',
    // publicId é opcional — sem ele, o widget exibe o cadastro do colaborador
    // publicId: 'PUBLIC_ID_DO_COLABORADOR',

    onReady: function () {
      console.log('Widget carregado e pronto');
    },

    onFlowComplete: function (data) {
      // Fluxo concluído com sucesso
      // data = { publicId, requestNumber, status }
      console.log('Proposta finalizada', data);
    },

    onFlowError: function (data) {
      // Erro durante o fluxo
      // data = { publicId, reason, message? }
      console.log('Erro no fluxo', data);
    },

    onAuthExpired: function () {
      // Sessão do usuário expirou
      console.log('Sessão expirada');
    },

    onOpenUrl: function (data) {
      // Widget solicita abertura de URL externa (ex: assinatura digital)
      // data = { url, target }
      window.open(data.url, data.target || '_blank');
    }
  });
</script>

3. Para remover o widget quando necessário:

widget.destroy();

Parâmetros do SDK

Parâmetro	Tipo	Obrigatório	Descrição
containerId	string	Sim	ID do elemento HTML onde o iframe será inserido
baseUrl	string	Sim	URL base do webapp
publicId	string	Não	Identificador público do colaborador. Se omitido, o widget exibe o cadastro.
style	object	Não	Estilos CSS customizados para o iframe
onReady	function	Não	Callback quando o widget está pronto
onFlowComplete	function	Não	Callback quando o fluxo é concluído
onFlowError	function	Não	Callback quando ocorre erro
onAuthExpired	function	Não	Callback quando a sessão expira
onOpenUrl	function	Não	Callback para abertura de URLs externas
onNavigate	function	Não	Callback para solicitação de navegação

Métodos retornados

Método	Descrição
destroy()	Remove o iframe e limpa os event listeners
getIframe()	Retorna o elemento <iframe> DOM

---

Opção 2 — Integração manual (sem SDK)

Se preferir controle total, monte o iframe e escute os eventos diretamente.

Com publicId (colaborador existente):

<iframe
  id="gt-widget"
  src="https://cliente.consignado.giro.tech/origination/embedded/SEU_PUBLIC_ID?embedded=true"
  style="width: 100%; min-height: 600px; border: none;"
  allow="clipboard-write"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-top-navigation-by-user-activation"
></iframe>

Sem publicId (novo colaborador — exibe cadastro):

<iframe
  id="gt-widget"
  src="https://cliente.consignado.giro.tech/origination/embedded?embedded=true"
  style="width: 100%; min-height: 600px; border: none;"
  allow="clipboard-write"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-top-navigation-by-user-activation"
></iframe>

<script>
  window.addEventListener('message', function (event) {
    // Validar origem da mensagem
    if (event.origin !== 'https://cliente.consignado.giro.tech') return;

    var data = event.data;
    if (!data || !data.type || data.type.indexOf('gt:') !== 0) return;

    switch (data.type) {
      case 'gt:ready':
        console.log('Widget pronto');
        break;
      case 'gt:open_url':
        window.open(data.payload.url, data.payload.target || '_blank');
        break;
      case 'gt:flow_complete':
        console.log('Concluído', data.payload);
        break;
      case 'gt:flow_error':
        console.log('Erro', data.payload);
        break;
      case 'gt:auth_expired':
        console.log('Sessão expirada');
        break;
    }
  });
</script>

Sempre valide a origem (event.origin) das mensagens recebidas via postMessage para evitar processamento de mensagens de terceiros.

---

Integração Mobile (WebView)

Android — Kotlin

val webView = findViewById<WebView>(R.id.webView)
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true

webView.addJavascriptInterface(object {
    @JavascriptInterface
    fun postMessage(message: String) {
        val json = JSONObject(message)
        when (json.getString("type")) {
            "gt:open_url" -> {
                val url = json.getJSONObject("payload").getString("url")
                startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url)))
            }
            "gt:flow_complete" -> {
                val payload = json.getJSONObject("payload")
                // payload.getString("publicId")
                // payload.getString("requestNumber")
                // payload.getString("status")
            }
            "gt:flow_error" -> {
                val payload = json.getJSONObject("payload")
                // payload.getString("reason")
            }
            "gt:auth_expired" -> {
                // Sessão expirou — recarregar ou redirecionar
            }
        }
    }
}, "AndroidBridge")

// Com publicId (colaborador existente):
webView.loadUrl("https://cliente.consignado.giro.tech/origination/embedded/SEU_PUBLIC_ID?embedded=true")
// Sem publicId (novo colaborador):
// webView.loadUrl("https://cliente.consignado.giro.tech/origination/embedded?embedded=true")

O nome do bridge deve ser AndroidBridge. O widget detecta automaticamente essa interface.

---

iOS — Swift (WKWebView)

import WebKit

let config = WKWebViewConfiguration()
let contentController = WKUserContentController()

contentController.add(self, name: "gtBridge")
config.userContentController = contentController

let webView = WKWebView(frame: view.bounds, configuration: config)
// Com publicId (colaborador existente):
let url = URL(string: "https://cliente.consignado.giro.tech/origination/embedded/SEU_PUBLIC_ID?embedded=true")!
// Sem publicId (novo colaborador):
// let url = URL(string: "https://cliente.consignado.giro.tech/origination/embedded?embedded=true")!
webView.load(URLRequest(url: url))

extension ViewController: WKScriptMessageHandler {
    func userContentController(
        _ userContentController: WKUserContentController,
        didReceive message: WKScriptMessage
    ) {
        guard let body = message.body as? [String: Any],
              let type = body["type"] as? String else { return }

        switch type {
        case "gt:open_url":
            if let payload = body["payload"] as? [String: Any],
               let urlString = payload["url"] as? String,
               let url = URL(string: urlString) {
                UIApplication.shared.open(url)
            }
        case "gt:flow_complete":
            // Tratar conclusão
            break
        case "gt:flow_error":
            // Tratar erro
            break
        case "gt:auth_expired":
            // Sessão expirou
            break
        default:
            break
        }
    }
}

O nome do message handler deve ser gtBridge. O widget detecta automaticamente o webkit.messageHandlers.gtBridge.

---

React Native

import { WebView } from 'react-native-webview';
import { Linking } from 'react-native';

function ConsignadoWidget({ publicId }) {
  const base = 'https://cliente.consignado.giro.tech/origination/embedded';
  const uri = publicId ? `${base}/${publicId}?embedded=true` : `${base}?embedded=true`;

  const handleMessage = (event) => {
    const data = JSON.parse(event.nativeEvent.data);

    switch (data.type) {
      case 'gt:ready':
        break;
      case 'gt:open_url':
        Linking.openURL(data.payload.url);
        break;
      case 'gt:flow_complete':
        // data.payload = { publicId, requestNumber, status }
        break;
      case 'gt:flow_error':
        // data.payload = { publicId, reason, message? }
        break;
      case 'gt:auth_expired':
        break;
    }
  };

  return (
    <WebView
      source={{ uri }}
      onMessage={handleMessage}
      javaScriptEnabled
      domStorageEnabled
      style={{ flex: 1 }}
    />
  );
}

O widget detecta automaticamente o bridge ReactNativeWebView e envia mensagens via window.ReactNativeWebView.postMessage().

---

Referência de Eventos

O widget comunica mudanças de estado via eventos. Todos seguem o formato:

{
  "type": "gt:<evento>",
  "payload": { ... }
}

Eventos emitidos pelo widget

Evento	Payload	Quando é disparado
gt:ready	{ timestamp }	Widget carregou e está pronto para uso
gt:flow_complete	{ publicId, requestNumber, status }	Fluxo concluído com sucesso
gt:flow_error	{ publicId, reason, message? }	Erro durante o fluxo
gt:auth_expired	{ timestamp }	Token JWT expirou (HTTP 401)
gt:open_url	{ url, target }	Widget solicita abertura de URL externa
gt:navigate	{ url }	Widget solicita navegação do parent

Detalhes dos payloads

gt:flow_complete

{
  "type": "gt:flow_complete",
  "payload": {
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "requestNumber": "GTAB12CD34EF",
    "status": "contract_signed"
  }
}

Campo	Tipo	Descrição
publicId	string	Identificador público do colaborador
requestNumber	string	Número da proposta/contrato gerado
status	string	Status final do fluxo

gt:flow_error

{
  "type": "gt:flow_error",
  "payload": {
    "publicId": "Kj8mP2xQ9nR4sT6v",
    "reason": "no_margin_available",
    "message": "Colaborador não possui margem disponível"
  }
}

Campo	Tipo	Descrição
publicId	string	Identificador público do colaborador
reason	string	Código do erro
message	string?	Mensagem legível (opcional)

gt:open_url

{
  "type": "gt:open_url",
  "payload": {
    "url": "https://assinatura.exemplo.com.br/sign/xyz",
    "target": "_blank"
  }
}

Campo	Tipo	Descrição
url	string	URL a ser aberta
target	string?	_blank, _top ou _parent (padrão: _blank)

É obrigatório implementar o handler de gt:open_url. Sem ele, etapas como assinatura digital não funcionam em ambientes embedded.

---

Fluxo do Usuário

O widget conduz o colaborador por todas as etapas do empréstimo consignado:

CPF → Cadastro → Autorização → Margem → Simulação → Proposta → Contrato → Conclusão

Etapa	Descrição
CPF	Identificação do colaborador
Cadastro	Coleta de dados básicos (nome, telefone, e-mail)
Autorização	Autorização de consulta via assinatura digital
Margem	Consulta de margem consignável disponível
Simulação	Seleção de valor e condições do empréstimo
Proposta	Revisão dos termos
Contrato	Assinatura digital do contrato (CCB)
Conclusão	Confirmação — evento gt:flow_complete é emitido

---

Personalização Visual

O widget herda a identidade visual configurada para o convênio. Elementos como logotipo, cores e nome da marca são configurados pela equipe de integração durante o onboarding.

Não é necessária nenhuma personalização via código na integração embedded.

---

Resolução de Problemas

Sintoma	Causa provável	Solução
iframe em branco ou erro de CSP no console	Domínio não autorizado no frame-ancestors	Solicite a liberação do seu domínio à equipe de integração
window.open bloqueado	Popup blocker em iframe cross-origin	Implemente o handler onOpenUrl / gt:open_url
Assinatura digital não carrega	Provedor de assinatura rejeita iframe aninhado	Use onOpenUrl para abrir em janela/aba separada
Sessão perdida ao reabrir	sessionStorage não persiste entre abas	Comportamento esperado — o usuário refaz a autenticação
Eventos não chegam ao parent	Validação de origin incorreta	Confirme que está filtrando por event.origin === 'https://cliente.consignado.giro.tech'
Widget não detecta modo embedded	URL sem ?embedded=true	Use a rota /origination/embedded ou adicione ?embedded=true na URL

Para suporte técnico na integração, entre em contato com a equipe pelo canal fornecido durante o onboarding.

---

Checklist de Integração

Use este checklist para validar sua integração antes de ir para produção:

• Widget renderiza corretamente no container/WebView

• Evento gt:ready é recebido após carregamento

• Handler de gt:open_url implementado (abre URLs externas)

• Handler de gt:flow_complete implementado (captura conclusão)

• Handler de gt:flow_error implementado (captura erros)

• Handler de gt:auth_expired implementado (trata expiração)

• Testado em dispositivos/navegadores alvo

• Domínio de produção liberado no CSP (solicitar à equipe)

Central de Atendimento | Giro.TechGiro.Tech