API plateformes

Trois appels : déclarer un vendeur, envoyer ses ventes du mois, récupérer le relevé. On vérifie ses inscriptions dans les registres officiels, on calcule ses éco-contributions emballages pays par pays et on vous dit qui les paie.

Sans intégration, les mêmes opérations se font par fichier dans l'espace plateforme.

Authentification

Chaque appel porte votre clé dans l'en-tête x-api-key (ou Authorization: Bearer). La clé se crée dans Mon espace, avec la formule Scale ou un contrat plateforme. Ce site tourne en démonstration : la clé rr_demo fonctionne.

600 appels par minute au plus. Les réponses sont en JSON, les montants en euros hors taxes.

1. Déclarer un vendeur

POST /api/v1/sellers

À chaque nouveau vendeur, et à chaque changement. Renvoyer un vendeur existant met à jour les champs envoyés. Pour une société française, le SIREN ou le numéro de TVA suffit : on trouve ses identifiants uniques dans la liste officielle de l'ADEME, sans rien lui demander.

`external_id`	Obligatoire. L'identifiant du vendeur chez vous.
`name`	Obligatoire à la création. Raison sociale.
`establishment`	Obligatoire à la création. Pays du siège, code à deux lettres : FR, DE, CN, TR, GB, US…
`countries`	Pays de l'UE où il livre des particuliers. Ses ventes complètent la liste ensuite.
`filieres`	pkg (emballages), eee (électronique), bat (piles et batteries), tlc (textile et chaussures), toy (jouets), amb (ameublement), asl (sport et loisirs), abj (bricolage et jardin), chem (produits chimiques). Les emballages sont toujours inclus.
`mode`	`own` : il gère ses inscriptions, on les vérifie. `covered` : on fait tout à sa place (mandataire, inscriptions, déclarations, paiement).
`vat, siren`	Facultatifs. Servent à retrouver ses inscriptions dans les registres.
`registrations`	Facultatif. Numéros qu'il vous a donnés : `[{"country", "filiere", "number"}]`.

curl -X POST https://votre-domaine/api/v1/sellers \
  -H "x-api-key: rr_demo" -H "Content-Type: application/json" \
  -d '{"external_id":"V-2002","name":"Shenzhen Example Trading","establishment":"CN","countries":["FR","DE","ES"],"filieres":["pkg","eee"],"mode":"covered"}'

Réponse : la fiche du vendeur et son statut pays par pays. coverage vaut covered (pris en charge), verified (trouvé dans le registre officiel), declared (numéro fourni, pas de registre public à interroger), missing (inscription non prouvée) ou future (pas encore obligatoire).

Exemple de réponse

{
  "id": "dfc3df9c-95cf-479a-90e3-2d81013bc7a4",
  "external_id": "V-2002",
  "name": "Shenzhen Example Trading",
  "establishment": "CN",
  "vat": null,
  "siren": null,
  "countries": [
    "FR",
    "DE",
    "ES"
  ],
  "filieres": [
    "pkg",
    "eee"
  ],
  "mode": "covered",
  "registrations": [],
  "created_at": "2026-11-10T11:55:03.552Z",
  "updated_at": "2026-11-10T11:55:03.552Z",
  "status": {
    "compliant": true,
    "missing": 0,
    "cells": [
      {
        "country": "FR",
        "filiere": "pkg",
        "coverage": "covered",
        "number": null,
        "ar_required": true,
        "registry": "SYDEREP (ADEME)",
        "note": "Inscription, mandataire, déclarations et paiement pris en charge."
      },
      {
        "country": "FR",
        "filiere": "eee",
        "coverage": "covered",
        "number": null,
        "ar_required": true,
        "registry": "SYDEREP (ADEME)",
        "note": "Inscription, mandataire, déclarations et paiement pris en charge."
      },
      {
        "country": "DE",
        "filiere": "pkg",
        "coverage": "covered",
        "number": null,
        "ar_required": true,
        "registry": "LUCID (registre des emballages)",
        "note": "Inscription, mandataire, déclarations et paiement pris en charge."
      },
      {
        "country": "DE",
        "filiere": "eee",
        "coverage": "covered",
        "number": null,
        "ar_required": true,
        "registry": "stiftung ear (registre EAR)",
        "note": "Inscription, mandataire, déclarations et paiement pris en charge."
      },
      {
        "country": "ES",
        "filiere": "pkg",
        "coverage": "covered",
        "number": null,
        "ar_required": true,
        "registry": "Registro de Productores de Producto",
        "note": "Inscription, mandataire, déclarations et paiement pris en charge."
      },
      {
        "country": "ES",
        "filiere": "eee",
        "coverage": "covered",
        "number": null,
        "ar_required": true,
        "registry": "RII-AEE",
        "note": "Inscription, mandataire, déclarations et paiement pris en charge."
      }
    ]
  },
  "discovered": 0,
  "warnings": []
}

Jusqu'à 500 vendeurs par appel avec {"sellers": [...]}. ?verify=false évite l'interrogation des registres. GET /api/v1/sellers?external_id=… relit un vendeur ; GET /api/v1/sellers?limit=100&offset=0 liste vos vendeurs avec leur résumé de conformité.

2. Envoyer les ventes du mois

POST /api/v1/fees

Une fois par mois et par vendeur : ses colis, pays par pays et matériau par matériau. Renvoyer le même mois remplace les chiffres précédents. Matériaux : paper (papier-carton), plastic (plastique), glass (verre), steel (acier), aluminium (aluminium), wood (bois), other (autre).

curl -X POST https://votre-domaine/api/v1/fees \
  -H "x-api-key: rr_demo" -H "Content-Type: application/json" \
  -d '{"period":"2026-11","seller":"V-2002","lines":[{"country":"FR","material":"paper","weight_g":310,"quantity":1200},{"country":"FR","material":"plastic","weight_g":40,"quantity":1200},{"country":"DE","material":"paper","weight_g":310,"quantity":900}]}'

Pour chaque ligne, la réponse dit qui paie :

service : vendeur pris en charge. On déclare et on paie ; vous retenez le montant sur son prochain versement.
platform : vendeur sans inscription prouvée en France. La loi vous rend redevable à sa place (art. L. 541-10-9 du Code de l'environnement) : retenez le montant, ou passez-le en prise en charge.
seller : vendeur inscrit, il paie lui-même. S'il n'a pas prouvé son inscription ailleurs, action vaut block_listing (Allemagne : ne pas le laisser vendre) ou collect_number (obtenir son numéro).

withhold_eur est le total à retenir. ?dry_run=true calcule sans enregistrer.

Exemple de réponse

{
  "period": "2026-11",
  "seller": {
    "external_id": "V-2002",
    "mode": "covered",
    "compliant": true
  },
  "currency": "EUR",
  "total_eur": 213.32,
  "withhold_eur": 213.32,
  "lines": [
    {
      "country": "FR",
      "material": "paper",
      "weight_g": 310,
      "quantity": 1200,
      "weight_kg": 372,
      "fee_eur": 96.01,
      "scheme": "Citeo",
      "tariff_ref": "Citeo 2026",
      "indicative": false,
      "payer": "service",
      "withhold": true,
      "action": null
    },
    {
      "country": "FR",
      "material": "plastic",
      "weight_g": 40,
      "quantity": 1200,
      "weight_kg": 48,
      "fee_eur": 36.96,
      "scheme": "Citeo",
      "tariff_ref": "Citeo 2026",
      "indicative": false,
      "payer": "service",
      "withhold": true,
      "action": null
    },
    {
      "country": "DE",
      "material": "paper",
      "weight_g": 310,
      "quantity": 900,
      "weight_kg": 279,
      "fee_eur": 80.35,
      "scheme": "Système dual (prix indicatif)",
      "tariff_ref": "Système dual (prix indicatif) 2026",
      "indicative": true,
      "payer": "service",
      "withhold": true,
      "action": null
    }
  ],
  "by_country": [
    {
      "country": "FR",
      "scheme": "Citeo",
      "weight_kg": 420,
      "fee_eur": 132.97
    },
    {
      "country": "DE",
      "scheme": "Système dual (prix indicatif)",
      "weight_kg": 279,
      "fee_eur": 80.35
    }
  ],
  "missing_tariffs": [],
  "new_countries": [],
  "stored_lines": 3,
  "dry_run": false,
  "errors": []
}

Variante fichier : Content-Type: text/csv et ?period=2026-11, colonnes seller;country;material;weight_g;quantity, plusieurs vendeurs dans le même fichier.

3. Récupérer le relevé

GET /api/v1/statements?period=2026-11

Le montant retenu par vendeur et le montant à reverser à chaque éco-organisme, pays par pays. &format=csv pour un fichier tableur.

Exemple de réponse

{
  "period": "2026-11",
  "currency": "EUR",
  "total_withheld_eur": 213.32,
  "by_payer": {
    "service": 213.32,
    "platform": 0
  },
  "payer_labels": {
    "service": "Pris en charge : nous déclarons et payons",
    "platform": "Plateforme redevable à la place du vendeur"
  },
  "by_scheme": [
    {
      "country": "FR",
      "scheme": "Citeo",
      "payer": "service",
      "weight_kg": 420,
      "fee_eur": 132.97,
      "lines": 2
    },
    {
      "country": "DE",
      "scheme": "Système dual (prix indicatif)",
      "payer": "service",
      "weight_kg": 279,
      "fee_eur": 80.35,
      "lines": 1
    }
  ],
  "by_seller": [
    {
      "external_id": "V-2002",
      "name": "Shenzhen Example Trading",
      "mode": "covered",
      "weight_kg": 699,
      "fee_eur": 213.32
    }
  ],
  "missing_tariffs": [],
  "sellers": 1,
  "covered_sellers": 1,
  "generated_at": "2026-11-10T11:55:03.574Z"
}

Erreurs

Une erreur renvoie {"error": {"code", "message", "details"}}.

`400 invalid_json`	Corps illisible.
`401 missing_key, invalid_key`	Clé absente, inconnue ou révoquée.
`403 plan_required`	Votre formule n'inclut pas l'API.
`404 not_found`	Vendeur inconnu : déclarez-le d'abord.
`413 too_many`	Trop de vendeurs ou de lignes dans un appel.
`422 invalid_…`	Champ manquant ou mal formé ; le détail est dans details.
`429 rate_limited`	Trop d'appels en une minute.

Vérification ponctuelle

Sans compte, pour tester : GET https://votre-domaine/api/check?q=NomDuVendeur&site=boutique.fr&pays=DE,ES. Pour une liste : POST https://votre-domaine/api/bulk avec un fichier, voir la page marketplaces.