# Documentation complète Orbit API

Orbit publie actuellement 69 758 centres d’intérêt dans six catégories. Cette valeur provient du dernier catalogue de production vérifié.

Cette ressource regroupe la documentation publique destinée aux outils et agents. Le document OpenAPI reste la vérité lisible par machine du contrat HTTP : https://orbit-data-api.com/openapi.json

# Contrat API v1

URL canonique : https://orbit-data-api.com/docs/api-contract

Le document courant décrit la version candidate `1.0.0-rc.3` du dépôt. Les routes de recherche et de résolution ainsi que le socle de comptage mensuel sont déployés sur `orbit-dev` et `orbit-prod`. Les en-têtes mensuels apparaissent uniquement sur les accès libre-service Gratuit ou Pro ; ils restent absents des accès historiques ou complémentaires non mesurés. Le préfixe HTTP reste `/v1` : la version du document peut progresser sans changer les routes ni les UUID Orbit. `orbit-dev` demeure la cible d’intégration par défaut et chaque environnement utilise ses propres clés.

## Routes canoniques

```text
GET  /v1/interests/search
POST /v1/interests/resolve
```

La cible d’intégration par défaut de cette version est `orbit-dev` : `https://anvhjdjxovzjnvpmjtkl.supabase.co/functions/v1/api`. Dans cette URL, `/functions/v1` appartient à la passerelle Edge Functions, `api` nomme la fonction canonique et le `/v1` ajouté par les routes ci-dessus versionne le contrat Orbit. La production reste documentée à `https://jsmxzmxgxwexgvaraeke.supabase.co/functions/v1/api`, mais elle utilise un paquet de clés distinct remis seulement après validation du passage en production.

## Authentification

Chaque requête canonique envoie une unique clé Orbit du même environnement, dotée des permissions nécessaires, dans `Authorization: Bearer <ORBIT_API_KEY>`. Elle est strictement serveur-à-serveur, révocable, renouvelable et soumise à des quotas minute/jour. Une limite dépassée produit `429` et `Retry-After`.

Orbit remet cette clé pendant l’intégration du client. Un consommateur n’a pas besoin d’accéder au tableau de bord Supabase et ne doit jamais substituer une clé Supabase publiable, secrète ou `service_role`. Consultez le [guide d’authentification](/docs/authentication).

Chaque réponse métier renvoie aussi un `X-Request-Id` généré par Orbit. Le preflight CORS peut être traité directement par la passerelle Supabase sans cet en-tête. Communiquez uniquement l’identifiant d’une réponse métier lors d’un diagnostic ; il permet de corréler les journaux sans partager une clé ou le contenu de la requête.

## Ressources

- [Référence OpenAPI en lecture seule](/reference)
- [Document OpenAPI 3.1](/openapi.json)
- [Résumé pour outils et agents](/llms.txt)

## Compatibilité

Dans Orbit v1, les champs requis, les types, les états de résolution, les catégories et les limites ne sont pas retirés ou modifiés de façon incompatible. Les champs de réponse optionnels peuvent évoluer et les clients doivent ignorer ceux qu’ils ne connaissent pas.

Le classement de recherche peut évoluer : il ne constitue ni une pagination, ni une garantie d’ordre stable. Les routes de lecture sont réessayables sans effet de bord, mais les clients doivent respecter `Retry-After` et borner leurs tentatives.

La version générale `1.0.0` reste conditionnée à la publication d’un canal d’assistance, des conditions applicables et de l’origine API durable approuvés. Jusqu’à cette publication, la version candidate n’est accessible qu’aux clients explicitement intégrés par Orbit.

---

# Authentification serveur

URL canonique : https://orbit-data-api.com/docs/authentication

## Une seule clé côté serveur

Chaque requête canonique utilise une clé Orbit propre à l’environnement ciblé :

```http
Authorization: Bearer <ORBIT_ENVIRONMENT_API_KEY>
```

Cette clé identifie l’accès commercial, ses permissions et ses quotas. Le client ne reçoit aucune clé de projet Supabase : cette infrastructure reste un détail interne à Orbit.

Ne placez jamais `ORBIT_API_KEY` dans un navigateur, une application mobile ou de bureau, une variable `NEXT_PUBLIC_*`, un dépôt, une URL ou des journaux. N’utilisez jamais de clé Supabase publiable, secrète ou `service_role` comme clé Orbit.

La [référence OpenAPI](/reference) est volontairement en lecture seule : sa copie rendue omet les schémas d’authentification et désactive les contrôles d’essai et de client. Le document complet lisible par machine reste disponible sur [`/openapi.json`](/openapi.json). Ne saisissez un identifiant secret Orbit dans aucune page web, y compris la documentation Orbit.

## Intégration initiale

Le parcours commercial a été validé sur une Preview contre `orbit-dev`, avec
des comptes confirmés créés par l’opérateur. L’inscription publique reste
fermée. Sur un accès de validation, la clé est révélée une seule fois dans le
portail et un test Pro via Stripe ne la remplace pas : il modifie seulement le
droit et les quotas du même accès. En production, l’intégration reste réservée
aux clients approuvés et Orbit fournit par canal sécurisé :

- l’environnement et son URL de base ;
- une clé Orbit révélée une seule fois ;
- les permissions autorisées, actuellement `interests:read` ;
- les quotas minute et jour ;
- la date d’expiration éventuelle et la procédure de rotation.

Le client confirme ensuite un appel authentifié sur `orbit-dev` et conserve le `X-Request-Id` de ce test de bon fonctionnement. Les clés de production sont distinctes et ne doivent être installées qu’après validation de l’intégration de développement.

## Stockage recommandé

Stockez les valeurs dans un gestionnaire de secrets côté serveur et injectez-les à l’exécution :

```text
ORBIT_BASE_URL
ORBIT_API_KEY
```

Limitez l’accès au seul service appelant Orbit. Masquez les valeurs dans les outils CI, interdisez leur affichage dans les erreurs et ne journalisez jamais les en-têtes de requête.

## Rotation et révocation

Un renouvellement utilise une courte période de chevauchement : installez la nouvelle clé, vérifiez-la côté serveur, puis révoquez l’ancienne. En cas de suspicion de fuite, cessez de l’utiliser et demandez sa révocation sans joindre la valeur compromise à un message ou une capture.

Une clé révoquée, expirée, suspendue ou mal formée reçoit `401`. Une clé valide sans la permission demandée reçoit `403`.

## Contraintes d’intégration

Les applications publiques appellent leur propre backend, qui appelle ensuite Orbit. CORS n’est pas une frontière de sécurité et ne transforme jamais une clé embarquée dans un client en secret.

Continuez avec le [démarrage rapide](/docs/quickstart) ou les [erreurs et nouvelles tentatives](/docs/errors-and-retries).

---

# Erreurs, quotas et nouvelles tentatives

URL canonique : https://orbit-data-api.com/docs/errors-and-retries

## Enveloppe d’erreur

Les erreurs produites par Orbit utilisent une enveloppe stable :

```json
{
  "error": {
    "code": "invalid_category",
    "message": "Le paramètre category doit valoir games, movies, anime, series, music ou books.",
    "requestId": "00000000-0000-0000-0000-000000000000"
  }
}
```

Conservez `X-Request-Id` ou `error.requestId` pour le diagnostic. Ne transmettez jamais une clé, un en-tête complet, une URL avec des paramètres sensibles ou le corps de la requête.

## Statuts et codes

| HTTP | Codes possibles | Action client |
|---:|---|---|
| `400` | `invalid_query`, `invalid_category`, `invalid_limit`, `invalid_json`, `invalid_ids` | Corriger la requête, sans nouvelle tentative automatique. |
| `401` | `missing_orbit_api_key`, `invalid_orbit_api_key` | Vérifier l’environnement et la clé Orbit, sans nouvelle tentative automatique. |
| `403` | `insufficient_scope` | Demander la permission requise, sans nouvelle tentative automatique. |
| `404` | `route_not_found` | Corriger la route. Un UUID inconnu reste un résultat `200/not_found`. |
| `405` | `method_not_allowed` | Utiliser la méthode indiquée par `Allow`. |
| `413` | `payload_too_large` | Réduire le corps à 32 KiB maximum. |
| `415` | `unsupported_media_type` | Envoyer `Content-Type: application/json`. |
| `429` | `rate_limit_exceeded`, `monthly_quota_exceeded` | Attendre la durée de `Retry-After`, puis réessayer. |
| `500` | `internal_error` | Réessayer avec une attente exponentielle bornée. |
| `503` | `environment_unavailable`, `authentication_unavailable`, `usage_metering_unavailable`, `catalog_unavailable` | Réessayer avec une attente exponentielle bornée. |

## Quotas

Chaque réponse authentifiée expose les limites minute et jour UTC :

```text
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
X-Orbit-Daily-RateLimit-Limit
X-Orbit-Daily-RateLimit-Remaining
X-Orbit-Daily-RateLimit-Reset
```

Les valeurs `Reset` sont des horodatages Unix en secondes. Une requête authentifiée consomme son quota avant la validation de la route ou du corps. Les clés absentes, invalides, expirées, révoquées, suspendues ou sans permission ne consomment pas de quota.

## Politique de nouvelle tentative

`GET /search` et `POST /resolve` sont des lectures réessayables sans effet de bord. Appliquez ces règles :

1. Ne réessayez jamais automatiquement un `400`, `401`, `403`, `404`, `405`, `413` ou `415`.
2. Pour `429`, attendez au minimum `Retry-After` secondes.
3. Pour `500`, `503`, une erreur réseau ou un délai dépassé, utilisez une attente exponentielle avec une petite variation aléatoire.
4. Bornez le nombre de tentatives et le temps total selon le budget de latence de votre service.
5. Ne lancez pas de nouvelles tentatives parallèles et ne contournez jamais un quota avec plusieurs clés.

Exemple de délais avant variation aléatoire : `250 ms`, `500 ms`, puis `1 s`. Cette recommandation client ne constitue pas un engagement de service.

---

# Documentation développeur

URL canonique : https://orbit-data-api.com/docs

Orbit API fournit aux applications un catalogue normalisé de **69 758 centres d’intérêt actifs** dans six catégories : jeux vidéo, films, anime et manga, séries, musique et livres.

Deux opérations composent la v1 : rechercher un concept publié et résoudre le cycle de vie d’un UUID déjà stocké. Le catalogue interne, les arbitrages et la provenance détaillée ne sont jamais exposés directement.

## Choisissez votre parcours

- **Première intégration** : suivez [le quickstart en cinq minutes](/docs/quickstart).
- **Architecture sûre** : choisissez un guide [Next.js](/docs/guides/nextjs-vercel), [Supabase Edge Functions](/docs/guides/supabase-edge-functions), [Expo](/docs/guides/expo-backend-securise), [Cloudflare Workers](/docs/guides/cloudflare-workers) ou [Python](/docs/guides/python).
- **Modèle de données** : découvrez [les catégories](/docs/concepts/catalogue-et-categories) et [les UUID stables](/docs/concepts/identifiants-stables).
- **Production** : consultez [l’authentification serveur](/docs/authentication), [les quotas](/docs/compte-et-securite/quotas) et [la sécurité](/docs/compte-et-securite/securite).
- **Contrat exact** : ouvrez la [référence API v1](/docs/reference-v1) ou le [document OpenAPI](/openapi.json).

## Le contrat public minimal

```ts
type OrbitInterest = {
  id: string;
  label: string;
  category: "games" | "movies" | "anime" | "series" | "music" | "books";
};
```

Persistez l’UUID comme identité. Le libellé et la catégorie peuvent être conservés comme instantané d’affichage, puis rafraîchis avec `resolve` lorsqu’un changement pertinent survient.

## Sécurité en une phrase

La clé Orbit est un secret strictement **serveur-à-serveur**. Elle ne doit jamais apparaître dans un navigateur, une application mobile, une variable `NEXT_PUBLIC_*` ou `EXPO_PUBLIC_*`, une URL ou des journaux.

Commencez par [obtenir un accès](/docs/bien-demarrer/obtenir-un-acces), puis effectuez [votre première requête](/docs/quickstart).

---

# Démarrage rapide

URL canonique : https://orbit-data-api.com/docs/quickstart

## Prérequis

Orbit remet à chaque client approuvé un paquet propre à un environnement : URL de base, clé Orbit, permission et quotas. En production, cette version candidate ne propose encore ni inscription, ni création d’accès, ni paiement en libre-service. Ce démarrage rapide cible `orbit-dev`, l’environnement d’intégration de la version candidate. Ne mélangez jamais les clés de développement et de production.

```bash
export ORBIT_BASE_URL="https://anvhjdjxovzjnvpmjtkl.supabase.co/functions/v1/api"
export ORBIT_API_KEY="votre-cle-orbit-dev"
```

La clé Orbit est un secret serveur. Stockez-la dans le gestionnaire de secrets de votre hébergeur, limitez son accès au service qui appelle Orbit et ne l’écrivez jamais dans les journaux. Ne l’exposez pas dans un navigateur, une application mobile, une variable `NEXT_PUBLIC_*`, un dépôt ou une capture d’écran. Une clé Supabase secrète/`service_role` n’est jamais nécessaire pour appeler Orbit.

## Rechercher un centre d’intérêt

```bash
curl --get \
  "${ORBIT_BASE_URL}/v1/interests/search" \
  --header "Authorization: Bearer ${ORBIT_API_KEY}" \
  --data-urlencode 'q=zelda' \
  --data-urlencode 'category=games' \
  --data-urlencode 'limit=10'
```

Une réponse réussie contient les UUID Orbit, les libellés canoniques et les catégories des résultats publiés. Les en-têtes `X-RateLimit-*` et `X-Orbit-Daily-RateLimit-*` indiquent les quotas courant et journalier de la clé. Une liste vide est une réponse `200` valide.

Conservez aussi `X-Request-Id` pour diagnostiquer un appel avec Orbit sans jamais transmettre vos clés.

Commencez toujours par `orbit-dev`. Une fois l’intégration validée et le passage en production autorisé, remplacez le paquet complet par l’URL `https://jsmxzmxgxwexgvaraeke.supabase.co/functions/v1/api` et la clé distincte de `orbit-prod`. Ne changez jamais seulement l’URL ou la clé.

## Exemple Node.js côté serveur

```ts
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5_000);

try {
  const response = await fetch(
    `${process.env.ORBIT_BASE_URL}/v1/interests/search?q=zelda&category=games&limit=10`,
    {
      headers: {
        Authorization: `Bearer ${process.env.ORBIT_API_KEY!}`,
      },
      signal: controller.signal,
    },
  );

  if (!response.ok) {
    const body = await response.json();
    throw new Error(`Orbit ${response.status}: ${body.error?.code ?? "unknown"}`);
  }

  const result = await response.json();
  console.log(result.data);
} finally {
  clearTimeout(timeout);
}
```

Le délai de cinq secondes est un exemple client, pas un engagement de service Orbit. Adaptez-le au budget de latence de votre service et utilisez les règles de nouvelle tentative documentées plutôt qu’une boucle illimitée.

## Étape suivante

Consultez la [recherche](/docs/search), la [résolution d’identifiants](/docs/resolve), les [erreurs et nouvelles tentatives](/docs/errors-and-retries) ou la [référence OpenAPI en lecture seule](/reference).

---

# Résoudre des identifiants Orbit

URL canonique : https://orbit-data-api.com/docs/resolve

```http
POST /v1/interests/resolve
Content-Type: application/json

{"ids":["<orbit-uuid>"]}
```

Le corps contient uniquement `ids`, un tableau de 0 à 100 UUID canoniques avec tirets. La casse d’entrée est ignorée et les UUID sortants utilisent des minuscules. Les doublons sont supprimés en conservant leur première position ; la réponse contient exactement un résultat par UUID unique, dans cet ordre.

## États de résolution

| `status` | Signification | Données retournées |
|---|---|---|
| `resolved` | L’UUID demandé est directement publié. | `interest`, avec son UUID canonique, son libellé et sa catégorie. |
| `replaced` | L’UUID demandé a été fusionné. | `replacedBy` et l’`interest` canonique directement publié. |
| `unavailable` | L’UUID a été publié mais n’est plus redistribuable. | Tombstone sans libellé ni catégorie. |
| `not_found` | L’UUID est inconnu ou n’a jamais été publié. | Aucun détail interne. |

Un UUID Orbit n’est jamais recyclé. Une correction de libellé ou de catégorie conserve l’UUID. Une fusion redirige en un seul saut vers un intérêt directement publié.

## Exemple

```bash
curl "${ORBIT_BASE_URL}/v1/interests/resolve" \
  --request POST \
  --header "Authorization: Bearer ${ORBIT_API_KEY}" \
  --header "content-type: application/json" \
  --data '{"ids":["00000000-0000-0000-0000-000000000000"]}'
```

```json
{
  "data": [
    {
      "requestedId": "00000000-0000-0000-0000-000000000000",
      "status": "not_found"
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "inputCount": 1,
    "uniqueCount": 1
  }
}
```

Cette route ne modifie aucune donnée : son `POST` peut être réessayé sans effet de bord. Elle renvoie `200` même lorsqu’un ou plusieurs UUID ont le statut `not_found` ou `unavailable`.

---

# Rechercher des centres d’intérêt

URL canonique : https://orbit-data-api.com/docs/search

```http
GET /v1/interests/search?q=<texte>&category=<catégorie>&limit=<1..50>
```

## Paramètres

| Paramètre | Obligatoire | Règles |
|---|---:|---|
| `q` | oui | Une occurrence, 1 à 100 caractères Unicode après trim. |
| `category` | non | Une à six occurrences uniques parmi `games`, `movies`, `anime`, `series`, `music`, `books`. |
| `limit` | non | Entier de 1 à 50, valeur par défaut `20`. |

La recherche ignore la casse et les accents. Les caractères `%`, `_` et `\` sont traités comme du texte, pas comme des jokers SQL.

La recherche porte uniquement sur les libellés canoniques et ne renvoie que les intérêts publiés. Un libellé exact est classé avant un préfixe, puis avant les autres occurrences contenues. Répéter `category` lance une seule recherche, consomme une seule requête de quota et applique `limit` au résultat total des catégories demandées.

## Exemple

```bash
curl --get \
  "${ORBIT_BASE_URL}/v1/interests/search" \
  --header "Authorization: Bearer ${ORBIT_API_KEY}" \
  --data-urlencode "q=zelda" \
  --data-urlencode "category=games" \
  --data-urlencode "category=anime" \
  --data-urlencode "limit=10"
```

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "label": "The Legend of Zelda",
      "category": "games"
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "query": "zelda",
    "category": null,
    "categories": ["games", "anime"],
    "limit": 10,
    "returnedCount": 1
  }
}
```

L’UUID et le libellé ci-dessus sont illustratifs. Une liste `data` vide est un succès et signifie qu’aucun intérêt publié n’a été retenu.

## Classement et pagination

La route renvoie un top-N classé par pertinence. Elle n’est ni exhaustive ni paginée, et l’ordre peut évoluer sans rupture de contrat. N’utilisez donc pas une position de résultat comme identifiant durable ; persistez uniquement l’UUID Orbit choisi.

La requête `GET` est réessayable sans effet de bord. Consultez les [quotas et règles de nouvelle tentative](/docs/errors-and-retries).

---

# Environnements et URLs

URL canonique : https://orbit-data-api.com/docs/bien-demarrer/environnements

| Environnement | URL de base |
|---|---|
| Développement | `https://anvhjdjxovzjnvpmjtkl.supabase.co/functions/v1/api` |
| Production | `https://jsmxzmxgxwexgvaraeke.supabase.co/functions/v1/api` |

Dans ces URLs, `/functions/v1` appartient à la passerelle Supabase, `api` nomme la fonction canonique et le `/v1` ajouté dans chaque route versionne le contrat Orbit. C’est pourquoi `v1` apparaît deux fois dans l’URL complète.

```text
https://…supabase.co/functions/v1/api/v1/interests/search
                             └─┬─┘ └┬┘
                        passerelle  contrat Orbit
```

Les comptes, accès et clés restent propres à chaque environnement. Une clé ne fonctionne pas en changeant simplement son URL, et les écritures du portail ne sont pas répliquées entre développement et production.

Configurez le paquet complet côté serveur :

```bash
ORBIT_BASE_URL="https://anvhjdjxovzjnvpmjtkl.supabase.co/functions/v1/api"
ORBIT_API_KEY="votre-cle-orbit-dev"
```

N’utilisez jamais de préfixe public pour ces variables.

---

# Bien démarrer avec Orbit API

URL canonique : https://orbit-data-api.com/docs/bien-demarrer

Une intégration Orbit suit quatre étapes simples.

## 1. Obtenir un accès

Chaque environnement possède sa propre URL et sa propre clé. Le parcours
Gratuit puis Pro a été validé contre `orbit-dev` avec un compte créé par
l’opérateur et Stripe en mode test. L’inscription publique reste fermée. La
production est réservée aux clients approuvés et ne propose pas encore de
création d’accès ou de paiement autonome.

[Comprendre l’intégration actuelle](/docs/bien-demarrer/obtenir-un-acces)

## 2. Installer les secrets côté serveur

Créez deux variables réservées à votre backend :

```text
ORBIT_BASE_URL
ORBIT_API_KEY
```

N’utilisez jamais un préfixe public comme `NEXT_PUBLIC_` ou `EXPO_PUBLIC_`. Une application distribuée ne peut pas conserver un secret.

## 3. Rechercher le concept choisi

Votre interface appelle votre backend. Votre backend appelle ensuite `GET /v1/interests/search`, puis renvoie seulement les résultats utiles au client.

[Effectuer une première requête](/docs/quickstart)

## 4. Persister et maintenir l’UUID

Enregistrez l’UUID Orbit sélectionné avec un instantané du libellé et de la catégorie. Utilisez `POST /v1/interests/resolve` lors d’une synchronisation ou d’un changement pertinent afin de suivre un remplacement ou un retrait.

[Stocker et maintenir les UUID Orbit](/docs/guides/stocker-et-resoudre-les-uuid)

---

# Obtenir un accès API

URL canonique : https://orbit-data-api.com/docs/bien-demarrer/obtenir-un-acces

Le parcours compte, accès Gratuit et Pro a été validé sur une Preview contre
`orbit-dev`, avec un compte confirmé créé par l’opérateur et Stripe en mode
test. L’inscription publique est actuellement fermée sur la Preview comme en
production. Les comptes et accès destinés aux clients approuvés restent
préparés manuellement.

Un paquet d’accès contient :

- l’environnement ciblé ;
- son URL de base ;
- une clé Orbit révélée une seule fois ;
- la permission autorisée, actuellement `interests:read` ;
- les quotas minute et jour ;
- une date d’expiration éventuelle.

La clé doit être transférée par un canal sécurisé puis installée directement dans le gestionnaire de secrets du service consommateur. Orbit ne conserve que son empreinte cryptographique.

## Développement avant production

Commencez avec un accès `orbit-dev`. Après validation de l’intégration, Orbit peut remettre un paquet `orbit-prod` entièrement distinct. Ne réutilisez jamais une clé de développement en production et ne changez jamais seulement l’URL.

## Prochaine ouverture du portail

Lorsque la Preview affichera « Créer un compte », l’inscription et l’accès
Gratuit seront ouverts contre `orbit-dev`. Un compte possédera au maximum un
accès libre-service et sa première clé sera révélée une seule fois. Vous pourrez
ensuite tester l’offre Pro à 9 €/mois avec Stripe en mode test ; aucune carte
réelle ne sera débitée. Gratuit sera plafonné à 10 000 réponses réussies par
mois, Pro à 50 000, sans dépassement facturé.

Tant que la page indique « Voir les modalités d’accès », le coupe-circuit de
l’environnement est fermé et aucun achat autonome n’est possible. Un
administrateur de plateforme peut toujours créer ses propres accès
complémentaires hors facturation.

Continuez avec [les environnements et URLs](/docs/bien-demarrer/environnements) ou [l’authentification serveur](/docs/authentication).

---

# Accès et clés API

URL canonique : https://orbit-data-api.com/docs/compte-et-securite/acces-et-cles

Un accès API porte le propriétaire, l’origine, le statut, la permission et les quotas. Une clé est seulement un moyen révocable d’utiliser cet accès.

## Révélation unique

La valeur complète d’une clé est révélée une seule fois. Orbit conserve uniquement son empreinte SHA-256, ce qui empêche toute récupération ultérieure de la valeur originale.

Installez immédiatement la clé dans un gestionnaire de secrets. N’utilisez ni dépôt, ni fichier partagé, ni capture d’écran, ni canal de support.

## Rotation sans interruption

1. Créez une nouvelle clé sur le même accès.
2. Installez-la dans tous les services consommateurs.
3. Vérifiez un appel authentifié et conservez son `X-Request-Id`.
4. Révoquez l’ancienne clé.

Les clés multiples servent au chevauchement de rotation. Elles ne multiplient pas les quotas : les compteurs restent partagés au niveau de l’accès.

Un accès libre-service Gratuit ou Pro accepte au maximum deux clés actives. La
rotation recommandée consiste donc à créer la seconde, déployer sa valeur, puis
révoquer la première avant la rotation suivante. Les accès complémentaires
d’administration restent gérés séparément.

## Erreurs d’accès

- `401` : clé absente, invalide, révoquée, expirée ou accès suspendu ;
- `403` : accès valide mais permission insuffisante ;
- `409` dans le portail : deux clés sont déjà actives sur l’accès libre-service ;
- `429` dans l’API : quota de l’accès dépassé.

La Preview commerciale permet à un compte confirmé créé par l’opérateur de
créer un accès Gratuit, puis de tester l’offre Pro sur ce même accès.
L’abonnement ne remplace ni ne révèle de nouveau les clés existantes.
L’inscription publique reste fermée. En production, la création autonome reste
également fermée ; un administrateur peut créer ses propres accès
complémentaires.

---

# Facturation

URL canonique : https://orbit-data-api.com/docs/compte-et-securite/facturation

## Portée de la Preview

La Preview commerciale permet de valider le parcours complet contre
`orbit-dev`. Stripe y fonctionne exclusivement en **mode test** : aucune carte
réelle n’est débitée et l’offre ne constitue pas encore une vente en production.

Vercel Production et `orbit-prod` conservent l’inscription fermée et ne proposent
aucun paiement. Leur ouverture fera l’objet d’une validation et d’une
autorisation distinctes.

## Offres testées

| Offre | Prix Preview | Réponses `2xx` par mois UTC | Limite minute | Dépassement |
|---|---:|---:|---:|---|
| Gratuit | 0 € | 10 000, plafond dur | 60 | aucun |
| Pro | 9 €/mois en mode test | 50 000, plafond dur | 300 | aucun |

Le volume inclus est aussi le plafond dur. Orbit ne facture aucune requête
supplémentaire et bloque le prochain appel lorsque la limite mensuelle est
atteinte. Stripe gère seulement l’abonnement mensuel fixe ; il n’est jamais
appelé pendant une requête API.

## Parcours Pro

Avec le compte de validation fourni par l’opérateur, vous devez d’abord posséder
l’accès Gratuit créé depuis le portail. Depuis `/dashboard/billing`, le bouton
Pro ouvre la page de paiement Stripe en mode test. Après un paiement accepté,
un webhook signé active l’offre Pro sur le même accès : vos clés existantes
restent valides et ne sont pas remplacées.

Le portail affiche l’offre, son état et le total agrégé de réponses réussies du
mois UTC. Orbit conserve uniquement les identifiants Stripe et états nécessaires
au suivi de l’abonnement. Aucune donnée de carte ni payload Stripe brut n’est
stocké dans sa base.

## Limites actuelles

La Preview ne possède pas encore de portail client Stripe, résiliation autonome,
facture, gestion de TVA, remboursement, crédit ni paiement à l’usage. Les états
d’échec, pause et résiliation désactivent le droit Pro selon le webhook, mais
leur parcours commercial final reste à définir avant la production.

L’inscription publique reste désactivée. Avant son ouverture, elle devra exiger
Turnstile et la confirmation de l’adresse par code à six chiffres. L’envoi à
une adresse arbitraire nécessite un SMTP personnalisé ; le fournisseur e-mail
par défaut du projet Supabase Free reste limité.

---

# Compte, accès et sécurité

URL canonique : https://orbit-data-api.com/docs/compte-et-securite

Orbit utilise une hiérarchie simple, sans organisation ni équipe :

```text
Compte Orbit
   └── Accès API
         ├── clé active
         └── clé de rotation éventuelle
```

Le compte correspond à l’utilisateur authentifié du portail. Un accès porte son propriétaire, son statut, sa permission et ses quotas. Les clés authentifient les appels serveur et partagent les limites de leur accès.

`/dashboard` présente les informations personnelles et les accès du compte connecté. Les vues `/admin` sont globales et réservées aux administrateurs de plateforme.

Une Preview commerciale a validé ce socle uniquement contre `orbit-dev` avec
un compte créé par l’opérateur : accès Gratuit sans carte, compteur mensuel et
test Pro via Stripe. Elle n’ouvre pas encore l’inscription publique.
Gratuit est plafonné à 10 000 réponses réussies par mois et Pro à 50 000, sans
dépassement facturé. La production reste fermée jusqu’aux e-mails
transactionnels, pages légales, domaine final et contrôles d’exploitation.
Consultez [Obtenir un accès](/docs/bien-demarrer/obtenir-un-acces) pour distinguer
les deux environnements.

## Continuer

- [Créer, stocker et faire tourner des clés](/docs/compte-et-securite/acces-et-cles)
- [Comprendre les quotas](/docs/compte-et-securite/quotas)
- [Vérifier votre intégration](/docs/compte-et-securite/securite)
- [État de la facturation](/docs/compte-et-securite/facturation)

---

# Quotas et limites

URL canonique : https://orbit-data-api.com/docs/compte-et-securite/quotas

Chaque réponse authentifiée expose les limites de son accès :

```text
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
X-Orbit-Daily-RateLimit-Limit
X-Orbit-Daily-RateLimit-Remaining
X-Orbit-Daily-RateLimit-Reset
```

Les valeurs `Reset` sont des timestamps Unix en secondes. Les quotas sont partagés entre toutes les clés d’un même accès.

Dans la Preview commerciale, les accès libre-service exposent aussi leur offre
et le compteur commercial :

```text
X-Orbit-Plan
X-Orbit-Monthly-Usage-Included
X-Orbit-Monthly-Usage-Used
X-Orbit-Monthly-Usage-Limit
X-Orbit-Monthly-Usage-Remaining
X-Orbit-Monthly-Usage-Reset
```

Ces en-têtes sont absents des accès historiques ou complémentaires qui ne sont
pas soumis au comptage commercial. `Included` désigne le volume inclus et
`Limit` le plafond dur. Ils ont tous les deux la valeur `10000` sur l’offre
Gratuite et `50000` sur l’offre Pro : aucun dépassement payant n’est accepté.

## Consommation actuelle

L’authentification consomme les quotas minute et jour avant la validation de la route ou du corps. Une requête dont la clé est valide peut donc consommer ces protections même si elle se termine ensuite en erreur applicative.

Les clés absentes, invalides, expirées, révoquées, les accès suspendus et les permissions insuffisantes ne consomment pas ces quotas.

Le compteur mensuel est séparé. Orbit réserve une place après authentification,
puis comptabilise le résultat métier lorsqu’il est compris entre `200` et
`299`. Dans le fonctionnement normal, une erreur `4xx` ou `5xx` libère la
réservation et n’entame pas le volume mensuel. Une requête en cours apparaît
temporairement dans le nombre réservé du portail.

Une coupure réseau exactement au moment de la confirmation peut rendre le
statut reçu par le client différent du résultat déjà enregistré. Orbit conserve
alors la réservation comme preuve afin de pouvoir rapprocher l’usage et, avant
toute facturation réelle, appliquer le crédit correctif prévu par la politique
commerciale.

## Dépassement

Un dépassement minute ou jour renvoie `429 rate_limit_exceeded`. Le plafond
mensuel renvoie `429 monthly_quota_exceeded`. Dans les deux cas, `Retry-After`
indique le délai minimal avant une nouvelle tentative. N’envoyez pas de
tentatives parallèles et ne contournez jamais la limite avec plusieurs clés.

Stripe n’est pas appelé pour mesurer chaque requête et ne reçoit aucun événement
de dépassement. Dans la Preview, l’abonnement Pro est un prix mensuel fixe et
50 000 constitue à la fois le volume inclus et le plafond.

---

# Sécurité d’intégration

URL canonique : https://orbit-data-api.com/docs/compte-et-securite/securite

Avant un déploiement, vérifiez les points suivants :

- l’appel Orbit part uniquement d’un backend, d’une Route Handler ou d’une Edge Function ;
- la clé vit dans un gestionnaire de secrets ;
- aucune variable `NEXT_PUBLIC_*` ou `EXPO_PUBLIC_*` ne contient la clé ;
- la base URL Orbit est fixe et ne provient jamais d’une entrée utilisateur ;
- les entrées `q`, `category`, `limit` et `ids` sont validées ;
- aucun header, secret, corps utilisateur ou URL sensible n’est journalisé ;
- les délais et nouvelles tentatives sont bornés ;
- `Retry-After` est respecté ;
- la rotation chevauche brièvement l’ancienne et la nouvelle clé ;
- seul `X-Request-Id` est conservé pour un diagnostic.

## Pourquoi CORS ne suffit pas

CORS contrôle certains appels effectués par les navigateurs. Il n’empêche pas un utilisateur d’extraire une clé présente dans le JavaScript, le réseau ou le binaire d’une application. Une clé distribuée au client est compromise par définition.

La référence web Orbit reste donc volontairement en lecture seule et ne demande jamais une clé.

---

# Cloudflare Workers

URL canonique : https://orbit-data-api.com/docs/guides/cloudflare-workers

Enregistrez la clé comme secret Worker :

```bash
wrangler secret put ORBIT_API_KEY
```

Définissez l’URL de base comme variable serveur ou constante contrôlée, jamais à partir d’une entrée utilisateur.

```ts
interface Env {
  ORBIT_API_KEY: string;
  ORBIT_BASE_URL: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const incoming = new URL(request.url);
    const query = incoming.searchParams.get("q")?.trim() ?? "";
    if (!query || query.length > 100) {
      return Response.json({ error: "invalid_query" }, { status: 400 });
    }

    const orbitUrl = new URL(`${env.ORBIT_BASE_URL}/v1/interests/search`);
    orbitUrl.searchParams.set("q", query);
    orbitUrl.searchParams.set("limit", "20");

    const response = await fetch(orbitUrl, {
      headers: { Authorization: `Bearer ${env.ORBIT_API_KEY}` },
      signal: AbortSignal.timeout(5_000),
    });

    const headers = new Headers({
      "content-type": "application/json",
      "cache-control": "private, no-store",
    });
    for (const name of [
      "x-request-id",
      "x-ratelimit-limit",
      "x-ratelimit-remaining",
      "x-ratelimit-reset",
      "x-orbit-daily-ratelimit-limit",
      "x-orbit-daily-ratelimit-remaining",
      "x-orbit-daily-ratelimit-reset",
      "retry-after",
    ]) {
      const value = response.headers.get(name);
      if (value) headers.set(name, value);
    }

    return new Response(response.body, {
      status: response.status,
      headers,
    });
  },
};
```

Ajoutez l’authentification et les limites propres à votre application. Ne renvoyez jamais `env`, l’en-tête envoyé à Orbit ou la clé dans les journaux.

---

# Expo avec un backend sécurisé

URL canonique : https://orbit-data-api.com/docs/guides/expo-backend-securise

Une application mobile distribuée ne peut pas protéger un secret serveur. `.env`, `EXPO_PUBLIC_*`, SecureStore et l’obfuscation ne rendent pas une clé Orbit confidentielle.

```text
Application Expo
      │ requête authentifiée de votre utilisateur
      ▼
Backend ou Edge Function de votre produit
      │ clé Orbit conservée comme secret serveur
      ▼
Orbit API
```

Dans Expo, appelez uniquement votre propre endpoint :

```ts
export async function searchInterests(query: string) {
  const response = await fetch(`${process.env.EXPO_PUBLIC_APP_API_URL}/interests/search`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ q: query, category: "anime" }),
  });

  if (!response.ok) throw new Error("Recherche indisponible");
  return response.json();
}
```

`EXPO_PUBLIC_APP_API_URL` désigne ici votre backend public, jamais Orbit directement. Votre backend vérifie la session utilisateur, valide les entrées, limite les abus et renvoie seulement les résultats nécessaires.

Pour construire ce backend, utilisez le guide [Supabase Edge Functions](/docs/guides/supabase-edge-functions), [Next.js](/docs/guides/nextjs-vercel) ou [Cloudflare Workers](/docs/guides/cloudflare-workers).

---

# Guides d’intégration

URL canonique : https://orbit-data-api.com/docs/guides

Orbit utilise HTTP et JSON : aucun SDK officiel n’est nécessaire pour les deux endpoints de la v1.

| Environnement | Guide |
|---|---|
| Service JavaScript ou TypeScript | [Node.js et TypeScript](/docs/guides/node-typescript) |
| Application App Router | [Next.js sur Vercel](/docs/guides/nextjs-vercel) |
| Backend Supabase | [Supabase Edge Functions](/docs/guides/supabase-edge-functions) |
| Application mobile | [Expo avec un backend sécurisé](/docs/guides/expo-backend-securise) |
| Runtime edge | [Cloudflare Workers](/docs/guides/cloudflare-workers) |
| Service Python | [Python](/docs/guides/python) |
| Modèle de persistance | [Stocker et maintenir les UUID](/docs/guides/stocker-et-resoudre-les-uuid) |

Tous les exemples respectent la même frontière : la clé Orbit reste dans un environnement serveur et le client public n’appelle que votre propre backend.

---

# Next.js sur Vercel

URL canonique : https://orbit-data-api.com/docs/guides/nextjs-vercel

L’architecture recommandée est : navigateur → Route Handler Next.js → Orbit API.

Dans Vercel, créez uniquement des variables serveur :

```text
ORBIT_BASE_URL
ORBIT_API_KEY
```

Ne préfixez jamais la clé avec `NEXT_PUBLIC_`.

```ts
// app/api/interests/search/route.ts
import { NextRequest, NextResponse } from "next/server";

const categories = new Set(["games", "movies", "anime", "series", "music", "books"]);

export async function GET(request: NextRequest) {
  const query = request.nextUrl.searchParams.get("q")?.trim() ?? "";
  const category = request.nextUrl.searchParams.get("category");
  const limit = Number(request.nextUrl.searchParams.get("limit") ?? 20);

  if (!query || query.length > 100) {
    return NextResponse.json({ error: "invalid_query" }, { status: 400 });
  }
  if (category && !categories.has(category)) {
    return NextResponse.json({ error: "invalid_category" }, { status: 400 });
  }
  if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
    return NextResponse.json({ error: "invalid_limit" }, { status: 400 });
  }

  const baseUrl = process.env.ORBIT_BASE_URL;
  const apiKey = process.env.ORBIT_API_KEY;
  if (!baseUrl || !apiKey) {
    return NextResponse.json({ error: "not_configured" }, { status: 503 });
  }

  const orbitUrl = new URL(`${baseUrl}/v1/interests/search`);
  orbitUrl.searchParams.set("q", query);
  orbitUrl.searchParams.set("limit", String(limit));
  if (category) orbitUrl.searchParams.set("category", category);

  const response = await fetch(orbitUrl, {
    headers: { Authorization: `Bearer ${apiKey}` },
    cache: "no-store",
    signal: AbortSignal.timeout(5_000),
  });

  const headers = new Headers({
    "content-type": "application/json",
    "cache-control": "private, no-store",
  });
  for (const name of [
    "x-request-id",
    "x-ratelimit-limit",
    "x-ratelimit-remaining",
    "x-ratelimit-reset",
    "x-orbit-daily-ratelimit-limit",
    "x-orbit-daily-ratelimit-remaining",
    "x-orbit-daily-ratelimit-reset",
    "retry-after",
  ]) {
    const value = response.headers.get(name);
    if (value) headers.set(name, value);
  }

  return new NextResponse(await response.text(), {
    status: response.status,
    headers,
  });
}
```

Le navigateur appelle seulement `/api/interests/search`. Ne lui permettez jamais de choisir l’hôte de destination et ne relayez pas son en-tête `Authorization` vers Orbit.

Ajoutez votre propre authentification utilisateur, validation et limitation anti-abus avant d’exposer cette route publiquement.

---

# Node.js et TypeScript

URL canonique : https://orbit-data-api.com/docs/guides/node-typescript

## Prérequis

Définissez `ORBIT_BASE_URL` et `ORBIT_API_KEY` dans le gestionnaire de secrets de votre service. Le code suivant doit rester dans un module serveur.

```ts
type OrbitCategory = "games" | "movies" | "anime" | "series" | "music" | "books";

type OrbitInterest = {
  id: string;
  label: string;
  category: OrbitCategory;
};

type SearchResponse = {
  data: OrbitInterest[];
  meta: {
    apiVersion: "v1";
    query: string;
    category: OrbitCategory | null;
    categories: OrbitCategory[] | null;
    limit: number;
    returnedCount: number;
  };
};

export async function searchInterests(input: {
  query: string;
  categories?: OrbitCategory[];
  limit?: number;
}) {
  const baseUrl = process.env.ORBIT_BASE_URL;
  const apiKey = process.env.ORBIT_API_KEY;
  if (!baseUrl || !apiKey) throw new Error("Orbit n’est pas configurée");

  const url = new URL(`${baseUrl}/v1/interests/search`);
  url.searchParams.set("q", input.query);
  for (const category of new Set(input.categories ?? [])) {
    url.searchParams.append("category", category);
  }
  url.searchParams.set("limit", String(input.limit ?? 20));

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${apiKey}` },
    signal: AbortSignal.timeout(5_000),
  });

  const body = await response.json();
  if (!response.ok) {
    const requestId = response.headers.get("x-request-id") ?? "absent";
    const code = body?.error?.code ?? "unknown_error";
    throw new Error(`Orbit ${response.status} ${code} (${requestId})`);
  }

  return body as SearchResponse;
}
```

Le délai de cinq secondes est un exemple client, pas un engagement de service. Ne journalisez ni les en-têtes, ni le corps complet, ni la clé.

Pour les `429`, attendez `Retry-After`. Réessayez uniquement les `500`, `503`, délais dépassés et erreurs réseau avec une attente exponentielle bornée et légèrement aléatoire.

Continuez avec [le guide de persistance](/docs/guides/stocker-et-resoudre-les-uuid).

---

# Python

URL canonique : https://orbit-data-api.com/docs/guides/python

Avec `httpx`, gardez la configuration dans l’environnement du service :

```python
import os
import httpx

BASE_URL = os.environ["ORBIT_BASE_URL"]
API_KEY = os.environ["ORBIT_API_KEY"]

def search_interests(query: str, category: str | None = None) -> dict:
    params = {"q": query, "limit": 20}
    if category:
        params["category"] = category

    with httpx.Client(timeout=5.0) as client:
        response = client.get(
            f"{BASE_URL}/v1/interests/search",
            params=params,
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        response.raise_for_status()
        return response.json()

def resolve_interests(ids: list[str]) -> dict:
    with httpx.Client(timeout=5.0) as client:
        response = client.post(
            f"{BASE_URL}/v1/interests/resolve",
            json={"ids": ids},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        response.raise_for_status()
        return response.json()
```

Ne journalisez jamais les en-têtes ou la clé. Pour un `429`, respectez `Retry-After`. Réessayez seulement les erreurs réseau, délais dépassés, `500` et `503`, avec un nombre de tentatives limité.

---

# Stocker et maintenir les UUID Orbit

URL canonique : https://orbit-data-api.com/docs/guides/stocker-et-resoudre-les-uuid

Votre produit n’a pas besoin de recopier l’intégralité du catalogue. Une table de sélection peut rester minimale :

```sql
create table user_interests (
  user_id uuid not null,
  orbit_interest_id uuid not null,
  label text not null,
  category text not null check (
    category in ('games', 'movies', 'anime', 'series', 'music', 'books')
  ),
  resolved_at timestamptz,
  primary key (user_id, orbit_interest_id)
);
```

Il n’existe pas de clé étrangère entre votre base et Orbit. `label` et `category` représentent l’instantané choisi par l’utilisateur ; ils ne recréent pas une source de vérité locale.

## Appliquer une résolution

Appelez `POST /v1/interests/resolve` par lots de 100 UUID au maximum, puis traitez chaque statut :

- `resolved` : conservez l’UUID et rafraîchissez éventuellement le libellé ou la catégorie ;
- `replaced` : remplacez l’UUID par `replacedBy` et l’instantané dans la même transaction ;
- `unavailable` : masquez ou retirez la sélection selon les règles de votre produit ;
- `not_found` : marquez la référence invalide et demandez une nouvelle sélection, sans inventer d’alias.

Vous n’avez pas besoin d’une table d’alias ou d’un cache complet du catalogue pour gérer les sélections. L’endpoint `resolve` porte précisément ce cycle de vie.

## Quand résoudre

Une tâche périodique, une migration de profil ou une lecture métier importante suffisent généralement. Évitez un appel à chaque rendu et regroupez les UUID pour limiter la latence et la consommation.

---

# Supabase Edge Functions

URL canonique : https://orbit-data-api.com/docs/guides/supabase-edge-functions

Installez les valeurs dans le coffre de secrets du projet consommateur :

```bash
supabase secrets set \
  ORBIT_BASE_URL="https://anvhjdjxovzjnvpmjtkl.supabase.co/functions/v1/api" \
  ORBIT_API_KEY="votre-cle-orbit-dev"
```

La commande ci-dessus est illustrative : évitez de laisser une vraie clé dans l’historique du terminal. Préférez une saisie sécurisée ou l’outil de secrets de votre CI.

```ts
const categories = new Set(["games", "movies", "anime", "series", "music", "books"]);

Deno.serve(async (request) => {
  const input = await request.json();
  const query = typeof input.q === "string" ? input.q.trim() : "";
  const category = typeof input.category === "string" ? input.category : null;

  if (!query || query.length > 100 || (category && !categories.has(category))) {
    return Response.json({ error: "invalid_request" }, { status: 400 });
  }

  const baseUrl = Deno.env.get("ORBIT_BASE_URL");
  const apiKey = Deno.env.get("ORBIT_API_KEY");
  if (!baseUrl || !apiKey) {
    return Response.json({ error: "not_configured" }, { status: 503 });
  }

  const url = new URL(`${baseUrl}/v1/interests/search`);
  url.searchParams.set("q", query);
  if (category) url.searchParams.set("category", category);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${apiKey}` },
    signal: AbortSignal.timeout(5_000),
  });

  const headers = new Headers({
    "content-type": "application/json",
    "cache-control": "private, no-store",
  });
  for (const name of [
    "x-request-id",
    "x-ratelimit-limit",
    "x-ratelimit-remaining",
    "x-ratelimit-reset",
    "x-orbit-daily-ratelimit-limit",
    "x-orbit-daily-ratelimit-remaining",
    "x-orbit-daily-ratelimit-reset",
    "retry-after",
  ]) {
    const value = response.headers.get(name);
    if (value) headers.set(name, value);
  }

  return new Response(response.body, {
    status: response.status,
    headers,
  });
});
```

Validez l’utilisateur ou l’appel entrant selon les règles de votre produit. Une clé Supabase publiable du projet consommateur n’est ni une clé Orbit ni un remplacement de votre authentification applicative.

---

# Catalogue et catégories

URL canonique : https://orbit-data-api.com/docs/concepts/catalogue-et-categories

Un centre d’intérêt publié contient exactement trois propriétés métier :

```ts
type OrbitInterest = {
  id: string; // UUID Orbit
  label: string;
  category: OrbitCategory;
};

type OrbitCategory =
  | "games"
  | "movies"
  | "anime"
  | "series"
  | "music"
  | "books";
```

## Catégories

| Valeur API | Domaine |
|---|---|
| `games` | Jeux vidéo |
| `movies` | Films |
| `anime` | Anime et manga |
| `series` | Séries |
| `music` | Musique |
| `books` | Livres |

Orbit vise un concept canonique par catégorie. Deux versions d’un même jeu sur des plateformes différentes ne deviennent pas automatiquement deux centres d’intérêt ; deux œuvres réellement distinctes peuvent en revanche conserver chacune leur identité.

## Limites actuelles

La réponse ne contient pas de description, image, score de popularité, traduction structurée, identifiant de source ou provenance brute. Le libellé canonique peut être français ou anglais : la v1 ne distingue pas encore les traductions par langue.

Pour sélectionner un concept, utilisez [la recherche](/docs/search). Pour suivre son évolution, utilisez [la résolution](/docs/resolve).

---

# Identifiants stables et cycle de vie

URL canonique : https://orbit-data-api.com/docs/concepts/identifiants-stables

L’UUID Orbit constitue l’identité durable d’un centre d’intérêt. Il n’est jamais recyclé pour désigner un autre concept.

Une correction de libellé ou de catégorie conserve normalement le même UUID. Lorsqu’un doublon est fusionné ou qu’une donnée ne peut plus être redistribuée, `resolve` expose un état explicite.

| Statut | Signification | Action recommandée |
|---|---|---|
| `resolved` | L’UUID est directement publié. | Conserver l’UUID et rafraîchir le libellé si utile. |
| `replaced` | L’UUID a été fusionné vers un autre concept. | Remplacer par `replacedBy` et mettre à jour l’instantané. |
| `unavailable` | L’UUID a existé mais n’est plus redistribuable. | Masquer ou retirer la sélection selon votre produit. |
| `not_found` | L’UUID est inconnu ou n’a jamais été publié. | Signaler la donnée invalide sans inventer de correspondance. |

Une fusion redirige en un seul saut vers un intérêt directement publié. Votre base n’a donc pas besoin d’entretenir une chaîne d’alias Orbit.

## Stockage conseillé

Persistez :

- l’UUID Orbit ;
- le dernier libellé sélectionné ;
- la catégorie ;
- éventuellement la date de dernière résolution.

Le libellé et la catégorie constituent un instantané utile à l’interface, pas un nouveau catalogue local.

---

# Comprendre Orbit

URL canonique : https://orbit-data-api.com/docs/concepts

Orbit publie un modèle volontairement minimal : un UUID, un libellé canonique et une catégorie. Cette simplicité permet d’utiliser la même API pour six domaines culturels sans importer la complexité de chaque source.

## Ce que fait Orbit

- normalise les concepts culturels dans un catalogue unique ;
- attribue des identifiants durables ;
- recherche les concepts publiés ;
- signale le remplacement ou le retrait d’un UUID ;
- conserve la provenance et les droits en interne.

## Ce qu’Orbit n’expose pas en v1

La v1 ne fournit ni images, ni descriptions, ni paroles, ni critiques, ni popularité, ni pages exhaustives du catalogue. Elle ne donne pas non plus un accès direct aux tables internes ou aux identifiants des sources.

Explorez [le catalogue et ses catégories](/docs/concepts/catalogue-et-categories), [le cycle de vie des UUID](/docs/concepts/identifiants-stables) puis [le flux recherche et résolution](/docs/concepts/recherche-et-resolution).

---

# Recherche et résolution

URL canonique : https://orbit-data-api.com/docs/concepts/recherche-et-resolution

Les deux endpoints répondent à des moments différents du cycle de vie.

## Lors d’une sélection utilisateur

1. L’interface envoie la saisie à votre backend.
2. Votre backend appelle `GET /v1/interests/search`.
3. L’utilisateur choisit un résultat.
4. Votre backend persiste son UUID, son libellé et sa catégorie.

La recherche renvoie un top-N non paginé. Quand l’interface limite la recherche à plusieurs catégories, répétez `category` dans une seule requête au lieu de lancer un appel par catégorie : Orbit n’authentifie et ne décompte alors qu’une requête. Son classement peut évoluer : ne stockez jamais une position de résultat ou le texte saisi comme identité.

## Lors de la maintenance

Regroupez les UUID utiles et appelez `POST /v1/interests/resolve` par lots de 100 au maximum. Un traitement périodique, une lecture métier importante ou une opération de synchronisation sont de bons moments pour résoudre les références. Il est rarement nécessaire de le faire à chaque rendu d’écran.

## Architecture

```text
Application publique
       │
       ▼
Backend du produit ── secret Orbit ──► Orbit API
       │
       ▼
UUID + instantané du libellé et de la catégorie
```

Consultez le guide [Stocker et maintenir les UUID Orbit](/docs/guides/stocker-et-resoudre-les-uuid) pour un exemple de table consommatrice.

---

# Référence API v1

URL canonique : https://orbit-data-api.com/docs/reference-v1

Le document courant est `1.0.0-rc.3`. Les routes publiques conservent le préfixe `/v1`.

| Méthode | Route | Usage |
|---|---|---|
| `GET` | `/v1/interests/search` | Rechercher un top-N de centres d’intérêt publiés. |
| `POST` | `/v1/interests/resolve` | Résoudre jusqu’à 100 UUID et leur cycle de vie. |

La cible d’intégration initiale est `orbit-dev`. L’accès production utilise une URL et une clé distinctes remises après validation du passage en production.

## Ressources

- [Recherche détaillée](/docs/search)
- [Résolution détaillée](/docs/resolve)
- [Erreurs et nouvelles tentatives](/docs/errors-and-retries)
- [Compatibilité v1](/docs/api-contract)
- [Référence Scalar en lecture seule](/reference)
- [OpenAPI 3.1 lisible par machine](/openapi.json)

La référence Scalar n’accepte volontairement aucune clé et ne propose aucun appel authentifié depuis le navigateur.

---

# Changelog

URL canonique : https://orbit-data-api.com/docs/ressources/changelog

Cette page ne reprend que les changements utiles aux consommateurs de l’API. L’historique interne des migrations et opérations reste séparé.

## 1.0.0-rc.3 — 14 septembre 2026

- Recherche multi-catégories en une requête avec jusqu’à six paramètres `category` répétés.
- Une recherche logique consomme un seul quota et expose le filtre effectif dans `meta.categories` ; les requêtes mono-catégorie existantes restent compatibles.
- Recherche accélérée par une projection privée indexée contenant uniquement les champs déjà publiés.
- Correction des expirations et réponses `503` observées par Lofy sous charge concurrente.

## 1.0.0-rc.2 — 4 septembre 2026

- Aucun changement incompatible des routes `/v1`, des réponses ou des UUID Orbit.
- Métadonnées de version alignées après le déploiement du site commercial et de la documentation en production.
- Durcissement pré-GA de l’inscription protégée et de la future gestion de l’abonnement ; ces parcours restent fermés en production.

## Catalogue revu — 2 septembre 2026

- Extension du catalogue à 69 758 centres d’intérêt actifs.
- Alignement exact des environnements de développement et production.
- Aucun changement de route, format ou version API.

Cette évolution de données ne constitue pas une rupture de contrat.

## 1.0.0-rc.1 — 31 août 2026

- Authentification par une clé Orbit Bearer unique.
- Recherche de centres d’intérêt publiés.
- Résolution des statuts `resolved`, `replaced`, `unavailable` et `not_found`.
- Quotas minute et jour avec en-têtes dédiés.
- `X-Request-Id` et enveloppes d’erreur versionnées.
- Document OpenAPI 3.1 et référence web en lecture seule.

Consultez [le contrat API v1](/docs/api-contract) pour la politique de compatibilité.

---

# Questions fréquentes

URL canonique : https://orbit-data-api.com/docs/ressources/faq

## Pourquoi `v1` apparaît-t-il deux fois dans l’URL ?

Le premier `/v1` appartient à la passerelle Supabase Edge Functions. Le second versionne le contrat Orbit : `/functions/v1/api/v1/interests/search`.

## Puis-je appeler Orbit depuis React ou Expo ?

Pas directement. Une clé Orbit est un secret serveur. React ou Expo appelle votre backend, qui appelle ensuite Orbit.

## Ai-je besoin d’une clé Supabase ?

Non. Le consommateur utilise uniquement la base URL Orbit et sa clé Orbit. L’infrastructure Supabase reste interne au service.

## Puis-je télécharger tout le catalogue ?

Non. La v1 expose une recherche top-N non paginée, pas un export exhaustif.

## Que dois-je stocker ?

L’UUID Orbit, accompagné du dernier libellé et de la catégorie sélectionnés. Le texte saisi ou la position d’un résultat ne constitue pas une identité.

## Faut-il maintenir une table d’alias ou un cache complet ?

Non pour les sélections d’utilisateurs. `resolve` indique si un UUID est résolu, remplacé, indisponible ou inconnu.

## Les libellés sont-ils toujours français ?

Non. La v1 ne fournit pas encore de langues ou traductions distinctes ; un libellé canonique peut être français ou anglais.

## Y a-t-il des images ou des descriptions ?

Non. La v1 se limite aux identifiants, libellés et catégories dont le périmètre de redistribution est établi.

## `not_found` est-il une erreur HTTP ?

Non. Dans une réponse de résolution valide, `not_found` est un résultat métier retourné avec HTTP `200`.

## Comment obtenir une clé ou payer en ligne ?

Le parcours a été validé sur une Preview avec un compte créé par l’opérateur :
un accès Gratuit révèle sa première clé une seule fois, puis Stripe permet de
tester Pro à 9 €/mois exclusivement en mode test. L’abonnement porte le plafond
mensuel de 10 000 à 50 000 réponses réussies sans changer la clé et sans
dépassement facturé. L’inscription publique et le paiement autonome restent
fermés en production ; les clients approuvés reçoivent actuellement leur accès
par intégration manuelle.

---

# Ressources

URL canonique : https://orbit-data-api.com/docs/ressources

- [Questions fréquentes](/docs/ressources/faq) : réponses rapides sur les clés, URLs, données et UUID.
- [Provenance et droits](/docs/ressources/provenance) : règles appliquées aux sources et contenus.
- [Statut du service](/docs/ressources/statut) : périmètre réellement disponible aujourd’hui.
- [Obtenir de l’aide](/docs/ressources/support) : préparer un diagnostic sans transmettre de secret.
- [Changelog](/docs/ressources/changelog) : évolutions visibles du contrat public.

---

# Provenance et droits des données

URL canonique : https://orbit-data-api.com/docs/ressources/provenance

Une API accessible publiquement n’accorde pas automatiquement le droit de stocker, transformer ou redistribuer ses données dans un produit commercial.

Orbit privilégie les jeux de données CC0. Pour toute autre source, quatre droits sont vérifiés séparément :

- usage commercial ;
- stockage local ;
- transformation ;
- redistribution à travers Orbit.

La licence d’un dataset et les conditions d’utilisation de son API hébergée sont analysées comme deux sujets distincts.

## Sources utilisées actuellement

Le catalogue historique Lofy a été constitué en interne. Son titulaire a explicitement autorisé son stockage, sa transformation, son usage commercial et sa redistribution par Orbit pour les champs identifiant, libellé et catégorie.

L’expansion structurée issue de Wikidata utilise les entités et identifiants couverts par CC0. Orbit conserve en interne les identifiants d’origine, les checksums et le manifeste d’import nécessaires à la traçabilité.

## Contenus exclus

Orbit n’intègre pas d’images, descriptions, articles, extraits audio ou vidéo, paroles, critiques ou autres contenus protégés tant que leurs droits de redistribution ne sont pas établis.

La provenance brute et les identifiants amont ne font pas partie de la réponse publique v1. Orbit n’est pas un proxy direct vers une API tierce.

---

# Statut du service

URL canonique : https://orbit-data-api.com/docs/ressources/statut

Les routes `search` et `resolve` sont déployées sur `orbit-dev` et `orbit-prod` pour les clients intégrés. Les deux environnements exposent le même catalogue revu de **69 758 centres d’intérêt actifs** dans six catégories.

Le contrat courant est identifié `1.0.0-rc.3` et utilise les routes `/v1`.

## Limites publiques actuelles

Orbit ne publie pas encore :

- de SLA contractuel ;
- de page de statut temps réel externe ;
- d’origine API sur un domaine de marque ;
- de disponibilité générale avec inscription autonome.

En cas d’incident, appliquez les règles de nouvelle tentative documentées et conservez `X-Request-Id`. Ne considérez pas cette page statique comme une sonde temps réel.

---

# Obtenir de l’aide

URL canonique : https://orbit-data-api.com/docs/ressources/support

Le canal de support est communiqué pendant l’intégration ; aucun canal public versionné n’est encore publié.

Pour préparer un diagnostic, rassemblez :

- l’horodatage UTC ;
- l’environnement concerné ;
- la méthode et la route ;
- le statut HTTP et le code d’erreur ;
- le `X-Request-Id` ;
- le comportement attendu et observé, sans donnée utilisateur.

Ne transmettez jamais une clé Orbit, un en-tête `Authorization`, une URL contenant des paramètres sensibles, le corps d’une requête utilisateur, une empreinte de clé ou une clé Supabase.

## Premières vérifications

- `401` : contrôlez que l’URL et la clé appartiennent au même environnement ;
- `403` : vérifiez la permission de l’accès ;
- `429` : attendez la durée de `Retry-After` ;
- `500` ou `503` : effectuez quelques nouvelles tentatives bornées, puis communiquez le `X-Request-Id`.