Une documentation pour avancer, étape par étape.

Un passeport numérique, un lien sur le produit.

Votre système transmet les informations du produit. Timelapse Trace doit les associer à un passeport, puis fournir le lien que l’utilisateur ouvrira en scannant son QR code ou en approchant son téléphone d’une puce NFC.

Le parcours API s’effectue dans vos outils : création, validation, publication et récupération des fichiers passent par les appels ci-dessous. L’interface de la plateforme SaaS n’est pas un préalable à la génération.

• Produit : la référence de votre catalogue, par exemple une veste dans une taille et une couleur.
• Lot : un ensemble issu d’une même fabrication, identifié par votre référence de lot.
• Passeport : les informations associées à un modèle, un lot ou un exemplaire.
• Support : le QR imprimé, la puce NFC ou les deux, qui donnent accès au passeport.
• Événement : un fait ajouté au suivi, comme un contrôle ou une réparation.

Le niveau requis et les données à publier dépendent de votre catégorie de produits et des textes applicables. Consulter les repères réglementaires.

Définir l’adresse et la clé API.

Une clé API identifie votre abonnement API lors d’un appel. Elle sera remise lors de l’activation de l’accès pilote et conservée dans les variables d’environnement de votre serveur. Elle ne doit pas figurer sur une étiquette ou dans le code envoyé au navigateur.

Configuration prévisionnelle d’un environnement de test

TRACE_API_URL=https://sandbox-api.timelapse-3d.com/trace/v1
TRACE_API_KEY=remplacer_par_la_cle_de_test_fournie

La clé est envoyée dans l’en-tête Authorization: Bearer …. L’en-tête Idempotency-Key fournit une référence unique pour une opération de création : en cas de nouvelle tentative du même appel, conservez cette référence et les mêmes données.

Dans les exemples, les routes comme /passports s’ajoutent à TRACE_API_URL.

Créer le passeport depuis Node.js.

Exemple avec un exemplaire de veste et deux supports. Ce script utilise fetch dans une version de Node.js qui le prend en charge. Les variables ci-dessus doivent être disponibles dans votre processus serveur.

const baseUrl = process.env.TRACE_API_URL;
const apiKey = process.env.TRACE_API_KEY;

if (!baseUrl || !apiKey) {
  throw new Error("Configurez TRACE_API_URL et TRACE_API_KEY.");
}

// Votre référence permet de relier le passeport à votre ERP.
const payload = {
  external_id: "LOT-2026-42-0001",
  identification_level: "item",
  product: {
    name: "Veste Atelier",
    sku: "VESTE-BLEU-M"
  },
  traceability: {
    batch: "2026-42",
    manufacturing_country: "FR",
    materials: [
      { name: "Coton", percentage: 80 },
      { name: "Polyester", percentage: 20 }
    ]
  },
  carriers: { qr: true, nfc: true }
};

const response = await fetch(`${baseUrl}/passports`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": payload.external_id
  },
  body: JSON.stringify(payload)
});

if (!response.ok) {
  const detail = await response.text();
  throw new Error(`Trace API (${response.status}) : ${detail}`);
}

const passport = await response.json();
console.log("Identifiant à conserver :", passport.id);
console.log("État du passeport :", passport.status);

Les champs à adapter à votre projet

• external_id : votre référence interne pour cet exemplaire, lot ou modèle.
• identification_level : model, batch ou item, selon le niveau choisi.
• product : au minimum le nom et la référence commerciale sku.
• traceability : les informations métier à définir pour votre secteur. Les matières ci-dessus sont un exemple, pas une liste réglementaire complète.
• carriers : qr: true, nfc: true ou les deux.

Comprendre la réponse.

Voici un exemple illustratif conforme à la structure du contrat. Les identifiants et liens ci-dessous sont fictifs.

{
  "id": "dpp_8f31d24",
  "identifier": "TL-2026-0042-0001",
  "status": "draft",
  "public_url": "https://id.timelapse-3d.com/p/TL-2026-0042-0001",
  "identification_level": "item",
  "carriers": {
    "qr_svg_url": "https://sandbox-api.timelapse-3d.com/trace/v1/passports/dpp_8f31d24/qr.svg",
    "nfc_ndef_uri": "https://id.timelapse-3d.com/p/TL-2026-0042-0001"
  }
}

id sert à consulter ou modifier le passeport dans l’API. identifier est son identifiant produit. public_url correspond au lien porté par les supports ; la présence de ce lien ne signifie pas que les informations sont déjà publiées.

status: "draft" indique un brouillon. qr_svg_url désigne le fichier graphique à récupérer ; nfc_ndef_uri est le lien à écrire dans la puce.

Vérifier les informations avant publication.

Votre équipe contrôle les données, les complète si nécessaire, puis déclenche la publication. Un passeport créé et un passeport publié sont deux étapes distinctes.

Remplacez {passportId} par l’id renvoyé à la création. Les règles de validation et les champs modifiables seront précisés dans la version stabilisée du contrat.

Passer du passeport à l’étiquette.

Option A · Imprimer un QR code

Récupérez le fichier vectoriel SVG, puis intégrez-le à votre modèle d’étiquette ou transmettez-le à votre imprimeur. La taille, le contraste et la pose doivent permettre une lecture fiable sur votre produit.

Une fois imprimée et posée, scannez l’étiquette pour vérifier qu’elle ouvre le bon passeport.

Option B · Encoder une puce NFC

Récupérez le lien NFC puis transmettez-le à une application d’encodage et à un téléphone ou lecteur compatibles avec la puce retenue. Le format NDEF URI désigne simplement un lien web stocké dans la puce.

Exemple de réponse NFC

{
  "carrier_id": "carrier_0042",
  "ndef_uri": "https://id.timelapse-3d.com/p/TL-2026-0042-0001"
}

Relisez la puce après écriture. Le résultat du contrôle peut ensuite être associé au support :

L’API prépare les données et enregistre le résultat. L’écriture sur une puce est une opération physique, effectuée avec votre équipement ou un prestataire.

Option C · Combiner QR et NFC

Une étiquette combinée peut porter le QR et intégrer une puce. Les deux donnent accès au même passeport ; les données sont mises à jour depuis votre système.

Votre système peut transmettre les fichiers à votre chaîne d’impression et les liens NFC à votre outil d’encodage, sans ouvrir la plateforme SaaS.

Préparer une série de passeports.

La route /passport-batches décrit une génération en arrière-plan. Utilisez l’identifiant d’un produit déjà créé et, si nécessaire, celui de son lot.

POST /passport-batches · Corps de la requête

{
  "product_id": "prod_42",
  "batch_id": "batch_2026_42",
  "quantity": 5000,
  "identification_level": "item",
  "outputs": ["manifest_csv", "qr_svg_zip"]
}

Une réponse 202 signifie que la demande est acceptée. Le traitement renvoie un objet avec son id et son status, par exemple :

{ "id": "job_0042", "status": "queued", "progress": 0 }

Interrogez GET /jobs/job_0042 pour suivre l’avancement. À la fin, outputs liste les fichiers disponibles : manifeste CSV pour les correspondances et archive des QR pour la préparation de l’impression.

Conserver les étapes utiles du produit.

Un événement décrit une opération, sa date et les informations utiles. Exemple : votre atelier enregistre un contrôle qualité sur l’exemplaire concerné.

POST /passports/dpp_8f31d24/events · Corps de la requête

{
  "type": "quality_check.completed",
  "occurred_at": "2026-09-26T08:30:00Z",
  "data": { "result": "passed", "station": "QC-02" }
}

Les types d’événements et les données associées se définissent selon votre processus de fabrication, de réparation ou de fin de vie.

Lire une erreur et retrouver la requête.

Le contrat prévoit une erreur 422 lorsqu’une donnée est invalide, et une erreur 409 en cas de conflit de référence ou d’idempotence à la création d’un passeport.

{
  "error": {
    "code": "validation_failed",
    "message": "Le champ product.sku est requis.",
    "request_id": "req_9ef2"
  }
}

message explique la correction attendue. Conservez request_id pour retrouver l’appel avec l’assistance. Après une erreur de validation, corrigez les données avant de relancer l’opération.

Recevoir des notifications automatiques.

Les notifications vers votre application, appelées webhooks, font partie des besoins étudiés pour la version pilote. Leur configuration, leur signature et leurs événements ne sont pas encore définis dans le contrat publié.

Pour cadrer dès maintenant un traitement par lots, utilisez le parcours de consultation GET /jobs/{jobId} décrit ci-dessus.

Ce que vous pouvez préparer aujourd’hui.

Le contrat OpenAPI peut être lu dans votre outil de documentation habituel pour examiner les ressources et les formats. Il ne constitue pas un service API actif.

• Identifier vos sources de données et les références à conserver.
• Déterminer le niveau modèle, lot ou exemplaire adapté à votre projet.
• Choisir les étiquettes QR, les puces NFC ou le support combiné.
• Définir qui valide, imprime, encode et contrôle les supports.

L’offre API payante se souscrit seule. La plateforme SaaS et l’application Shopify sont deux autres offres autonomes ; leur abonnement n’est pas requis pour utiliser l’API.

Le contrat prévoit des environnements de test et de production distincts. L’activation des accès pilote, les règles de publication et le contrat stabilisé restent à finaliser avant une intégration opérationnelle.