# API HTTP (/fr-FR/ontwikkelaars/http)
L'API Tillor est une API REST. Authentifiez-vous avec une clé API et envoyez les bons en-têtes à chaque requête. Les clés API sont **par compte** - une seule clé fonctionne pour toutes les organisations auxquelles vous avez accès.
## Référence de l'API et OpenAPI [#api-referentie-en-openapi]
- **[Référence de l'API](/api-referentie)** - Chaque endpoint avec ses paramètres et des exemples ; testez les requêtes directement dans le navigateur
- **[Spécification OpenAPI](https://tillor.eu/api/openapi.json)** - Documentation complète de l'API au format JSON pour la génération de code ou l'import dans Postman/Insomnia
---
## Clés API [#api-sleutels]
### Création [#aanmaken]
Vous créez les clés API dans l'application Tillor via le menu utilisateur sous **Compte > Clés API** (repère **1** = menu, repère **2** = Clés API sur la capture d'écran). Vous pouvez aussi les créer via l'API avec une session connectée (pas de clé API). Voir la [spécification OpenAPI](https://tillor.eu/api/openapi.json) sous le tag `api-keys` pour les chemins et les schémas de requête et de réponse.
La clé brute n'est renvoyée qu'**une seule fois** lors de la création ou de la régénération. Conservez-la en lieu sûr ; vous ne pourrez plus la récupérer ensuite.
### Limiter les droits [#rechten-beperken]
Par défaut, une clé peut tout ce que vous pouvez vous-même, dans chaque organisation dont vous êtes membre. Dans la fenêtre de la clé, activez **Limiter aux autorisations sélectionnées** et choisissez les droits dont l'intégration a besoin, par exemple uniquement lire les factures. Une clé limitée reçoit, dans chaque organisation, l'intersection de ses droits et de votre appartenance à cette organisation : une clé ne peut jamais faire plus que vous. Un appel en dehors des droits choisis reçoit `403 Forbidden`, comme un utilisateur sans ce droit. Une modification des droits s'applique en moins d'une minute. Via l'API : `scopes` (liste d'identifiants de droits comme `invoices:read`, ou `null` pour tout) à la création et à la mise à jour d'une clé.
### Utilisation [#gebruik]
Envoyez la clé API dans l'en-tête `x-api-key` :
```http
x-api-key: tkn_xxx
```
Les clés utilisent le préfixe `tkn_`. Pour les endpoints d'organisation, l'identifiant de l'organisation figure dans le chemin (`/orgs/org_abc123/...`) ; un en-tête distinct n'est pas nécessaire.
### Limites de débit [#rate-limits]
- **Par défaut :** 5000 requêtes par 60 secondes par clé
- En cas de dépassement : `429 Too Many Requests` avec `Retry-After`
- Chaque réponse à une clé API contient les en-têtes IETF `RateLimit-*` :
```http
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60
```
`RateLimit-Reset` est le nombre de secondes avant le redémarrage de la fenêtre actuelle. Les clients de navigateur peuvent lire ces en-têtes via CORS (`Access-Control-Expose-Headers`).
### Sécurité [#beveiliging]
- **Jamais** d'exposition de clés API dans du code côté client ou dans des dépôts publics
- Régénérez les clés régulièrement via **Régénérer** dans l'application (OpenAPI : `POST /api/api-keys/:id/renew`)
- Supprimez les clés inutilisées avec `DELETE /api/api-keys/:id`
---
## URL de base et contexte d'organisation [#base-url-en-organisatie-context]
**URL de base :** `https://tillor.eu` (ou l'URL de votre déploiement ; OpenAPI mentionne `{APP_URL}/api`)
**Chemins d'organisation :** ajoutez l'identifiant de l'organisation dans le chemin :
```
/api/orgs/:orgId/...
```
**Exemple :**
```
GET https://tillor.eu/api/orgs/org_abc123/customers
```
**En-tête requis pour les endpoints d'organisation :** `x-api-key: tkn_xxx`. L'identifiant de l'organisation figure dans le chemin.
---
## Exemple : cURL [#voorbeeld-curl]
```bash
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
-H "x-api-key: tkn_xxx" \
-H "Content-Type: application/json"
```
---
## Intégrations (marketplace) [#integraties-marketplace]
Les intégrations d'organisation (auparavant « apps » dans l'API) utilisent une ressource par type sous `/api/orgs/:orgId/integrations/{integrationType}`. Les permissions requises sont `organization:integrations:read` et `organization:integrations:write` (elles remplacent `organization:apps:*`).
| Méthode | Chemin | Description |
|--------|------|-------------|
| GET | `/integrations/{integrationType}` | Statut (`installed`, `available`) et `settings` masqués |
| POST | `/integrations/{integrationType}` | Installer (`settings` facultatif dans le corps ; OAuth peut renvoyer `redirectUrl`) |
| PUT | `/integrations/{integrationType}` | Mettre à jour les réglages (`settings` dans le corps) |
| DELETE | `/integrations/{integrationType}` | Désinstaller |
Avec `GET` et après `PUT`, `settings` ne contient que les champs **publics**, plus `{ configured: true }` par champ secret. Les mots de passe, clés API et jetons OAuth ne sont pas renvoyés. Laissez les champs secrets vides lors d'un `PUT` pour conserver la valeur existante.
Voir la [spécification OpenAPI](https://tillor.eu/api/openapi.json) (tag `integrations`) pour les schémas exacts.
---
## Voir aussi [#gerelateerd]
- [Référence de l'API](/api-referentie) - Chaque endpoint, à tester dans le navigateur
- [OpenAPI](https://tillor.eu/api/openapi.json) - Spécification de l'API (JSON)
- [MCP](/ontwikkelaars/mcp) - Connecter Cursor, Claude, ChatGPT ou Gemini via OAuth
- [Notifications externes](/ontwikkelaars/externe-notificaties) - Enregistrer les e-mails envoyés par votre propre système
- [Webhooks](/ontwikkelaars/webhooks) - Recevoir des événements via HTTP POST
- [Webhook entrant d'une automatisation](/ontwikkelaars/automatiseringen#een-automatisering-starten-met-een-webhook) - Démarrer une automatisation avec un POST, sans clé API
- [SSE](/ontwikkelaars/sse) - Diffuser des événements via Server-Sent Events
- [Exemples](/ontwikkelaars/voorbeelden) - Exemples de code et de charges utiles