> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/es/implement-nfc-wallet/enroll-wallet.md).

# Inscribir billetera

## Descripción general

Inscribir la aplicación de cartera digital después **SDK de Cartera NFC** inicialización y antes de que comiences **Tokenización**.

La inscripción de la cartera proporciona a la aplicación de cartera digital los activos de seguridad necesarios para usar **servicios de Cartera NFC** servicios:

* Ejecuta esto una vez por instancia de cartera.
* Ejecuta esto solo si la aplicación de cartera digital utiliza **servicios de Cartera NFC** servicios.
* Ejecuta esto solo en dispositivos elegibles.

{% hint style="warning" %}
Inscribe solo las aplicaciones de cartera digital que usan **servicios de Cartera NFC** servicios.

Esto evita tráfico de red innecesario desde la aplicación de cartera digital y carga innecesaria en **servicios de Cartera NFC**.
{% endhint %}

## Diagrama de secuencia

Flujo de alto nivel para inscribir tu aplicación de cartera.

<figure><img src="/files/9fce7f0712f4fb74d80fdd9db239dfbd2f03250e" alt=""><figcaption><p>Flujo de alto nivel de inscripción de cartera.</p></figcaption></figure>

{% hint style="info" %}
Técnicamente, este flujo se llama **inscripción segura de cartera** en **servicios de Cartera NFC**.
{% endhint %}

## Integración del SDK

### Prerrequisitos

Antes de comenzar, verifica lo siguiente:

* Tu aplicación de cartera digital está registrada en el backend de Cartera NFC.
* Has inicializado el **SDK de Cartera NFC**.
* La cartera no está inscrita (ver más abajo).

### Realizar la inscripción de la cartera

La inscripción de la cartera es una acción única en el ciclo de vida de la aplicación de cartera digital.

Ejecuta esto después de la inicialización del SDK, y solo si la cartera no está inscrita.

1. Obtén un `WalletSecureEnrollmentBusinessService` instancia.
2. Comprueba `getState()` devuelve `WSE_REQUIRED`.
3. Si es necesario, llama `startWalletSecureEnrollment()` para iniciar la inscripción de la cartera.
4. Implementa `WalletSecureEnrollmentListener` para seguir el progreso.

Estos son los callbacks posibles:

* `onProgressUpdate` con estado `WSE_STARTED`: El proceso comienza.
* `onProgressUpdate` con estado `WSE_COMPLETED`: El proceso finaliza correctamente.
* `onError`: El proceso falla con un error.

Después de que la inscripción de la cartera se complete correctamente, continúa con [Tokenizar una tarjeta](/nfc-wallet-sdk-android/es/implement-nfc-wallet/tokenize-a-card.md).

```java
public void performWseIfNeeded() {
    // Primero verifica el estado actual. Si necesitamos WSE en absoluto.
    final WalletSecureEnrollmentBusinessService wseService 
                = ProvisioningServiceManager.getWalletSecureEnrollmentBusinessService();
    final WalletSecureEnrollmentState state = wseService.getState();

    switch (state) {
        case WSE_COMPLETED:
        case WSE_NOT_REQUIRED:
            // WSE ya se realizó en la instancia actual o en alguna instancia previa.
            break;
        case WSE_STARTED:
            // WSE se activó durante esta instancia. Simplemente espera a que termine la primera.
            return;
        case WSE_REQUIRED:
            // Activar la inscripción WS.
            wseService.startWalletSecureEnrollment(new WalletSecureEnrollmentListener() {
                @Override
                public void onProgressUpdate(final WalletSecureEnrollmentState wseState) {
                    if (wseState == WalletSecureEnrollmentState.WSE_COMPLETED) {
                        // Éxito
                    }
                    else if (wseState == WalletSecureEnrollmentState.WSE_STARTED) {
                        // Iniciado
                    }
                }

                @Override
                public void onError(final WalletSecureEnrollmentError wbDynamicKeyRenewalServiceError) {
                    // Registrar error
                }
            });
            break;
        default:
            // Registrar error ya que no debería suceder
            break;
    }
}   
```

### Detalles del código de error

Cuando `WalletSecureEnrollmentListener.onError(...)` se activa, el SDK proporciona un `WalletSecureEnrollmentError`.

Incluye un código de error y un mensaje, además de campos adicionales dependiendo del tipo de fallo.

#### Analizar `WalletSecureEnrollmentError`

La estructura del `WalletSecureEnrollmentError` objeto es la siguiente:

* Código de error del SDK: El tipo de error para esta operación.
* Código de error CPS: El código numérico de error devuelto por el módulo CPS (lado servidor).
* Código de estado HTTP: El código de estado HTTP devuelto por errores de comunicación.
* Mensaje: Una descripción de error legible por humanos.

El error debe analizarse de la siguiente manera:

1. Lee `getSdkErrorCode()` para obtener un `WalletSecureEnrollmentErrorCodes` valor.
2. Si el código de error del SDK indica un error de comunicación (`COMM_ERROR`), lee `getHttpStatusCode()`.
3. Si el código de error del SDK indica un error del lado del servidor (`SERVER_ERROR`), lee `getCpsErrorCode()`.
4. Lee `getErrorMessage()` para una descripción apta para registros.
5. Si el código de error del SDK es `DEVICE_SUSPICIOUS`, lee `getStatusAdditionalInfo()` y regístralo para la resolución de problemas.

Consulta `WalletSecureEnrollmentErrorCodes` en el [API de Android](/nfc-wallet-sdk-android/es/android-api.md) referencia para la lista completa de códigos.

#### `WalletSecureEnrollmentErrorCodes`

Usa las siguientes recomendaciones para decidir si reintentar, detener o restablecer el SDK.

{% hint style="info" %}
Llama `SDKDataController.wipeAll()` cuando la recomendación sea restablecer el SDK.
{% endhint %}

<details>

<summary>Tablas de códigos de error</summary>

<table data-full-width="true"><thead><tr><th width="240">Código de error</th><th>Cuándo ocurre</th><th>Acción recomendada</th></tr></thead><tbody><tr><td><code>WSE_INTERNAL_ERROR</code></td><td>Ocurre un error interno del SDK.</td><td><p>Reintenta la inscripción de la cartera.</p><p>Si el problema persiste, restablece el SDK.</p></td></tr><tr><td><code>COMMON_NO_INTERNET</code></td><td>El dispositivo no tiene conectividad de red.</td><td>Pide al usuario final que se conecte a una red, luego reintenta la inscripción de la cartera.</td></tr><tr><td><code>COMMON_COMM_ERROR</code></td><td>Ocurre un error de comunicación al recuperar los activos de seguridad.</td><td>Reintenta la inscripción de la cartera.</td></tr><tr><td><code>COMMON_SERVER_ERROR</code></td><td>Ocurre un error del lado del servidor al recuperar los activos de seguridad.</td><td><p>Reintenta la inscripción de la cartera.</p><p>Si el problema persiste, contacta al equipo de entrega de Thales para validar la configuración del entorno.</p></td></tr><tr><td><code>RE_ENROLLMENT_REQUIRED</code></td><td>Se requiere reinscripción por razones de seguridad.</td><td>Restablece el SDK, luego ejecuta la inscripción de la cartera nuevamente.</td></tr><tr><td><code>WSE_STORAGE_ACCESS_ERROR</code></td><td>El SDK excede su límite interno de reintentos al acceder al almacenamiento seguro.</td><td>Restablece el SDK, luego reintenta la inscripción de la cartera.</td></tr><tr><td><code>JSON_PARSING_ERROR</code></td><td>Los datos de la respuesta no se pueden analizar.</td><td><p>Reintenta la inscripción de la cartera.</p><p>Si el problema persiste, restablece el SDK.</p></td></tr><tr><td><code>WSE_REQUEST_ERROR</code></td><td>La solicitud de inscripción falla.</td><td>Reintenta la inscripción de la cartera.</td></tr><tr><td><code>WSE_DOWNLOAD_ERROR</code></td><td>La descarga de los activos de seguridad falla.</td><td>Verifica la conectividad de red, luego reintenta la inscripción de la cartera.</td></tr><tr><td><code>WSE_ERROR_INIT_SESSION</code></td><td>La inicialización de la sesión WSE falla (típicamente relacionada con la autenticación).</td><td>Reintenta la inscripción de la cartera.</td></tr><tr><td><code>WSE_ERROR_COMPUTE_AUTH_VALUE_FAILED_PACKAGE_NOT_FOUND</code></td><td>El SDK no puede calcular el valor de autenticación porque no se puede resolver el nombre del paquete.</td><td>Verifica el nombre del paquete de la aplicación usado en tu configuración de registro, luego reintenta la inscripción de la cartera.</td></tr><tr><td><code>WSE_ERROR_COMPUTE_AUTH_VALUE_FAILED_CERT_EXCEPTION</code></td><td>El SDK no puede calcular el valor de autenticación debido a un problema con la firma de la aplicación o la clave pública.</td><td>Verifica el certificado de firma de la aplicación usado en tu configuración de registro, luego reintenta la inscripción de la cartera.</td></tr><tr><td><code>WSE_CPS_COMPONENT_NOT_INITIALIZED</code></td><td>La inscripción de la cartera comienza antes de que el componente CPS esté inicializado.</td><td>Inicializa el SDK, luego reintenta la inscripción de la cartera.</td></tr><tr><td><code>WSE_MG_COMPONENT_NOT_INITIALIZED</code></td><td>La inscripción de la cartera comienza antes de que el componente MobileGateway esté inicializado.</td><td>Inicializa el SDK, luego reintenta la inscripción de la cartera.</td></tr><tr><td><code>DEVICE_SUSPICIOUS</code></td><td>El SDK detecta una amenaza de seguridad en el dispositivo.</td><td><p>Detén el flujo e informa al usuario final que el dispositivo no puede usarse.</p><p>Captura y comparte <code>getStatusAdditionalInfo()</code> al contactar con el soporte de Thales.</p></td></tr><tr><td><code>WSE_KCV_ERROR</code></td><td>El SDK no valida los activos de seguridad descargados (la comprobación KCV falla).</td><td>Reintenta la inscripción de la cartera.</td></tr></tbody></table>

</details>

## Clave de vinculación de la aplicación (notas)

Como se describe en [registro](/nfc-wallet-sdk-android/es/get-started/configuration/2.-onboarding.md) debes proporcionar la **clave de vinculación de la aplicación.**

Si la clave de vinculación de la aplicación no se proporciona o es incorrecta, la inscripción de la cartera fallará.

Por favor, revisa la advertencia y la nota a continuación.

{% hint style="warning" %}

## Rotación de clave de firma / Múltiples firmantes <a href="#receive-this-from-the-thales-delivery-team" id="receive-this-from-the-thales-delivery-team"></a>

Si la clave de firma más antigua no se proporciona como el primer valor de firmante en la estructura de prueba de rotación, entonces la inscripción de la cartera fallará
{% endhint %}

{% hint style="info" %}

#### Descenso a versiones anteriores del SDK de Cartera NFC <a href="#downgrading-to-earlier-versions-of-nfc-wallet-sdk" id="downgrading-to-earlier-versions-of-nfc-wallet-sdk"></a>

Para degradar a una versión anterior del SDK de Cartera NFC, la aplicación debe asegurarse de que la clave de firma más antigua se proporcione como el primer firmante en la estructura de prueba de rotación.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/es/implement-nfc-wallet/enroll-wallet.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.