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

# Integración con Pix Lerian

> Configura una integración de pruebas Pix Lerian v1.0.0, aplica las convenciones de solicitud y sigue los flujos de la API pública sin llamar a callbacks exclusivos del adaptador.

Pix Lerian v1.0.0 está listo para integrarse y probarse con el proveedor mock incluido. Tu aplicación llama a las API públicas de DICT, SPI y COB. El plugin llama a Midaz y al proveedor mock; el mock devuelve callbacks asíncronos al plugin.

<Note>
  Las rutas de callbacks son exclusivas del adaptador. No las llames desde una aplicación cliente. La conectividad nativa del riel y la disponibilidad de un proveedor de producción están fuera de la ruta de integración compatible con esta versión.
</Note>

## Crea tu ruta de pruebas

1. Despliega las dependencias del plugin, incluidos Midaz y el proveedor mock, en un entorno de pruebas.
2. Obtén un token de acceso cuando la autenticación esté habilitada e identifica la cuenta que posee cada solicitud.
3. Prueba un flujo público: [una clave](/es/interfaces/pix-lerian/pix-lerian-dict), [una transferencia](/es/interfaces/pix-lerian/pix-lerian-spi) o [un cobro](/es/interfaces/pix-lerian/pix-lerian-cob).
4. Conserva el identificador de operación que devuelve la solicitud de creación. Lee esa operación hasta que alcance un estado terminal después del callback del mock.
5. Registra juntos la contabilización de Midaz y el resultado de la operación en la evidencia de pruebas.

## Convenciones de solicitud

Usa la referencia de cada operación como autoridad final. Estas convenciones se repiten en todo el plugin:

| Aspecto | Uso |
| - | - |
| Autenticación | Envía un token bearer en `Authorization` cuando la autenticación de Access Manager está habilitada. |
| Ámbito de cuenta | Envía `X-Account-Id` en las operaciones públicas cuyo ámbito es una cuenta. El plugin lo usa para exigir la propiedad de la cuenta. |
| Repetición de mutaciones | Envía un valor `X-Idempotency` nuevo para cada escritura prevista y reutiliza ese valor exacto solo para reintentar la misma solicitud. La mayoría de las operaciones POST públicas lo requieren. |
| Justificación de negocio | Envía `X-Reason` cuando la operación de DICT requiere un motivo, como en la mutación de una entrada. |
| Tipo de contenido | Usa `application/json` para cuerpos JSON. Un JSON merge patch requiere `application/merge-patch+json`. |

Un header de idempotencia ausente o no válido es un error del cliente. Reutilizar una clave con un payload diferente es un fallo de precondición. Algunas operaciones también mantienen una regla de repetición duradera y específica de la operación; la referencia describe la respuesta de esa ruta.

## Lee el estado después de una escritura asíncrona

Una solicitud correcta puede significar que el plugin aceptó el trabajo, no que el pago o el cobro externo terminó. Para SPI, usa el identificador de transferencia o devolución devuelto con el endpoint de lectura de [transferencia](/es/reference/interfaces/pix-lerian/spi/get-transfer) o [devolución](/es/reference/interfaces/pix-lerian/spi/get-refund). Para los cobros, lee el cobro mediante su identificador.

Trata estos resultados de forma distinta:

* **Error de validación o autorización:** corrige la solicitud o el token. No repitas una entrada sin cambios.
* **Respuesta de repetición:** conserva el resultado original; no crees una segunda operación de negocio.
* **Conflicto:** lee el recurso y elige la siguiente transición legal.
* **Error temporal de dependencia:** conserva el valor de idempotencia antes de reintentar. Una ruta que documenta una dependencia de fallo seguro seguirá rechazando la escritura hasta que esa dependencia se restaure.

## Mantén claros los límites

Tu cliente es dueño de las llamadas y lecturas de la API pública. El proveedor mock es dueño de los resultados externos simulados. El plugin es dueño del procesamiento de callbacks y de la contabilización en Midaz. Esta separación evita que un cliente de pruebas fabrique estados de liquidación o evite las comprobaciones de cuenta y proveedor.

Continúa con [Flujos de SPI](/es/interfaces/pix-lerian/pix-lerian-spi) para la secuencia de pagos, [Flujos de DICT](/es/interfaces/pix-lerian/pix-lerian-dict) para claves y MED 2.0, o [Flujos de COB](/es/interfaces/pix-lerian/pix-lerian-cob) para BR Codes y cobros.