> ## 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. # Conectar un motor > Qué cambia e implementa el equipo de cada motor de core bancario para trabajar detrás de JD Courier: el riel SPB, el riel Pix, el tránsito Pix, las llamadas al Courier y el relay entre cores. Esta página es para el equipo de cada motor que trabaja detrás del Courier: tu core actual y el stack de Lerian. Primero, un operador registra el motor en el Courier, a través de la [API de motores](https://docs.lerian.studio/es/reference/interfaces/jd-courier/register-an-engine.md). El registro guarda los ISPBs participantes del motor, su primera credencial y las direcciones en las que el motor recibe las llamadas Pix y las TED entre cores. ## SPB: apunta el motor al Courier *** En el riel SPB, el Courier sirve la misma interfaz SOAP que JD. Un motor que ya habla con JD cambia la dirección y la credencial del canal. Mantiene sus mensajes y sus llamadas. El rol `spb-sender` sirve la interfaz en la ruta `/soap`, en su propio puerto (predeterminado `8081`). Acepta las cuatro operaciones de JD: | Operación | Qué hace el Courier | | - | - | | `RecebeMensagem` | Le da al motor el mensaje SPB más antiguo que lo espera. Cuando ninguno espera, responde con el código de cola vacía `ALS01`. El Courier no llama a JD. | | `EnviaMensagem` | Escribe el envío en el registro de envíos, envía el mensaje a JD una vez y reenvía la respuesta de JD. | | `ConsultaNumCtrlIF` | Reenvía la consulta a JD, para los números de control de los envíos que este motor hizo a través del Courier. | | `ConsultaMensagem` | Reenvía la consulta a JD, para los números de secuencia de los mensajes de este motor. | Cada motor se autentica en la dirección SOAP del Courier con su propia credencial de canal, no con tu credencial JD. Un operador emite la credencial a través de la API del Courier. La respuesta muestra la contraseña una vez. Guárdala en ese momento. Cuando emites una nueva credencial para el mismo motor, la anterior sigue funcionando durante una ventana de superposición (24 horas de forma predeterminada) y después deja de funcionar. Un operador puede revocar una credencial en cualquier momento. El Courier reenvía cada envío a JD con tu credencial JD. Una autenticación rechazada recibe 401 sin cuerpo. ### Antes de que el motor cambie su dirección 1. Vacía el pendiente de conciliación del motor con JD. El Courier responde una consulta solo para los envíos y los mensajes que pasaron por él. Una consulta sobre un envío anterior recibe `503`. 2. Pide al operador que emita la credencial del canal del motor. 3. Cambia la dirección y la credencial JD del motor por los valores del Courier. ### Qué recibe el motor Un mensaje reentregado mantiene su número de secuencia original (`NumCabSeq`). El motor debe aceptar un número de secuencia repetido como una repetición, no como un mensaje nuevo. El Courier da estas respuestas a `EnviaMensagem`: | Respuesta | Significado | | - | - | | La respuesta de JD, tal como llegó | JD respondió. | | La respuesta de JD con el encabezado `X-Send-Outcome: indeterminate` | JD falló o respondió sin un veredicto. El mensaje posiblemente llegó a JD. | | `503` con `X-Send-Outcome: indeterminate` y `X-Control-Id` | El mensaje salió y no volvió ninguna respuesta. Posiblemente llegó a JD. | | `503` con `X-Send-Outcome: duplicate` | El número de control ya tiene un envío. El Courier no envió el mensaje. | | `503` sin `X-Send-Outcome` | El mensaje no llegó a JD. | Después de un envío indeterminado, consulta el número de control con `ConsultaNumCtrlIF`. Una respuesta final de JD resuelve el envío en el registro. No envíes el mensaje de nuevo con el mismo número de control: el Courier lo rechaza. Cuando cada envío anterior del número de control tiene el resultado `NOT_SENT`, el Courier responde la consulta con el código JD `ALN01`, y no reenvía la consulta. ## Pix: recibe las llamadas de JD *** En el riel Pix, el Courier entrega cada llamada entrante a la dirección Pix del motor dueño. El motor sirve las mismas rutas que JD llama, para la validación de cuenta, el cash-in, la devolución y las llamadas de Pix Automático. Para una [validación de cuenta asíncrona](https://docs.lerian.studio/es/interfaces/jd-courier/jd-courier-routing.md#asynchronous-account-validation), el motor recibe su parte de los créditos en `/v1/webhooks/validates/async`. ### Cómo llama el Courier al motor * El Courier agrega la ruta de la llamada de JD a la dirección Pix del motor. Usa el mismo método. * El cuerpo es el cuerpo que JD envió, byte a byte. * El Courier reenvía estos encabezados cuando JD los envía: `Chave-Idempotencia`, `X-DataHoraEvento`, `X-NomeEvento` y `Content-Type`. * El Courier espera la respuesta hasta 60 segundos. Lee hasta 1 MiB de la respuesta. * El Courier no sigue redirecciones. Para entregar los mensajes Pix, el Courier llama a la dirección Pix que registras para cada motor. Registra una credencial para cada motor: entonces, el Courier envía un token de Access Manager con cada llamada. Sin una credencial, el Courier llama al motor sin autenticación. En producción, usa una dirección https. Registrar una dirección Pix requiere el permiso `pix-delivery:write`. El client ID y el secret del motor están en AWS Secrets Manager. Consulta [Credenciales de los motores](https://docs.lerian.studio/es/interfaces/jd-courier/jd-courier-deployment.md#engine-credentials). ### Cómo lee el Courier la respuesta El Courier reenvía a JD la respuesta del motor. Para un mensaje, el estado decide qué pasa después: | Estado del motor | Resultado | | - | - | | `5xx`, `408`, `429` | El Courier reenvía la respuesta a JD y retiene el mensaje. El siguiente reenvío de JD llega de nuevo al motor. | | `3xx`, `401`, `403` o ninguna respuesta | JD recibe `503`, y el Courier retiene el mensaje. | | Cualquier otro estado, por ejemplo `200`, `400` o `422` | El mensaje se entrega. El Courier guarda la respuesta y se la da a JD en cada reenvío. | Un estado de la última fila es final. Para que JD envíe el mensaje de nuevo, responde con un estado de la primera fila. El motor puede recibir el mismo mensaje más de una vez. Por ejemplo, el Courier llama al motor de nuevo después de un timeout. Usa los identificadores que JD envía, como `Chave-Idempotencia`, para reconocer una repetición. ## Pix: envía llamadas a JD a través del Courier *** Cuando activas el [tránsito Pix](https://docs.lerian.studio/es/interfaces/jd-courier/jd-courier-deployment.md#pix-transit), un motor envía sus llamadas Pix a JD a través del Courier, en las rutas JDPI que usa con JD. El Courier llama a JD con la credencial de la cabina SPI de tu institución. 1. Pide al operador que [emita la credencial del tránsito Pix](https://docs.lerian.studio/es/reference/interfaces/jd-courier/issue-the-engines-pix-transit-credential.md) del motor. La respuesta muestra el secret una vez. Guárdalo en ese momento. 2. Cambia la dirección JDPI del motor a la dirección del tránsito. 3. El motor pide su token en la ruta de token JDPI del tránsito, con el client ID y el secret de esa credencial. El propio Courier responde a la solicitud de token. Cuando emites una nueva credencial del tránsito Pix para el mismo motor, la anterior sigue funcionando durante la ventana de superposición y después deja de funcionar. Un operador puede [revocar una credencial](https://docs.lerian.studio/es/reference/interfaces/jd-courier/revoke-one-of-the-engines-pix-transit-credentials.md) en cualquier momento, y sus tokens dejan de funcionar de inmediato. Fuera del resultado de la validación de cuenta, el Courier escribe por su cuenta solo estas respuestas: el token, un `401` sin cuerpo para una credencial rechazada, un `404` sin cuerpo para una ruta fuera de las rutas JDPI y un `503` con `X-Send-Outcome: not-sent`. Ese `503` significa que nada llegó a JD, y el motor puede liberar su retención. Todas las demás respuestas, incluido un `503` de JD, vuelven tal como JD las escribió. Cuando la solicitud pudo llegar a JD y la respuesta de JD se pierde, el Courier cierra la conexión sin respuesta. Trata ese resultado como desconocido y concílialo antes de liberar cualquier cosa. Ningún proxy entre el motor y el JD Courier puede repetir un `503`. En el resultado de la validación de cuenta, el Courier también puede responder `409 JDC-0503`: el crédito ya tiene un resultado diferente, y el primero prevalece. Un `503 JDC-9001` en esa ruta significa que JD no dio veredicto o que el Courier no pudo reenviar el resultado: envía el mismo resultado de nuevo con el mismo `Chave-Idempotencia`. ## Llamadas que el motor hace al Courier *** El rol `admin` sirve las operaciones que llaman los motores: la consulta de titularidad, las reclamaciones, las declaraciones de etapa y el [relay entre cores](#cross-core-relay). Cada motor llama a estas operaciones con una aplicación de Access Manager que el operador vincula al motor. Un motor puede tener varias aplicaciones, una para cada producto que llama al Courier. Un ejemplo es el plugin Pix y el plugin TED del stack de Lerian. El operador registra la primera aplicación con el motor y [vincula](https://docs.lerian.studio/es/reference/interfaces/jd-courier/bind-one-more-credential-to-the-engine.md) cada una de las demás. Una aplicación pertenece a un solo motor. Necesita el permiso `ownership:read` para la consulta, `ownership:write` para las reclamaciones y las declaraciones de etapa, y `cross-core:send` para el relay entre cores. El Courier responde `401` a cualquier otro llamador. Cuando el motor es [Pix vía JD](https://docs.lerian.studio/es/interfaces/pix-jd/direct-pix-via-jd.md), su worker reclama en el Courier sus recurrencias, del lado del pagador o del cobrador, y el CNPJ de cada cobrador que atiende. Antes de que el Courier empiece a recibir Pix, un operador llama a su [ruta de propiedad del Courier](https://docs.lerian.studio/es/reference/interfaces/pix-jd/tell-the-jd-courier-which-pix-automatico-traffic-is-this-engine-s.md) (`POST /v1/pix-automatico/courier-ownership`). La ruta reclama las recurrencias que ya existen y declara las etapas de los pagos en curso. Consulta [Reclamaciones en el Courier](https://docs.lerian.studio/es/interfaces/pix-jd/pix-jd-environment-variables.md#claims-on-the-courier). ### Consulta de titularidad Antes de que el motor liquide un pago dentro de tu institución, debe saber qué motor es dueño del destino. Llama a la [consulta de titularidad](https://docs.lerian.studio/es/reference/interfaces/jd-courier/resolve-which-engine-owns-a-key.md) con la clave como la guardas. La respuesta dice si la clave tiene un dueño, y si ese dueño es el motor que hizo la llamada. La respuesta es definitiva: * `200` con `resolved: true` nombra al dueño. * `200` con `resolved: false` significa que ningún motor de tu institución es dueño de la clave. * `422` significa que la clave no es válida. * Trata cualquier otro estado como un rechazo: falla el pago y no lo liquides dentro de tu institución. ### Reclamación de cuentas y documentos [Reclama](https://docs.lerian.studio/es/reference/interfaces/jd-courier/claim-accounts-charger-documents-and-recurrence-charger-sides-for-the-calling-engine.md) cada cuenta que el motor abre, cuando la abre. Antes de la transición, reclama de la misma forma las cuentas que el motor ya tiene, hasta 1000 claves en cada llamada. La misma llamada reclama el CNPJ de cada cobrador de Pix Automático que atiende el motor (`DOCUMENT`) y el lado del cobrador de cada recurrencia (`PIX_RECURRENCE_ID_CHARGER`). * Reclama una cuenta de pago sin agencia. Una cuenta de pago reclamada con agencia es una clave que el enrutamiento nunca lee. * La respuesta da un resultado para cada clave, en el orden de la solicitud: `CLAIMED`, `ALREADY_OWNED`, `HELD_ELSEWHERE` o `INVALID`. Informa cada `HELD_ELSEWHERE` a un operador: solo un operador mueve una clave. * Después de un `503` o de una respuesta perdida, envía la misma llamada de nuevo. La reclamación es idempotente. ### Reclamación de recurrencia de Pix Automático Cuando el motor autoriza una recurrencia de Pix Automático, [reclama la recurrencia](https://docs.lerian.studio/es/reference/interfaces/jd-courier/claim-a-pix-automatico-recurrence-for-the-calling-engine.md) del lado del pagador. Entonces, el Courier enruta al motor las llamadas de agendamiento de esa recurrencia. La reclamación es idempotente. Una recurrencia que tiene otro motor recibe `409 JDC-0102`. Solo un operador puede moverla. Antes de que el Courier empiece a recibir Pix, cada motor reclama las recurrencias que ya existen. Un mensaje de agendamiento para una recurrencia sin dueño queda retenido hasta que llega la reclamación. Una validación de agendamiento para esa recurrencia recibe `503`. ### Declaración de etapa de Pix Automático Algunas llamadas de Pix Automático siguen una etapa anterior del mismo pago. Consulta [Qué clave enruta cada llamada](https://docs.lerian.studio/es/interfaces/jd-courier/jd-courier-routing.md#which-key-routes-each-call). Antes de que el Courier empiece a recibir Pix, cada motor [declara las etapas que tiene](https://docs.lerian.studio/es/reference/interfaces/jd-courier/declare-an-earlier-leg-of-a-pix-automatico-payment-the-calling-engine-holds.md) para los pagos en curso: * `block`: cada bloqueo del débito que el motor aceptó, cuando el débito o su reversión todavía no llegó. * `schedule`: cada agendamiento cuyo débito, reversión o estado de cancelación todavía no llegó. Sin un bloqueo aceptado, el débito y su reversión siguen al agendamiento. Una llamada que llega antes de que se declare su etapa queda retenida. El Courier la libera después de la declaración. Una declaración que entra en conflicto con el registro del Courier recibe `409 JDC-0116`. Detente e informa a un operador. ## Relay entre cores *** Dos motores de tu institución pueden compartir un ISPB. Un pago de una cuenta de un motor a una cuenta del otro motor no va al STR ni al SPI. El motor pagador lo envía al motor dueño a través del Courier. El Courier reenvía cuatro tipos de pago: | Pago | El motor pagador llama a | El motor dueño lo recibe en | | - | - | - | | Crédito de TED | [`POST /v1/cross-core/ted/credits`](https://docs.lerian.studio/es/reference/interfaces/jd-courier/relay-a-cross-core-ted-credit) | `/v1/cross-core/ted/credits` de su dirección TED | | Devolución de TED | [`POST /v1/cross-core/ted/returns`](https://docs.lerian.studio/es/reference/interfaces/jd-courier/relay-a-cross-core-ted-return) | `/v1/cross-core/ted/returns` de su dirección TED | | Cash-in de Pix | [`POST /v1/cross-core/pix/cash-ins`](https://docs.lerian.studio/es/reference/interfaces/jd-courier/relay-a-cross-core-pix-cash-in) | `/v1/cross-core/pix/cash-ins` de su dirección Pix | | Devolución de Pix | [`POST /v1/cross-core/pix/refunds`](https://docs.lerian.studio/es/reference/interfaces/jd-courier/relay-a-cross-core-pix-refund) | `/v1/cross-core/pix/refunds` de su dirección Pix | Bank Transfer no devuelve una TED que recibió a través del relay. Para el lado de Bank Transfer, consulta [Transferencias entre cores](https://docs.lerian.studio/es/interfaces/ted-jd/ted-cross-core.md). Cada motor sigue el contrato siguiente, incluido el otro core de tu institución. ### Recibir un pago entre cores 1. Pide al operador que registre la dirección TED (`tedDelivery`) y la dirección Pix (`pixDelivery`) del motor. Definirlas requiere los permisos `ted-delivery:write` y `pix-delivery:write`. 2. Sirve las rutas de la tabla. El Courier envía el cuerpo del motor pagador byte a byte. También envía `Content-Type`, `Chave-Idempotencia` cuando el motor pagador lo envía, y `X-Courier-Origin-Engine` con el ID del motor pagador. Cuando la dirección tiene una [credencial](https://docs.lerian.studio/es/interfaces/jd-courier/jd-courier-deployment.md#engine-credentials), el Courier envía un token de Access Manager. 3. Responde con un estado `2xx` cuando acreditas al receptor. El Courier reenvía tu respuesta al motor pagador tal como la escribiste. El Courier hace un intento y espera hasta 15 segundos. El Courier trata una redirección, un `401` y un `403` de tu dirección como una llamada que no aceptaste. El motor pagador envía los mismos bytes de nuevo mientras su resultado es desconocido, así que acredita cada pago una vez. ### Enviar un pago entre cores 1. Llama a la [consulta de titularidad](https://docs.lerian.studio/es/reference/interfaces/jd-courier/resolve-which-engine-owns-a-key.md) para la cuenta del receptor. Envía el pago a través del relay solo cuando otro motor es dueño de la cuenta. 2. Llama a la ruta del relay con una aplicación del motor que tiene el permiso `cross-core:send`. Envía el encabezado `X-Courier-Expected-Owner` con el ID del motor que devolvió la consulta. 3. Pon la cuenta del receptor en el cuerpo. En TED, el Courier lee `payee.branch`, `payee.account` y `payee.accountType` (`PG` para una cuenta de pago, sin agencia). En Pix, lee `recebedor.nrAgencia`, `recebedor.nrConta` y `recebedor.tpConta` (`3` para una cuenta de pago, sin agencia). El Courier reenvía la llamada solo cuando el mapa nombra al motor de `X-Courier-Expected-Owner`. Lee su respuesta así: | Respuesta | Significado | | - | - | | El estado y el cuerpo del motor dueño, sin `X-Send-Outcome` | La llamada llegó al motor dueño. Un estado `2xx` significa que acreditó al receptor. | | `X-Send-Outcome: not-sent` | Nada llegó a un receptor. El código da la causa, por ejemplo: `409 JDC-0118`, ningún motor es dueño de la cuenta; `409 JDC-0119`, el dueño no es el motor de `X-Courier-Expected-Owner`; `409 JDC-0121`, la cuenta es tuya; `503 JDC-0120`, el motor dueño está deshabilitado, no tiene dirección para el riel o no aceptó la llamada. | | `401` | El Courier rechazó tu credencial. No se envió nada. | | Ninguna respuesta: el Courier cierra la conexión | La llamada pudo llegar al motor dueño, y su respuesta no volvió en 15 segundos. El resultado es desconocido. Envía los mismos bytes de nuevo. | Trata `X-Send-Outcome: not-sent` como no enviado. Vale solo para esta llamada. Cuando un intento anterior del mismo pago tuvo un resultado desconocido, mantén la retención: envía los mismos bytes de nuevo, o detente para un operador después de `409 JDC-0119`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.