Supplier API – Developer Guide

  • Aktualisiert am Jul 18, 2025
  • Veröffentlicht am Jul 18, 2025
  • 18 Minute(n) Lesezeit
Prev Next

Note

This content is only available in English. Please excuse the inconvenience.

Overview

The osapiens EUDR Supplier API enables automated submission and management of EUDR-relevant data through a REST-based interface. This API is particularly useful for companies with high data volumes or existing IT systems that need to be integrated.

Note:

This guide must be used in conjunction with the other articles within the Supplier Portal Help Center and Supplier API documentation. This article does not replace either of the resources. Always refer to the complete Supplier Portal Help Center and Supplier API documentation for the most detailed and up-to-date information.

API Documentation Access

You can get the link and access for the documentation for the osapiens REST API from your customers if required.

What you will learn

  • How to authenticate with Basic Auth and manage your API credentials for the Supplier Portal.

  • How to create and update land plots for non-EU suppliers.

  • How to list pending EUDR information requests and handle pagination.

  • How to create and manage product batches (including DDS numbers for EU suppliers).

  • How to submit responses to both purchase-order and product-based requests.

  • Best practices for integration and data handling.

EUDR API endpoints used

  • /api_v1_eudrsupplier_plot (POST) – Create or update land plots (GeoJSON) for non-EU suppliers.

  • /api_v1_eudrsupplier_inforequest_list (GET) – Retrieve all pending EUDR information requests (with pagination).

  • /api_v1_eudrsupplier_batch (POST) – Create or update EUDR batches (plots or DDS lists).

  • /api_v1_eudrsupplier_inforequest_response (POST) – Submit responses to EUDR information requests.

Common Workflow

The typical workflow for using the EUDR Supplier API follows these steps:

  1. Create Land Plots (for non-EU suppliers only)

    • Use the Create or Update Plot endpoint to define geographical areas where commodities are sourced.

    • Include GeoJSON coordinates and commodity types.

    • Land plots must be created before they can be referenced in batches.

  2. Monitor Information Requests

    • Use the List endpoint to check for pending EUDR information requests.

    • Identify whether requests are product-based or purchase order-based.

    • Use pagination to handle large volumes of requests.

  3. Create Product Batches

    • Use the Create or Update Product Batch endpoint.

    • For non-EU suppliers: Link batches to previously created plots using plot IDs.

    • For EU suppliers: Include DDS reference numbers and verification codes.

    • Set validity periods and harvest timeframes.

  4. Respond to Requests

    • Use the Respond endpoint.

    • Answer requests by referencing existing batches.

    • For purchase order-based requests: Provide delivery quantities and completion status.

    • Attach additional reference documents if needed.

    • Handle partial deliveries for purchase orders when necessary.

Authentication

Getting API Credentials

To use the EUDR Supplier API, you need two authentication credentials that can be generated in the Supplier Portal:

  • API Token – Used for Basic Authentication.

  • Account ID – Used as a request header (x-osapiens-account-id).

How to Generate API Credentials in the Supplier Portal

Note:

Only Administrator users can create and manage API access credentials.

  1. Navigate to Organisation Profile:

    1. Log into your Supplier Portal.

    2. Click on ORGANISATION PROFILE in the header navigation.

  2. Access API Management:

    1. Within the Organisation Profile section, click on the API ACCESS tab.

  3. Create New API Credentials:

    1. Click on the CREATE button (blue button at the upper right).

    2. A dialog will appear showing the generated credentials.

  4. Save Your Credentials:

    • Name: A descriptive name for your API token (e.g., osapiens Supplier Portal API Access).

    • Token: This is your actual API token used for Basic authentication – a long Base64-encoded string
      (e.g., eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...).

    • Account ID: Your account identifier (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567...).

Important Security Note:

The API token is displayed only once for security reasons. Make sure to copy and save the token securely before closing the dialog. Click on I SAVED THE TOKEN to confirm.

Base URLs and Environments

The API base URL depends on your environment:

Production Environment:

https://prod.osapiens.cloud/data/integration/supplier-os-hub/supplier-os-hub/api_v1_eudrsupplier_{endpoint}

Demo/Preprod Environment:

https://preprod.osapiens.cloud/data/integration/supplier-os-hub/supplier-os-hub/api_v1_eudrsupplier_{endpoint}

Note:

To determine which environment you are using, check the URL of the Supplier Portal that you were invited to. Usually, suppliers are onboarded to the Production environment, as osapiens customers typically onboard suppliers at scale in the production system.

Authentication Method

The Supplier Portal API uses Basic Authentication. Each API request requires two essential headers:

  • Authorization Header: Uses Basic Authentication with your API token.

  • Account ID Header: Identifies your Supplier Account.

Required Authentication Headers

Every API request must include these headers:

Authorization: Basic {your-api-token}
x-osapiens-account-id: {your-account-id}
Content-Type: application/json

Example Authentication Setup (Postman)

// Required Headers
Authorization: Basic eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-osapiens-account-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Content-Type: application/json

Example Postman illustration

EUDR Information Request Types

The osapiens EUDR system supports two main types of information requests that customers can send to suppliers. Understanding these request types is crucial for efficient EUDR compliance management.

Your customers will typically inform you about their intended usage of the osapiens system and which type of requests they plan to use. This helps you prepare the appropriate response strategy and data management approach.

Purchase Order-Based Requests

Purchase order-based requests are transaction-specific and tied to actual customer orders. These are the most common type of request and require detailed delivery information for each specific transaction.

Key Requirements

  • EUDR Batch Information (supplierBatchId): Provide batch data containing either geodata and/or DDS reference numbers.

  • Delivery Confirmation (poItemCompleted): Specify whether this is a full or partial delivery.

  • Accurate Quantities (quantityDelivered): Report exact delivered quantities (critical for the Due Diligence Statements of your customers).

  • Optional Documentation (references): Include reference document IDs (e.g., delivery note numbers) to help identify the shipment.

Note:

User-Specific Visibility: Purchase order requests are only visible to the specific e-mail address that your customer designated when sending the request. If you need the request sent to another Supplier Account (and e-mail address), reach out to your customer.

Product-Based Requests

Product-based requests focus on establishing EUDR compliance data for specific products in your catalog.

Key Characteristics

  • Product-Specific: Target individual products and their associated EUDR data.

  • Forward-Looking (validTillDate): Include validity dates for automated future responses – also for purchase orders!

Key Requirements

  • EUDR Batch Information (supplierBatchId): Provide batch data containing either geodata and/or DDS reference numbers.

Note:

Product-based requests do not require quantity or delivery completion information (quantityDelivered, poItemCompleted) and references are only considered based on the batch used to answer.

Automation Feature

When you respond to a product-based request with a batch that includes a validity date, the osapiens system will automatically use that batch to answer future requests for the same product. This automation applies to:

  • Future product-based requests for the same product.

  • Future purchase order-based requests containing that product.

Example:

If you provide a coffee batch valid until December 31, 2024, all customer requests for that coffee product received before the validity date will be automatically answered with your batch data — no manual or API-based intervention required.

API Endpoints

The EUDR Supplier API provides four main functionalities, typically used in this sequence:

1. Create or Update Land Plots (Non-EU Suppliers Only)

Endpoint: POST /api_v1_eudrsupplier_plot

Create and manage land plot data with GeoJSON coordinates.

Note:

Only non-EU suppliers need to submit land plot data.

Request Body:

[
  {
    "supplierPlotId": "WOOD_PLOT_001",
    "countryCode": "BR",
    "eudrCommodityCode": "wood",
    "geoJson": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [-45.2471, -15.7801],
                [-45.2461, -15.7801],
                [-45.2461, -15.7791],
                [-45.2471, -15.7791],
                [-45.2471, -15.7801]
              ]
            ]
          }
        }
      ]
    },
    "scientificProductNames": ["Acer campestre~Field maple"]
  }
]

Key Fields:

  • supplierPlotId: Unique identifier for the plot of land in your system – this ID will be shared with your customer (the osapiens HUB user).

  • countryCode: ISO 3166-alpha2 country code (auto-detected if not provided).

  • eudrCommodityCode: Definition of commodity type per plot (cattle, cocoa, coffee, palmoil, rubber, soya, wood) – exactly one commodity type must be specified.

  • geoJson: Geographic coordinates (supports Point and Polygon geometries – Multipolygons will be supported in the future; Multilines and Multipoints are not supported).

  • scientificProductNames: Scientific names of wood species (only required for wood products). Can be either a valid 4-letter code based on the EN-13556 standard (e.g., "ACCM") or custom species names in the format <scientificName>~<commonName>

Response Structure:

[
  {
    "statusCode": "success",
    "message": "Plot WOOD_PLOT_001 created.",
    "referenceId": "WOOD_PLOT_001",
    "requestItemIndex": 0,
    "errorCode": null
  }
]

2. List Pending EUDR Information Requests

Endpoint: GET /api_v1_eudrsupplier_inforequest_list

Retrieve all open EUDR information requests with pagination support.

Parameters:

  • Request body can be left empty.

  • page (optional): Page number to retrieve (default: 1, page size: 50) - required for pagination mechanism, if response contains "hasMore": true

Response Structure – Purchase Order Request:

{
  "currentPage": 1,
  "hasMore": false,
  "data": [
    {
      "informationRequestKey": "eyJ0eXBlIjoyLCJjdXN0b21lciI6Im9kZXMtc2FuZGJveC0wODAiLCJvYmplY3QiOiJQTy0wMS0xMTEifQ",
      "requestType": 2,
      "customerId": "Wood Customer Inc.",
      "creationDate": "2023-09-10T22:00:00.000Z",
      "requestStatus": 10,
      "items": [
        {
          "itemKey": "10",
          "customerProductId": "PROD-01-250117",
          "gtin": "00112345678912",
          "descriptions": [
            {
              "languageCode": "de",
              "text": "Holz roh, Rundholz"
            },
            {
              "languageCode": "en",
              "text": "Wood round wood"
            }
          ],
          "referenceType": 1,
          "referenceId": "PO_5536629",
          "referenceItemId": "10"
        }
      ]
    }
  ]
}

Key Response Fields Explanation:

Top-Level Parameters:

  • currentPage (integer): The current page returned by the request.

  • hasMore (boolean): Indicates if there are more pages with data that can be requested (needed for pagination).

  • data (Array): Array of information requests (up to 50 records per page).

Information Request Parameters:

  • informationRequestKey (string): Unique ID of the information request for technical communication.

  • requestType (integer): Nature of the information request.

    • 1 = product based (request for a product without relation to a specific purchase order from your customer).

    • 2 = purchase order based (data request based on a purchase order that has been placed).

  • requestStatus (integer): Status code of the information request.

    • 10 = open – this request requires a response.

    • 20 = in process – this request already was responded by you and the response is being processed.

    • 30 = complete – this request was already responded and closed.

    • 90 = rejected

    • 91 = expired

    • 100 = withdrawn

  • customerId (string): ID of the customer that raised the information request.

  • creationDate (string): Timestamp of document creation in ISO-8601 format.

Item Parameters:

  • itemKey (string): Unique ID of the information request item for technical communication.

  • customerProductId (string): Product ID from the customer's ERP system.

  • gtin (string): Global Trade Item Number of the relevant product (if specified in the customer's ERP system).

  • descriptions (Array): Language-dependent descriptions of the product (as specified in the customer's ERP system).

  • referenceType (integer): Type of the reference document (1 = Purchase order).

  • referenceId (string): ID of the referenced document (typically purchase order number for PO-based requests, max 128 chars).

  • referenceItemId (string): Item number of the referenced document (max 128 chars).

Response Structure – Product Request:

{
  "currentPage": 1,
  "hasMore": false,
  "data": [
    {
      "informationRequestKey": "eyJ0eXBlIjoxLCJjdXN0b21lciI6Im9kZXMtc2FuZGJveC0wODAiLCJvYmplY3QiOiI1MDVjZjcyMS04MDY4LTRhODktOGVjNC0xNWRhNTEwMTFlYmQifQ==",
      "requestType": 1,
      "customerId": "odes-sandbox-080",
      "creationDate": "2025-07-18T09:30:25.741Z",
      "requestStatus": 10,
      "items": [
        {
          "itemKey": "PROD-012",
          "customerProductId": "PROD-012",
          "gtin": "00112345678912",
          "descriptions": [
            {
              "languageCode": "de",
              "text": "Pulp"
            },
            {
              "languageCode": "en",
              "text": "Pulp"
            }
          ]
        }
      ]
    }
  ]
}

Key Response Fields Explanation:

Top-Level Parameters:

  • currentPage (integer): The current page returned by the request.

  • hasMore (boolean): Indicates if there are more pages with data that can be requested (needed for pagination).

  • data (Array): Array of information requests (up to 50 records per page).

Information Request Parameters:

  • informationRequestKey (string): Unique ID of the information request for technical communication.

  • requestType (integer): Nature of the information request.

    • 1 = product based (request for a product without relation to a specific purchase order from your customer).

    • 2 = purchase order based (data request based on a purchase order that has been placed).

  • requestStatus (integer): Status code of the information request.

    • 10 = open - this request requires a response.

    • 20 = in process - this request already was responded by you and the response is being processed.

    • 30 = complete - this request was already responded and closed.

    • 90 = rejected

    • 91 = expired

    • 100 = withdrawn

  • customerId (string): ID of the customer that raised the information request.

  • creationDate (string): Timestamp of document creation in ISO-8601 format.

Item Parameters (Product-Based Requests):

  • itemKey (string): Unique ID of the information request item for technical communication.

  • customerProductId (string): Product ID from the customer's ERP system.

  • gtin (string): Global Trade Item Number of the relevant product (if specified in the customer's ERP system).

  • descriptions (Array): Language-dependent descriptions of the product (as specified in the customer's ERP system).

    • languageCode (string): ISO language code (e.g., "en", "de").

    • text (string): Product description in the specified language.

Note:

For product-based requests (type 1), referenceType, referenceId and referenceItemId are not defined.

Usage Example with pagination mechanism (to receive results from response page 2):

# Initial request (no page parameter needed)
curl -X GET \
  "https://prod.osapiens.cloud/data/integration/supplier-os-hub/supplier-os-hub/api_v1_eudrsupplier_inforequest_list" \
  -H "Authorization: Basic {your-token}" \
  -H "x-osapiens-account-id: {your-account-id}"
# Subsequent requests with pagination
curl -X GET \
  "https://prod.osapiens.cloud/data/integration/supplier-os-hub/supplier-os-hub/api_v1_eudrsupplier_inforequest_list?page=2" \
  -H "Authorization: Basic {your-token}" \
  -H "x-osapiens-account-id: {your-account-id}"

3. Create or Update Product Batches

Endpoint: POST /api_v1_eudrsupplier_batch

Create EUDR batches that can contain either land plots (for non-EU suppliers) or DDS numbers (for EU suppliers).

Note:

Land plots must be created before batch creation, and only the plot IDs must be referenced in the batch.

Request Body for non-EU suppliers (including land plots)

[
  {
    "supplierBatchId": "API_BATCH_222",
    "validTillDate": "2025-12-31T01:00:00.000+01:00",
    "plotAssignment": [
      {
        "supplierPlotId": "WOOD_PLOT_001",
        "harvestTimeframes": [
          {
            "startDate": "2023-06-15T01:00:00.000+01:00",
            "endDate": "2023-06-17T01:00:00.000+01:00"
          }
        ]
      }
    ],
    "references": [
      {
        "documentType": 99,
        "documentId": "JuneWoodHarvest"
      }
    ]
  }
]

Key Fields:

  • supplierBatchId: Unique identifier for the batch.

  • validTillDate: Validity end date in ISO-8601 format – within the validity period the batch will be used to automatically answer future requests for the same product. This automation applies to:

    • Future product-based requests for the same product.

    • Future purchase order-based requests containing that product.

  • plotAssignment: Array of assigned land plots with harvest timeframes (for non-EU suppliers).

  • references: Optional reference documents that will be reported to your customer (e.g., "January Production").

Request Body for EU suppliers (including DDS number pairs)

[
  {
    "supplierBatchId": "API_BATCH_222",
    "validTillDate": "2025-12-31T01:00:00.000+01:00",
        "ddsList": [
      {
        "euDdsId": "25DEHVMJ221758",
        "euDdsVerificationCode": "18IBHNO1"
      }
    ],
    "references": [
      {
        "documentType": 99,
        "documentId": "JuneWoodHarvest"
      }
    ]
  }
]

Key Fields:

  • supplierBatchId: Unique identifier for the batch.

  • validTillDate: Validity end date in ISO-8601 format – within the validity period the batch will be used to automatically answer future requests for the same product. This automation applies to:

    • Future product-based requests for the same product.

    • Future purchase order-based requests containing that product.

  • ddsList: EU DDS numbers and verification codes (for EU suppliers).

  • references: Optional reference documents that will be reported to your customer (e.g., "January Production").

4. Respond to EUDR Information Requests

Endpoint: POST /api_v1_eudrsupplier_inforequest_response

Submit responses to EUDR information requests using previously created batches.

Request Body – Answering purchase order information requests

{
  "informationRequestKey": "eyJ0eXBlIjoyLCJjdXN0b21lciI6Im9kZXMtc2FuZGJveC0wODAiLCJvYmplY3QiOiJQTy1vZGVzLWNvZmZlZS0yMDI1LTAwMSJ9",
  "items": [
    {
      "itemKey": "10",
      "supplierBatchId": "API_BATCH_222",
      "quantityDelivered": 111,
      "poItemCompleted": true
    }
  ]
}

Key Fields:

  • informationRequestKey: The ID of the information request that you are responding to (queried before via the List endpoint).

  • supplierBatchId: Reference to a previously created batch.

  • quantityDelivered: Quantity delivered (mandatory for PO-based requests).

  • poItemCompleted: Indicates if the purchase order item is fully completed (and subsequently closes the request if all items were specified as completed – subsequent GET /api_v1_eudrsupplier_inforequest_list requests will display the information request with "requestStatus" : 30

  • references: Optional reference documents.

Request Body – Answering product information requests

{
  "informationRequestKey": "eyJ0eXBlIjoyLCJjdXN0b21lciI6Im9kZXMtc2FuZGJveC0wODAiLCJvYmplY3QiOiJQTy1vZGVzLWNvZmZlZS0yMDI1LTAwMSJ9",
  "items": [
    {
      "itemKey": "PROD-01-250117",
      "supplierBatchId": "API_BATCH_222"
    }
  ]
}

Key Fields:

  • informationRequestKey: The ID of the information request you're responding to (queried before via the "list" endpoint).

  • supplierBatchId: Reference to a previously created batch.

  • references: Optional reference documents.

End-to-End Implementation Example

Note:

This is a fictional example – actual implementation will vary significantly based on the specific systems, processes, and business requirements of each supplier.

This section demonstrates a complete workflow using all API endpoints for a coffee supplier from Brazil.

Scenario:

  • Company / Supplier: Brazilian Coffee Supplier (non-EU).

  • Customer of Brazilian Coffee Supplier (osapiens customer): European Coffee Importer GmbH (EU).

  • Product: Coffee beans.

  • Customer Request: Purchase order for 1000 kg of coffee.

Step 1: Create Land Plots (Non-EU Suppliers Only)

First, create the land plot where the coffee is grown:

Endpoint:POST /api_v1_eudrsupplier_plot

Request:

[
  {
    "supplierPlotId": "FARM_BRAZIL_001",
    "countryCode": "BR",
    "eudrCommodityCode": "coffee",
    "geoJson": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [-45.123456, -15.789012],
                [-45.123456, -15.790012],
                [-45.124456, -15.790012],
                [-45.124456, -15.789012],
                [-45.123456, -15.789012]
              ]
            ]
          }
        }
      ]
    }
  }
]

Response:

[
  {
    "requestItemIndex": 0,
    "referenceId": "FARM_BRAZIL_001",
    "statusCode": "success",
    "message": "Plot created successfully",
    "errorCode": null
  }
]

Custom Logic Required:

  • Obtain accurate GPS coordinates of your coffee plantation.

  • Ensure coordinates form a valid polygon (first and last points must be identical).

  • For wood products only: Include scientificProductNames array with scientific names of tree species.

Step 2: Monitor Information Requests

Regularly check for incoming requests from customers:

Endpoint: GET /api_v1_eudrsupplier_inforequest_list

Response:

{
  "currentPage": 1,
  "data": [
    {
      "informationRequestKey": "erG0eXBlIjoyLCJjdXN0b21lciI6Im9kZXMtc2FuZGJveC0wODAiLCJvYmplY3QiOiJQTy1vZGVzLWNvZmZlZS0yMDI1LTAwMSJ9",
      "requestType": 2,
      "customerId": "European Coffee Importer GmbH",
      "items": [
        {
          "itemKey": "10",
          "customerProductId": "COFFEE_ARABICA_001",
          "gtin": "00112345678912",
          "descriptions": [
            {
              "languageCode": "de",
              "text": "Arabica Kaffee, 1000kg"
            },
            {
              "languageCode": "en",
              "text": "Arabica Coffee, 1000kg"
            }
          ],
          "referenceType": 1,
          "referenceId": "PO_coffee_2025_001",
          "referenceItemId": "10"
        }
      ],
  "creationDate": "2024-04-15T23:59:59.000Z",
  "requestStatus": 10,
  "hasMore": false
    }
  ]
}

Custom Logic Required:

  • Implement automated polling (e.g., every hour during business hours and keep polling until "hasMore": false to receive all requests).

  • Parse response to identify request types (product-based vs purchase order-based).

  • Alert relevant staff when new requests arrive.

  • Use requests to map responses to Step 4.

Example response analysis:

// Custom logic to process incoming requests
    function processIncomingRequests(response)
   {
      response.data.forEach(request => {
        if (requestType === 'purchase_order') {
          // Handle PO-based request
          console.log(`New PO request: ${request.requestId}`);
          console.log(`Quantity needed: ${request.quantity}`);
          console.log(`Product: ${request.productId}`);
          // Store in your system for processing
        } else if (requestType === 'product') {
          // Handle product-based request
          console.log(`New product request: ${request.requestId}`);
          // Different handling logic
        }
      });
    }

Step 3: Create Product Batch

After receiving a request, create a batch linking the coffee to your land plot (this step only needs to be conducted, if there is no batch with applicable DDS or land plots that could be "reused").

Endpoint: POST /api_v1_eudrsupplier_batch

Request:

[
  {
    "supplierBatchId": "COFFEE_BATCH_2024_Q1",
    "validTillDate": "2025-12-31T23:59:59.000Z",
    "plotAssignment": [
      {
        "supplierPlotId": "FARM_BRAZIL_001",
        "harvestTimeframes": [
          {
            "startDate": "2024-03-15T06:00:00.000Z",
            "endDate": "2024-03-20T18:00:00.000Z"
          }
        ]
      }
    ],
    "references": [
      {
        "documentType": 99,
        "documentId": "HARVEST_2024_001"
      }
    ]
  }
]

Response:

[
  {
    "statusCode": "success",
    "message": "Product batch COFFEE_BATCH_2024_Q1 created.",
    "referenceId": "COFFEE_BATCH_2024_Q1",
    "requestItemIndex": 0,
    "errorCode": null
  }
]

Custom Logic Required:

  • Ensure that the plot ID matches exactly what was created in Step 1.

  • Generate meaningful batch IDs that align with your internal systems.

Step 4: Respond to Customer Request

Submit your response using the created batch:

Endpoint: POST /api_v1_eudrsupplier_inforequest_response

Request:

{
  "informationRequestKey": "erG0eXBlIjoyLCJjdXN0b21lciI6Im9kZXMtc2FuZGJveC0wODAiLCJvYmplY3QiOiJQTy1vZGVzLWNvZmZlZS0yMDI1LTAwMSJ9",
  "items": [
    {
      "itemKey": "10",
      "supplierBatchId": "COFFEE_BATCH_2024_Q1",
      "quantityDelivered": 1000,
      "poItemCompleted": true
    }
  ]
}

Response:

{
  "message": "Request processed successfully",
  "statusCode": "success",
  "requestItemIndex": 0,
  "referenceId": "erG0eXBlIjoyLCJjdXN0b21lciI6Im9kZXMtc2FuZGJveC0wODAiLCJvYmplY3QiOiJQTy1vZGVzLWNvZmZlZS0yMDI1LTAwMSJ9"
}

Custom Logic Required:

  • Match request IDs from Step 2 monitoring.

  • Calculate accurate delivery quantities from your inventory system.

  • Determine if the PO item is fully completed or partial delivery.

  • Map batch with land plots to deliveries.

Implementation Tips

Request Monitoring Strategy

function monitorRequests() {
  setInterval(async () => {
    try {
      const response = await checkForNewRequests();
      processIncomingRequests(response);
    } catch (error) {
      console.error('Failed to check requests:', error);
      // Alert operations team
    }
  }, 3600000); // Check every hour
}

Data Consistency Checks

// Validation before API calls
function validateBatchData(batch) {
  // Ensure plot exists
  if (!plotExists(batch.plotAssignment[0].supplierPlotId)) {
    throw new Error('Referenced plot does not exist');
  }
  // Validate dates
  if (new Date(batch.validTillDate) < new Date()) {
    throw new Error('Batch validity date cannot be in the past');
  }
  return true;
}

EU Supplier Variation

For EU suppliers, Step 1 (land plots) is skipped, and Step 3 (batch creation) includes DDS information instead:

POST /api_v1_eudrsupplier_batch

Request:

[
  {
    "supplierBatchId": "EU_COFFEE_BATCH_2024_001",
    "validTillDate": "2024-12-31T23:59:59.000Z",
    "ddsList": [
      {
        "euDdsId": "25DEHVMJ221758",
        "euDdsVerificationCode": "18IBHNO1",
        "timestamp": "2025-07-15T10:30:00.000Z"
      }
    ],
    "references": [
      {
        "documentType": 99,
        "documentId": "EU_CERT_2024_001"
      }
    ]
  }
]

Response:

[
  {
    "requestItemIndex": 0,
    "referenceId": "EU_COFFEE_BATCH_2024_001",
    "statusCode": "success",
    "message": "Product batch EU_COFFEE_BATCH_2024_001 created.",
    "errorCode": null
  }
]

Custom Logic Required for EU Suppliers:

  • Obtain valid DDS numbers from EU TRACES system.

  • Map DDS numbers to deliveries.

Conclusion

This guide provides comprehensive information for integrating with the osapiens EUDR Supplier API. For the most up-to-date API documentation, always refer to the official API documentation.