OrderVoucher

POST /api/trade/orderVoucher

Retrieves the hotel voucher for an order you placed — the travel document your guest presents at the hotel desk.

The voucher is produced by the platform when the supplier confirms the booking, so it is not available the instant Book returns. This endpoint always reports a status; the voucher block is present only when that status is GENERATED. A booking that is genuinely yours but whose voucher has not been issued yet is a 200 with status: NOT_GENERATED, not an error — poll it the same way you poll QueryOrders.

Identifying the order

Supply at least one of customerReferenceNo (your own reference, sent on Book), platformReferenceNo (our order number) or supplierReferenceNo. If a reference matches more than one order the call is refused with 100001008 rather than guessing — supply platformReferenceNo, which is unique.

Getting the bytes

voucher.downloadUrl is a time-limited object URL; voucher.expiresIn is how many seconds it remains valid. Set includeDocument: true to receive the PDF inline as base64 in voucher.content instead of following the link — intended for integrations that cannot reach an object-storage URL from where they run. Documents above 8 MB are never inlined; that request is refused with 100001005.

Checking the document is the one we issued

Every voucher is signed at the moment it is rendered. voucher.signature.digest is the SHA-256 of the exact bytes we issued, in lowercase hex. Hash whatever you received and compare — if the two differ, the file has been altered since issue and must not be given to a traveller. signature.signature is a detached HMAC only we can verify; it is returned so the claim is auditable, not so you can check it yourself. A voucher rendered before document signing was introduced has no signature block at all, rather than a fabricated one.

voucher.verifyUrl is the same public verification page the voucher's QR code opens, which reports whether the document is still valid and whether it is unaltered.

Access

The calling key must be scoped booking:read, and the order must belong to you. An order that is not yours answers 100000404 not found — the same answer as a reference that never existed, so the endpoint cannot be used to probe another seller's order book.

Status values

• GENERATED — issued and current; voucher is present.
• NOT_GENERATED — no voucher has been issued for this order yet.
• PENDING — a voucher number is reserved and the document is being produced.
• FAILED — generation was attempted and did not complete; contact support.
• CANCELLED — the booking is cancelled. The document is deliberately withheld: a reissued voucher for a cancelled stay is stamped "not valid for check-in" and must not be handed to a traveller by an automated pipeline.

Request headers

Request body

Example request

{
  "customerReferenceNo": "9d1f4b2a-7c60-4f3e-9a58-1b0c2d3e4f50"
}

Response

Successful calls return the standard envelope. code is 0 on success — check it rather than the HTTP status alone, because some business failures are delivered with HTTP 200.

Example response

{
  "code": 0,
  "msg": "string",
  "data": {
    "customerReferenceNo": "string",
    "platformReferenceNo": "string",
    "supplierReferenceNo": "string",
    "status": "GENERATED",
    "voucher": {
      "voucherNumber": "VCH-TTD-2026-000042-01",
      "version": 0,
      "issuedAt": "string",
      "contentType": "application/pdf",
      "byteSize": 0,
      "verifyUrl": "string",
      "downloadUrl": "string",
      "expiresIn": 0,
      "signature": {
        "alg": "HMAC-SHA256",
        "keyId": "ttd-derived-v1",
        "digest": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
        "signature": "string",
        "signedAt": "string"
      },
      "content": {
        "contentType": "string",
        "byteSize": 0,
        "base64": "string"
      }
    }
  }
}

Failure responses

Every failure uses the { code, msg } envelope. See Error handling for the full business-code table.