> ## Documentation Index
> Fetch the complete documentation index at: https://developers.novatrade24.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Compliance rollup

> One endpoint, one source of truth for end-to-end compliance state of an order.

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

```json theme={null}
{
  "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:

```bash theme={null}
# 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.

## When to poll vs subscribe to webhooks

| 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](/concepts/webhooks-overview) for the subscription
pattern.

## Next

<CardGroup cols={2}>
  <Card title="Idempotency" icon="arrows-rotate" href="/concepts/idempotency">
    How to retry safely.
  </Card>

  <Card title="Webhooks overview" icon="bell" href="/concepts/webhooks-overview">
    Event-driven alternative to polling.
  </Card>
</CardGroup>