> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/integracao-embedded.md).

# Integração Embedded

Widget que roda o fluxo de consignado dentro do seu site (**iframe**) ou app (**WebView**), sem redirecionamento. Ele exibe só o fluxo de originação, avisa seu sistema dos eventos (conclusão, erro, expiração) e pede ao seu app que abra URLs externas (assinatura digital, termos).

***

## Pré-requisitos

| Item                      | Descrição                                                                                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`baseUrl`**             | URL do webapp, entregue no onboarding (ex: `https://cliente.consignado.giro.tech`). Cada originador tem a sua, com a própria identidade visual, e é identificado por ela. |
| **`publicId`** (opcional) | Identificador público do colaborador. Com ele, o fluxo começa direto; sem ele, o widget exibe o cadastro (CPF, nome, telefone) e segue normalmente.                       |
| **Domínio autorizado**    | Seu domínio liberado no CSP; peça à equipe de integração                                                                                                                  |

{% hint style="success" %}
**Recomendado:** cadastre o colaborador antes, server-to-server, e abra o widget já com o `publicId`: ele entra direto no fluxo, sem preencher cadastro.
{% endhint %}

***

## Integração Web (iframe)

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

O SDK `gt-embed.js` cria o iframe e trata os eventos.

**1. Adicione um container na sua página:**

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

**2. Carregue o SDK e inicialize o widget:**

```html
<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:**

```javascript
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)

Monte o iframe e escute os eventos você mesmo.

**Com `publicId` (colaborador existente):**

```html
<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):**

```html
<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>
```

{% hint style="warning" %}
Sempre valide `event.origin` das mensagens `postMessage`, para ignorar mensagens de terceiros.
{% endhint %}

***

## Integração Mobile (WebView)

### Android — Kotlin

```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")
```

{% hint style="info" %}
O bridge **deve** se chamar `AndroidBridge`.
{% endhint %}

***

### iOS — Swift (WKWebView)

```swift
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))
```

```swift
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
        }
    }
}
```

{% hint style="info" %}
O message handler **deve** se chamar `gtBridge` (`webkit.messageHandlers.gtBridge`).
{% endhint %}

***

### React Native

```jsx
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 }}
    />
  );
}
```

{% hint style="info" %}
O widget envia as mensagens por `window.ReactNativeWebView.postMessage()`.
{% endhint %}

***

## Referência de Eventos

Formato de todos os eventos:

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`) |

{% hint style="warning" %}
O handler de `gt:open_url` é **obrigatório**: sem ele, a assinatura digital não funciona no embedded.
{% endhint %}

***

## Fluxo do Usuário

```
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

Logotipo, cores e nome da marca são configurados pela equipe de integração no onboarding. Não há personalização por código.

***

## 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                    |

***

## Checklist de 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)

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
