Saltar al contenido principal
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. 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: 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: 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, 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.

​
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: 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, 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 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 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. 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 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, 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 (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.

​
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 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 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 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. Antes de que el Courier empiece a recibir Pix, cada motor declara las etapas que tiene 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: Bank Transfer no devuelve una TED que recibió a través del relay. Para el lado de Bank Transfer, consulta Transferencias entre cores. 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, 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 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í: 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.