URL de base : https://card-seal.com/api/v1

Authentification : envoyez votre token dans l'en-tête HTTP Authorization :

Authorization: Bearer cs_live_pk_XXXX...

Conditions d'import (cartes refusées)

Une carte n'est pas enregistrée si :

• Champ obligatoire manquant (cert_number, grading_company ou owner_ref) → missing_fields.
• Référence propriétaire invalide : accent, espace ou caractère spécial. Format attendu : 1 à 32 caractères ASCII [A-Za-z0-9_-], idéalement un identifiant unique et stable par client → bad_owner_ref.
• Numéro déjà enregistré par un autre partenaire → pending_review (le premier à inscrire reste le garant).
• Carte déjà présente chez vous → duplicate_own (ou duplicate_own_deleted si elle avait été supprimée).
• Client ayant déjà activé son compte → owner_already_active (correction via hello@card-seal.com).
• Limite : 5000 cartes maximum par requête → too_many_cards.
• Société de gradation non référencée (valeurs acceptées : PSA, BGS, CGC, SGC, TAG, PCA, ARS) → unknown_grader.
• Note invalide : un nombre entre 0 et 10 est attendu → bad_grade.

Le détail par statut figure plus bas (« Statuts par carte »). Un mail de bilan vous est aussi envoyé après chaque import.

Format de réponse

Toutes les réponses sont en JSON. Succès : un champ ok: true + des données. Erreur : un champ error (code court, ex. unauthorized) et éventuellement message (texte plus parlant). Les dates sont au format ISO 8601 (ex. 2026-06-09T17:30:00+00:00).

Sécurité du token

Le token donne un accès complet en votre nom à l'API. Traitez-le comme un mot de passe.

• Stockez-le dans un gestionnaire de secrets (1Password, AWS Secrets Manager, Vault…) ou une variable d'environnement. Jamais dans le code source ni dans un repo Git.
• Ne le partagez jamais en clair par email ou messagerie.
• S'il est compromis : révoquez-le immédiatement depuis cet onglet, puis générez-en un nouveau. La révocation est instantanée et irréversible.
• Bonne pratique : utilisez un token par environnement (un pour la prod, un pour la recette, etc.) avec un nom explicite.

Idempotence

Si votre script échoue (timeout réseau, crash en plein batch), vous pouvez retenter le même appel POST /cards sans risque de duplication. Les cartes déjà créées renverront simplement duplicate_own dans results, au lieu d'être ré-enregistrées. Vous pouvez donc coder du retry automatique côté client sans crainte. La règle : une carte est identifiée de façon unique par votre reseller_id et son cert_number.

POST /cards — enregistrer 1 ou N cartes

curl -X POST https://card-seal.com/api/v1/cards \
  -H "Authorization: Bearer cs_live_pk_XXXX..." \
  -H "Content-Type: application/json" \
  -d '{
    "cards": [
      {
        "cert_number": "125864354",
        "grading_company": "PSA",
        "grade": "10",
        "owner_ref": "JD-2026-0042",
        "card_name": "Dracaufeu ex",
        "card_set": "Mew FR",
        "card_number": "199",
        "card_year": "2026"
      }
    ]
  }'

Champs obligatoires : cert_number, grading_company, owner_ref. Les autres sont optionnels mais recommandés. Limite : 5000 cartes par requête. Au-delà, splitter en plusieurs appels. En pratique, l'enregistrement tient ~50 à 100 cartes par seconde côté serveur (variable selon l'enrichissement PSA disponible en cache).

Réponse : un statut par carte (created, duplicate_own, duplicate_own_deleted, owner_already_active, pending_review, missing_fields, bad_owner_ref). Le code d'activation est renvoyé pour chaque nouvelle référence propriétaire.

Exemple de réponse :

{
  "ok": true,
  "results": [
    {
      "cert_number": "125864354",
      "status": "created",
      "owner_ref": "JD-2026-0042",
      "activation_code": "ABCDEFGH",
      "invite_url": "https://card-seal.com/c/ABCDEFGH?k=..."
    }
  ]
}

invite_url est le lien d'activation prêt à transmettre à votre client (par email, WhatsApp, QR code en live, etc.). Le client clique, atterrit sur l'activation pré-remplie, choisit pseudo + mot de passe. CardSeal ne vous demande aucun email à l'émission. Une fois activé, invite_url repasse à null sur les endpoints GET (le lien est consommé).

GET /cards — lister vos cartes

curl "https://card-seal.com/api/v1/cards?limit=100&offset=0" \
  -H "Authorization: Bearer cs_live_pk_XXXX..."

Filtres optionnels : ?owner_ref=JD-2026-0042 pour ne récupérer que les cartes d'un client, ?status=ok ou ?status=duplicate ou ?status=deleted pour filtrer par statut. Les filtres se combinent.

Exemple de réponse :

{
  "ok": true,
  "cards": [
    {
      "id": "uuid",
      "cert_number": "125864354",
      "grading_company": "PSA",
      "grade": "10",
      "grade_label": "GEM MT 10",
      "owner_ref": "JD-2026-0042",
      "status": "ok",
      "card_name": "Dracaufeu ex",
      "card_set": "Mew FR",
      "card_number": "199",
      "card_year": "2026",
      "image_url": "https://...",
      "imported_at": "2026-06-09T17:30:00+00:00"
    }
  ],
  "total": 42,
  "limit": 100,
  "offset": 0,
  "filters": { "owner_ref": "JD-2026-0042", "status": null }
}

GET /cards/{cert_number} — détail

curl https://card-seal.com/api/v1/cards/125864354 \
  -H "Authorization: Bearer cs_live_pk_XXXX..."

GET /clients — vos références propriétaires

curl https://card-seal.com/api/v1/clients \
  -H "Authorization: Bearer cs_live_pk_XXXX..."

Retourne pour chaque référence : invite_url (lien d'activation à transmettre tant que claimed_at = null), owner_email_at_claim (email enregistré par le client une fois activé, pour rapprochement avec votre CRM), statut, nombre de régénérations utilisées, nombre de cartes liées.

Exemple de réponse :

{
  "ok": true,
  "clients": [
    {
      "owner_ref": "JD-2026-0042",
      "code": "ABCDEFGH",
      "invite_url": "https://card-seal.com/c/ABCDEFGH?k=...",
      "claimed_at": null,
      "owner_email_at_claim": null,
      "regenerations_count": 0,
      "card_count": 3
    },
    {
      "owner_ref": "JD-2026-0041",
      "code": "ZYXW9876",
      "invite_url": null,
      "claimed_at": "2026-06-08T14:22:18+00:00",
      "owner_email_at_claim": "client@example.com",
      "regenerations_count": 0,
      "card_count": 1
    }
  ]
}

GET /clients/{owner_ref} — détail d'une référence

curl https://card-seal.com/api/v1/clients/JD-2026-0042 \
  -H "Authorization: Bearer cs_live_pk_XXXX..."

Retourne la référence propriétaire (invite_url, owner_email_at_claim, statut, régénérations) + la liste des cartes liées à cette référence (cert_number, grading_company, grade, status, card_name).

Exemple de réponse :

{
  "ok": true,
  "client": {
    "owner_ref": "JD-2026-0042",
    "code": "ABCDEFGH",
    "invite_url": "https://card-seal.com/c/ABCDEFGH?k=...",
    "claimed_at": null,
    "owner_email_at_claim": null,
    "regenerations_count": 0
  },
  "cards": [
    {
      "cert_number": "125864354",
      "grading_company": "PSA",
      "grade": "10",
      "status": "ok",
      "card_name": "Dracaufeu ex"
    }
  ]
}

claimed_at est null tant que le client n'a pas activé son espace. Une fois activé : claimed_at contient la date ISO 8601, invite_url repasse à null (lien consommé), et owner_email_at_claim contient l'email du compte créé (rapprochement CRM côté partenaire).

GET /clients/{owner_ref}/invitation-email : email prêt à envoyer

curl https://card-seal.com/api/v1/clients/JD-2026-0042/invitation-email \
  -H "Authorization: Bearer cs_live_pk_xxx"

{
  "ok": true,
  "owner_ref": "JD-2026-0042",
  "card_count": 3,
  "activation_url": "https://card-seal.com/c/ABCDEFGH?k=...",
  "subject": "Votre boutique vous offre la traçabilité de vos cartes",
  "body_text": "Bonjour,\n\nChez ...",
  "body_html": "<p>Bonjour,</p>...",
  "variables": {
    "nom_partenaire": "Votre boutique",
    "nombre_cartes": 3,
    "lien_activation": "https://card-seal.com/c/ABCDEFGH?k=..."
  }
}

Renvoie l'email d'invitation prêt à envoyer à ce client, variables déjà remplies (nom du partenaire, nombre de cartes, lien d'activation) : subject, body_text, body_html, plus variables si vous préférez gérer votre propre gabarit. Refus si la référence est introuvable (404) ou si le client a déjà activé (409 already_activated). CardSeal n'envoie rien : c'est à vous d'envoyer l'email à votre client.

POST /clients/{owner_ref}/regenerate-code

curl -X POST https://card-seal.com/api/v1/clients/JD-2026-0042/regenerate-code \
  -H "Authorization: Bearer cs_live_pk_XXXX..."

Régénère un nouveau code + nouveau secret HMAC, donc un nouveau invite_url complet. L'ancien lien devient invalide immédiatement. Limite : 1 régénération maximum. Refus si le lien a déjà été consommé par un compte collectionneur (409 already_activated) ou si la limite est atteinte (429 limit_reached).

Exemple de réponse :

{
  "ok": true,
  "new_code": "WXYZ1234",
  "invite_url": "https://card-seal.com/c/WXYZ1234?k=...",
  "regenerations_count": 1
}

GET /me — vérifier votre identité

curl https://card-seal.com/api/v1/me \
  -H "Authorization: Bearer cs_live_pk_XXXX..."

Retourne l'identité du partenaire associé à votre token, et les méta-données du token utilisé. Utile pour valider qu'un token est actif et savoir à quel compte il est rattaché.

Exemple de réponse :

{
  "ok": true,
  "partner": {
    "id": "uuid",
    "slug": "pokeloutre",
    "name": "PokéLoutre",
    "prefix": "PL",
    "admin_login": "pokeloutre"
  },
  "token": {
    "prefix": "cs_live_pk_AbCdEfGh",
    "name": "backend prod",
    "created_at": "2026-06-09T10:00:00+00:00",
    "last_used_at": "2026-06-09T17:30:00+00:00"
  }
}

GET /openapi.json — spec OpenAPI 3.0

Téléchargez la spec OpenAPI complète et importez-la dans Postman, Stoplight ou tout générateur de SDK. Auth Bearer requise (spec privée).

Codes d'erreur

400 invalid_payload	Body JSON malformé ou impossible à parser
400 missing_cards	Champ cards absent ou liste vide (POST /cards)
400 missing_fields	Champs obligatoires manquants sur une carte (par-carte dans results)
400 too_many_cards	Plus de 5000 cartes en une requête
401 unauthorized	Token absent, invalide ou révoqué
404 not_found	Ressource introuvable
405 method_disabled	PATCH ou DELETE désactivés sur l'API (passez par l'espace partenaire)
405 method_not_allowed	Méthode HTTP non supportée pour cette ressource
409 already_activated	Le code d'activation a déjà été consommé par un compte (régénération impossible)
429 limit_reached	Limite de régénération de code atteinte (1/1)

Statuts par carte (POST /cards)

La réponse contient un tableau results avec un statut par carte envoyée :

created	Carte enregistrée. Champs activation_code et invite_url renvoyés si nouvelle référence propriétaire (sinon : référence déjà existante, code et lien existants côté GET /clients).
duplicate_own	Vous aviez déjà ce cert_number. Non ré-enregistrée.
duplicate_own_deleted	Vous aviez supprimé ce cert_number. La re-saisie n'est pas autorisée par l'API : contactez hello@card-seal.com.
owner_already_active	Ce owner_ref est déjà rattaché à un collectionneur. Pour ajouter une carte à son compte, contactez hello@card-seal.com.
pending_review	Carte en cours de vérification par les équipes CardSeal. Vous serez informé sous quelques jours.
bad_owner_ref	owner_ref mal formé. Format attendu : 1 à 32 caractères ASCII parmi [A-Za-z0-9_-].
missing_fields	Au moins un des trois champs obligatoires (cert_number, grading_company, owner_ref) manque sur cette carte.
unknown_grader	Société de gradation non référencée. Valeurs acceptées : PSA, BGS, CGC, SGC, TAG, PCA, ARS. La carte n'est pas enregistrée.
bad_grade	Note invalide : un nombre entre 0 et 10 est attendu. La carte n'est pas enregistrée.