Példák

Kész, másolható példák OTEP-integráció építéséhez és ellenőrzéséhez. Minden végpont nyilvános és csak olvasható.

1 Az egységes OTEP idővonal lekérése

Egy normalizált idővonal a saját kézbesítés, harmadik felek és futárszolgálatok között.

GET kérés

curl https://api.superlabel.ca/api/v1/otep/trackings/SR123456789

válasz

{
  "result": true,
  "format": "otep",
  "data": {
    "otep_version": "0.1",
    "profile": "parcel",
    "subject": { "order_id": 12345, "tracking_number": "SR123456789" },
    "current_status": "delivered",
    "delivered": true,
    "events": [
      { "occurred_at": "2026-06-10T08:00:00-04:00", "status_code": "out_for_delivery",
        "phase": "out_for_delivery", "location": { "name": "Toronto Hub" },
        "source": { "type": "self_delivery" } },
      { "occurred_at": "2026-06-10T11:30:00-04:00", "status_code": "delivered",
        "source": { "type": "self_delivery" }, "pod": { "recipient": "J. Smith" } }
    ]
  }
}

2 Vetítés külső szabványra

Add hozzá a ?format= paramétert (vagy egy Accept profilt), hogy ugyanazt az idővonalat GS1 EPCIS 2.0, IATA ONE Record, UN/CEFACT, OpenTelemetry (OTLP), OGC SensorThings, AfterShip, Shopify, Amazon, Walmart, BigCommerce, Magento, WooCommerce vagy Etsy formátumban kapd meg.

GET EPCIS

curl "https://api.superlabel.ca/api/v1/otep/trackings/SR123456789?format=epcis"

{ "format": "epcis", "data": { "type": "EPCISDocument", "schemaVersion": "2.0",
  "epcisBody": { "eventList": [
    { "type": "ObjectEvent", "action": "OBSERVE", "eventTime": "2026-06-10T11:30:00-04:00",
      "bizStep": "urn:epcglobal:cbv:bizstep:receiving", "disposition": "urn:epcglobal:cbv:disp:received" } ] } } }

GET OpenTelemetry (egy küldemény = egy trace, minden esemény = egy span)

curl "https://api.superlabel.ca/api/v1/otep/trackings/SR123456789?format=otlp"

3 Megfelelőség ellenőrzése

Küldj bármilyen idővonalat POST-tal a validátornak, és visszakapod a specifikációhoz mért pontos hibákat és figyelmeztetéseket.

POST kérés

curl -X POST https://api.superlabel.ca/api/v1/otep/validate \
  -H "Content-Type: application/json" -d '{
    "otep_version":"0.1","profile":"parcel",
    "subject":{"tracking_number":"SR1"},
    "events":[{"status_code":"not_a_code","source":{"type":"bogus"}}]
  }'

válasz

{
  "conformant": false,
  "errors": [
    { "path": "events[0].occurred_at", "message": "occurred_at is required (ISO-8601 with offset)" },
    { "path": "events[0].status_code", "message": "unknown status_code 'not_a_code'..." },
    { "path": "events[0].source.type", "message": "source.type must be one of: self_delivery, ..." }
  ],
  "warnings": []
}

4 Saját állapotkódok leképezése OTEP-re

Fordítsd le a nyers kódjaidat OTEP-kódokra; tartsd meg a natív kódot a source.external_event_code mezőben. A teljes kódlista a Codebook-ban található.

# your code        ->  OTEP status_code
"OFD"            ->  "out_for_delivery"
"DELIVERED"      ->  "delivered"
"ATTEMPT_FAIL"   ->  "delivery_failed"
"RTS"            ->  "return_to_sender"

eredmény esemény

{ "occurred_at": "2026-06-10T08:00:00-04:00", "status_code": "out_for_delivery",
  "source": { "type": "carrier_label", "carrier_code": "ACME", "external_event_code": "OFD" } }

5 Használat AI-asszisztensből (MCP)

A nyilvános MCP-szerver egy otep_tracking eszközt tesz elérhetővé — egy asszisztens természetes nyelven lekérhet (és vetíthet) egy idővonalat.

{ "method": "tools/call",
  "params": { "name": "otep_tracking",
    "arguments": { "tracking_number": "SR123456789", "format": "epcis" } } }

Mélyebb segítségért a fejlesztői MCP a get_otep_guide eszközt teszi elérhetővé, és minden (specifikáció, JSON Schema, Codebook, MCP-konfiguráció, skill) elérhető a protokoll főoldaláról.