Integration guide: Connecting a third-party system to QHUB for receiving/sending Peppol documents via APEX

1. Dohodnutie SystemCode + TenantId s ASOL
         ↓
2. Odoslanie popisu entity PeppolDocument do QHUB Registration API
         ↓
3. Administrátor ASOL vygeneruje jednorazový registračný kľúč
         ↓
4. Váš systém odošle kľúč na Registration API → získa RabbitMQ credentials
         ↓
5. Nakonfigurujete RabbitMQ v svojom systéme
         ↓
6. Otestujete end-to-end komunikáciu

POST {QHUB_REGISTRATION_URL}/api/v1/SyncEntityCatalogItem/StoreSyncEntityItems
Content-Type: application/json
X-Api-Key: {váš API kľúč}

{
  "System": "MYERP",
  "SyncEntityDatas": [
    {
      "EntityCode": "PeppolDocument",
      "EntityType": 100,
      "DefaultAllowed": true,
      "Version": "1.0.0",
      "SyncEntityDefinitionData": {
        "SyncPropertiesData": [
          { "Name": "SenderParticipantId",   "OriginalName": "senderParticipantId",   "ProperyType": "String",   "Required": true,  "IsBusinessKey": false },
          { "Name": "ReceiverParticipantId", "OriginalName": "receiverParticipantId", "ProperyType": "String",   "Required": true,  "IsBusinessKey": false },
          { "Name": "DocumentTypeId",        "OriginalName": "documentTypeId",        "ProperyType": "String",   "Required": true,  "IsBusinessKey": false },
          { "Name": "ProcessId",             "OriginalName": "processId",             "ProperyType": "String",   "Required": true,  "IsBusinessKey": false },
          { "Name": "UblDocument",           "OriginalName": "ublDocument",           "ProperyType": "String",   "Required": true,  "IsBusinessKey": false },
          { "Name": "As4MessageId",          "OriginalName": "as4MessageId",          "ProperyType": "String",   "Required": false, "IsBusinessKey": true  },
          { "Name": "ReceivedAt",            "OriginalName": "receivedAt",            "ProperyType": "DateTime", "Required": false, "IsBusinessKey": false }
        ],
        "SyncForeignKeysData": []
      }
    }
  ]
}

POST {QHUB_REGISTRATION_URL}/api/v1/Registration/Validate
Content-Type: application/json

{
  "ParticipantSystem": "MYERP",
  "ParticipantTenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "RegistrationKey": "REG-KEY-ODOSLANY-ADMINOM",
  "RoutingKey": "MYERP.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

{
  "ParticipantSystem": "MYERP",
  "ParticipantTenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "RabbitMqUrl": "amqps://rmq.qcloud.assecosoldevsk.com:5671",
  "RabbitMqName": "myerp_tenant_abc123",
  "RabbitMqPass": "••••••••••••",
  "ErrorCode": null,
  "Success": true,
  "RegisteredEntities": [
    {
      "EntityType": 100,
      "OwnerSystem": "APEX",
      "OwnerTenantId": "...",
      "RoutingKey": "MYERP.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "Operations": 1,
      "Direction": 0,
      "SyncMode": 0,
      "AllowedFrom": "2026-04-16T00:00:00Z",
      "AllowedTo": "2027-04-16T00:00:00Z",
      "DeliverySystem": "MYERP",
      "DeliveryTenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ]
}

Meno:       clouderp-delivery-queue.MYERP.{TenantId}
Durable:    true
Auto-delete: false
Arguments:
  x-dead-letter-exchange: clouderp.dlq   (odporúčané)

Exchange:    clouderp.delivery
Type:        direct
Routing key: MYERP.{TenantId}

Peppol odosielateľ
    → AS4 → APEX
        → QHUB (SynchronizationMessage, EntityType=PeppolDocument)
            → clouderp-delivery-queue.MYERP.{TenantId}
                → VÁŠ KONZUMER
                    → spracujete UBL XML (importujete faktúru)
                        → SynchronizationResponseMessage → clouderp.sync.response

{
  "TransactionId": 123456,
  "EventType": 1,
  "EntityType": 100,
  "RoutingKey": "MYERP.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "OwnerTenantId": "apex-tenant-uuid",
  "OwnerSystem": "APEX",
  "DeliverySystem": "MYERP",
  "DeliveryTenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "SyncKey": "550e8400-e29b-41d4-a716-446655440000",
  "SchemaVersion": "1.0.0",
  "Environment": "prod",
  "DomainSyncVersion": 1,
  "OccurredAt": "2026-04-16T10:30:00+02:00",
  "Data": "{\"SenderParticipantId\":\"0245:2024000001\",\"ReceiverParticipantId\":\"0245:9999999999\",\"DocumentTypeId\":\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1\",\"ProcessId\":\"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0\",\"UblDocument\":\"<?xml version=\\\"1.0\\\"...>\",\"As4MessageId\":\"uuid@peppol\",\"ReceivedAt\":\"2026-04-16T10:29:58+02:00\"}",
  "IgnoredProperties": null
}

{
  "TransactionId": 123456,
  "Result": {
    "Success": true,
    "ErrorCode": null,
    "ErrorParams": null
  }
}

{
  "TransactionId": 123456,
  "Result": {
    "Success": false,
    "ErrorCode": "ImportFailed",
    "ErrorParams": ["Duplicitná faktúra INV-2026-001"]
  }
}

VÁŠ SYSTÉM
    → SynchronizationMessage (EntityType=PeppolDocument)
        → clouderp.sync (fanout exchange)
            → QHUB Synchronization Service
                → APEX (clouderp-delivery-queue.APEX)
                    → AS4 / HTTPS
                        → Peppol príjemca

QHUB → SynchronizationResponseMessage → clouderp.sync.response
    → VÁŠ konzumer odpovede (voliteľné, ale odporúčané)

{
  "TransactionId": 0,
  "EventType": 1,
  "EntityType": 100,
  "RoutingKey": "MYERP.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "OwnerTenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "OwnerSystem": "MYERP",
  "DeliverySystem": null,
  "DeliveryTenantId": null,
  "SyncKey": "novy-uuid-pre-tuto-spravu",
  "SchemaVersion": "1.0.0",
  "Environment": "prod",
  "DomainSyncVersion": 1,
  "OccurredAt": "2026-04-16T10:30:00+02:00",
  "Data": "{\"SenderParticipantId\":\"0245:2024000001\",\"ReceiverParticipantId\":\"0245:9999999999\",\"DocumentTypeId\":\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1\",\"ProcessId\":\"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0\",\"UblDocument\":\"<?xml version=\\\"1.0\\\"...>\"}",
  "IgnoredProperties": null
}

{
  "SenderParticipantId": "0245:2024000001",
  "ReceiverParticipantId": "0245:9999999999",
  "DocumentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
  "ProcessId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
  "UblDocument": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">...</Invoice>",
  "As4MessageId": "abc123@receiver.peppol.ap",
  "ReceivedAt": "2026-04-16T10:29:58+02:00"
}

@Configuration
public class QhubRabbitConfig {

    @Value("${qhub.rabbitmq.host}")      private String host;
    @Value("${qhub.rabbitmq.port:5671}") private int port;
    @Value("${qhub.rabbitmq.username}")  private String username;
    @Value("${qhub.rabbitmq.password}")  private String password;
    @Value("${myapp.tenant-id}")         private String tenantId;

    @Bean
    public ConnectionFactory qhubConnectionFactory() {
        CachingConnectionFactory cf = new CachingConnectionFactory(host, port);
        cf.setUsername(username);
        cf.setPassword(password);
        cf.setVirtualHost("/");
        cf.getRabbitConnectionFactory().useSslProtocol(); // TLS povinné
        return cf;
    }

    @Bean
    public RabbitTemplate qhubRabbitTemplate(ConnectionFactory qhubConnectionFactory) {
        RabbitTemplate rt = new RabbitTemplate(qhubConnectionFactory);
        rt.setMessageConverter(new Jackson2JsonMessageConverter());
        return rt;
    }

    @Bean
    public Queue myDeliveryQueue() {
        return QueueBuilder
            .durable("clouderp-delivery-queue.MYERP." + tenantId)
            .withArgument("x-dead-letter-exchange", "clouderp.dlq")
            .build();
    }

    @Bean
    public DirectExchange deliveryExchange() {
        return new DirectExchange("clouderp.delivery", true, false);
    }

    @Bean
    public Binding myDeliveryBinding(Queue myDeliveryQueue, DirectExchange deliveryExchange) {
        return BindingBuilder.bind(myDeliveryQueue)
            .to(deliveryExchange)
            .with("MYERP." + tenantId);
    }
}

@Slf4j
@Component
@RequiredArgsConstructor
public class PeppolDocumentConsumer {

    private static final int PEPPOL_DOCUMENT_ENTITY_TYPE = 100; // dohodnuté s ASOL

    private final ObjectMapper objectMapper;
    private final RabbitTemplate qhubRabbitTemplate;
    private final MyInvoiceImportService importService; // vaša biznis logika

    @RabbitListener(queues = "#{myDeliveryQueue.name}")
    public void onMessage(SynchronizationMessage message) {
        if (message.getEntityType() != PEPPOL_DOCUMENT_ENTITY_TYPE) {
            return; // neznáma entita, ignorovať
        }

        SyncResult result;
        try {
            PeppolDocument doc = objectMapper.readValue(
                message.getData(), PeppolDocument.class);

            // Importujte UBL XML do vášho systému
            importService.importInvoice(doc.getUblDocument(), doc.getSenderParticipantId());

            result = new SyncResult(true, null, null);
        } catch (DuplicateDocumentException e) {
            log.warn("Duplicate document, transactionId={}", message.getTransactionId());
            result = new SyncResult(false, "DuplicateDocument", new String[]{e.getMessage()});
        } catch (Exception e) {
            log.error("Failed to process PeppolDocument, transactionId={}",
                message.getTransactionId(), e);
            result = new SyncResult(false, "UnexpectedError", new String[]{e.getMessage()});
        }

        // Vždy odošlite odpoveď
        sendResponse(message.getTransactionId(), result);
    }

    private void sendResponse(long transactionId, SyncResult result) {
        SynchronizationResponseMessage response =
            new SynchronizationResponseMessage(transactionId, result);
        qhubRabbitTemplate.convertAndSend("clouderp.sync.response", "", response);
    }
}

@Slf4j
@Component
@RequiredArgsConstructor
public class PeppolDocumentSender {

    private static final int    PEPPOL_DOCUMENT_ENTITY_TYPE = 100;
    private static final int    EVENT_TYPE_CREATE            = 1;
    private static final String SCHEMA_VERSION               = "1.0.0";

    private final RabbitTemplate qhubRabbitTemplate;
    private final ObjectMapper objectMapper;

    @Value("${myapp.system-code:MYERP}")
    private String systemCode;

    @Value("${myapp.tenant-id}")
    private String tenantId;

    /**
     * Odošle UBL XML dokument do QHUB → APEX → Peppol.
     */
    public void send(String senderParticipantId,
                     String receiverParticipantId,
                     String documentTypeId,
                     String processId,
                     String ublXml) throws Exception {

        PeppolDocument doc = new PeppolDocument();
        doc.setSenderParticipantId(senderParticipantId);
        doc.setReceiverParticipantId(receiverParticipantId);
        doc.setDocumentTypeId(documentTypeId);
        doc.setProcessId(processId);
        doc.setUblDocument(ublXml);

        SynchronizationMessage msg = new SynchronizationMessage();
        msg.setEventType(EVENT_TYPE_CREATE);
        msg.setEntityType(PEPPOL_DOCUMENT_ENTITY_TYPE);
        msg.setRoutingKey(systemCode + "." + tenantId);
        msg.setOwnerSystem(systemCode);
        msg.setOwnerTenantId(tenantId);
        msg.setSyncKey(UUID.randomUUID().toString());
        msg.setSchemaVersion(SCHEMA_VERSION);
        msg.setEnvironment("prod");
        msg.setDomainSyncVersion(1);
        msg.setOccurredAt(OffsetDateTime.now());
        msg.setData(objectMapper.writeValueAsString(doc));

        qhubRabbitTemplate.convertAndSend("clouderp.sync", "", msg);
        log.info("Document sent to QHUB: sender={}, receiver={}", senderParticipantId, receiverParticipantId);
    }
}

services.AddMassTransit(config =>
{
    config.AddConsumer<PeppolDocumentConsumer>();

    config.UsingRabbitMq((ctx, cfg) =>
    {
        cfg.Host(configuration["Qhub:RabbitMq:Host"], "/", h =>
        {
            h.Username(configuration["Qhub:RabbitMq:Username"]);
            h.Password(configuration["Qhub:RabbitMq:Password"]);
            h.UseSsl(s => s.Protocol = SslProtocols.Tls12);
        });

        // Konfigurácia odosielania (sync queue)
        cfg.Message<SynchronizationMessage>(p =>
            p.SetEntityName("clouderp.sync"));

        // Konfigurácia odposielania odpovede
        cfg.Message<SynchronizationResponseMessage>(p =>
            p.SetEntityName("clouderp.sync.response"));

        // Delivery queue s binding na exchange
        cfg.ReceiveEndpoint(
            $"clouderp-delivery-queue.MYERP.{tenantId}", e =>
        {
            e.ConfigureConsumeTopology = false;
            e.UseMessageRetry(r => r.Immediate(1));
            e.Bind("clouderp.delivery", x =>
            {
                x.RoutingKey  = $"MYERP.{tenantId}";
                x.ExchangeType = ExchangeType.Direct;
            });
            e.ConfigureConsumer<PeppolDocumentConsumer>(ctx);
        });
    });
});

public class PeppolDocumentConsumer : IConsumer<SynchronizationMessage>
{
    private const int PeppolDocumentEntityType = 100;
    private readonly IInvoiceImportService _importService;
    private readonly IPublishEndpoint _publishEndpoint;

    public PeppolDocumentConsumer(IInvoiceImportService importService,
                                   IPublishEndpoint publishEndpoint)
    {
        _importService   = importService;
        _publishEndpoint = publishEndpoint;
    }

    public async Task Consume(ConsumeContext<SynchronizationMessage> context)
    {
        var message = context.Message;
        if (message.EntityType != PeppolDocumentEntityType)
            return;

        SyncResult result;
        try
        {
            var doc = JsonSerializer.Deserialize<PeppolDocument>(message.Data!);

            await _importService.ImportAsync(doc.UblDocument, doc.SenderParticipantId);

            result = SyncResult.Ok();
        }
        catch (DuplicateDocumentException ex)
        {
            result = SyncResult.Fail("DuplicateDocument", new[] { ex.Message });
        }
        catch (Exception ex)
        {
            result = SyncResult.Fail("UnexpectedError", new[] { ex.Message });
        }

        await _publishEndpoint.Publish(
            new SynchronizationResponseMessage(message.TransactionId, result));
    }
}

public class PeppolDocumentSender
{
    private const int    PeppolDocumentEntityType = 100;
    private const string SchemaVersion            = "1.0.0";

    private readonly IPublishEndpoint _bus;
    private readonly string _systemCode;
    private readonly string _tenantId;

    public PeppolDocumentSender(IPublishEndpoint bus,
                                 IConfiguration config)
    {
        _bus        = bus;
        _systemCode = config["MyApp:SystemCode"]!;
        _tenantId   = config["MyApp:TenantId"]!;
    }

    public async Task SendAsync(string senderParticipantId,
                                string receiverParticipantId,
                                string documentTypeId,
                                string processId,
                                string ublXml,
                                CancellationToken ct = default)
    {
        var doc = new PeppolDocument
        {
            SenderParticipantId   = senderParticipantId,
            ReceiverParticipantId = receiverParticipantId,
            DocumentTypeId        = documentTypeId,
            ProcessId             = processId,
            UblDocument           = ublXml
        };

        var message = new SynchronizationMessage
        {
            EventType         = 1, // CREATE
            EntityType        = PeppolDocumentEntityType,
            RoutingKey        = $"{_systemCode}.{_tenantId}",
            OwnerSystem       = _systemCode,
            OwnerTenantId     = _tenantId,
            SyncKey           = Guid.NewGuid().ToString(),
            SchemaVersion     = SchemaVersion,
            Environment       = "prod",
            DomainSyncVersion = 1,
            OccurredAt        = DateTimeOffset.UtcNow,
            Data              = JsonSerializer.Serialize(doc)
        };

        await _bus.Publish(message, ct);
    }
}

import json
import ssl
import uuid
from datetime import datetime, timezone
import pika

QHUB_HOST      = "rmq.qcloud.assecosoldevsk.com"
QHUB_PORT      = 5671
QHUB_USER      = "myerp_tenant_abc123"
QHUB_PASS      = "••••••••"
MY_SYSTEM_CODE = "MYERP"
MY_TENANT_ID   = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
ENTITY_TYPE    = 100  # PeppolDocument

DELIVERY_QUEUE  = f"clouderp-delivery-queue.{MY_SYSTEM_CODE}.{MY_TENANT_ID}"
SYNC_EXCHANGE   = "clouderp.sync"
RESPONSE_EXCHANGE = "clouderp.sync.response"


def connect():
    ssl_ctx = ssl.create_default_context()
    credentials = pika.PlainCredentials(QHUB_USER, QHUB_PASS)
    params = pika.ConnectionParameters(
        host=QHUB_HOST, port=QHUB_PORT,
        credentials=credentials,
        ssl_options=pika.SSLOptions(ssl_ctx, QHUB_HOST)
    )
    return pika.BlockingConnection(params)


# ── Prijímanie dokumentov ──────────────────────────────────────────────────

def on_message(channel, method, properties, body):
    msg = json.loads(body)
    if msg.get("EntityType") != ENTITY_TYPE:
        channel.basic_ack(delivery_tag=method.delivery_tag)
        return

    transaction_id = msg["TransactionId"]
    try:
        doc = json.loads(msg["Data"])
        ubl_xml = doc["UblDocument"]

        # --- vaša biznis logika ---
        import_invoice(ubl_xml, doc["SenderParticipantId"])

        result = {"Success": True, "ErrorCode": None, "ErrorParams": None}
    except Exception as e:
        result = {"Success": False, "ErrorCode": "UnexpectedError", "ErrorParams": [str(e)]}

    response = {"TransactionId": transaction_id, "Result": result}
    channel.basic_publish(
        exchange=RESPONSE_EXCHANGE, routing_key="",
        body=json.dumps(response),
        properties=pika.BasicProperties(content_type="application/json")
    )
    channel.basic_ack(delivery_tag=method.delivery_tag)


def start_consuming():
    conn    = connect()
    channel = conn.channel()
    channel.queue_declare(queue=DELIVERY_QUEUE, durable=True,
                          arguments={"x-dead-letter-exchange": "clouderp.dlq"})
    channel.queue_bind(queue=DELIVERY_QUEUE,
                       exchange="clouderp.delivery",
                       routing_key=f"{MY_SYSTEM_CODE}.{MY_TENANT_ID}")
    channel.basic_consume(queue=DELIVERY_QUEUE, on_message_callback=on_message)
    channel.start_consuming()


# ── Odosielanie dokumentov ──────────────────────────────────────────────────

def send_document(sender_id, receiver_id, document_type_id, process_id, ubl_xml):
    doc = {
        "SenderParticipantId":   sender_id,
        "ReceiverParticipantId": receiver_id,
        "DocumentTypeId":        document_type_id,
        "ProcessId":             process_id,
        "UblDocument":           ubl_xml,
    }
    message = {
        "TransactionId":     0,
        "EventType":         1,
        "EntityType":        ENTITY_TYPE,
        "RoutingKey":        f"{MY_SYSTEM_CODE}.{MY_TENANT_ID}",
        "OwnerSystem":       MY_SYSTEM_CODE,
        "OwnerTenantId":     MY_TENANT_ID,
        "SyncKey":           str(uuid.uuid4()),
        "SchemaVersion":     "1.0.0",
        "Environment":       "prod",
        "DomainSyncVersion": 1,
        "OccurredAt":        datetime.now(timezone.utc).isoformat(),
        "Data":              json.dumps(doc),
    }
    conn    = connect()
    channel = conn.channel()
    channel.basic_publish(
        exchange=SYNC_EXCHANGE, routing_key="",
        body=json.dumps(message),
        properties=pika.BasicProperties(content_type="application/json",
                                        delivery_mode=2)  # persistent
    )
    conn.close()


def import_invoice(ubl_xml: str, sender_id: str):
    # Vaša implementácia importu
    pass