> ## Documentation Index
> Fetch the complete documentation index at: https://help.polygon-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bestellungen erstellen

> Create a single order (synchronous), or bulk-import orders (asynchronous). Batch imports use a flat structure — each row is one order line, grouped by `orderNumber`; supplier/article are resolved by name/number; orders upsert idempotently on `orderNumber`. After import, the system automatically attempts to assign each order to a matching DDS statement if auto-assignment is enabled. **A batch that names an order must carry ALL of that order's lines** — a batch that would delete stored lines fails with `lineReplacementRequired` unless the envelope sets `"replaceLines": true`. **Batch form (array, or `{"rows": […]}` envelope, max 5000 rows) is asynchronous:** it stages an import job and returns `202` with a `jobId` — poll `GET /api/import-jobs/{jobId}` for progress and the final result. A single object stays synchronous (`201`). See the Batch Import guide.



## OpenAPI

````yaml POST /api/orders
openapi: 3.1.0
info:
  title: Polygon One EUDR Compliance API
  description: >-
    API for integrating ERP systems with the Polygon One EUDR Compliance
    Platform. Allows management of Articles, Suppliers, Orders, and Due
    Diligence Statements (DDS).
  version: 1.0.0
servers:
  - url: https://app.polygon-one.com
    description: Production Server
security:
  - bearerAuth: []
paths:
  /api/orders:
    post:
      summary: Create Order
      description: >-
        Create a single order (synchronous), or bulk-import orders
        (asynchronous). Batch imports use a flat structure — each row is one
        order line, grouped by `orderNumber`; supplier/article are resolved by
        name/number; orders upsert idempotently on `orderNumber`. After import,
        the system automatically attempts to assign each order to a matching DDS
        statement if auto-assignment is enabled. **A batch that names an order
        must carry ALL of that order's lines** — a batch that would delete
        stored lines fails with `lineReplacementRequired` unless the envelope
        sets `"replaceLines": true`. **Batch form (array, or `{"rows": […]}`
        envelope, max 5000 rows) is asynchronous:** it stages an import job and
        returns `202` with a `jobId` — poll `GET /api/import-jobs/{jobId}` for
        progress and the final result. A single object stays synchronous
        (`201`). See the Batch Import guide.
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CreateOrderInput'
                - type: array
                  items:
                    $ref: '#/components/schemas/BatchOrderInput'
                  maxItems: 5000
                  description: Batch import (bare array form) — asynchronous, returns 202
                - type: object
                  description: >-
                    Batch envelope form (orders only: optional `replaceLines`
                    flag)
                  properties:
                    rows:
                      type: array
                      items:
                        $ref: '#/components/schemas/BatchOrderInput'
                      maxItems: 5000
                    replaceLines:
                      type: boolean
                      default: false
                      description: >-
                        Authorize wholesale replacement of an existing order's
                        line set. Without it, a batch that would delete stored
                        order lines fails all-or-nothing with
                        `lineReplacementRequired`.
                  required:
                    - rows
      responses:
        '201':
          description: Order created successfully (single)
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
        '202':
          $ref: '#/components/responses/BatchAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateOrderInput:
      type: object
      required:
        - supplierId
        - orderNumber
        - orderDate
        - orderType
        - lines
      properties:
        supplierId:
          type: string
          format: uuid
        orderNumber:
          type: string
        orderDate:
          type: string
          format: date-time
          description: ISO 8601 date string
        deliveryDate:
          type: string
          format: date-time
          description: Optional ISO 8601 delivery date. Often unknown at order time.
        orderType:
          $ref: '#/components/schemas/OrderType'
        lines:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CreateOrderLineInput'
    BatchOrderInput:
      type: object
      description: >-
        Flat structure for bulk order import. Supplier and article are resolved
        by name/number. Multiple rows with the same orderNumber are merged into
        one order with multiple lines. Each row must provide at least one of
        `quantity` or `pieceCount`.
      required:
        - orderNumber
        - orderDate
        - supplierName
        - articleNumber
      properties:
        orderNumber:
          type: string
        orderDate:
          type: string
          format: date-time
        deliveryDate:
          type: string
          format: date-time
          description: Optional ISO 8601 delivery date.
        orderType:
          $ref: '#/components/schemas/OrderType'
        supplierName:
          type: string
          description: Resolved to a supplier ID by matching name
        supplierEmail:
          type: string
          format: email
          description: Used when creating a new supplier during resolution
        supplierCountry:
          type: string
          description: Used when creating a new supplier during resolution
        supplierAddress:
          type: string
          description: Used when creating a new supplier during resolution
        supplierExternalId:
          type: string
          description: External supplier ID from your ERP system
        articleNumber:
          type: string
          description: Resolved to an article ID by matching internal article number
        articleDescription:
          type: string
        quantity:
          type: number
          description: Net mass in kilograms. Required unless `pieceCount` is provided.
        pieceCount:
          type: integer
          description: >-
            Number of pieces. Used to derive net mass when `quantity` is
            omitted.
        volumeM3:
          type: number
          description: Volume in m³ — feeds the EUDR DDS supplementary unit (MTQ).
        dryWeight90Kg:
          type: number
          description: >-
            Kilograms of 90 %-dry substance — feeds the EUDR DDS supplementary
            unit (KSD).
        hsCode:
          type: string
        ddsReferenceNumber:
          type: string
          description: >-
            Existing TRACES reference number to link this order to a DDS
            statement
        ddsVerificationNumber:
          type: string
          description: >-
            Existing TRACES verification number to link this order to a DDS
            statement
    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        orderNumber:
          type: string
        orderDate:
          type: string
          format: date-time
        orderType:
          $ref: '#/components/schemas/OrderType'
        supplier:
          $ref: '#/components/schemas/Supplier'
        totalVolume:
          type: number
          description: Sum of all order line quantities
        lines:
          type: array
          items:
            $ref: '#/components/schemas/OrderLine'
        ddsReferences:
          type: array
          description: DDS statements linked to this order
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              referenceNumber:
                type: string
              verificationNumber:
                type: string
    OrderType:
      type: string
      enum:
        - purchase
        - sale
      description: >-
        `purchase` = inbound order from a supplier, `sale` = outbound order to a
        customer
    CreateOrderLineInput:
      type: object
      required:
        - articleId
      description: >-
        Each line must provide `articleId` and at least one of `quantity` or
        `pieceCount`. When only `pieceCount` is given, net mass (kg) is derived
        as `pieceCount × weightPerPieceKg` from the article master data.
      properties:
        articleId:
          type: string
          format: uuid
        quantity:
          type: number
          minimum: 0
          description: Net mass in kilograms. Required unless `pieceCount` is provided.
        pieceCount:
          type: integer
          minimum: 1
          description: >-
            Number of pieces. Used to derive net mass when `quantity` is
            omitted.
        volumeM3:
          type: number
          minimum: 0
          description: >-
            Volume in m³. Feeds the EUDR DDS supplementary unit (MTQ). Optional
            and independent of net mass.
        dryWeight90Kg:
          type: number
          minimum: 0
          description: >-
            Kilograms of 90 %-dry substance. Feeds the EUDR DDS supplementary
            unit (KSD) for wood-pulp HS codes.
    Supplier:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type:
            - string
            - 'null'
        contactName:
          type:
            - string
            - 'null'
        country:
          type: string
        externalSupplierId:
          type:
            - string
            - 'null'
          description: External ID from your ERP system
        address:
          $ref: '#/components/schemas/Address'
        status:
          $ref: '#/components/schemas/SupplierStatus'
        isCompanySelf:
          type: boolean
          description: >-
            True if this supplier represents your own company (for sale
            articles)
        articles:
          type: array
          items:
            $ref: '#/components/schemas/Article'
    OrderLine:
      type: object
      properties:
        id:
          type: string
          format: uuid
        article:
          $ref: '#/components/schemas/Article'
        quantity:
          type: number
          description: >-
            Net mass in kilograms. Derived from `pieceCount × weightPerPieceKg`
            when the line was created with `pieceCount` instead of `quantity`.
        pieceCount:
          type:
            - number
            - 'null'
          description: >-
            Number of pieces, when the line was quantified by piece count rather
            than net mass.
        volumeM3:
          type:
            - number
            - 'null'
          description: >-
            Volume in m³. Feeds the EUDR DDS supplementary unit (MTQ) for HS
            codes that require it.
        dryWeight90Kg:
          type:
            - number
            - 'null'
          description: >-
            Kilograms of 90 %-dry substance. Feeds the EUDR DDS supplementary
            unit (KSD) for wood-pulp HS codes.
    ImportJobAccepted:
      type: object
      description: >-
        Batch import staged as an async job. Nothing is imported yet — poll
        `statusUrl` for progress and the final result.
      properties:
        jobId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - queued
        statusUrl:
          type: string
          example: /api/import-jobs/6f7a…
      required:
        - jobId
        - status
        - statusUrl
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        details:
          description: Additional error details (e.g. validation issues)
      required:
        - error
    Address:
      type: object
      required:
        - street
        - postalCode
        - city
      properties:
        street:
          type: string
        postalCode:
          type: string
        city:
          type: string
        additional:
          type: string
        validated:
          type: boolean
        latitude:
          type: number
        longitude:
          type: number
    SupplierStatus:
      type: string
      enum:
        - data_incomplete
        - data_complete
        - dds_submitted
      description: Supplier data completeness status
    Article:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        internalArticleNr:
          type: string
          description: Internal article number (ERP ID)
        externalArticleNr:
          type:
            - string
            - 'null'
        hsCode:
          type: string
          description: Harmonized System code
        ean:
          type:
            - string
            - 'null'
        shortDescription:
          type:
            - string
            - 'null'
        eudrRelevant:
          type: boolean
          description: Automatically determined from HS code
        articleType:
          $ref: '#/components/schemas/ArticleType'
        commodityGroup:
          $ref: '#/components/schemas/CommodityGroup'
        suppliers:
          type: array
          items:
            $ref: '#/components/schemas/Supplier'
        complianceResults:
          type: array
          items:
            $ref: '#/components/schemas/ComplianceResult'
        countryOfProduction:
          type:
            - string
            - 'null'
    ArticleType:
      type: string
      enum:
        - purchase
        - sale
      description: >-
        `purchase` = inbound article from a supplier, `sale` = outbound article
        you sell
    CommodityGroup:
      type: string
      enum:
        - cattle
        - cocoa
        - coffee
        - oil_palm
        - rubber
        - soya
        - wood
        - non_relevant
      description: >-
        EUDR-regulated commodity groups. `non_relevant` = article is not covered
        by EUDR.
    ComplianceResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
        supplierArticleId:
          type: string
          format: uuid
        overallStatus:
          $ref: '#/components/schemas/ComplianceStatus'
        geoStatus:
          $ref: '#/components/schemas/ComplianceStatus'
        legalStatus:
          $ref: '#/components/schemas/ComplianceStatus'
        generatedReportUrl:
          type:
            - string
            - 'null'
        generatedAt:
          type:
            - string
            - 'null'
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ComplianceStatus:
      type: string
      enum:
        - compliant
        - non_compliant
        - invalid
        - unknown
        - not_eudr_relevant
        - pending_review
        - not_required_before_cutoff
      description: >-
        `invalid` = geolocation present but rejected as invalid (data-quality
        failure, blocks a compliant verdict until corrected);
        `not_required_before_cutoff` = article placed before the EUDR
        application date and not yet in scope.
  responses:
    BatchAccepted:
      description: >-
        Batch accepted — async import job staged. Nothing imported yet; poll the
        job.
      headers:
        Location:
          description: URL of the import job to poll
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ImportJobAccepted'
    BadRequest:
      description: Invalid request data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions for this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: >-
        Batch exceeds the row cap. Nothing staged — page the sync across
        multiple requests (orders: keep all lines of one order in the same
        request, see the Batch Import guide).
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                enum:
                  - batchTooLarge
              maxBatchSize:
                type: integer
                example: 5000
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key generated in Settings > API Keys. Include as `Authorization:
        Bearer <key>`.

````