GETMéthode GET/resolve/{identifier}

Code HTTP 200. Un article complet, avec certificat, passeport publié, un média, un événement et les deux preuves d'ancrage.

{
  "token_id": "1024",
  "uid_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "product_name": "Sac de voyage Exemple SAS",
  "brand_name": "Exemple SAS",
  "category_name": "Maroquinerie",
  "sku": null,
  "description": null,
  "metadata_uri": "ipfs://bafyexemple00000000000000000000000000000000000000000000000",
  "created_at": "2026-08-14T09:12:33.418000Z",
  "tx_hash": "0x4444444444444444444444444444444444444444444444444444444444444444",
  "contract_address": "0x0000000000000000000000000000000000000000",
  "certificate": {
    "certificate_number": "ST-CERT-000000000000",
    "status": "active",
    "issued_at": "2026-08-14T09:14:02.117043Z",
    "expires_at": null,
    "issuer_name": "Exemple SAS"
  },
  "passport": {
    "schema_version": "1.0",
    "passport_version": 3,
    "data": {
      "product_identity": {
        "gtin": "03701234567891",
        "model": "Sac de voyage",
        "brand": "Exemple SAS",
        "made_in": "FR",
        "production_facility": "Atelier Exemple SAS"
      },
      "circularity": {
        "recyclability_percentage": 62,
        "recycled_content_percentage": 0
      },
      "compliance": {
        "eu_espr": true,
        "reach": true
      }
    },
    "published_at": "2026-08-18T07:03:11.902000Z",
    "data_hash": "0000000000000000000000000000000000000000000000000000000000000000"
  },
  "media": [
    {
      "id": 4821,
      "file_name": "sac-face.jpg",
      "media_type": "image",
      "url": "https://cdn.example.com/exemple-sas/sac-face.jpg",
      "alt_text": "Sac de voyage vu de face"
    }
  ],
  "events": [
    {
      "id": 9137,
      "event_type": "warranty_activation",
      "description": "Garantie activée à l'achat en boutique.",
      "occurred_at": "2026-08-19T14:32:07.481920Z",
      "actor_name": "Boutique Exemple SAS Lyon"
    }
  ],
  "merkle_anchor": {
    "anchor_tx_hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "root": "0x2222222222222222222222222222222222222222222222222222222222222222",
    "leaf_index": 17,
    "leaf": "0x3333333333333333333333333333333333333333333333333333333333333333",
    "proof": [
      "0x5555555555555555555555555555555555555555555555555555555555555555",
      "0x6666666666666666666666666666666666666666666666666666666666666666"
    ]
  },
  "passport_anchor": {
    "tx_hash": "0x7777777777777777777777777777777777777777777777777777777777777777",
    "basescan_url": "https://basescan.org/tx/0x7777777777777777777777777777777777777777777777777777777777777777",
    "merkle_root": "0x2222222222222222222222222222222222222222222222222222222222222222",
    "anchored_at": "2026-08-18T07:05:44.220118Z",
    "confirmed_at": null,
    "block_timestamp": "2026-08-18T07:05:58.000000Z",
    "block_number": 34129877,
    "passport_version": 3,
    "data_hash_matches": true
  },
  "evidence": {
    "sections": {
      "identity": "verified",
      "integrity": "verified",
      "composition": "declared"
    },
    "legend": {
      "declared": "Stated by the brand. Recorded, dated and attributable, but not independently checked.",
      "verified": "Rests on an on-chain reference that anyone can re-check independently. SealTrust records it and does not re-query the chain on each request."
    },
    "derived": true,
    "note": "Statuses are computed by SealTrust from verifiable facts. A brand cannot set them."
  }
}

Code HTTP 200 également pour un article minimal. Un article sans certificat en cours, sans passeport publié, sans média, sans historique et dont le lot n'a pas été ancré rend la même structure avec des valeurs vides.

{
  "token_id": null,
  "uid_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "product_name": "Sac de voyage Exemple SAS",
  "brand_name": "Exemple SAS",
  "category_name": null,
  "sku": null,
  "description": null,
  "metadata_uri": "ipfs://bafyexemple00000000000000000000000000000000000000000000000",
  "created_at": "2026-08-14T09:12:33.418000Z",
  "tx_hash": null,
  "contract_address": "0x0000000000000000000000000000000000000000",
  "certificate": null,
  "passport": null,
  "media": [],
  "events": [],
  "merkle_anchor": null,
  "passport_anchor": null,
  "unit_anchor": null,
  "evidence": null
}

#Les champs de premier niveau

#certificate

Le serveur rend le certificat le plus récemment émis parmi ceux qui sont encore actifs à l'instant de l'appel. Il écarte un certificat révoqué, et il écarte un certificat dont la date d'expiration est passée.

#passport

Le passeport rendu est celui qui porte le numéro de version le plus élevé parmi les versions publiées. Le serveur cherche d'abord un passeport rattaché à l'article lui-même, puis celui de son lot de production, et ne retombe sur le passeport de référence du modèle que s'il n'en trouve aucun. L'ordre compte : un article qui a son propre passeport ne doit jamais recevoir celui d'un autre exemplaire du même modèle, avec le numéro de série et l'état de batterie de cet autre exemplaire. Le serveur ne rend ici ni les brouillons, ni les passeports réservés à la marque.

Le filtrage retient les sections destinées au public, quand le passeport les contient : identité du produit, identification du fabricant, conformité ESPR, conformité REACH, marquage CE, marquages des articles 13(4) et 13(5), lien vers la déclaration UE de conformité, étiquettes, spécification de batterie, ingrédients, nom et adresse de la personne responsable d'un cosmétique, et dans la circularité le taux de recyclabilité, le contenu recyclé, l'agent extincteur et le lien sur la gestion des déchets.

L'impact environnemental, le reste de la circularité, la durabilité, l'efficacité énergétique, l'empreinte carbone, les matières principales, l'entretien et le mouvement relèvent du niveau end_user : ils ne sortent pas par ce point d'entrée. Un client connecté les lit sur GET /passport/{identifier}.

Une section distincte, « déclaration UE de conformité », porte le contenu de la déclaration elle-même quand la marque l'a rempli : numéro, date et lieu d'émission, personne morale sous la responsabilité de laquelle elle est établie, objet, textes de l'Union couverts, normes harmonisées appliquées, et le cas échéant l'organisme notifié avec son numéro d'identification et son attestation. Les champs laissés vides ne sont pas publiés, et la section entière est absente tant que rien n'a été rempli : un bloc vide affirmerait qu'un document existe sans rien en dire.

Pour un passeport batterie, ce découpage suit l'annexe XIII du règlement (UE) 2023/1542 : le point 1 y ajoute les substances dangereuses, les matières premières critiques, l'empreinte carbone et sa classe, le rapport de diligence raisonnable, le contenu recyclé après consommation par métal et la part de contenu renouvelable. En sens inverse, trois champs en sortent, parce que les points 2 et 4 les réservent aux personnes ayant un intérêt légitime : les références de pièces, l'état de la batterie et la durée de vie en cycles.

Pour un passeport textile, le nom et le pourcentage de chaque matière sont publics : c'est la composition en fibres que le règlement (UE) n° 1007/2011 impose sur l'étiquette et veut visible avant l'achat, en ligne compris. L'origine des matières reste réservée. Pour un passeport chaussure, la matière de la tige, de la doublure, de la première de propreté et de la semelle est publique, comme sur l'étiquette que la directive 94/11/CE fait porter à la chaussure. Ces mentions d'étiquette, comme les données publiques de l'annexe XIII, restent publiques quelles que soient les règles de la marque.

Les champs que la console écrit à la racine du passeport (composition, care_instructions, size...) ont chacun leur propre niveau, décrit dans Les règles d'accès au passeport. Ceux qui identifient le produit, la composition en fibres, les matières d'une chaussure, la taille, la couleur et le poids sont publics. Les conseils d'entretien relèvent du niveau end_user.

Le serveur retire tout le reste avant l'envoi, y compris à l'intérieur d'une section partiellement retenue. Dans l'exemple ci-dessus, la section circularity du passeport complet porte aussi l'indice de réparabilité et la durée de vie estimée : ces deux entrées ne sortent pas par ce point d'entrée.

Une marque peut définir ses propres règles d'accès pour ses groupes de produits. Ces règles remplacent alors entièrement le découpage par défaut décrit ci-dessus, y compris pour le niveau public : une règle publique posée sur la nomenclature de fabrication la fait sortir par ce point d'entrée.

#media

Jusqu'à 20 entrées, dans l'ordre d'affichage défini par la marque.

Le serveur prend d'abord les médias rattachés à l'article. S'il n'y en a aucun, il prend ceux du modèle. En dernier recours, il rend l'image de couverture du modèle, seule, avec l'identifiant 0. Cette valeur 0 signale une entrée fabriquée pour l'occasion, sans enregistrement propre.

#events

Jusqu'à 20 entrées, de la plus récente à la plus ancienne. La liste est tirée des 60 derniers événements enregistrés, puis nettoyée.

Le serveur retire deux familles d'événements. Les étapes de rachat qui n'ont rien changé à l'objet : proposition, refus, expiration, accord non réglé. Et les transferts de propriété, qui ne figurent pas dans cette liste.

#merkle_anchor

Présent seulement si trois conditions sont réunies : l'article appartient à un lot dont la racine a été ancrée sur Base, l'article porte un identifiant de jeton, et la racine recalculée aujourd'hui est identique à la racine ancrée. Si le lot a changé depuis l'ancrage, la preuve serait invérifiable sur la chaîne et le champ vaut null. Le serveur ne rend jamais une preuve trompeuse.

Vous pouvez vérifier cette preuve vous-même, sans nous faire confiance. La recomposition part de leaf, applique les entrées de proof dans l'ordre, et doit aboutir à root.

L'empreinte utilisée est keccak256. La convention de couple est celle d'OpenZeppelin : à chaque étage, vous concaténez les 32 octets de la valeur courante et les 32 octets de l'entrée de proof dans l'ordre croissant, puis vous appliquez keccak256 au résultat.

from eth_utils import keccak  # pip install eth-utils

root = "0x2222222222222222222222222222222222222222222222222222222222222222"
leaf = "0x3333333333333333333333333333333333333333333333333333333333333333"
proof = [
    "0x5555555555555555555555555555555555555555555555555555555555555555",
    "0x6666666666666666666666666666666666666666666666666666666666666666",
]

node = bytes.fromhex(leaf[2:])
for entree in proof:
    voisin = bytes.fromhex(entree[2:])
    node = keccak(node + voisin) if node < voisin else keccak(voisin + node)

print("0x" + node.hex() == root)

Les valeurs ci-dessus sont inventées, donc ce programme affiche False. Remplacez-les par celles d'une réponse réelle et il affiche True.

#passport_anchor

Présent seulement si cette version exacte du passeport a été ancrée et si la transaction d'ancrage existe. Ce champ date le contenu du passeport. Le champ merkle_anchor ci-dessus date l'article. Les deux restent séparés parce qu'ils ne prouvent pas la même chose.

Aucune preuve d'inclusion n'accompagne l'ancrage du passeport. Pour vérifier l'appartenance vous-même, appelez GET /v1/passport/{identifier}/proof, qui rend la feuille, sa position et les empreintes sœurs.

#unit_anchor

Présent seulement pour une pièce créée en mode ancré : son lot est inscrit sur Base sous une seule racine, et la pièce n'a son propre jeton qu'à partir de sa première revendication (pièces enregistrées par lot). Le bloc est le même que la réponse de GET /v1/verify/unit-anchor/{identifier}, sans la lecture du contrat : onchain_root_matches vaut toujours null ici.

#evidence

Sur quelle base chaque section du passeport peut être crue. C'est le même bloc, calculé par la même fonction, que celui de GET /v1/passport/{identifier}.

Trois valeurs existent, et elles sont calculées par SealTrust. Une marque ne peut pas les choisir.

Quatre sections peuvent porter une de ces valeurs : identity, integrity, composition et substances_of_concern. Seules les sections que le passeport contient réellement en reçoivent une.

identity et integrity sont toujours présentes, parce qu'elles portent sur l'exemplaire lui-même. La section identity passe à verified quand l'unité porte un identifiant de jeton sur la chaîne. La section integrity passe à verified quand l'empreinte de cette version a été ancrée et correspond toujours aux données enregistrées.

composition et substances_of_concern n'apparaissent que si les données du passeport les portent. Un bloc de matières resté vide (lignes sans nom, sans part et sans origine) ne décrit aucune matière. Dans la réponse d'exemple ci-dessus, le passeport complet décrit ses matières, absentes du bloc public, et ne déclare aucune substance préoccupante : sections compte donc trois entrées. Le nombre d'entrées va de deux à quatre selon le passeport servi.

Le bloc porte en plus legend, qui redit le sens des valeurs présentes, derived à true, et note.

Aucune autre section du passeport ne reçoit de mention. Une section que sections ne nomme pas n'est ni vérifiée ni infirmée, elle n'est pas notée. N'affichez donc une mention que pour les sections que ce champ nomme.

Le champ vaut null quand aucun passeport publié n'est servi, et null si son calcul échoue. Un client qui ne trouve pas le bloc n'affiche aucune mention.