QREDI Integration API (1.1.2)

The QREDI Integration API simplifies interoperability between clients and transportation companies. It introduces a new approach to logistics data exchange by adopting the global GS1 standard for Electronic Product Code Information Services (EPCIS 2.0).

EPICS 2.0 standard provides a unified way to track and trace physical and digital objects across your supply chain. By enabling a single, standardized interface, the QREDI API helps companies reduce future costs and complexity by avoiding the need for multiple, tailor-made integrations.

This API specification is under active development. We are continuously enhancing it to support a growing number of partners and diverse business cases. Having validated market needs with initial custom integrations, we are now transitioning to this standardized API to better serve our customers with a more scalable and interoperable solution.

The QREDI API is a RESTful service that uses standard JSON for request and response bodies and secures endpoints with OAuth 2.0 (Client Credentials grant).

All API endpoints described in this document are relative to the base URL: https://api.qredi.eu/v1/.

Its core capabilities allow you to:

• Register Transport Units: Create new logistics records using GS1 identifiers.
• Modify Transport Unit: Updates existing logistics records using GS1 identifiers.
• Remove Transport Unit: Deletes existing logistics records using GS1 identifiers.
• Query EPCIS Events: Retrieve event data by EPC (e.g., SSCC) with powerful filtering, sorting, and pagination.

Before making a request, understand these fundamental principles.

Standards & Identifiers:

• Vocabularies: All API payloads and data structures adhere to the GS1 EPCIS 2.0 and GS1 Core Business Vocabulary (CBV) standards.
• Resource Identifiers: Electronic Product Codes (EPCs) and Global Location Numbers (GLNs) are represented as GS1 Digital Link URIs.
  • Example: https://id.qredi.eu/00/{sscc}
• URL Encoding: When using a GS1 Digital Link URI in a URL path parameter, it MUST be URL-encoded.

Error Handling

• Authentication Errors: Follow the standard definitions in RFC 6749.
• API Errors: Invalid query parameters, oversized requests, or other bad requests will return a structured problem detail response as defined in RFC 7807. See the Responses section in the endpoint documentation for specific error shapes.

Access is protected using OAuth 2.0. To authenticate, you must obtain a bearer token.

1. Encode Your Credentials: Combine your client_id and client_secret into the format client_id:client_secret and Base64-encode the string.

2. Request a Token: Make a POST request to the /auth/token endpoint with the following:

   • Header: Authorization: Basic <your_base64_encoded_credentials>
   • Header: Content-Type: application/x-www-form-urlencoded
   • Body: grant_type=client_credentials

3. Use the Token: The server will respond with a JSON object containing an access_token. Include this token in the Authorization header of all subsequent API requests.

   • Header: Authorization: Bearer <your_access_token>

The Transport Units endpoints provide a standardized way for external systems to manage logistics records within QREDI.

A transport unit represents a physical or logical grouping of goods, typically identified by a unique logistics identifier such as an SSCC (Serial Shipping Container Code). These endpoints are designed to support common operational workflows where transport units need to be registered, updated, or removed as part of the supply chain process.

POST - allows external systems to create new transport units in QREDI. This is typically used to register shipments or pallets at the point of preparation or dispatch.

PUT - enables the modification of existing transport units identified by their external identifier. This operation is used when certain details, such as location or order references, need to be updated during the reserving phase of the logistics process.

DELETE - provides a way to remove transport units from the system when they are no longer needed or were created in error. Deletions are restricted to units in eligible states to ensure data consistency.

When creating a transport unit, you can provide details such as external identifier of physical barcode (in cases where QREDI identifier is not available), sales order ID, and the location where the transport unit is placed. The location must include a postal address with specific fields like street address, locality, country, and postal code.

The API will validate the provided information and return a response indicating the success or failure of the operation. If successful, it will return the details of the created transport unit.

Together, these operations help maintain accurate, real-time visibility of goods movement and support efficient integration between QREDI and partner systems.

Once authenticated, you can retrieve event data from the EPCIS endpoints.

Filtering

Refine your search using query parameters. Common filters include:

• Time: GE_eventTime, LE_eventTime, GE_recordTime, LE_recordTime
• Business Context: EQ_bizStep, EQ_disposition, EQ_action
• Location: EQ_bizLocation

Sorting

Control the order of results using orderBy (eventTime or recordTime) and orderDirection (asc or desc).

Pagination

The API uses a token-based, Link header strategy for pagination.

1. Set the number of results per page with the perPage parameter.
2. If more results exist, the response will include a Link header containing a URL with rel="next".
3. To retrieve the next page, make a GET request to this "next" URL.
4. Continue this process until a response is returned without a Link header where rel="next".