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

# FAQ

> Answers to the questions we've heard most during integration planning conversations.

## General

<AccordionGroup>
  <Accordion title="When will the API be available in production?">
    The Integration API is currently in draft specification stage. Production
    availability is coordinated per pilot customer. Reach out via
    [our contact page](https://www.novatrade24.com/contact) for your timeline.
  </Accordion>

  <Accordion title="Is there a sandbox I can hit today?">
    A hosted Prism mock at `https://mock.api.novatrade24.com` serves stub
    responses from the spec so you can exercise request/response shape.
    Full functional staging (`https://api.stage.novatrade24.com`) opens to
    pilot customers during onboarding.
  </Accordion>

  <Accordion title="Can I use the API in production before my DPA is signed?">
    No. API calls are rejected with `403 dpa-not-accepted` until the DPA is
    signed and registered on your organization. This is a hard gate.
  </Accordion>

  <Accordion title="Do you have an SDK?">
    Not in Phase 1. Generate your own from the OpenAPI spec with
    `openapi-generator-cli` in your target language. First-party SDKs
    (TypeScript, Python, Java) are on the Phase 3 roadmap.
  </Accordion>
</AccordionGroup>

## Auth and credentials

<AccordionGroup>
  <Accordion title="Can one organization have multiple API clients?">
    Yes. Common setup is one client per consuming system (e.g. your DMS
    plus your accounting tool). Each client has its own credentials but
    shares the same `IntegrationOrganization` scope, rate-limit budget, and
    capability flags.
  </Accordion>

  <Accordion title="How do I rotate my client secret?">
    Contact support to regenerate. Both old and new secrets are valid during
    a rotation window (typically 24-72h) so you can migrate without
    downtime.
  </Accordion>

  <Accordion title="Does one Keycloak client limit me to one partner?">
    No. An `IntegrationOrganization` can have multiple authorized partners;
    every partner-scoped URL takes the partner UUID in the path. One API
    client can act on behalf of all authorized partners within its org.
  </Accordion>
</AccordionGroup>

## Buyers and KYC

<AccordionGroup>
  <Accordion title="What if I don't know if a buyer exists yet?">
    Just POST — the API upserts by `(sellerId, vatNumber)`. First call
    creates; subsequent identical calls return the existing record with
    `200`.
  </Accordion>

  <Accordion title="Can I switch a buyer between Mode A and Mode B?">
    Upgrades A → B are allowed via `PATCH`. Downgrades B → A are not —
    iDenfy and AML artifacts are legal records that can't be retroactively
    de-scoped.
  </Accordion>

  <Accordion title="The buyer doesn't have the documents yet. What do I do?">
    Generate a self-service invitation
    (`POST /buyers/{id}/kyc/self-service-invitations`). The buyer receives
    an email with a branded upload link. Their submissions flow in the same
    way as API-uploaded documents — no branching in your code.
  </Accordion>

  <Accordion title="VIES is down. Does the whole API go down?">
    No. VIES checks are async workflows; pending/unknown results don't
    block other operations. The compliance rollup reports
    `viesResult: PENDING` / `UNKNOWN` until VIES recovers.
  </Accordion>
</AccordionGroup>

## Orders

<AccordionGroup>
  <Accordion title="Can I have multiple orders with the same VIN?">
    Yes. VIN is not unique platform-wide — a vehicle may reappear in
    multiple orders over time (resale, buyback).
    `GET /orders?vin={vin}` returns all matches scoped to your authorized
    partners.
  </Accordion>

  <Accordion title="Why is my order creation returning 403?">
    Most likely: the `{sellerId}` in the URL path is not in your org's
    authorized partners list, or a required capability is not granted. Run
    `GET /v1/me` and check.
  </Accordion>

  <Accordion title="Can I cancel an order after compliance has decided?">
    Cancellation before the `VALID` / `INVALID` verdict works via
    `POST /orders/{uuid}/cancel`. Post-verdict cancellations are restricted
    — contact support; the Export File has likely already been produced as
    a legal artifact.
  </Accordion>
</AccordionGroup>

## Transport

<AccordionGroup>
  <Accordion title="I confirmed pickup with the wrong date. Now what?">
    Use `POST /transport/pickup/revoke` with a reason. Then re-confirm with
    the correct data. Revocation is audited.
  </Accordion>

  <Accordion title="Do you support partial deliveries across multiple VINs?">
    Multi-VIN orders track per-VIN transport state. Some VINs may be
    delivered while others are in transit; overall transport status is
    `PARTIAL`. Multi-VIN requires the `allowMultiVinOrders` capability.
  </Accordion>

  <Accordion title="What if the CMR gets lost?">
    Upload a replacement document (same type). Documents are append-only;
    supersede the bad upload with `PATCH` setting `status: ARCHIVED` on the
    old record. Latest `ACTIVE` document counts.
  </Accordion>
</AccordionGroup>

## Webhooks

<AccordionGroup>
  <Accordion title="Can I subscribe to all events?">
    Root wildcard (`*`) is not supported — explicit opt-in at least at the
    segment level (`compliance.*`, `kyc.*`). This prevents accidental
    firehose subscriptions.
  </Accordion>

  <Accordion title="My endpoint was down for a day. Did I lose events?">
    Probably not. NT24 retries for up to 72 hours (10 attempts with
    exponential backoff). If your endpoint comes back in time, events are
    delivered. For longer outages, the delivery history endpoint lets you
    replay events within 30 days.
  </Accordion>

  <Accordion title="Do you deliver events in order?">
    At the per-endpoint level, best-effort — but retries can reorder
    deliveries. Design handlers to be order-independent and keyed on the
    resource state (compliance rollup version, etc.), not on event order.
  </Accordion>

  <Accordion title="What happens if my endpoint returns 4xx?">
    Non-`2xx` responses are treated as failures. `4xx` responses still
    count against the retry budget — the retries continue on schedule.
    If you want to signal "don't retry, I reject this", return `200 OK` and
    swallow the event silently on your side.
  </Accordion>
</AccordionGroup>

## Errors and retries

<AccordionGroup>
  <Accordion title="I got a 409 on a retry with the same idempotency key.">
    The body changed between retries. Safe retry requires identical key AND
    identical body. Fresh data = fresh key.
  </Accordion>

  <Accordion title="I got a 429. How aggressively should I back off?">
    Honor `Retry-After` plus a small jitter. Don't busy-loop retries —
    10 consecutive `429`s from the same API client auto-pauses the client
    for 15 minutes.
  </Accordion>

  <Accordion title="Can I cache `/me` responses?">
    Yes. The server returns `Cache-Control` hints; we recommend an in-process
    5-minute TTL on the org's partner list and capabilities. Capability
    changes are rare.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Error reference" icon="triangle-exclamation" href="/reference/errors">
    Full problem-type catalog.
  </Card>

  <Card title="Contact" icon="envelope" href="https://www.novatrade24.com/contact">
    Ask anything not covered here.
  </Card>
</CardGroup>