Skip to main content
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.

​
The six modules

1

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

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

Invoice

Submit the buyer’s VAT-compliance invoice data and PDF. One preliminary invoice per order. Final invoice is submitted later during finalization when the VAT decision is known.See Invoice & Payment.
4

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

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

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.

​
Compliance rollup

GET /orders/{uuid}/compliance returns the authoritative state of every module plus a list of blockers: 
{
  "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.

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

Buyer onboarding

Start the workflow — create a buyer, run KYC.

Compliance rollup

Understand how module states aggregate into a single decision.