# Novatrade24 Integration API

> Customer-facing integration API documentation for the Novatrade24 compliance platform.

## Docs

- [Add a contact person to the buyer.](https://developers.novatrade24.com/api-reference/buyers/add-a-contact-person-to-the-buyer.md)
- [Block a buyer.](https://developers.novatrade24.com/api-reference/buyers/block-a-buyer.md)
- [Get a buyer (business data only).](https://developers.novatrade24.com/api-reference/buyers/get-a-buyer-business-data-only.md): Returns company-level data (name, VAT, address, status). Personal contact data is on `/contacts` and gated by `allowContactPersonalData` capability.
- [List buyer contact persons.](https://developers.novatrade24.com/api-reference/buyers/list-buyer-contact-persons.md): GDPR-gated: requires `allowContactPersonalData` capability. Access is audited to the PII access log (6-year retention).
- [Lookup buyer by VAT number.](https://developers.novatrade24.com/api-reference/buyers/lookup-buyer-by-vat-number.md)
- [Unblock a buyer.](https://developers.novatrade24.com/api-reference/buyers/unblock-a-buyer.md)
- [Update a buyer (including KYC mode upgrade A→B).](https://developers.novatrade24.com/api-reference/buyers/update-a-buyer-including-kyc-mode-upgrade-a→b.md): Updates mutable fields. `kycMode` may be upgraded from `MARKETPLACE_LED` to `NT24_LED` but not downgraded. Requires `If-Match` header with current ETag for optimistic locking.
- [Upsert a buyer (create or return existing by VAT).](https://developers.novatrade24.com/api-reference/buyers/upsert-a-buyer-create-or-return-existing-by-vat.md): Upserts a buyer by `(sellerId, vatNumber)`. Second call with identical body returns `200` with the existing buyer. Second call with a different body returns `409` with the current resource (use `PATCH` to update fields explicitly).
- [Get end-to-end compliance rollup for an order.](https://developers.novatrade24.com/api-reference/compliance/get-end-to-end-compliance-rollup-for-an-order.md): Lean endpoint returning compliance status, blockers, and per-module sub-state (buyer, order, invoice, payment, transport, export file). Use with `If-None-Match` to poll cheaply — `304` when unchanged.
- [Get current integration organization and authorized partners.](https://developers.novatrade24.com/api-reference/discovery/get-current-integration-organization-and-authorized-partners.md): Returns the caller's `IntegrationOrganization` profile, the list of `TradePartner` entities the caller is authorized to act on behalf of, and the capability flags that gate feature access. Call once at client startup.
- [List authorized partners.](https://developers.novatrade24.com/api-reference/discovery/list-authorized-partners.md)
- [Download a document.](https://developers.novatrade24.com/api-reference/documents/download-a-document.md): Access control: caller must be authorized for the partner that owns the document. KYC documents additionally require `allowKycDocumentDownload` capability.
- [Supersede a document (archive).](https://developers.novatrade24.com/api-reference/documents/supersede-a-document-archive.md): Set `status: ARCHIVED` to supersede. Latest `ACTIVE` document of each type is what counts for compliance.
- [Force regeneration of the Export File.](https://developers.novatrade24.com/api-reference/finalization/force-regeneration-of-the-export-file.md)
- [Get Export File status and download URL.](https://developers.novatrade24.com/api-reference/finalization/get-export-file-status-and-download-url.md)
- [Submit final invoice data (when required).](https://developers.novatrade24.com/api-reference/finalization/submit-final-invoice-data-when-required.md)
- [Get current invoice.](https://developers.novatrade24.com/api-reference/invoice/get-current-invoice.md)
- [Submit invoice data.](https://developers.novatrade24.com/api-reference/invoice/submit-invoice-data.md): Upsert by `(orderUuid, type)`. One preliminary + one final per order.
- [Update invoice data.](https://developers.novatrade24.com/api-reference/invoice/update-invoice-data.md)
- [Upload invoice PDF.](https://developers.novatrade24.com/api-reference/invoice/upload-invoice-pdf.md): Allowed types: `SHIPMENT_INVOICE`, `SHIPMENT_PRELIMINARY_INVOICE`.
- [Download the verified KYC profile PDF (Mode B only).](https://developers.novatrade24.com/api-reference/kyc/download-the-verified-kyc-profile-pdf-mode-b-only.md)
- [Get KYC status for a buyer.](https://developers.novatrade24.com/api-reference/kyc/get-kyc-status-for-a-buyer.md): Mode-aware payload. Includes VIES result, document completeness, and (Mode B) verification + AML status.
- [Trigger a VIES check on the buyer's VAT number.](https://developers.novatrade24.com/api-reference/kyc/trigger-a-vies-check-on-the-buyers-vat-number.md): Works for both Mode A and Mode B. Result is written to KYC status. Failing checks emit the `kyc.vies_check_failed` webhook.
- [Trigger NT24-led verification (Mode B only).](https://developers.novatrade24.com/api-reference/kyc/trigger-nt24-led-verification-mode-b-only.md): Starts iDenfy + AML flow for buyers created with `kycMode: NT24_LED`. Returns `400` on Mode A buyers.
- [Upload a KYC document.](https://developers.novatrade24.com/api-reference/kyc/upload-a-kyc-document.md): Allowed `type` values (from platform `DocumentType` enum): `COC_*`, `BANK_*`, `VAT_*`, `CONTACT_*`, `ADDRESS_*`, `TP_*`, `AML_DECLARATION`.
- [Cancel an order.](https://developers.novatrade24.com/api-reference/orders/cancel-an-order.md)
- [Create an order.](https://developers.novatrade24.com/api-reference/orders/create-an-order.md): `externalOrderId` is required and unique per `(sellerId, externalOrderId)`. Second call with same body returns `200`; different body returns `409`.
- [Get an order.](https://developers.novatrade24.com/api-reference/orders/get-an-order.md)
- [List orders.](https://developers.novatrade24.com/api-reference/orders/list-orders.md)
- [Update an order.](https://developers.novatrade24.com/api-reference/orders/update-an-order.md)
- [Upload an order-level document.](https://developers.novatrade24.com/api-reference/orders/upload-an-order-level-document.md): Allowed `type` values: `ORDER_PURCHASING_CONTRACT`, `ORDER_ADDITIONAL_INFORMATION`.
- [Get current payment.](https://developers.novatrade24.com/api-reference/payment/get-current-payment.md)
- [Mark payment ready for pickup.](https://developers.novatrade24.com/api-reference/payment/mark-payment-ready-for-pickup.md): Triggers the daily VIES-check workflow on the buyer until pickup is confirmed. Safe to call repeatedly (idempotent).
- [Submit payment data.](https://developers.novatrade24.com/api-reference/payment/submit-payment-data.md): Upsert by `orderUuid` (one payment record per order).
- [Update payment data.](https://developers.novatrade24.com/api-reference/payment/update-payment-data.md)
- [Upload proof-of-payment document.](https://developers.novatrade24.com/api-reference/payment/upload-proof-of-payment-document.md): Allowed types: `PAYMENT_BANK_TRANSFER_SCREENSHOT`, `PAYMENT_CONFIRMATION`, `PAYMENT_SOURCE_OF_FUNDS_DECLARATION`.
- [Create a shareable prospect submission link.](https://developers.novatrade24.com/api-reference/prospects/create-a-shareable-prospect-submission-link.md)
- [Get a prospect.](https://developers.novatrade24.com/api-reference/prospects/get-a-prospect.md)
- [List prospect invitations.](https://developers.novatrade24.com/api-reference/prospects/list-prospect-invitations.md)
- [List submitted prospects.](https://developers.novatrade24.com/api-reference/prospects/list-submitted-prospects.md)
- [Revoke a prospect invitation.](https://developers.novatrade24.com/api-reference/prospects/revoke-a-prospect-invitation.md)
- [Create a self-service KYC invitation (emailed link).](https://developers.novatrade24.com/api-reference/self-service-invitations/create-a-self-service-kyc-invitation-emailed-link.md)
- [List self-service KYC invitations for a buyer.](https://developers.novatrade24.com/api-reference/self-service-invitations/list-self-service-kyc-invitations-for-a-buyer.md)
- [Revoke a self-service KYC invitation.](https://developers.novatrade24.com/api-reference/self-service-invitations/revoke-a-self-service-kyc-invitation.md)
- [Confirm delivery.](https://developers.novatrade24.com/api-reference/transport/confirm-delivery.md)
- [Confirm pickup.](https://developers.novatrade24.com/api-reference/transport/confirm-pickup.md): Immutable-once-set. Retry with same body returns `409` with current state. Use `/pickup/revoke` to explicitly reverse.
- [Get transport state.](https://developers.novatrade24.com/api-reference/transport/get-transport-state.md)
- [Revoke pickup confirmation.](https://developers.novatrade24.com/api-reference/transport/revoke-pickup-confirmation.md)
- [Upload transport document.](https://developers.novatrade24.com/api-reference/transport/upload-transport-document.md): Allowed types: `TRANSPORT_CMR`, `TRANSPORT_CMR_DELIVERY`, `TRANSPORT_PICTURE_OF_TRANSPORT`, `TRANSPORT_CONFIRMATION_OF_ARRIVAL`, `TRANSPORT_PICKUP_DECLARATION`.
- [Delete a webhook endpoint.](https://developers.novatrade24.com/api-reference/webhooks/delete-a-webhook-endpoint.md)
- [Fire a synthetic test event to the endpoint.](https://developers.novatrade24.com/api-reference/webhooks/fire-a-synthetic-test-event-to-the-endpoint.md): Sends a signed webhook with the provided payload. Use this to exercise your signature verification and handler logic before live events flow.
- [Get a webhook endpoint.](https://developers.novatrade24.com/api-reference/webhooks/get-a-webhook-endpoint.md)
- [List recent deliveries (30-day retention).](https://developers.novatrade24.com/api-reference/webhooks/list-recent-deliveries-30-day-retention.md)
- [List webhook endpoints.](https://developers.novatrade24.com/api-reference/webhooks/list-webhook-endpoints.md)
- [Manually replay a delivery.](https://developers.novatrade24.com/api-reference/webhooks/manually-replay-a-delivery.md)
- [Register a webhook endpoint.](https://developers.novatrade24.com/api-reference/webhooks/register-a-webhook-endpoint.md)
- [Update a webhook endpoint.](https://developers.novatrade24.com/api-reference/webhooks/update-a-webhook-endpoint.md)
- [Authentication](https://developers.novatrade24.com/authentication.md): OAuth2 client_credentials via Keycloak service accounts. No per-user login, no passwords in your backend.
- [Compliance rollup](https://developers.novatrade24.com/concepts/compliance-rollup.md): One endpoint, one source of truth for end-to-end compliance state of an order.
- [Idempotency](https://developers.novatrade24.com/concepts/idempotency.md): Safe retries via the Idempotency-Key header and natural-key upsert for Buyer, Order, Invoice, and Payment.
- [Optimistic concurrency](https://developers.novatrade24.com/concepts/optimistic-concurrency.md): ETag / If-Match prevents lost updates when the API and the NT24 web app edit the same resource concurrently.
- [Rate limits](https://developers.novatrade24.com/concepts/rate-limits.md): Per-organization tiers, per-category budgets, standard headers, and how idempotency replay interacts.
- [Webhooks overview](https://developers.novatrade24.com/concepts/webhooks-overview.md): Event-driven updates — the 10 events, delivery guarantees, and when to pair webhooks with polling.
- [End-to-end workflow](https://developers.novatrade24.com/concepts/workflow.md): How the six modules chain together into one EU VAT-compliant cross-border transaction.
- [Buyer onboarding](https://developers.novatrade24.com/guides/buyer-onboarding.md): Create or sync a buyer by VAT number, upload KYC documents, run VIES, and optionally trigger NT24-led verification.
- [Finalization & Export File](https://developers.novatrade24.com/guides/finalization.md): Final invoice based on compliance decision, auto-generated Export File PDF, regeneration, and immutable versioning.
- [Invoice & Payment](https://developers.novatrade24.com/guides/invoice-payment.md): Submit the buyer's VAT-compliance invoice, upload the PDF, and record the proof-of-payment.
- [KYC modes (A vs B)](https://developers.novatrade24.com/guides/kyc-modes.md): Marketplace-led vs NT24-led verification — who runs KYC, what artifacts are produced, and when to pick which.
- [Order creation](https://developers.novatrade24.com/guides/order-creation.md): Register a VIN-based transaction linked to an existing buyer.
- [Transport](https://developers.novatrade24.com/guides/transport.md): Confirm pickup and delivery, upload CMR documents, reverse mistakes with explicit revoke.
- [Introduction](https://developers.novatrade24.com/introduction.md): Embed EU VAT-compliant cross-border vehicle transactions into your platform via the Novatrade24 Integration API.
- [Quickstart](https://developers.novatrade24.com/quickstart.md): Authenticate, discover your organization, and call your first endpoint in about 5 minutes.
- [Changelog](https://developers.novatrade24.com/reference/changelog.md): Integration API changes by date. Additions, deprecations, sunsets.
- [Error reference](https://developers.novatrade24.com/reference/errors.md): RFC 7807 problem detail format, status-code catalog, and troubleshooting recipes.
- [FAQ](https://developers.novatrade24.com/reference/faq.md): Answers to the questions we've heard most during integration planning conversations.
- [Versioning](https://developers.novatrade24.com/reference/versioning.md): URL-path versioning, breaking-change policy, and deprecation timelines.
- [Data Processing Agreement (DPA)](https://developers.novatrade24.com/security/dpa.md): Controller/processor relationship, obligations, sub-processors, and how DPA state is enforced technically.
- [GDPR](https://developers.novatrade24.com/security/gdpr.md): Data categories, lawful basis, subject rights, retention, and how the Integration API implements each.
- [Security & Compliance Overview](https://developers.novatrade24.com/security/overview.md): GDPR posture, DPA requirement, encryption, EU-only data residency, and audit trail.
- [Event catalog](https://developers.novatrade24.com/webhooks/event-catalog.md): All 10 Phase 1 webhook events with payload schemas.
- [Replay & test](https://developers.novatrade24.com/webhooks/replay-and-test.md): Inspect delivery history, manually replay events, and fire synthetic test events for handler development.
- [Webhook setup](https://developers.novatrade24.com/webhooks/setup.md): Register an endpoint, subscribe to events, and start receiving signed POSTs on compliance transitions.
- [Signature verification](https://developers.novatrade24.com/webhooks/signature-verification.md): Verify the X-Novatrade-Signature header before trusting webhook payloads.

## OpenAPI Specs

- [openapi-integration-v1](https://developers.novatrade24.com/openapi-integration-v1.yaml)
- [openapi](https://developers.novatrade24.com/api-reference/openapi.json)