> ## 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.

# End-to-end workflow

> How the six modules chain together into one EU VAT-compliant cross-border transaction.

Every Novatrade24 Integration API transaction flows through the same six
modules. Each module is a distinct resource (or sub-resource) with its own
endpoints, but they share a single compliance rollup that tells you — at any
point — whether the transaction is ready for pickup, ready for export, or
blocked on a specific missing artifact.

```mermaid theme={null}
flowchart LR
    B[Buyer / KYC] --> O[Order]
    O --> I[Invoice]
    O --> P[Payment]
    O --> T[Transport]
    I --> C[Compliance rollup]
    P --> C
    T --> C
    C --> F[Finalization /<br/>Export File]
```

## The six modules

<Steps>
  <Step title="Buyer / KYC">
    Upsert a buyer by VAT number. Choose a KYC mode:

    * **`MARKETPLACE_LED`** (Mode A) — You provide KYC data. NT24 stores it and
      runs VIES validation only. Your `IntegrationOrganization` must have
      `allowMarketplaceLedKyc=true`.
    * **`NT24_LED`** (Mode B) — NT24 runs full verification (iDenfy + AML) and
      generates a signed KYC profile PDF.

    Upload KYC documents, trigger VIES, and optionally generate a buyer-facing
    self-service invitation so the buyer uploads their own documents via an
    emailed link. See [Buyer onboarding](/guides/buyer-onboarding).
  </Step>

  <Step title="Order">
    Register a VIN-based transaction linked to the buyer. Orders carry one or
    more VINs (single-VIN for the Santander pilot; `allowMultiVinOrders` gates
    N-VIN orders). Each order gets an UUID and your `externalOrderId` is the
    natural key for idempotent upsert.

    VIN is not globally unique — the same VIN may appear in multiple orders over
    time (resale, buyback). Look up orders by VIN with `GET /orders?vin={vin}`.

    See [Order creation](/guides/order-creation).
  </Step>

  <Step title="Invoice">
    Submit the buyer's VAT-compliance invoice data and PDF. One preliminary
    invoice per order. Final invoice is submitted later during
    [finalization](/guides/finalization) when the VAT decision is known.

    See [Invoice & Payment](/guides/invoice-payment).
  </Step>

  <Step title="Payment">
    Submit proof-of-payment data (date, bank amount, cash amount, source IBAN)
    and the supporting document. Call `/payment/ready-for-pickup` when payment
    is fully received — this triggers the daily VIES re-check workflow until
    the vehicle is picked up.
  </Step>

  <Step title="Transport">
    Confirm pickup and (later) delivery. Each milestone is **immutable once
    set** — retries return `409` with the current state. If a pickup needs to
    be reversed, use the explicit `/pickup/revoke` endpoint.

    Upload transport documents as you go: `TRANSPORT_CMR`, `TRANSPORT_CMR_DELIVERY`,
    `TRANSPORT_PICKUP_DECLARATION`, or `TRANSPORT_CONFIRMATION_OF_ARRIVAL`.

    See [Transport](/guides/transport).
  </Step>

  <Step title="Compliance & Finalization">
    Poll `GET /orders/{uuid}/compliance` for the rollup or subscribe to the
    `compliance.status_changed` webhook. When compliance transitions to `VALID`
    or `INVALID`, NT24 auto-generates the Export File PDF and fires
    `export_file.generated`.

    If compliance is `INVALID`, submit the final invoice with VAT applied. The
    Export File regenerates to document the rationale for tax authorities.

    See [Finalization](/guides/finalization).
  </Step>
</Steps>

## Compliance rollup

`GET /orders/{uuid}/compliance` returns the authoritative state of every
module plus a list of blockers:

```json theme={null}
{
  "orderUuid": "...",
  "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", "viesResult": "VALID", ... },
    "order":    { "status": "COMPLETE", ... },
    "invoice":  { "status": "VALID", ... },
    "payment":  { "status": "VALID", ... },
    "transport":{ "status": "IN_PROGRESS", ... },
    "exportFile":{ "status": "PENDING", ... }
  },
  "version": 12,
  "updatedAt": "2026-04-22T10:15:00Z"
}
```

This single endpoint is what you poll (or what your webhook handler fetches
after `compliance.status_changed`) to know **exactly** what's blocking
progress. See [Compliance rollup](/concepts/compliance-rollup).

## Two synchronization styles

### Poll the rollup

Simple, stateless. Poll `GET /orders/{uuid}/compliance` every 30s for orders
in flight. Use `If-None-Match` with the previous `ETag` to get `304 Not
Modified` when nothing changed — cheap.

### Subscribe to webhooks

Real-time, event-driven. Register a webhook endpoint via
`POST /v1/webhooks` and subscribe to the events you care about. NT24
delivers signed HTTP POSTs on state transitions. See [Webhooks
setup](/webhooks/setup).

Most integrations use **both**: webhooks for real-time react + polling as
a reconciliation fallback.

## Manual fallback

Everything that can be done via API can also be done in the Novatrade24 web
app. API-created orders are visible to your NT24 staff users; staff edits
show up in API responses (with `source: WEB_APP` on the corresponding
webhook events — Phase 3+). Use the web app for exceptional cases the API
doesn't cover; the compliance rollup is the source of truth either way.

## Next

<CardGroup cols={2}>
  <Card title="Buyer onboarding" icon="user-plus" href="/guides/buyer-onboarding">
    Start the workflow — create a buyer, run KYC.
  </Card>

  <Card title="Compliance rollup" icon="gauge" href="/concepts/compliance-rollup">
    Understand how module states aggregate into a single decision.
  </Card>
</CardGroup>