148 lines
5.8 KiB
Plaintext
148 lines
5.8 KiB
Plaintext
---
|
|
title: API
|
|
description: Interrogez et modifiez vos données CRM par programmation à l'aide de REST ou de GraphQL.
|
|
---
|
|
|
|
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
|
|
|
Twenty a été conçu pour être convivial pour les développeurs, offrant des API puissantes qui s'adaptent à votre modèle de données personnalisé. Nous fournissons quatre types d'API distincts pour répondre à différents besoins d'intégration.
|
|
|
|
## Approche axée sur les développeurs
|
|
|
|
Twenty génère des API spécifiquement pour votre modèle de données :
|
|
|
|
* **Pas besoin d'ID longs** : Utilisez directement les noms de vos objets et champs dans les points de terminaison
|
|
* **Objets standard et personnalisés traités à égalité** : Vos objets personnalisés bénéficient du même traitement API que ceux intégrés
|
|
* **Points de terminaison dédiés** : Chaque objet et champ a son propre point de terminaison API
|
|
* **Documentation personnalisée** : Générée spécifiquement pour le modèle de données de votre espace de travail
|
|
|
|
<Note>
|
|
Votre documentation API personnalisée est disponible sous **Paramètres → API & Webhooks** après la création d'une clé API. Comme Twenty génère des API qui correspondent à votre modèle de données personnalisé, la documentation est propre à votre espace de travail.
|
|
</Note>
|
|
|
|
## Les deux types d'API
|
|
|
|
### API principale
|
|
|
|
Accessible sur `/rest/` ou `/graphql/`
|
|
|
|
Travaillez avec vos **enregistrements** réels (les données) :
|
|
|
|
* Créer, lire, mettre à jour, supprimer People, Companies, Opportunities, etc.
|
|
* Interroger et filtrer les données
|
|
* Gérer les relations entre les enregistrements
|
|
|
|
### API de métadonnées
|
|
|
|
Accessible sur `/rest/metadata/` ou `/metadata/`
|
|
|
|
Gérez votre **espace de travail et votre modèle de données** :
|
|
|
|
* Créer, modifier ou supprimer des objets et des champs
|
|
* Configurer les paramètres de l'espace de travail
|
|
* Définir les relations entre les objets
|
|
|
|
## REST vs GraphQL
|
|
|
|
Les API Core et Metadata sont disponibles aux formats REST et GraphQL :
|
|
|
|
| Format | Opérations disponibles |
|
|
| ----------- | ----------------------------------------------------------------------- |
|
|
| **REST** | CRUD, opérations par lot, upserts |
|
|
| **GraphQL** | Identique + **upserts par lot**, requêtes de relations en un seul appel |
|
|
|
|
Choisissez selon vos besoins — les deux formats accèdent aux mêmes données.
|
|
|
|
## Points d'accès API
|
|
|
|
| Environnement | URL de base |
|
|
| ---------------- | ------------------------- |
|
|
| **Cloud** | `https://api.twenty.com/` |
|
|
| **Auto-hébergé** | `https://{your-domain}/` |
|
|
|
|
## Authentification
|
|
|
|
Chaque requête API nécessite une clé API dans l'en-tête :
|
|
|
|
```
|
|
Authorization: Bearer YOUR_API_KEY
|
|
```
|
|
|
|
### Créer une clé API
|
|
|
|
1. Allez dans **Paramètres → API & Webhooks**
|
|
2. Cliquez sur **+ Créer une clé**
|
|
3. Configurer:
|
|
* **Nom** : Nom descriptif pour la clé
|
|
* **Date d'expiration** : Date à laquelle la clé expire
|
|
4. Cliquez sur **Enregistrer**
|
|
5. **Copiez immédiatement** — la clé n'est affichée qu'une seule fois
|
|
|
|
<VimeoEmbed videoId="928786722" title="Création d'une clé API" />
|
|
|
|
<Warning>
|
|
Votre clé API donne accès à des données sensibles. Ne la partagez pas avec des services non fiables. Si elle est compromise, désactivez-la immédiatement et générez-en une nouvelle.
|
|
</Warning>
|
|
|
|
### Attribuer un rôle à une clé API
|
|
|
|
Pour une meilleure sécurité, attribuez un rôle spécifique pour limiter l'accès :
|
|
|
|
1. Allez dans **Paramètres → Rôles**
|
|
2. Cliquez sur le rôle à attribuer
|
|
3. Ouvrez l'onglet **Attribution**
|
|
4. Sous **Clés API**, cliquez sur **+ Attribuer à une clé API**
|
|
5. Sélectionnez la clé API
|
|
|
|
La clé héritera des autorisations de ce rôle. Voir [Autorisations](/l/fr/user-guide/permissions-access/capabilities/permissions) pour plus de détails.
|
|
|
|
### Gérer les clés API
|
|
|
|
**Régénérer** : Paramètres → API & Webhooks → Cliquez sur la clé → **Régénérer**
|
|
|
|
**Supprimer** : Paramètres → API & Webhooks → Cliquez sur la clé → **Supprimer**
|
|
|
|
## Bac à sable API
|
|
|
|
Testez vos API directement dans le navigateur avec notre bac à sable intégré — disponible pour **REST** et **GraphQL**.
|
|
|
|
### Accéder au bac à sable
|
|
|
|
1. Allez dans **Paramètres → API & Webhooks**
|
|
2. Créer une clé API (obligatoire)
|
|
3. Cliquez sur **REST API** ou **GraphQL API** pour ouvrir le bac à sable
|
|
|
|
### Ce que vous obtenez
|
|
|
|
* **Documentation interactive** : Générée pour votre modèle de données spécifique
|
|
* **Tests en direct** : Exécutez de véritables appels API sur votre espace de travail
|
|
* **Explorateur de schéma** : Parcourez les objets, champs et relations disponibles
|
|
* **Générateur de requêtes** : Construisez des requêtes avec l'autocomplétion
|
|
|
|
Le bac à sable reflète vos objets et champs personnalisés, de sorte que la documentation est toujours précise pour votre espace de travail.
|
|
|
|
## Opérations par Lot
|
|
|
|
REST et GraphQL prennent en charge les opérations par lot :
|
|
|
|
* **Taille du lot** : Jusqu'à 60 enregistrements par requête
|
|
* **Opérations** : Créer, mettre à jour, supprimer plusieurs enregistrements
|
|
|
|
**Fonctionnalités spécifiques à GraphQL :**
|
|
|
|
* **Upsert par lot** : Créer ou mettre à jour en un seul appel
|
|
* Utilisez des noms d'objets au pluriel (par exemple, `CreateCompanies` au lieu de `CreateCompany`)
|
|
|
|
## Limites de débit
|
|
|
|
Les requêtes API sont limitées pour garantir la stabilité de la plateforme :
|
|
|
|
| Limite | Valeur |
|
|
| ----------------- | ---------------------------- |
|
|
| **Requêtes** | 100 appels par minute |
|
|
| **Taille du lot** | 60 enregistrements par appel |
|
|
|
|
<Tip>
|
|
Utilisez les opérations par lot pour maximiser le débit — traitez jusqu'à 60 enregistrements dans un seul appel API au lieu d'effectuer des requêtes individuelles.
|
|
</Tip>
|