Compliance rollup

The compliance rollup is the single authoritative view of a transaction’s end-to-end state. Instead of assembling state from six module endpoints (buyer, order, invoice, payment, transport, export file), call one endpoint and get everything — including a human-readable list of blockers.

Endpoint

GET /partners/{sellerId}/orders/{uuid}/compliance

Response shape

{
  "orderUuid": "o1p2q3r4-...",
  "complianceStatus": "INCOMPLETE",
  "decision": null,
  "blockers": [
    { "module": "transport", "code": "MISSING_CMR", "message": "Signed CMR not uploaded" },
    { "module": "transport", "code": "VIES_PENDING", "message": "Daily VIES check due" }
  ],
  "modules": {
    "buyer": {
      "status": "VALID",
      "viesLastCheckedAt": "2026-04-22T08:00:00Z",
      "viesResult": "VALID",
      "documentsComplete": true,
      "kycVerificationStatus": "VERIFIED"
    },
    "order": {
      "status": "COMPLETE",
      "vins": [{ "vin": "WVW...", "complianceStatus": "TRANSPORT_PENDING" }]
    },
    "invoice": {
      "status": "VALID",
      "type": "PRELIMINARY",
      "vatIncluded": false,
      "finalInvoiceRequired": true,
      "finalInvoiceReceived": false
    },
    "payment": {
      "status": "VALID",
      "amountMatchesInvoice": true,
      "ibanConsistent": true,
      "readyForPickup": true
    },
    "transport": {
      "status": "IN_PROGRESS",
      "pickupConfirmed": true,
      "pickupDate": "2026-04-18",
      "deliveryConfirmed": false,
      "cmrUploaded": false,
      "dailyViesChecksActive": true,
      "vins": [
        { "vin": "WVW...", "pickupConfirmed": true, "deliveryConfirmed": false }
      ]
    },
    "exportFile": {
      "status": "PENDING",
      "downloadUrl": null
    }
  },
  "version": 12,
  "updatedAt": "2026-04-22T10:15:00Z"
}

Status values

complianceStatus is a three-state rollup:

Status	Meaning
`INCOMPLETE`	One or more required artifacts missing. See `blockers[]`.
`VALID`	All modules valid. VAT exemption applies. Export File generates.
`INVALID`	Terminal failure (VIES invalid at pickup, documents unrecoverable, etc.). VAT must be applied. Export File still generates documenting rationale.

decision is populated after the terminal status is reached:

VALID_EXPORT — VAT-exempt transaction complete.
VAT_APPLICABLE — VAT must be applied on the final invoice.

Blockers

blockers[] is the actionable list of what’s missing. Each entry carries:

module — which module is blocking
code — machine-readable key (safe to map to UI copy)
message — human-readable explanation

Always display these to your users. They’re the fastest path to diagnosing “why isn’t this order moving?”

Per-VIN variance

Transport state may differ per VIN in multi-VIN orders (one vehicle picked up, another pending). Check modules.transport.vins[] for per-VIN milestones. Buyer/invoice/payment are order-level.

Polling efficiently with ETag

The rollup supports If-None-Match for cheap polling:

# First call
curl -v "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders/${ORDER_UUID}/compliance" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
# Response includes: ETag: "12"

# Subsequent poll
curl -v "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders/${ORDER_UUID}/compliance" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'If-None-Match: "12"'
# Response: 304 Not Modified  (empty body, no bandwidth spent)

Only refetch the body when version bumps. Use a short poll interval (10–60s) for orders in flight; less for completed orders.

Pattern	Use when
Poll rollup + ETag	Simple integrations, no webhook endpoint infrastructure, small order volume.
Subscribe to `compliance.status_changed` + refetch on event	High volume, need real-time reaction, already running HTTP server.
Both	Defense in depth — webhooks for latency, polling for reconciliation.

See Webhooks overview for the subscription pattern.

Idempotency

How to retry safely.

Webhooks overview

Event-driven alternative to polling.

Get Started

Core Concepts

Integration Guide

Webhooks

Reference

Security & Compliance

Endpoint

Response shape

Status values

Blockers

Per-VIN variance

Polling efficiently with ETag

Next

Idempotency

Webhooks overview

​Endpoint

​Response shape

​Status values

​Blockers

​Per-VIN variance

​Polling efficiently with ETag

​When to poll vs subscribe to webhooks

​Next

Idempotency

Webhooks overview

Endpoint

Response shape

Status values

Blockers

Per-VIN variance

Polling efficiently with ETag

When to poll vs subscribe to webhooks

Next