> ## 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. # Update a buyer (including KYC mode upgrade A→B). > 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. ## OpenAPI ````yaml /openapi-integration-v1.yaml patch /partners/{sellerId}/buyers/{buyerId} openapi: 3.1.0 info: title: Novatrade24 Integration API version: 1.0.0-draft summary: Customer-facing integration API for the Novatrade24 compliance platform. description: > The Novatrade24 Integration API lets marketplaces, dealers, and financial partners embed EU VAT-compliant cross-border vehicle transactions into their own systems. The API is organized around the end-to-end compliance workflow: 1. **Buyer (KYC)** — create or sync a buyer, run VIES, upload KYC documents, optionally trigger NT24-led verification. 2. **Order** — register a VIN-based transaction linked to a buyer. 3. **Invoice** — submit preliminary and final invoice data and documents. 4. **Payment** — submit proof-of-payment and trigger pickup readiness. 5. **Transport** — confirm pickup and delivery with CMR / declarations. 6. **Compliance rollup** — poll workflow status or subscribe to webhooks. 7. **Finalization** — download the generated Export File. **Status:** Draft — no production endpoint yet. Specification published for integration planning. Hosted mock available at `https://mock.api.novatrade24.com`. termsOfService: https://novatrade24.com/terms contact: name: Novatrade24 Integration Support email: integration-support@novatrade24.com url: https://developers.novatrade24.com license: name: Proprietary url: https://novatrade24.com/terms servers: - url: https://api.novatrade24.com/v1 description: Production (Phase 1 pilot — restricted access) - url: https://api.stage.novatrade24.com/v1 description: Staging environment - url: https://mock.api.novatrade24.com description: Hosted mock server (Prism) — spec-driven stub responses security: - oauth2ClientCredentials: [] tags: - name: Discovery description: Organization + capability discovery. - name: Buyers description: | Manage buyer (trade partner) records and KYC lifecycle. Buyers are upserted by `(sellerId, vatNumber)`. - name: KYC description: KYC documents, VIES checks, Mode B verification, profile. - name: Self-service invitations description: | Orchestrate buyer-facing self-service links for KYC submission and prospect onboarding. - name: Orders description: | Register vehicle transactions. Orders may contain one or more VINs; Phase 1 Santander pilot uses single-VIN orders. - name: Invoice description: Buyer's VAT-compliance invoice (preliminary or final). - name: Payment description: Proof-of-payment data and documents; pickup readiness trigger. - name: Transport description: Pickup + delivery milestones and documents (CMR, declarations). - name: Compliance description: End-to-end compliance rollup per order. - name: Finalization description: Final invoice submission and Export File download. - name: Prospects description: Public prospect submission flow. - name: Documents description: Typed document download. - name: Webhooks description: Webhook endpoint registration, delivery history, test-fire. paths: /partners/{sellerId}/buyers/{buyerId}: parameters: - $ref: '#/components/parameters/SellerIdPath' - $ref: '#/components/parameters/BuyerIdPath' patch: tags: - Buyers summary: Update a buyer (including KYC mode upgrade A→B). description: | 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. operationId: updateBuyer parameters: - $ref: '#/components/parameters/IdempotencyKeyHeader' - $ref: '#/components/parameters/IfMatchHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BuyerUpdateRequest' responses: '200': description: Updated headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/BuyerResponse' '409': description: If-Match version mismatch — entity modified elsewhere. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' 4XX: $ref: '#/components/responses/Problem' 5XX: $ref: '#/components/responses/Problem' components: parameters: SellerIdPath: name: sellerId in: path required: true description: UUID of the seller trade partner (must be in caller's authorized list). schema: type: string format: uuid BuyerIdPath: name: buyerId in: path required: true description: UUID of the buyer trade partner. schema: type: string format: uuid IdempotencyKeyHeader: name: Idempotency-Key in: header required: true description: | Client-generated unique key (UUID recommended) for this write operation. Identical key + identical body within 24h returns the cached response. Identical key + different body returns `422`. schema: type: string minLength: 1 maxLength: 255 IfMatchHeader: name: If-Match in: header description: | ETag value from a previous response, used for optimistic concurrency. Mismatch returns `409` with the current resource. schema: type: string schemas: BuyerUpdateRequest: type: object description: > All fields optional. `kycMode` may be upgraded `MARKETPLACE_LED` → `NT24_LED` only. properties: kycMode: $ref: '#/components/schemas/KycMode' companyName: type: string address: $ref: '#/components/schemas/AddressRequest' BuyerResponse: type: object required: - uuid - vatNumber - companyName - address - kycMode - status - version - createdAt - updatedAt properties: uuid: type: string format: uuid vatNumber: type: string companyName: type: string address: $ref: '#/components/schemas/Address' kycMode: $ref: '#/components/schemas/KycMode' status: $ref: '#/components/schemas/BuyerStatus' version: type: integer description: Optimistic-concurrency version. createdAt: type: string format: date-time updatedAt: type: string format: date-time Problem: type: object required: - type - title - status properties: type: type: string format: uri title: type: string status: type: integer detail: type: string instance: type: string traceId: type: string KycMode: type: string enum: - MARKETPLACE_LED - NT24_LED description: > `MARKETPLACE_LED` (Mode A) — partner provides KYC data; NT24 stores + runs VIES only. `NT24_LED` (Mode B) — NT24 runs full verification (iDenfy + AML) and generates a profile. AddressRequest: type: object required: - street - postCode - city - country properties: street: type: string postCode: type: string city: type: string country: type: string example: DE Address: type: object properties: uuid: type: string format: uuid readOnly: true street: type: string postCode: type: string city: type: string country: type: string description: ISO 3166-1 alpha-2 country code. example: DE BuyerStatus: type: string enum: - ACTIVE - BLOCKED headers: ETag: description: Entity tag derived from the resource's optimistic-concurrency version. schema: type: string responses: Problem: description: | RFC 7807 problem detail. Default fallback for any status not explicitly enumerated on the operation. Concrete status is in `status` field. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: oauth2ClientCredentials: type: oauth2 description: | OAuth 2.0 client_credentials grant via Keycloak service account. Clients are provisioned per `IntegrationOrganization` in the `nt24-idp` realm. flows: clientCredentials: tokenUrl: >- https://auth.novatrade24.com/realms/nt24-idp/protocol/openid-connect/token scopes: {} ````