> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/sdk-web/preguntas-y-errores-frecuentes.md).

# Perguntas e erros frequentes

### Compatibilidade com Turbopack

Alguns frameworks modernos, como **Next.js 16**, usam **Turbopack** como bundler padrão. Turbopack atualmente tem algumas limitações que causam problemas de compatibilidade com a distribuição padrão do SDK Web.

#### Uso da Versão Bundle

Para usar o SDK Web com frameworks habilitados para Turbopack, **você deve** importar do ponto de entrada **bundle**:

```ts
import { defineCustomElements } from '@facephi/sdk-web-wc/bundle';
```

Para poder usar este módulo quando se usa TypeScript, ele deve ser declarado em um arquivo .d.ts da seguinte forma:

```ts
// global.d.ts
declare module '@facephi/sdk-web-wc/bundle';
```

No entanto, tem algumas limitações descritas a seguir.

**Considerações sobre Importações de Tipos**

Você pode importar **tipos puros de TypeScript** a partir do pacote principal usando `import type`:

```typescript
import type { ErrorData, SelphiWidgetLoadedEvent, SelphiExtractionFinishEvent } from '@facephi/sdk-web-wc';
```

No entanto, enums como `Language` e `TypeFamily` **não podem ser importados** de `@facephi/sdk-web-wc`.

**Solução:** Use valores literais de string diretamente:

```typescript
<facephi-sdk-provider
  type={'ONBOARDING'}           // em vez de TypeFamily.onboarding
  language={'en'}               // em vez de Language.en
>
```

> **Aviso**: Nem todas as propriedades aceitam esse tipo de configuração. Isso só é válido para as propriedades com valores simples (`string`, `number`, `boolean`...).

#### Exemplo (Implementação em Next.js 16)

```typescript
'use client';
import type { 
  ErrorData, 
  SelphiWidgetLoadedEvent, 
  SelphiExtractionFinishEvent, 
  FacephiSelphiWidgetCustomEvent 
} from '@facephi/sdk-web-wc';
import { defineCustomElements } from '@facephi/sdk-web-wc/bundle';

// Eventos do Provider
function handleEmitData(event: CustomEvent<{ operationId: string; sessionId: string; extraData: string }>) {
  const result = event.detail;
}

// Eventos de Selphi
function handleModuleLoaded(event: FacephiSelphiWidgetCustomEvent<SelphiWidgetLoadedEvent>) {
  const result = event.detail.detail;
}

function handleExtractionFinish(event: FacephiSelphiWidgetCustomEvent<SelphiExtractionFinishEvent>) {
  const result = event.detail.detail;
}

return (
  <facephi-sdk-provider
    apikey={apiKey}
    type={TypeFamily.onboarding}
    language={Language.en}
    onemitData={handleEmitData}
  >
    <facephi-selphi-widget
      interactible={true}
      previewImage={true}
      onModuleLoaded={handleModuleLoaded}
      onExtractionFinish={handleExtractionFinish}
    />
  </facephi-sdk-provider>
);
```

#### Compatibilidade com Wrappers de React e Angular

Os pacotes **`@facephi/sdk-web-react`** e **`@facephi/sdk-web-angular`** atualmente **não são compatíveis com Turbopack** porque internamente importam de `@facephi/sdk-web-wc`  (não a versão bundle), o que provoca os mesmos problemas de compatibilidade. Para ambientes com Turbopack, use Web Components nativos com a versão bundle e tratamento manual de eventos como mostrado acima.

***

### Integração Incorreta de APIKEY

Uma integração incorreta do `apikey` pode levar a vários problemas. A seguir, são descritos os mais comuns:

#### 1. Erro de Configuração Web

É um requisito obrigatório fornecer à Facephi um domínio web válido onde o SDK será utilizado. Se o SDK for implantado em um domínio web diferente, você encontrará um erro conhecido do navegador chamado **CORS (Cross-Origin Resource Sharing)**.

**O que é CORS?**

CORS é uma restrição de segurança aplicada pelos navegadores web que limita as interações entre um servidor web e APIs externas. Neste caso, quando o site do cliente se comunica com o serviço de licenças da Facephi, falhará se o domínio web do cliente não estiver corretamente configurado durante a configuração da APIKEY.

**Como Evitar Erros CORS?**

* Certifique-se de que o domínio web correto seja compartilhado com a equipe de Suporte da Facephi ao solicitar a APIKEY.
* Implante o SDK exclusivamente no domínio autorizado.

***

#### 2. Erro de Configuração de Componentes

O `apikey` está vinculado aos componentes que o cliente contratou, que estão pré-configurados pela equipe de Suporte da Facephi. Se um componente específico, como **Selphid** ou **Selphi**, não estiver habilitado, esses componentes não serão renderizados na web, mesmo que tenham sido integrados no nível de código.

**Depuração de Erros de Configuração de Componentes**

Para depurar esses erros, você pode habilitar o parâmetro `debug` no `facephi-sdk-provider`. Isso fornecerá logs detalhados e ajudará a identificar configurações incorretas.

**Exemplo: Habilitar Debug**

```jsx
import { TrackingSteps, TypeFamily } from '@facephi/sdk-web-wc';

<facephi-sdk-provider
  apikey={process.env.FACEPHI_SDK_APIKEY}
  debug={true}
  steps={`${TrackingSteps.start},${TrackingSteps.selphiWidget},${TrackingSteps.selphidWidget},${TrackingSteps.finish}`}
  customerId={customerId}
  type={TypeFamily.onboarding}
/>
```