API Rectofil v1

Lecture des ventes d'un compte Rectofil par une application tierce.

URL de base	`https://rectofil.com/api/v1`
Format	JSON, UTF-8
Authentification	clé d'accès, en-tête `Authorization: Bearer`
Accès	lecture seule, ventes du compte titulaire de la clé

Sommaire

Authentification
Lister les ventes
Objet Sale
Pagination
Synchronisation
Erreurs
Limites
Versions

1. Authentification

Chaque requête porte une clé d'accès dans l'en-tête Authorization :

Authorization: Bearer rf_<43 caractères>

Propriété	Valeur
Format	préfixe `rf_` suivi de 43 caractères base64url (46 au total)
Émission	par le titulaire du compte, dans Rectofil : Réglages > Mon compte > Accès pour une autre application
Affichage	une seule fois, à la création. Rectofil n'en conserve que l'empreinte
Portée	lecture des ventes du compte émetteur, rien d'autre
Révocation	à tout moment par le titulaire ; effet immédiat (réponse `401`)
Nombre	5 clés actives au plus par compte

La clé doit rester côté serveur et être stockée chiffrée. Elle n'est jamais acceptée en paramètre d'URL.

2. Lister les ventes

GET /api/v1/sales

Renvoie les ventes du compte, triées par date de vente croissante (sold_at, puis id).

Paramètres de requête

Nom	Type	Requis	Défaut	Description
`since`	date ISO 8601	non		Ventes à partir de cet instant, inclus
`until`	date ISO 8601	non		Ventes avant cet instant, exclu
`limit`	entier	non	`100`	Nombre de ventes par page, de `1` à `500`
`cursor`	chaîne	non		Valeur `next_cursor` de la page précédente

Formats de date acceptés : date seule, 2026-10-01 (minuit UTC), ou date et heure avec fuseau, 2026-10-01T08:00:00Z ou 2026-10-01T10:00:00+02:00.

Exemple

curl "https://rectofil.com/api/v1/sales?since=2026-10-01&limit=200" \
  -H "Authorization: Bearer rf_..."

Réponse `200 OK`

{
  "sales": [
    {
      "id": "sal_gscbzssstrgd",
      "sold_at": "2026-10-01T10:00:00Z",
      "platform": "vinted",
      "title": "L’Étranger",
      "authors": "Albert Camus",
      "isbn": "9782070360024",
      "quantity": 1,
      "price_cents": 1200,
      "currency": "EUR"
    }
  ],
  "next_cursor": null
}

Champ	Type	Description
`sales`	tableau de Sale	Ventes de la page
`next_cursor`	chaîne ou `null`	Curseur de la page suivante ; `null` sur la dernière page

En-tête de réponse : Cache-Control: no-store.

3. Objet Sale

Champ	Type	Description
`id`	chaîne	Identifiant unique et stable de la vente
`sold_at`	date ISO 8601, UTC	Date et heure de la vente
`platform`	chaîne	Plateforme de la vente : `vinted`, `leboncoin`, `bookvillage`
`title`	chaîne	Titre du livre
`authors`	chaîne	Auteurs, séparés par des virgules ; chaîne vide si inconnus
`isbn`	chaîne ou `null`	ISBN-13 ; `null` si inconnu
`quantity`	entier	Nombre d'exemplaires vendus
`price_cents`	entier	Prix payé par l'acheteur pour l'article, hors frais de port, en centimes
`currency`	chaîne	Code devise ISO 4217 (`EUR`)

Aucune donnée relative à l'acheteur n'est exposée.

4. Pagination

Pagination par curseur. Pour lire l'ensemble des résultats, répéter la requête avec cursor égal au next_cursor reçu, en conservant les mêmes since, until et limit, jusqu'à obtenir next_cursor: null.

Le curseur est opaque : ne pas l'interpréter ni le construire.

5. Synchronisation

Une vente peut être corrigée ou supprimée (doublon) après sa création. Méthode recommandée :

Lire la fenêtre des 30 derniers jours (since = date du jour moins 30 jours), toutes pages comprises.
Insérer ou mettre à jour chaque vente par id.
Supprimer de votre côté les ventes de la fenêtre absentes de la réponse.

6. Erreurs

Corps d'erreur :

{ "error": "Clé d’accès absente, invalide ou révoquée." }

Le message est destiné à un humain, en français ; ne pas le parser. Se fonder sur le code HTTP.

Code	Signification	Conduite
`400`	Paramètre invalide (date, `limit`, curseur)	Corriger la requête
`401`	Clé absente, invalide ou révoquée. En-tête `WWW-Authenticate: Bearer`	Demander une nouvelle clé au titulaire ; ne pas réessayer
`429`	Limite de débit atteinte. En-tête `Retry-After` en secondes	Attendre la durée indiquée
`5xx`	Erreur du service	Réessayer plus tard avec un délai croissant

7. Limites

Limite	Valeur
Requêtes par clé	120 par minute
Requêtes avec une clé invalide, par adresse IP	30 par minute, puis `429`
Taille de page	500 ventes

8. Versions

La version figure dans le chemin (/api/v1). Dans une même version, des champs peuvent être ajoutés aux réponses et de nouvelles valeurs peuvent apparaître dans platform : le client doit ignorer les champs inconnus et tolérer les valeurs inconnues. Toute modification incompatible fera l'objet d'une nouvelle version.