Twenty a fost creat pentru a fi prietenos cu dezvoltatorii, oferind API-uri puternice care se adaptează la modelul dvs. de date personalizat. Oferim patru tipuri distincte de API-uri pentru a satisface diferite nevoi de integrare.
Abordare orientată către dezvoltatori
Twenty generează API-uri special pentru modelul dvs. de date:
- Nu sunt necesare ID-uri lungi: Utilizați direct numele obiectelor și câmpurilor în punctele finale
- Obiectele standard și personalizate tratate în mod egal: Obiectele dvs. personalizate primesc același tratament API ca și cele încorporate
- Puncte finale dedicate: Fiecare obiect și câmp primește propriul său punct final API
- Documentație personalizată: Generată special pentru modelul de date al spațiului dvs. de lucru
Documentația API personalizată este disponibilă la Settings → API & Webhooks după crearea unei chei API. Deoarece Twenty generează API-uri care se potrivesc modelului dvs. de date personalizat, documentația este unică pentru spațiul dvs. de lucru.
Cele două tipuri de API-uri
API Core
Accesibil prin /rest/ sau /graphql/
Lucrați cu înregistrările reale (datele):
- Creați, citiți, actualizați, ștergeți Persoane, Companii, Oportunități etc.
- Interogați și filtrați datele
- Gestionați relațiile de înregistrări
Accesibil prin /rest/metadata/ sau /metadata/
Gestionați-vă spațiul de lucru și modelul de date:
- Creați, modificați sau ștergeți obiecte și câmpuri
- Configurați setările spațiului de lucru
- Definiți relațiile dintre obiecte
REST vs GraphQL
Atât API-urile Core, cât și API-urile Metadata sunt disponibile în formatele REST și GraphQL:
| Format | Operațiuni disponibile |
|---|
| REST | CRUD, operațiuni de grup, upsert-uri |
| GraphQL | La fel + upsert-uri de grup, interogări de relații într-un singur apel |
Puncte Finale API
| Mediu | URL de bază |
|---|
| Cloud | https://api.twenty.com/ |
| Găzduire proprie | https://{your-domain}/ |
Autentificare
Fiecare solicitare API necesită o cheie API în antet:
Authorization: Bearer YOUR_API_KEY
Creați o cheie API
- Mergeți la Setări → API-uri & Webhook-uri
- Faceți clic pe + Create key
- Configurați:
- Name: Nume descriptiv pentru cheie
- Expiration Date: Când expiră cheia
- Faceți clic pe Salvare
- Copiați imediat — cheia este afișată o singură dată
Cheia dvs. API oferă acces la date sensibile. Nu o partajați cu servicii care nu sunt de încredere. Dacă este compromisă, dezactivați-o imediat și generați una nouă.
Atribuiți un rol unei chei API
Pentru o securitate sporită, atribuiți un rol specific pentru a limita accesul:
- Accesați Setări → Roluri
- Faceți clic pe rolul pe care doriți să-l atribuiți
- Deschideți fila Atribuire
- În API Keys, faceți clic pe + Assign to API key
- Selectați cheia API
Cheia va moșteni permisiunile acelui rol. Consultați Permisiuni pentru detalii.
Gestionați cheile API
Regenerate: Settings → APIs & Webhooks → Faceți clic pe cheie → Regenerate
Delete: Settings → APIs & Webhooks → Faceți clic pe cheie → Delete
Testați API-urile direct în browser cu platforma noastră integrată de testare — disponibilă atât pentru REST, cât și pentru GraphQL.
- Mergeți la Setări → API-uri & Webhook-uri
- Creați o cheie API (obligatoriu)
- Faceți clic pe REST API sau GraphQL API pentru a deschide platforma de testare
Ce obțineți
- Documentație interactivă: Generată pentru modelul dvs. de date specific
- Testare live: Executați apeluri API reale către spațiul dvs. de lucru
- Explorator de scheme: Parcurgeți obiectele, câmpurile și relațiile disponibile
- Constructor de cereri: Construiți interogări cu completare automată
Platforma de testare reflectă obiectele și câmpurile dvs. personalizate, astfel încât documentația este întotdeauna corectă pentru spațiul dvs. de lucru.
Operațiuni de grup
Atât REST, cât și GraphQL suportă operațiuni de grup:
- Dimensiunea grupului: Până la 60 de înregistrări pe cerere
- Operațiuni: Creați, actualizați, ștergeți mai multe înregistrări
Funcții exclusive GraphQL:
- Upsert de grup: Creați sau actualizați într-un singur apel
- Folosiți nume de obiecte la plural (de exemplu,
CreateCompanies în loc de CreateCompany)
Limitări de rată
Solicitările API sunt limitate pentru a asigura stabilitatea platformei:
| Limită | Valoare |
|---|
| Solicitări | 100 de apeluri pe minut |
| Dimensiunea lotului | 60 de înregistrări pe apel |
Utilizați operațiunile de grup pentru a maximiza debitul — procesați până la 60 de înregistrări într-un singur apel API în loc să faceți solicitări individuale.
