generated: '2026-08-02'
method: searched
source: >-
  TraceLink published API guides on opus.tracelink.com/documentation/2026.1 and the
  first-party code samples at https://github.com/tracelink/code-samples
docs:
- https://github.com/tracelink/code-samples/blob/main/python/FormatRequests.MD
- https://opus.tracelink.com/documentation/2026.1/en-US/api/smart-event-manager/pdfs/smart_event_manager_api_guide_2026.1.pdf
- https://opus.tracelink.com/documentation/2026.1/en-US/api/administration/pdfs/admin_api_guide_2026.1.pdf

authentication:
  style: HTTP Basic (RFC 7617) across all surfaces; short-lived Bearer only for key bootstrap
  artifact: authentication/tracelink-authentication.yml

transport:
  surfaces:
  - name: OPUS Platform Event API
    style: single-endpoint RPC over HTTP
    method: POST
    path: /api/events
    note: >-
      One exposed /api/events endpoint per environment. The HTTP method is always
      POST regardless of the operation or object being operated upon; the operation
      is selected by the eventName inside the request body header.
  - name: OPUS GraphQL API
    style: GraphQL over HTTP POST
    path: /api/graphql
    note: >-
      Calls go through generic dispatch fields — genericActionCall(action, payload)
      and genericGetObject — rather than a typed field per operation, so the GraphQL
      surface mirrors the same action/payload model as the events API.
  - name: Smart Event Manager REST API
    style: synchronous JSON request/response
    messages: [Set Event, Get Event, Get Result]
  - name: SOAP services
    style: SOAP 1.1 over HTTPS, WSDL published at ?wsdl on the production host
    hosts: [https://api.tracelink.com, https://itestapi.tracelink.com]
  - name: B2B asynchronous message exchange
    style: file-based message exchange
    channels: [AS2, SFTP, HTTP POST]
    note: >-
      Message Type (e.g. SOM_DESTROY_EVENT) selects the flow. Over AS2 it travels in
      the AS2 header; over HTTP POST it is part of the URL
      (https://prodb2b.tracelink.com:5443/server?request=send&directory=inbox/<MESSAGE_TYPE>&filename=<filename>);
      over SFTP/SSTP it is the folder the message is saved to.
    limits:
      inbound_file_size: 300 MB for asynchronous messages sent inbound to TraceLink

envelope:
  description: >-
    Every OPUS Platform API request and response is a JSON object with exactly two
    top-level members, header and payload. The header identifies how the platform
    routes and processes the request; the payload carries the business object.
  request_header_fields:
  - name: headerVersion
    type: integer
    required: true
    description: Version identifier for the request envelope. Current value 1.
  - name: eventName
    type: string
    required: true
    description: Fully qualified name of the request event, in the form <app>:<action>:<version>.
  - name: ownerId
    type: string
    required: true
    description: The Owner company associated with the request.
  - name: processNetworkId
    type: string
    required: true
    description: The network within the Owner company containing the process.
  - name: appName
    type: string
    required: true
    description: The application that owns the event (e.g. agile-process-teams).
  - name: dataspace
    type: string
    required: true
    description: The dataspace inside the environment where the request is made (e.g. default).
  response_header_fields:
  - name: eventName
    description: The response event name, conventionally the request event name with a -response suffix.
  - name: isErr
    type: boolean
    description: Whether the call failed.
  - name: errCode
    type: string
    description: Result code, e.g. 200_OK.
  - name: licensePlate
    type: string
    description: >-
      Per-call correlation identifier returned on the response header; the closest
      thing TraceLink publishes to a request-id for tracing a single call.

versioning:
  operation_level:
    scheme: version suffix on the event name
    example: 'agile-process-teams:add-direct-supplier-incident:v3'
    note: >-
      Operations are versioned individually. Multiple versions of the same action
      coexist (add is at v3 while reopen is still v1), so an integration pins a
      version per event rather than per API.
  schema_level:
    scheme: dataVersion on each canonical JSON Schema
    note: Canonical objects carry dataVersion (e.g. canonicalInvoice v1, v2, v4) side by side.
  platform_level:
    scheme: calendar release train YYYY.N
    current: '2026.1'
    artifact: lifecycle/tracelink-lifecycle.yml

errors:
  envelope: response header isErr + errCode, with HTTP status carried at the transport layer
  http_status_codes: [200, 307, 400, 401, 403, 404, 500, 502, 503, 504]
  artifact: errors/tracelink-problem-types.yml
  rfc9457: false
  note: >-
    TraceLink does not use application/problem+json. Synchronous errors are returned
    in the response header of its own JSON envelope; asynchronous message errors are
    returned as coded error entries documented per message in each API guide.

idempotency:
  supported: false
  note: >-
    No idempotency-key header, request-deduplication token, or safe-retry contract is
    documented on any TraceLink surface. The asynchronous B2B pipeline detects
    duplicate FILES ("File <inFilename> is a potential duplicate match with file
    <origFilename>") and offers an operator-driven Reprocess/Park-and-Retry action,
    but that is server-side duplicate rejection, not a client-controlled idempotency
    key. Recorded as absent rather than inferred — no Idempotency pointer is emitted.

pagination:
  documented: false
  note: >-
    No cursor or offset pagination convention is published. Bulk reads are modelled
    as asynchronous jobs instead: a request returns an eventQueryResponseId, and the
    caller polls Get Result to learn whether the job has completed and what it
    returned.

rate_limits:
  documented: false
  note: No published rate limit or quota, and no rate-limit response headers documented.

tracing:
  request_id: licensePlate (response header, OPUS events API)
  monitoring: >-
    Info Exchange is the operator-facing surface for monitoring and troubleshooting
    messages exchanged with partners; the Info Exchange Display Name accompanies each
    Message Type in every API guide.

data_formats:
  request: application/json (REST/events/GraphQL); XML (SOAP, EPCIS, TL XML)
  canonical_objects: json-schema/ (37 canonical JSON Schemas, draft-04)
  b2b_formats: [EPCIS 1.2, EPCIS 2.0, GS1 XML, EDI ANSI X12, SAP IDoc, TL XML, CSV]