Prewave EUDR - Shared API

openapi: 3.2.0
info:
  title: Public Prewave EUDR - Shared API
  description: Documentation of the Public Prewave API.
  version: '1.0'
servers:
- url: https://api.prewave.com
  description: Production Environment
security:
- Token authentication: []
tags:
- name: EUDR - Shared
  description: Shared reference data for EUDR, including countries, HS codes, and commodities. Available to both customers and suppliers.
paths:
  /public/v2/eudr/shared/hscodes:
    get:
      tags:
      - EUDR - Shared
      summary: Get a list of EUDR related HS Codes
      description: 'Retrieve a list of Harmonized System (HS) codes relevant for EUDR compliance.


        This endpoint returns reference data containing all HS codes that are applicable for EUDR products.

        HS codes are used to classify products for customs and compliance purposes. Each entry includes

        the code, description, and linked commodity ID when available.


        **Use Cases**:

        - Get HS code reference data for products

        - Populate HS code selection dropdowns

        - Validate product classifications


        **Required permissions (one of):** `access_public_products` or `access_public_eudr_suppliers`'
      operationId: findHSCodes
      responses:
        '200':
          description: List of EUDR-related HS codes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicProductHSCode'
              examples:
                EUDR HS codes:
                  summary: HS codes with descriptions and commodity IDs
                  description: EUDR HS codes
                  value: '[{"code":"440799","description":"Wood sawn or chipped lengthwise, sliced or peeled, of oak","commodityId":1},{"code":"441510","description":"Plywood, veneered panels and similar laminated wood","commodityId":1},{"code":"180100","description":"Cocoa beans, whole or broken, raw or roasted","commodityId":2},{"code":"151110","description":"Crude palm oil","commodityId":3}]'
        '403':
          description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedErrorDTO'
              examples:
                Access denied example:
                  summary: User lacks necessary permissions or authentication
                  value: "{\n        \"loggedIn\": true,\n        \"code\": \"access_denied\",\n        \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n        \"solution\": \"Contact support for appropriate permissions\"\n    }"
        '500':
          description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              examples:
                Error - Server Error:
                  summary: Unexpected server error
                  value: "{\n        \"code\": \"internal_error\",\n        \"message\": \"An unexpected error occurred\",\n        \"solution\": \"Please try again later or contact support\"\n    }"
        '429':
          description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRateLimitResponse'
              examples:
                Rate limit exceeded example:
                  summary: API rate limit exceeded
                  value: "{\n        \"error\": \"API rate limit exceeded\",\n        \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n        \"requestLimit\": 100,\n        \"requestCount\": 100,\n        \"limits\": [\n            {\n                \"requestLimit\": 100,\n                \"timeInSeconds\": 10\n            },\n            {\n                \"requestLimit\": 500,\n                \"timeInSeconds\": 60\n            }\n        ],\n        \"currentTime\": \"2026-01-15T10:30:00\",\n        \"nextResetAt\": \"2026-01-15T10:30:10\"\n    }"
  /public/v2/eudr/shared/countries:
    get:
      tags:
      - EUDR - Shared
      summary: Get a list of countries
      description: 'Retrieve a list of all available countries for EUDR compliance.


        This endpoint returns reference data containing all countries that can be used in EUDR workflows,

        such as product origins, supplier locations, and compliance reporting.


        **Use Cases**:

        - Get country reference data for product origins

        - Populate country selection dropdowns

        - Validate country codes


        **Required permissions (one of):** `access_public_products` or `access_public_eudr_suppliers`'
      operationId: findCountries
      responses:
        '200':
          description: List of countries available for EUDR workflows.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicCountry'
              examples:
                Countries:
                  summary: Countries with ISO 3166-1 alpha-2 codes
                  description: Countries
                  value: '[{"id":14,"name":"Austria","countryCode":"AT","bounds":null},{"id":276,"name":"Germany","countryCode":"DE","bounds":null},{"id":826,"name":"United Kingdom","countryCode":"GB","bounds":null},{"id":756,"name":"Switzerland","countryCode":"CH","bounds":null}]'
        '403':
          description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedErrorDTO'
              examples:
                Access denied example:
                  summary: User lacks necessary permissions or authentication
                  value: "{\n        \"loggedIn\": true,\n        \"code\": \"access_denied\",\n        \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n        \"solution\": \"Contact support for appropriate permissions\"\n    }"
        '500':
          description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              examples:
                Error - Server Error:
                  summary: Unexpected server error
                  value: "{\n        \"code\": \"internal_error\",\n        \"message\": \"An unexpected error occurred\",\n        \"solution\": \"Please try again later or contact support\"\n    }"
        '429':
          description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRateLimitResponse'
              examples:
                Rate limit exceeded example:
                  summary: API rate limit exceeded
                  value: "{\n        \"error\": \"API rate limit exceeded\",\n        \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n        \"requestLimit\": 100,\n        \"requestCount\": 100,\n        \"limits\": [\n            {\n                \"requestLimit\": 100,\n                \"timeInSeconds\": 10\n            },\n            {\n                \"requestLimit\": 500,\n                \"timeInSeconds\": 60\n            }\n        ],\n        \"currentTime\": \"2026-01-15T10:30:00\",\n        \"nextResetAt\": \"2026-01-15T10:30:10\"\n    }"
  /public/v2/eudr/shared/commodities:
    get:
      tags:
      - EUDR - Shared
      summary: Get a list of EUDR related commodities
      description: 'Retrieve a list of commodities relevant for EUDR compliance.


        This endpoint returns reference data containing all commodities that are applicable for EUDR products.

        Only commodities whose names start with "EUDR " are included. Commodities are used to categorize

        products for compliance and reporting purposes.


        **Use Cases**:

        - Get commodity reference data for products

        - Populate commodity selection dropdowns

        - Validate product categorizations


        **Required permissions (one of):** `access_public_products` or `access_public_eudr_suppliers`'
      operationId: findCommodities
      responses:
        '200':
          description: List of EUDR-related commodities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicCommodity'
              examples:
                EUDR commodities:
                  summary: Commodities applicable to EUDR products
                  description: EUDR commodities
                  value: '[{"id":1,"name":"EUDR Wood"},{"id":2,"name":"EUDR Cocoa"},{"id":3,"name":"EUDR Palm Oil"}]'
        '403':
          description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedErrorDTO'
              examples:
                Access denied example:
                  summary: User lacks necessary permissions or authentication
                  value: "{\n        \"loggedIn\": true,\n        \"code\": \"access_denied\",\n        \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n        \"solution\": \"Contact support for appropriate permissions\"\n    }"
        '500':
          description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              examples:
                Error - Server Error:
                  summary: Unexpected server error
                  value: "{\n        \"code\": \"internal_error\",\n        \"message\": \"An unexpected error occurred\",\n        \"solution\": \"Please try again later or contact support\"\n    }"
        '429':
          description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRateLimitResponse'
              examples:
                Rate limit exceeded example:
                  summary: API rate limit exceeded
                  value: "{\n        \"error\": \"API rate limit exceeded\",\n        \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n        \"requestLimit\": 100,\n        \"requestCount\": 100,\n        \"limits\": [\n            {\n                \"requestLimit\": 100,\n                \"timeInSeconds\": 10\n            },\n            {\n                \"requestLimit\": 500,\n                \"timeInSeconds\": 60\n            }\n        ],\n        \"currentTime\": \"2026-01-15T10:30:00\",\n        \"nextResetAt\": \"2026-01-15T10:30:10\"\n    }"
components:
  schemas:
    ApiRateLimitResponse:
      type: object
      properties:
        error:
          type: string
          description: Error type identifier
          example: RateLimitExceeded
        message:
          type: string
          description: Human-readable error message explaining the rate limit violation
          example: API rate limit exceeded. Please reduce your request rate.
        requestLimit:
          type: integer
          description: Maximum number of requests allowed in the current time window
          format: int32
          example: 100
        requestCount:
          type: integer
          description: Number of requests made in the current time window
          format: int32
          example: 101
        limits:
          type: array
          description: All rate limits that apply to this endpoint, showing different time windows
          items:
            $ref: '#/components/schemas/ApiRateLimitTimeRequestLimit'
          example: null
        currentTime:
          type: string
          description: Current server time in ISO 8601 format
          format: date-time
          example: '2026-01-19T10:30:00'
        nextResetAt:
          type: string
          description: Time when the rate limit will reset in ISO 8601 format
          format: date-time
          example: '2026-01-19T10:30:10'
      description: Response returned when API rate limit is exceeded (HTTP 429)
      example: null
    PublicCountry:
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: integer
          description: Country ID
          format: int32
          example: 14
        name:
          type: string
          description: Country name
          example: Austria
        countryCode:
          maxLength: 2
          minLength: 2
          type:
          - string
          - 'null'
          description: Country code in form of ISO 3166-1 alpha-2 code
          example: AT
        bounds:
          allOf:
          - $ref: '#/components/schemas/PublicGeometrySchema'
          example: null
      description: Country where the economic activity is taking place
      example: null
    ApiRateLimitTimeRequestLimit:
      type: object
      properties:
        requestLimit:
          type: integer
          description: Maximum number of requests allowed in this time window
          format: int32
          example: 100
        timeInSeconds:
          type: integer
          description: Time window duration in seconds
          format: int32
          example: 10
      description: Rate limit configuration for a specific time window
      example: null
    AccessDeniedErrorDTO:
      required:
      - code
      - loggedIn
      - message
      type: object
      properties:
        loggedIn:
          type: boolean
          example: null
        permission:
          type:
          - string
          - 'null'
          example: null
        code:
          type: string
          description: Error code
          example: null
        message:
          type: string
          description: Error message
          example: null
        solution:
          type:
          - string
          - 'null'
          description: Possible solution to the error
          example: null
      example: null
    PublicGeometrySchema:
      required:
      - coordinates
      - type
      type: object
      properties:
        type:
          type: string
          description: 'Geometry available types: Point, MultiPoint, Polygon, MultiPolygon'
          example: null
        coordinates:
          type: array
          description: Geometry coordinates
          items:
            type: array
            description: Geometry coordinates
            items:
              type: array
              description: Geometry coordinates
              items:
                type: number
                description: Geometry coordinates
                format: double
                example: null
              example: null
            example: null
          example: null
      description: Geometry plot object
      example: null
    PublicProductHSCode:
      required:
      - code
      type: object
      properties:
        code:
          type: string
          description: HS code
          example: '440799'
        description:
          type:
          - string
          - 'null'
          description: HS code description
          example: Wood sawn or chipped lengthwise, sliced or peeled, of oak
        commodityId:
          type:
          - integer
          - 'null'
          description: Commodity ID for the HS code
          format: int32
          example: 1
      description: List of HS codes associated with this DDS unit
      example: null
    ErrorDTO:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: null
        message:
          type: string
          description: Error message
          example: null
        solution:
          type:
          - string
          - 'null'
          description: Possible solution to the error
          example: null
      description: Error response
      example: null
    PublicCommodity:
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: integer
          description: Commodity ID
          format: int32
          example: 1
        name:
          type: string
          description: Commodity name
          example: Timber
      example: null
  securitySchemes:
    Token_authentication:
      type: apiKey
      description: Generate an API token at https://www.prewave.com/management/api and paste it in here.
      name: X-Auth-Token
      in: header