> 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/sdks/sdk-web/preguntas-y-errores-frecuentes.md).

# Preguntas y errores frecuentes

### Compatibilidad con Turbopack

Algunos frameworks modernos, como **Next.js 16**, utilizan **Turbopack** como bundler por defecto. Turbopack actualmente tiene algunas limitaciones que causan problemas de compatibilidad con la distribución estándar del SDK Web.

#### Uso de la Versión Bundle

Para usar el SDK Web con frameworks habilitados para Turbopack, **debes** importar desde el punto de entrada **bundle**:

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

Para poder usar este módulo cuando se utiliza TypeScript, debe declararse en un archivo .d.ts de la siguiente manera:

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

Sin embargo, tiene algunas limitaciones descritas a continuación.

**Consideraciones sobre Importaciones de Tipos**

Puedes importar **tipos puros de TypeScript** desde el paquete principal usando `import type`:

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

No obstante, los enums como `Language` y `TypeFamily` **no se pueden importar** desde `@facephi/sdk-web-wc`.

**Solución:** Usa valores literales de cadena directamente:

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

> **Advertencia**: No todas las propiedades aceptan este típo de configuración. Ésto sólo es válido para las propiedades con valores simples (`string`, `number`, `boolean`...).

#### Ejemplo (Implementación en 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 del 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>
);
```

#### Compatibilidad con Wrappers de React y Angular

Los paquetes **`@facephi/sdk-web-react`** y **`@facephi/sdk-web-angular`** actualmente **no son compatibles con Turbopack** porque internamente importan desde `@facephi/sdk-web-wc` (no la versión bundle), lo que provoca los mismos problemas de compatibilidad. Para entornos con Turbopack, usa Web Components nativos con la versión bundle y manejo manual de eventos como se muestra arriba.

***

### Integración Incorrecta de APIKEY

Una integración incorrecta del `apikey` puede llevar a varios problemas. A continuación se describen los más comunes:

#### 1. Error de Configuración Web

Es un requisito obligatorio proporcionar a Facephi un dominio web válido donde se utilizará el SDK. Si el SDK se despliega en un dominio web diferente, encontrarás un error conocido del navegador web llamado **CORS (Cross-Origin Resource Sharing)**.

**¿Qué es CORS?**

CORS es una restricción de seguridad aplicada por los navegadores web que limita las interacciones entre un servidor web y APIs externas. En este caso, cuando la web del cliente se comunica con el servicio de licencias de Facephi, fallará si el dominio web del cliente no está correctamente configurado durante la configuración de la APIKEY.

**¿Cómo Evitar Errores CORS?**

* Asegúrate de que el dominio web correcto se comparta con el equipo de Soporte de Facephi al solicitar la APIKEY.
* Despliega el SDK exclusivamente en el dominio autorizado.

***

#### 2. Error de Configuración de Componentes

El `apikey` está vinculado a los componentes que el cliente ha contratado, que están preconfigurados por el equipo de Soporte de Facephi. Si un componente específico, como **Selphid** o **Selphi**, no está habilitado, esos componentes no se renderizarán en la web, incluso si se han integrado a nivel de código.

**Depuración de Errores de Configuración de Componentes**

Para depurar estos errores, puedes habilitar el parámetro `debug` en el `facephi-sdk-provider`. Esto proporcionará logs detallados y ayudará a identificar configuraciones incorrectas.

**Ejemplo: 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}
/>
```