CirculeID

Documentation

Begin hier

Alles wat u nodig hebt om een paspoort uit te geven, ketengebeurtenissen toe te voegen en een credential te verifiëren — met de standaarden waarop elk daarvan afbeeldt, zodat niets wat u bouwt aan dit platform vastzit.

API-referentieEen API-sleutel ophalen
Protocol
JSON over HTTPS
Gebeurtenissen
EPCIS 2.0 JSON-LD
Credentials
W3C VC 2.0

Definition

Hoe geeft u een digitaal productpaspoort uit via een API?

Maak een paspoortresource aan op een GS1-identificator met het productrecord, voeg EPCIS 2.0-gebeurtenissen toe terwijl het product beweegt, en geef W3C Verifiable Credentials uit voor claims die bewijsbaar moeten zijn. Lezen resolvet de identificator en geeft de weergave terug waar de credentials van de aanroeper recht op geven.

The wire formats are not ours: GS1 Digital Link for identity, EPCIS 2.0 for events, and W3C Verifiable Credentials for claims.

Snelstart

Uw eerste paspoort

Eén geauthenticeerde request. Het antwoord bevat de resolvebare Digital Link en de dragerpayload die u drukt of codeert.
POST /v1/passports
curl https://api.circuleid.com/v1/passports \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gtin": "09506000134352",
    "productGroup": "textiles",
    "level": "model",
    "record": {
      "name": "Merino Crew Knit",
      "materials": [
        { "name": "merino wool", "share": 0.82, "certification": "RWS" },
        { "name": "recycled polyamide", "share": 0.18 }
      ]
    }
  }'

Illustrative request shape. The API reference carries the authoritative schema and error contract.

Referentie

Waar u daarna heen gaat

Acht pagina’s dekken het hele oppervlak. Ze staan in de volgorde waarin een integratie doorgaans verloopt.

Integratiepad

Van API-sleutel naar een resolvebaar paspoort

Vier stappen. De tweede is de enige die doorgaans langer duurt dan een middag.
  1. 01

    Een sleutel met scope ophalen

    Sleutels zijn begrensd per omgeving en per functie, zodat een uitgiftedienst nooit leestoegang heeft tot afgeschermde data.

  2. 02

    Het productrecord in kaart brengen

    Post uw productmaster op de bijbehorende GS1-identificator. Het antwoord benoemt de velden die de productgroep nog vereist.

  3. 03

    Gebeurtenissen en credentials toevoegen

    Schrijf EPCIS 2.0-gebeurtenissen terwijl het artikel beweegt; geef credentials uit voor claims die onafhankelijke toetsing moeten doorstaan.

  4. 04

    Resolven en abonneren

    De identificator resolvet naar de voor de aanroeper passende weergave, en webhooks waarschuwen uw systemen zodra er iets verandert.

Antwoorden

Veelgestelde vragen

Wat heb ik nodig voordat ik een paspoort kan uitgeven?

Een API-sleutel, een GS1-identificator voor het product, en het productrecord zelf. Hebt u nog geen GS1-identificatoren, dan is dat de eerste afhankelijkheid om op te lossen — ze komen van uw GS1-lidorganisatie, niet van ons, omdat de identiteit buiten ons platform wereldwijd uniek moet zijn.

Is er een sandbox?

Ja. Sleutels zijn per omgeving afgebakend, dus sandboxsleutels kunnen geen productiepaspoorten raken en productiesleutels kunnen niet per ongeluk in een testopstelling worden gebruikt. Sandboxpaspoorten resolven precies zoals productiepaspoorten, tegen een aparte resolver-hostnaam.

Wat zijn de wire-formaten?

JSON over HTTPS voor de API. Gebeurtenissen volgen de GS1 EPCIS 2.0 JSON-LD-serialisatie, en credentials het W3C Verifiable Credentials 2.0-datamodel. Waar een standaard een representatie vastlegt gebruiken wij die in plaats van er een te verzinnen, waardoor bestaande tooling voor die standaarden op onze output werkt.

Hoe moeten fouten worden afgehandeld?

De API geeft gebruikelijke HTTP-statuscodes terug met een gestructureerde foutbody die het veld en de geschonden voorwaarde benoemt. Validatiefouten komen volledig terug in plaats van één voor één, zodat een onjuist productrecord elk probleem in één response toont in plaats van over vijf rondgangen.

Hoe krijgen wij ondersteuning tijdens het integreren?

Via het supportkanaal bij uw account, of via de contactroute als u nog aan het evalueren bent. Integratievragen die een gat in de documentatie blootleggen worden behandeld als documentatiedefecten, en dat is de enige manier waarop een referentie nauwkeurig blijft terwijl de API groeit.

Next step

Een paspoort uitgeven op uw eigen GTIN

Haal een sandboxsleutel op, post één productrecord, en zie wat de teruggegeven drager resolvet.

Een API-sleutel ophalenAPI-referentie

Index

Verwante artikelen