> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Página de Onboarding Hospedada

> A maneira mais rápida de criar páginas de verificação de identidade otimizadas, hospedadas na Gu1 — na API KYC da gu1 para fluxos de verificação de identidade.

## Visão Geral

Nossa solução hospedada é uma página segura e totalmente personalizável de KYC e verificação de identidade que permite verificar seus clientes rapidamente sem código. A página de onboarding hospedada é a maneira mais rápida de começar com a verificação KYC.

<Info>
  **Design Mobile-Responsive**: A página hospedada é totalmente responsiva e otimizada para todos os dispositivos (desktop, tablet e mobile). Seus usuários terão uma experiência de verificação perfeita independentemente do dispositivo que usarem.
</Info>

## Como Funciona

```mermaid theme={null}
sequenceDiagram
    participant Client as Seu Cliente
    participant YourApp as Seu Backend
    participant Gu1API as Gu1 API
    participant HostedPage as Página Hospedada

    YourApp->>Gu1API: 1. Criar entidade pessoa (POST /api/entities)
    Gu1API-->>YourApp: ID da entidade

    YourApp->>Gu1API: 2. Criar validação KYC (POST /api/kyc/validations)
    Gu1API-->>YourApp: providerSessionUrl

    YourApp->>Client: 3. Enviar providerSessionUrl<br/>(Email, SMS, etc.)

    Client->>HostedPage: 4. Abrir providerSessionUrl
    HostedPage->>Client: Página de verificação personalizada

    Client->>HostedPage: 5. Fazer upload de documento e selfie
    HostedPage->>Gu1API: Processar verificação

    Gu1API->>YourApp: 6. Webhook (aprovado/rejeitado)
    YourApp->>YourApp: Atualizar status do usuário

    Client->>HostedPage: Ver status de conclusão
```

## Parâmetros de Personalização

Você pode personalizar a página de onboarding usando estes parâmetros:

### Personalização de Marca e Visual

<ParamField path="domain" type="string">
  A página web pode ser hospedada em seu próprio domínio
</ParamField>

<ParamField path="lang" type="string" default="en">
  O idioma padrão da página. Valores suportados: `en`, `es`, `pt`
</ParamField>

<ParamField path="icon" type="string">
  O ícone da página (favicon)
</ParamField>

<ParamField path="logo" type="string">
  O logo principal exibido na página
</ParamField>

### Personalização de Cores

Todos os parâmetros de cor aceitam códigos hexadecimais (ex., `#6366f1`):

<ParamField path="headersColor" type="string">
  Código hex para a cor dos cabeçalhos
</ParamField>

<ParamField path="paragraphsColor" type="string">
  Código hex para a cor dos parágrafos
</ParamField>

<ParamField path="supportTextsColor" type="string">
  Código hex para a cor dos textos de suporte
</ParamField>

<ParamField path="backgroundColor" type="string">
  Código hex para a cor de fundo
</ParamField>

<ParamField path="pillsColor" type="string">
  Código hex para a cor das pílulas
</ParamField>

<ParamField path="progressBarColor" type="string">
  Código hex para a cor da barra de progresso
</ParamField>

<ParamField path="primaryButtonColor" type="string">
  Código hex para a cor do botão primário
</ParamField>

<ParamField path="secondaryButtonColor" type="string">
  Código hex para a cor do botão secundário
</ParamField>

<ParamField path="selectorColor" type="string">
  Código hex para a cor do seletor
</ParamField>

<ParamField path="primaryButtonTextColor" type="string">
  Código hex para a cor do texto do botão primário
</ParamField>

<ParamField path="secondaryButtonTextColor" type="string">
  Código hex para a cor do texto do botão secundário
</ParamField>

<ParamField path="borderRadius" type="number">
  Raio da borda web. Número entre 0 e 50
</ParamField>

## Configuração de Regras de Validação

Você pode personalizar as regras de validação usando estes parâmetros:

### Verificação de Idade

<ParamField path="Exclude By Age" type="number">
  Rejeita automaticamente todas as sessões realizadas por usuários menores de certa idade. Número entre 1 e 100
</ParamField>

### Captura de Documentos

<ParamField path="Capture Method" type="string">
  Selecione os métodos permitidos para as imagens:

  * `Camera` - Apenas captura com câmera
  * `Upload` - Apenas upload de arquivos
  * `Both` - Permitir ambos os métodos
</ParamField>

### Detecção de Duplicados

<ParamField path="Duplicated users" type="string">
  Quando um usuário tem documentos previamente aprovados da mesma aplicação, você pode definir uma regra automática:

  * `Approve` - Aprovar automaticamente
  * `Review` - Enviar para revisão manual
  * `Decline` - Rejeitar automaticamente
</ParamField>

### Regras de Validação de Documentos

<ParamField path="QR / barcode" type="string">
  Se um código de barras ou QR era esperado no documento mas não pôde ser lido, você pode definir uma regra automática:

  * `Approve` - Aprovar automaticamente
  * `Review` - Enviar para revisão manual
  * `Decline` - Rejeitar automaticamente
</ParamField>

<ParamField path="MRZ not valid" type="string">
  Quando uma Zona de Leitura Mecânica (MRZ) é esperada no documento mas não pode ser lida:

  * `Approve` - Aprovar automaticamente
  * `Review` - Enviar para revisão manual
  * `Decline` - Rejeitar automaticamente
</ParamField>

<ParamField path="Expiration date" type="string">
  Quando a data de validade do documento é esperada mas não pode ser lida ou está em formato inválido:

  * `Approve` - Aprovar automaticamente
  * `Review` - Enviar para revisão manual
  * `Decline` - Rejeitar automaticamente
</ParamField>

<ParamField path="Invalid validation" type="string">
  Este problema surge quando não conseguimos validar uma data, detectar um número de documento ou reconhecer com precisão o documento:

  * `Review` - Enviar para revisão manual
  * `Decline` - Rejeitar automaticamente
</ParamField>

<ParamField path="Invalid document liveness" type="string">
  Este problema surge quando não conseguimos validar a vivacidade do documento:

  * `Approve` - Aprovar automaticamente
  * `Review` - Enviar para revisão manual
  * `Decline` - Rejeitar automaticamente
</ParamField>

<ParamField path="Address not processed" type="string">
  Este problema surge quando o endereço no documento não pôde ser encontrado ou geolocalizado, provavelmente devido a um endereço inválido ou ausente:

  * `Approve` - Aprovar automaticamente
  * `Review` - Enviar para revisão manual
  * `Decline` - Rejeitar automaticamente
</ParamField>

<Note>
  Estes parâmetros de validação devem ser comunicados à equipe da Gu1 através do seu canal de suporte dedicado. Se você precisar fazer alterações ou modificações a estes parâmetros, por favor envie uma solicitação através do seu canal de suporte dedicado do cliente. No futuro, estes parâmetros serão editáveis no painel da Gu1.
</Note>

## Como Obter a URL da Página de Onboarding?

<Steps>
  <Step title="Criar uma entidade pessoa">
    Crie uma entidade do tipo pessoa na Gu1 pela API de Entidades (nome, taxId, countryCode).

    [Aprenda como criar uma entidade →](/pt/api-reference/entities/create)
  </Step>

  <Step title="Criar uma validação KYC">
    Crie uma sessão de validação KYC para essa entidade com `POST /api/kyc/validations` usando o ID da entidade e `integrationCode` (ex.: `global_gueno_validation_kyc`).

    [Aprenda como criar uma validação →](/pt/use-cases/kyc/create-validation)
  </Step>

  <Step title="Obter o providerSessionUrl">
    Recupere o `providerSessionUrl` da resposta da validação. É a URL da página hospedada que você compartilha com seu cliente.
  </Step>

  <Step title="Compartilhar com seu cliente">
    Compartilhe o `providerSessionUrl` com seu cliente por e-mail, SMS ou incorporado em sua aplicação.
  </Step>
</Steps>

## Exemplo de Implementação

<CodeGroup>
  ```javascript Node.js theme={null}
  // 1. Criar uma entidade pessoa (API de Entidades)
  const entityRes = await fetch('https://api.gu1.ai/api/entities', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer SUA_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'person',
      name: 'João Silva',
      taxId: '12345678900',
      countryCode: 'BR',
      entityData: { person: { email: 'joao@exemplo.com' } }
    })
  });
  const entityData = await entityRes.json();
  const entityId = entityData.entity?.id ?? entityData.id;

  // 2. Criar uma sessão de validação KYC
  const validationRes = await fetch('https://api.gu1.ai/api/kyc/validations', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer SUA_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityId,
      integrationCode: 'global_gueno_validation_kyc'
    })
  });
  const validationData = await validationRes.json();

  // 3. Obter a URL da página hospedada (providerSessionUrl)
  const hostedPageUrl = validationData.providerSessionUrl;
  console.log('Compartilhe esta URL com seu cliente:', hostedPageUrl);

  // 4. Compartilhar com o cliente (por e-mail, SMS, etc.)
  await sendEmail({
    to: 'joao@exemplo.com',
    subject: 'Complete sua Verificação de Identidade',
    body: `Por favor complete sua verificação aqui: ${hostedPageUrl}`
  });
  ```

  ```python Python theme={null}
  import requests

  # 1. Criar uma entidade pessoa (API de Entidades)
  entity_response = requests.post(
      'https://api.gu1.ai/api/entities',
      headers={
          'Authorization': 'Bearer SUA_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'type': 'person',
          'name': 'João Silva',
          'taxId': '12345678900',
          'countryCode': 'BR',
          'entityData': { 'person': { 'email': 'joao@exemplo.com' } }
      }
  )
  entity_data = entity_response.json()
  entity_id = entity_data.get('entity', {}).get('id') or entity_data.get('id')

  # 2. Criar uma sessão de validação KYC
  validation_response = requests.post(
      'https://api.gu1.ai/api/kyc/validations',
      headers={
          'Authorization': 'Bearer SUA_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityId': entity_id,
          'integrationCode': 'global_gueno_validation_kyc'
      }
  )
  validation_data = validation_response.json()

  # 3. Obter a URL da página hospedada (providerSessionUrl)
  hosted_page_url = validation_data['providerSessionUrl']
  print('Compartilhe esta URL com seu cliente:', hosted_page_url)

  # 4. Compartilhar com o cliente (por e-mail, SMS, etc.)
  send_email(
      to='joao@exemplo.com',
      subject='Complete sua Verificação de Identidade',
      body=f'Por favor complete sua verificação aqui: {hosted_page_url}'
  )
  ```

  ```curl cURL theme={null}
  # 1. Criar uma entidade pessoa (API de Entidades)
  curl -X POST https://api.gu1.ai/api/entities \
    -H "Authorization: Bearer SUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "person",
      "name": "João Silva",
      "taxId": "12345678900",
      "countryCode": "BR"
    }'

  # Resposta: {"entity": {"id": "entity-uuid", ...}, ...} ou {"id": "entity-uuid", ...}

  # 2. Criar uma sessão de validação KYC
  curl -X POST https://api.gu1.ai/api/kyc/validations \
    -H "Authorization: Bearer SUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityId": "entity-uuid",
      "integrationCode": "global_gueno_validation_kyc"
    }'

  # Resposta: {"id": "...", "providerSessionUrl": "https://...", "status": "pending", ...}

  # 3. Compartilhar o providerSessionUrl com seu cliente
  ```
</CodeGroup>

## Melhores Práticas

<AccordionGroup>
  <Accordion title="Personalize para sua Marca">
    Configure o esquema de cores, logo e idioma para combinar com a identidade da sua marca. Isso cria uma experiência perfeita para seus usuários.
  </Accordion>

  <Accordion title="Defina Regras de Validação Apropriadas">
    Configure as regras de validação com base em seus requisitos de conformidade e tolerância ao risco. Regras mais rigorosas fornecem melhor segurança, mas podem resultar em mais revisões manuais.
  </Accordion>

  <Accordion title="Monitore o Status da Sessão">
    Use webhooks para receber notificações em tempo real quando a verificação for concluída. Isso permite que você atualize imediatamente o acesso do usuário em seu sistema.
  </Accordion>

  <Accordion title="Gerencie a Expiração e Segurança">
    **Expiração de Sessões**: As sessões normalmente expiram após 7 dias. Se a sessão de um usuário expirar, crie uma nova validação para gerar uma URL nova.

    **Melhores Práticas de Segurança**:

    * Nunca exponha o providerSessionUrl publicamente (não compartilhe em fóruns públicos, URLs públicas, etc.)
    * Sempre gere URLs do lado do servidor - nunca exponha as chaves de API no código do lado do cliente
    * Use HTTPS ao compartilhar URLs através de seus próprios sistemas
    * Implemente autenticação adequada antes de gerar sessões para usuários
    * Considere implementar rate limiting na criação de sessões para prevenir abuso
    * Armazene os IDs de validação em seu banco de dados vinculados a registros de usuários para trilhas de auditoria
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Criar Entidade" icon="user" href="/pt/api-reference/entities/create">
    Aprenda como criar uma entidade de pessoa
  </Card>

  <Card title="Criar Validação" icon="shield-check" href="/pt/use-cases/kyc/create-validation">
    Crie uma sessão de validação KYC
  </Card>

  <Card title="Integração de Webhooks" icon="webhook" href="/pt/use-cases/kyc/webhook-integration">
    Receba atualizações de status em tempo real
  </Card>

  <Card title="Integração de Cliente" icon="code" href="/pt/use-cases/kyc/client-integration">
    Incorpore em sua aplicação móvel ou web
  </Card>
</CardGroup>