A veces las partes de un documento provienen de diferentes fuentes. Piensa en una factura XML que llega vía Peppol y un adjunto PDF entregado por separado, o múltiples adjuntos que pertenecen a la misma factura. Con un join hook, el PSB combina automáticamente estos eventos separados en un único documento.

Un join hook escucha en múltiples topics simultáneamente y reconoce qué eventos pertenecen entre sí. El hook distingue dos tipos de eventos:

• Eventos target: el documento principal (por ejemplo, una factura u orden).
• Eventos matching: adjuntos o suplementos que deben vincularse al documento principal.

Mediante expresiones determinas qué evento es el documento principal (target) y cómo se emparejan los adjuntos (when). En cuanto el PSB encuentra una coincidencia, fusiona los adjuntos con el documento principal y publica un nuevo topic.

El flujo es el siguiente:

1. El PSB recibe eventos en los topics configurados (por ejemplo, SalesInvoiceReceived y AttachmentReceived)
2. El join hook evalúa cada evento contra la expresión target para identificar el documento principal
3. Con cada nuevo evento, el hook verifica la expresión when para encontrar una coincidencia
4. Una vez que el target y los eventos matching están vinculados, el PSB añade los adjuntos al documento principal
5. Se publica un nuevo topic (por ejemplo, SalesInvoiceJoined)

La potencia de los join hooks reside en las expresiones. Escribes dos expresiones: una para identificar el documento principal y otra para emparejar los adjuntos.

La expresión target determina si un evento es el documento principal. Un patrón comúnmente utilizado es la coincidencia por topic:

topic=="SalesInvoiceReceived"

La expresión when vincula un evento matching con el evento target correcto. Aquí comparas campos entre el evento de origen (source) y el evento target (target):

target.id == source.id && target.sender == source.sender

En este ejemplo, los eventos se emparejan si tienen el mismo ID de documento y el mismo remitente.

Nota: todas las expresiones deben estar URL-encoded en la URL de acción. La expresión topic=="SalesInvoiceReceived" se convierte en topic%3D%3D%22SalesInvoiceReceived%22. No olvides esto, ya que el PSB analiza las expresiones desde la query string.

Registra un hook a través de la API con una acción join://AddAttachment:

{
  "id": "1",
  "name": "join hook",
  "action": "join://AddAttachment?target=topic%3D%3D%22SalesInvoiceReceived%22&when=target.id%20%3D%3D%20source.id%20%26%26%20target.sender%20%3D%3D%20source.sender&ttl=00:15:00&delay=00:30:00",
  "topics": [
    "AttachmentReceived",
    "SalesInvoiceReceived"
  ],
  "publishTopics": [
    "SalesInvoiceJoined"
  ],
  "isActive": true
}

La acción sigue el formato:

join://AddAttachment?target={target-expression}&when={when-expression}&ttl={ttl}&delay={delay}

El array topics del hook debe contener todos los topics en los que el join hook debe escuchar. Esto incluye topics tanto para el documento principal como para los adjuntos.

El campo publishTopics determina en qué topic se publica el documento fusionado. Puedes configurar un webhook o e-mail hook normal en este topic para recibir el resultado.

El ttl (Time to Live) determina cuánto tiempo espera el PSB para encontrar una coincidencia. Si después del período TTL falta el documento principal o el adjunto, el PSB publica un topic de error (*JoinedError). Esto te permite detectar cuándo un conjunto está incompleto.

Establece el TTL en un valor que se ajuste a tu tiempo de respuesta esperado. Si los adjuntos suelen llegar dentro de una hora, un TTL de 01:00:00 es suficiente.

Consejo: configura un webhook o e-mail hook en el topic *JoinedError. Así recibes una señal cuando falta un adjunto o una factura, lo que te permite actuar a tiempo.

Sin un delay, la fusión comienza en cuanto se encuentran el evento target y un evento matching. Si esperas múltiples adjuntos para el mismo documento, establece un delay. El PSB espera el tiempo especificado después de detectar el evento target y luego fusiona todos los adjuntos emparejados durante ese período de una sola vez.

Supongamos que esperas tres adjuntos PDF para una factura y llegan en un período de 20 minutos. Un delay de 00:30:00 proporciona suficiente margen para recopilar todos los adjuntos.

Una organización recibe facturas vía Peppol (topic SalesInvoiceReceived) y adjuntos PDF acompañantes a través de un canal separado (topic AttachmentReceived). Los adjuntos se emparejan por ID de documento y remitente. Después de la fusión, el documento completo se publica en SalesInvoiceJoined, tras lo cual un webhook lo reenvía al sistema ERP.

Un join hook también sirve para facturas salientes vía SFTP (véase integración SFTP, opcionalmente con fileNameFilter si el XML y el PDF llegan a la misma carpeta).

• target=topic=="SendInvoice" — el XML es el documento primario.
• when=source.fileName.contains(target.id) — el nombre del PDF contiene el número de factura del XML.
• El join publica el topic SendInvoiceJoined.

Atención: un hook que antes escuchaba SendInvoice (por ejemplo un hook de Collabrr o de la plataforma) ya no recibe la factura fusionada en ese topic. Apunte ese hook a SendInvoiceJoined para seguir recibiendo el XML y el PDF fusionados.

Si ve el error SendInvoiceJoinedError con el mensaje JoinEvent TimeToLive reached without receiving matching event, el join hook no ha recibido todos los eventos necesarios dentro del ttl configurado. Falta el documento primario (target) o un evento coincidente (adjunto o parte de la factura), o ha llegado tarde. Las facturas afectadas siguen bloqueadas en el canal hasta que se resuelva.

Diagnóstico y solución:

1. Compruebe qué evento falta: el documento primario (target) o un evento coincidente (when).
2. Vuelva a entregar la parte que falta o corrija el envío en origen.
3. Si el TTL predeterminado de un día es demasiado corto para el ritmo de entrega, ajuste el parámetro ttl del hook.

Consejo: configure un webhook o un hook de correo en el topic SendInvoiceJoinedError para recibir una señal en cuanto un conjunto llegue incompleto.

¿Necesitas ayuda para configurar las expresiones correctas? Contacta con TechSupport en techsupport@econnect.eu. Consulta la especificación completa de la API en psb.econnect.eu para todas las opciones de configuración.