API partenaire, vue d'ensemble

En quittant cette page, vous saurez authentifier un appel à l'API partenaire, choisir la bonne adresse, lire les en-têtes qui vous disent combien d'appels il vous reste, rejouer une requête sans doubler son effet, et reconnaître les trois plafonds qui peuvent vous refuser. C'est la page à lire une fois, avant d'ouvrir la référence point d'entrée par point d'entrée.

#Ce que cette API fait

L'API partenaire à clef sert à piloter SealTrust depuis votre propre système, sans passer par la console. Elle compte huit points d'entrée, répartis en trois usages.

L'envoi d'un lot ne crée que des produits identifiés par QR. Le serveur pose lui-même, sur chaque ligne du lot, la méthode d'identification et l'identifiant technique de l'article. Vos lignes ne portent ni l'un ni l'autre, et vous ne pouvez pas en demander d'autres.

Il n'y a pas de point d'entrée pour lister vos produits ni pour en lire un seul avec une clef d'API. Vous lisez un produit par les points d'entrée publics de vérification, qui ne demandent aucune clef.

Le portail partenaire, à l'adresse /partner-portal, est une surface différente. Il s'authentifie avec la session d'un compte partenaire réparateur ou recycleur, et une clef d'API n'y donne aucun accès.

#L'adresse de base et le préfixe /v1

Vous appelez l'API sur https://api.sealtrust.io.

Chaque point d'entrée décrit sur ce site existe à deux adresses qui appellent exactement le même code : avec le préfixe /v1, et sans aucun préfixe.

POST https://api.sealtrust.io/v1/partner/mint/batch
POST https://api.sealtrust.io/partner/mint/batch

Utilisez la forme /v1 pour toute nouvelle intégration.

Les pages de référence de ce site titrent chaque point d'entrée avec son chemin sans préfixe, par exemple POST /partner/mint/batch. Ajoutez /v1 devant ce chemin quand vous écrivez votre appel.

Les adresses sans préfixe sont des alias permanents. Nous ne leur attachons aucune date de fin de service, et nous n'envoyons sur ces réponses aucun en-tête d'annonce de suppression. Si votre intégration les appelle déjà, elle continuera de fonctionner.

#Authentifier un appel

Vous envoyez votre clef dans l'en-tête Authorization, au format Bearer.

Authorization: Bearer votre_clef

C'est le seul mode d'authentification de cette API. Il n'y a ni paramètre d'URL, ni cookie, ni signature de requête à calculer.

#Obtenir une clef

Vous créez vos clefs depuis la console de votre marque, dans Paramètres puis l'onglet Développeurs. L'onglet reste visible quelle que soit votre offre. Si votre offre ne comprend pas l'accès API, l'écran s'affiche verrouillé et vous ne pouvez y créer aucune clef.

Trois points comptent au moment de la création.

• Le secret complet ne s'affiche qu'une seule fois, dans la fenêtre qui suit la création. Copiez-le à ce moment. Aucun écran et aucun point d'entrée ne permet de le relire ensuite. Nous n'en conservons qu'une empreinte.
• Une clef appartient à une seule marque. Nous rattachons à cette marque toutes les opérations faites avec elle, et à aucune autre.
• Une clef expire toujours. Vous choisissez une durée de vie à la création. Si vous n'en choisissez pas, elle est de 365 jours. Notez la date dans votre agenda : le jour venu, vos appels s'arrêtent.

La console affiche ensuite les premiers caractères de chaque clef, pour vous permettre de la reconnaître dans la liste sans jamais réafficher son secret. Elle affiche aussi la date de dernière utilisation. Nous ne rafraîchissons cette date qu'au plus une fois par minute, elle peut donc retarder d'une minute sur votre dernier appel.

#Révoquer une clef

Vous révoquez une clef depuis la même page, et la révocation prend effet immédiatement. Le premier appel qui suit reçoit un refus. Révoquer une clef libère une place si votre offre limite le nombre de clefs actives.

#Les refus d'authentification

#Votre premier appel

Vérifiez qu'une clef fonctionne avec la liste de vos abonnements aux notifications. Ce point d'entrée ne modifie rien et ne consomme aucun quota. Il demande le droit webhooks:read.

curl -i https://api.sealtrust.io/v1/partner/webhooks \
  -H "Authorization: Bearer st_test_0000000000000000000000000000000000000000000000"

import { SealTrustClient } from "@sealtrust-io/sdk";

const client = new SealTrustClient({
  apiKey: "st_test_0000000000000000000000000000000000000000000000",
});

const page = await client.webhooks.list();

console.log(page.total);
console.log(page.items);

import requests

response = requests.get(
    "https://api.sealtrust.io/v1/partner/webhooks",
    headers={
        "Authorization": "Bearer st_test_0000000000000000000000000000000000000000000000"
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Réponse, code HTTP 200, pour une marque qui n'a encore aucun abonnement :

{
  "items": [],
  "total": 0
}

Le SDK TypeScript vous rend le corps de la réponse, jamais ses en-têtes. Pour lire les en-têtes de plafond décrits dans Le débit, en appels par minute, appelez l'API en HTTP direct depuis votre serveur, ou passez par curl -i. Un navigateur ne peut pas les lire : nous n'exposons au navigateur que l'en-tête X-Total-Count.

#Les droits attachés à une clef

Chaque clef porte une liste de droits. Un droit absent fait refuser l'appel en 403, et le message de refus nomme le droit qui manque.

Quatre droits commandent l'accès aux points d'entrée de cette API.

#Les trois plafonds

Trois compteurs différents peuvent refuser un appel. Ils ne se ressemblent pas et ils ne se lisent pas au même endroit. Traitez-les séparément.

#Le débit, en appels par minute

Nous comptons vos appels sur une fenêtre fixe de 60 secondes. Ce plafond s'applique aux huit points d'entrée, y compris la lecture du statut d'un lot et la suppression d'un abonnement.

Deux compteurs tournent en même temps : un pour votre clef, un pour la somme de toutes les clefs de votre marque. Le plafond est le même des deux côtés.

Votre plafond vient d'une valeur posée sur votre compte, ou à défaut de votre offre. Quand aucune des deux n'est définie, vous disposez de 120 appels par fenêtre. Ne devinez pas cette valeur : vous la lisez sur chaque réponse.

Toute réponse qui passe le plafond porte les quatre en-têtes suivants.

Ces en-têtes décrivent toujours le compteur le plus serré des deux. Pilotez votre cadence dessus, et ralentissez avant d'atteindre zéro.

Un dépassement renvoie 429 avec les mêmes en-têtes, plus Retry-After. Retry-After compte les secondes qui restent dans la fenêtre en cours, et vaut au minimum 1. Respectez-le. X-RateLimit-Scope vous dit lequel des deux compteurs a refusé, ce qui évite de chercher du côté de la clef quand c'est le total de la marque qui est plein.

Un dernier cas, rare : si le service qui tient ces compteurs est momentanément indisponible, les huit points d'entrée répondent 503. Un 503 signifie que l'appel n'a rien fait du tout. Réessayez plus tard.

#Le quota quotidien de la clef

Chaque clef peut porter un quota quotidien. Une clef sans quota est illimitée de ce côté. Le compteur repart de zéro au passage de minuit en temps universel. Votre fuseau horaire n'entre pas en compte.

Ce quota se compte par ligne envoyée.

• Un lot de 100 lignes consomme 100 unités.
• Une déclaration de vente consomme 1 unité.
• Les six autres points d'entrée ne consomment rien : les cinq points d'entrée d'abonnement aux notifications, et la lecture de l'avancement d'un lot.

Un dépassement renvoie 429 avec trois en-têtes qui lui sont propres.

La réponse porte en plus les quatre en-têtes X-RateLimit-* du contrôle de débit, que l'appel venait de passer avant d'être arrêté par le quota.

#Le quota mensuel de votre offre

Votre offre fixe un nombre de produits créables par mois, sur votre période de facturation. Elle décide aussi si l'accès API vous est ouvert, et si les abonnements aux notifications vous sont ouverts.

Trois refus en 403 en découlent, tous porteurs d'un code lisible par votre programme.

Votre offre ne comprend pas l'accès API :

{
  "detail": {
    "code": "FEATURE_NOT_AVAILABLE",
    "feature": "api_access"
  }
}

Votre offre ne comprend pas les abonnements aux notifications :

{
  "detail": {
    "code": "FEATURE_NOT_AVAILABLE",
    "feature": "webhooks"
  }
}

Ce refus-là ne touche que la création et la modification d'un abonnement. Vous gardez la lecture et la suppression quelle que soit votre offre. Vous gardez aussi l'extinction d'un abonnement, à une condition : envoyez is_active à faux et rien d'autre. Dès qu'un second champ accompagne cette valeur, l'appel compte comme une modification et le refus s'applique.

Vous avez atteint le nombre de produits de votre période de facturation :

{
  "detail": {
    "code": "QUOTA_EXCEEDED",
    "resource": "products",
    "current": 4800,
    "additional": 300,
    "max": 5000,
    "period": "monthly"
  }
}

Celui-ci se lit ainsi : vous avez déjà créé 4800 produits sur la période, vous en demandez 300 de plus, le maximum est de 5000. Découpez votre lot ou attendez la période suivante.

#Rejouer un appel sans doubler son effet

L'envoi d'un lot accepte un en-tête Idempotency-Key. Cet en-tête porte une clef d'idempotence, c'est-à-dire une valeur qui garantit qu'un même envoi renvoyé deux fois ne produit qu'un seul traitement. Vous en choisissez la valeur, et vous la gardez le temps de vos tentatives.

Idempotency-Key: lot-exemple-0001

Cet en-tête répond au cas où vous n'obtenez pas de réponse : coupure réseau, délai dépassé, redémarrage de votre côté. Vous ne savez pas si le lot est parti. Renvoyez la même requête avec la même valeur, et vous obtenez la réponse du premier appel sans qu'un second lot parte en traitement.

Trois comportements à connaître.

• Même clef d'idempotence, même lot : vous récupérez la réponse du premier appel. Nous ne lançons pas un second traitement.
• Même clef d'idempotence, lot différent : la réponse est 409. Nous ne vous rendons pas la réponse du premier appel, parce qu'elle ne décrit pas ce que vous venez d'envoyer.
• Même clef d'idempotence pendant que le premier appel est encore en cours de traitement : la réponse est également 409. Attendez la fin du premier appel, puis réessayez.

Nous gardons une valeur 24 heures. Passé ce délai, la même valeur redevient une requête neuve, et un renvoi enverrait un second lot en traitement. N'utilisez donc jamais une valeur fixe : tirez une valeur nouvelle par lot, et gardez-la le temps des tentatives de ce lot.

La comparaison entre deux lots porte sur leur contenu une fois normalisé. L'ordre des lignes, l'ordre des colonnes, le format choisi entre CSV et JSON et les cellules laissées vides ne changent rien : nous reconnaissons deux envois du même contenu comme identiques.

Un renvoi qui rend la réponse mise en cache consomme quand même un appel sur votre plafond de débit. Il ne consomme ni votre quota quotidien, ni le quota mensuel de votre offre.

#Pagination

Un seul point d'entrée de cette API rend une liste : GET /v1/partner/webhooks.

La réponse contient deux champs : items, la page demandée, et total, le nombre total d'abonnements de votre marque. Vous parcourez donc la liste en augmentant skip de la valeur de limit jusqu'à couvrir total.

Vous recevez les abonnements du plus récent au plus ancien.

#Ce qu'il faut retenir avant d'ouvrir la référence

• L'adresse est https://api.sealtrust.io, et la forme à utiliser est /v1.
• La clef part dans Authorization: Bearer, et nulle part ailleurs.
• Le secret ne s'affiche qu'une fois. Une clef expire toujours.
• Un 401 parle de la clef elle-même. Un 403 parle d'un droit, d'un statut, ou de ce que votre offre autorise.
• Un 429 vient soit du débit, soit du quota quotidien. Retry-After désigne le débit, X-Quota-Limit désigne le quota quotidien.
• Un 503 vient du service qui tient les compteurs de débit, et signifie que l'appel n'a rien fait.
• Le suivi d'un lot répond finished quand la file d'exécution a fini, jamais pour dire que les lignes ont réussi.
• Une requête de lot renvoyée après une coupure doit porter la même Idempotency-Key que la première tentative.

Chaque point d'entrée a sa propre page, avec ses paramètres, sa réponse réelle et son tableau d'erreurs complet. Vous les retrouvez dans la barre latérale, rangés par tâche : « Créer des produits », « Déclarer une vente », « Recevoir les événements ».

• POST /partner/mint/batch
• GET /partner/mint/batch/status/{job_id}
• POST /partner/sellout
• POST /partner/webhooks
• GET /partner/webhooks
• GET /partner/webhooks/{webhook_id}
• PUT /partner/webhooks/{webhook_id}
• DELETE /partner/webhooks/{webhook_id}

La page Erreurs rassemble les codes communs à toute l'API.