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

# Sincronizar Validação KYC

> Sincronizar manualmente os dados de validação KYC com o provedor — na API KYC da gu1 para fluxos de verificação de identidade, com exemplos para sync.

## Visão Geral

Este endpoint permite sincronizar manualmente uma validação KYC com o provedor de verificação para obter o status e os dados de decisão mais recentes. Quando você sincroniza:

* **Busca os dados mais recentes** do provedor KYC em tempo real
* **Atualiza URLs de imagens expiradas** (URLs do provedor expiram após \~4 horas)
* **Atualiza o status da validação** se o provedor tomou uma decisão
* **Preserva decisões manuais** - não sobrescreve validações aprovadas/rejeitadas/canceladas manualmente
* **Retorna dados de verificação atualizados** incluindo documentos, biometria e avaliação de risco

<Info>
  A sincronização é útil quando você precisa de dados atualizados imediatamente sem esperar por webhooks, ou quando as URLs de imagens expiraram e você precisa visualizar os documentos de verificação.
</Info>

## Quando Usar Isso

* **Verificar status atual**: Obter atualizações de status em tempo real do provedor
* **Atualizar imagens expiradas**: URLs de imagens do provedor expiram após 4 horas
* **Forçar atualização**: Acionar manualmente uma sincronização se a entrega do webhook falhou
* **Depurar verificação**: Revisar os dados e decisões de verificação mais recentes
* **Antes de decisão manual**: Sincronizar antes de aprovar/rejeitar para ver os dados mais recentes do provedor

## Solicitação

### Endpoint

```
POST https://api.gu1.ai/api/kyc/validations/{id}/sync
```

### Parâmetros de Rota

<ParamField path="id" type="string" required>
  O ID da validação a ser sincronizada
</ParamField>

### Cabeçalhos

```json theme={null}
{
  "Authorization": "Bearer SUA_API_KEY",
  "Content-Type": "application/json"
}
```

### Parâmetros do Corpo

<ParamField body="force" type="boolean">
  Forçar sincronização mesmo se sincronizado recentemente (opcional)

  **Tipo**: `boolean` (padrão: `false`)

  **Exemplo**: `true`
</ParamField>

## Resposta

### Resposta de Sucesso (200 OK)

Retorna o objeto de validação atualizado com os dados mais recentes do provedor:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "approved",
  "provider": "Provedor KYC",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "decision": {
    "status": "Approved",
    "features": ["id_verification", "liveness", "face_match"],
    "id_verification": {
      "status": "Approved",
      "document_type": "Identity Card",
      "first_name": "João",
      "last_name": "Silva",
      "date_of_birth": "1990-05-15",
      "nationality": "BR",
      "front_image": "https://provider.com/fresh-url-1.jpg",
      "portrait_image": "https://provider.com/fresh-url-2.jpg"
    },
    "liveness": {
      "status": "Approved",
      "score": 98,
      "method": "PASSIVE",
      "reference_image": "https://provider.com/fresh-url-3.jpg"
    },
    "face_match": {
      "status": "Approved",
      "score": 95
    }
  },
  "extractedData": {
    "firstName": "João",
    "lastName": "Silva",
    "dateOfBirth": "1990-05-15",
    "nationality": "BR",
    "documentNumber": "AB123456",
    "documentType": "Identity Card"
  },
  "documentsVerified": [
    {
      "type": "Identity Card",
      "verified": true,
      "verifiedAt": "2025-01-27T10:30:00Z"
    }
  ],
  "biometricResult": {
    "livenessScore": 0.98,
    "faceMatchScore": 0.95,
    "passed": true,
    "timestamp": "2025-01-27T10:30:00Z"
  },
  "riskAssessment": {
    "riskLevel": "low"
  },
  "verifiedFields": ["firstName", "lastName", "dateOfBirth", "nationality", "documentNumber"],
  "warnings": [],
  "isCurrent": true,
  "verifiedAt": "2025-01-27T10:30:00Z",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-27T10:30:00Z"
}
```

## Exemplo de Solicitação

<CodeGroup>
  ```javascript Node.js theme={null}
  const validationId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://api.gu1.ai/api/kyc/validations/${validationId}/sync`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer SUA_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        force: false
      })
    }
  );

  const synced = await response.json();
  console.log('Validação sincronizada:', synced.status);
  console.log('Atualizada em:', synced.updatedAt);
  ```

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

  validation_id = '550e8400-e29b-41d4-a716-446655440000'

  response = requests.post(
      f'https://api.gu1.ai/api/kyc/validations/{validation_id}/sync',
      headers={
          'Authorization': 'Bearer SUA_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'force': False
      }
  )

  synced = response.json()
  print('Validação sincronizada:', synced['status'])
  print('Atualizada em:', synced['updatedAt'])
  ```

  ```curl cURL theme={null}
  curl -X POST https://api.gu1.ai/api/kyc/validations/550e8400-e29b-41d4-a716-446655440000/sync \
    -H "Authorization: Bearer SUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "force": false
    }'
  ```
</CodeGroup>

## Respostas de Erro

### Validação Não Encontrada (404)

```json theme={null}
{
  "error": "NOT_FOUND",
  "message": "Validation not found"
}
```

### Sem ID de Sessão (400)

A validação não tem sessão do provedor para sincronizar:

```json theme={null}
{
  "error": "NO_SESSION_ID",
  "message": "Validation has no session ID"
}
```

### Integração do Provedor Não Configurada (400)

```json theme={null}
{
  "error": "INTEGRATION_NOT_CONFIGURED",
  "message": "Integration not configured for organization: kyc_provider_code"
}
```

## Notas Importantes

<AccordionGroup>
  <Accordion title="Sincronização Automática">
    As validações são sincronizadas automaticamente ao serem consultadas via GET se as imagens tiverem mais de 3.5 horas. A sincronização manual é útil quando você precisa de atualizações imediatas.
  </Accordion>

  <Accordion title="Decisões Manuais São Protegidas">
    Se uma validação foi aprovada, rejeitada ou cancelada manualmente, a sincronização NÃO sobrescreverá essa decisão. Decisões manuais são preservadas para manter trilhas de auditoria.
  </Accordion>

  <Accordion title="Atualização de URLs de Imagens">
    URLs de imagens do provedor (fotos de documentos, selfies) expiram após \~4 horas. A sincronização busca URLs atualizadas para que você possa visualizar os documentos novamente.
  </Accordion>

  <Accordion title="Atualizações de Status">
    Se o provedor tomou uma decisão desde a última sincronização, o status da validação será atualizado automaticamente (a menos que tenha um status manual).
  </Accordion>

  <Accordion title="Cobrança de Créditos">
    A sincronização NÃO cobra créditos. Os créditos são cobrados apenas quando uma validação atinge um estado final (aprovada/rejeitada) pela primeira vez.
  </Accordion>
</AccordionGroup>

## Casos de Uso

### 1. Atualizar Imagens Expiradas

```javascript theme={null}
// O usuário deseja revisar documentos mas as imagens expiraram
const validation = await fetch(
  `https://api.gu1.ai/api/kyc/validations/${validationId}/sync`,
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer SUA_API_KEY' }
  }
);

const data = await validation.json();
// URLs de imagens atualizadas disponíveis em data.decision.id_verification.front_image
```

### 2. Verificar Status Antes de Decisão Manual

```javascript theme={null}
// Sincronizar antes de tomar uma decisão de aprovação manual
const synced = await fetch(
  `https://api.gu1.ai/api/kyc/validations/${validationId}/sync`,
  { method: 'POST', headers: { 'Authorization': 'Bearer SUA_API_KEY' } }
);

const data = await synced.json();

// Revisar dados mais recentes do provedor
console.log('Status do provedor:', data.status);
console.log('Nível de risco:', data.riskAssessment?.riskLevel);
console.log('Avisos:', data.warnings);

// Então aprovar se satisfeito
if (data.status === 'in_progress' && data.warnings.length === 0) {
  await approveValidation(validationId, 'Todas as verificações passaram');
}
```

### 3. Forçar Atualização Após Falha de Webhook

```javascript theme={null}
// Se você suspeita que os webhooks não foram entregues
const validations = await getValidationsWithStatus('in_progress');

for (const validation of validations) {
  // Sincronizar cada uma para obter o status mais recente
  await fetch(
    `https://api.gu1.ai/api/kyc/validations/${validation.id}/sync`,
    {
      method: 'POST',
      headers: { 'Authorization': 'Bearer SUA_API_KEY' },
      body: JSON.stringify({ force: true })
    }
  );
}
```

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Aprovar Validação" icon="check" href="/pt/use-cases/kyc/approve-validation">
    Aprovar manualmente uma validação
  </Card>

  <Card title="Rejeitar Validação" icon="xmark" href="/pt/use-cases/kyc/reject-validation">
    Rejeitar manualmente uma validação
  </Card>

  <Card title="Verificar Status de Verificação" icon="magnifying-glass" href="/pt/use-cases/kyc/check-status">
    Consultar resultados de validação
  </Card>

  <Card title="Cancelar Validação" icon="ban" href="/pt/use-cases/kyc/cancel-validation">
    Cancelar uma validação pendente
  </Card>
</CardGroup>