Prezentare generală
Twenty oferă atât GraphQL, cât și API-uri REST pentru importul programatic de date. Utilizați API-ul când importul CSV nu este practic pentru volumul dvs. de date sau când aveți nevoie de importuri automate, recurente.Când să utilizați importul prin API
| Scenariu | Metodă recomandată |
|---|---|
| Sub 10.000 de înregistrări | Import CSV |
| 10.000 - 50.000 de înregistrări | Import CSV (împărțit în fișiere) |
| Peste 50.000 de înregistrări | Import prin API |
| Migrare unică | Oricare (în funcție de volum) |
| Importuri recurente | Import prin API |
| Sincronizare în timp real | Import prin API |
| Integrare cu alte sisteme | Import prin API |
Pentru seturi de date de ordinul sutelor de mii, API-ul este semnificativ mai rapid și mai fiabil decât importurile CSV multiple.
Limitări de rată API
Twenty impune limitări de rată pentru a asigura stabilitatea sistemului:| Limită | Valoare |
|---|---|
| Cereri pe minut | 100 |
| Înregistrări per apel de lot | 60 |
| Debit maxim | ~6.000 înregistrări/minut |
Începeți
Pasul 1: Obțineți cheia API
- Accesați Setări → Dezvoltatori
- Faceți clic pe + Creați cheie API
- Dați cheii un nume descriptiv
- Copiați imediat cheia API (nu va mai fi afișată).
- Stocați-o în siguranță
Pasul 2: Alegeți API-ul
Twenty acceptă două tipuri de API:| API | Cel mai potrivit pentru | Documentație |
|---|---|---|
| GraphQL | Interogări flexibile, preluarea datelor asociate, operațiuni complexe | Documentație API |
| REST | Operațiuni CRUD simple, tipare REST familiare | Documentație API |
- Crearea, citirea, actualizarea și ștergerea înregistrărilor
- Operațiuni în lot — creați sau actualizați până la 60 de înregistrări per apel
Pasul 3: Planificați ordinea de import
La fel ca la importurile CSV, ordinea contează pentru relații:- Companii mai întâi (fără dependențe)
- Persoane în al doilea rând (pot fi legate de Companii)
- Oportunități în al treilea rând (pot fi legate de Companii și Persoane)
- Sarcini/Note (pot fi legate de oricare dintre cele de mai sus)
- Obiecte personalizate (respectând dependențele lor)
Cele mai bune practici
Grupați cererile în loturi
- Nu trimiteți înregistrările una câte una
- Grupați până la 60 de înregistrări per apel API
- Aceasta maximizează debitul în limitele de rată
Gestionați limitările de rată
- Implementați întârzieri între cereri (minim 600 ms pentru importuri susținute)
- Utilizați backoff exponențial când atingeți limitele
- Monitorizați răspunsurile 429 (Too Many Requests)
Validați datele mai întâi
- Curățați și validați datele înainte de import
- Verificați ca câmpurile obligatorii să fie completate
- Verificați că formatele corespund cerințelor Twenty (consultați Maparea câmpurilor)
Jurnalizați totul
- Jurnalizați fiecare înregistrare importată (inclusiv ID-urile)
- Jurnalizați erorile cu tot contextul
- Acest lucru ajută la depanarea problemelor și la verificarea finalizării
Testați mai întâi
- Testați cu un lot mic (10-20 de înregistrări)
- Verificați că datele apar corect în Twenty
- Apoi rulați importul complet
Upsert pentru a evita duplicatele
API-ul GraphQL acceptă upsert în lot — actualizați dacă înregistrarea există, creați dacă nu. Acest lucru previne duplicatele când rulați din nou importurile.Găsirea numelor de obiecte și câmpuri
Pentru a vedea obiectele și câmpurile disponibile:- Accesați Setări → API și webhook-uri
- Explorați Metadata API
- Vizualizați toate obiectele standard și personalizate cu câmpurile lor
Servicii Profesionale
Pentru migrații API complexe, partenerii noștri vă pot ajuta:| Serviciu | Ce este inclus |
|---|---|
| Proiectarea modelului de date | proiectați structura optimă a datelor |
| Scripturi de migrare | scrieți și rulați scripturile de import |
| Transformare de date | gestionați maparea complexă și curățarea |
| Validare și QA | verificați că migrarea este completă |
- Migrări de peste 100.000 de înregistrări
- Transformări complexe ale datelor
- Termene strânse
- Echipe fără resurse de dezvoltare
Întrebări frecvente
Care este diferența dintre GraphQL și REST?
Care este diferența dintre GraphQL și REST?
GraphQL vă permite să solicitați exact datele de care aveți nevoie într-o singură interogare și este mai potrivit pentru operațiuni complexe. REST folosește metode HTTP standard (GET, POST, PUT, DELETE) și poate fi mai familiar dacă ați lucrat cu API-uri tradiționale.
Pot actualiza înregistrările existente prin API?
Pot actualiza înregistrările existente prin API?
Da! Utilizați mutații de tip update (GraphQL) sau cereri PUT/PATCH (REST) cu
id-ul înregistrării.Cum gestionez duplicatele?
Cum gestionez duplicatele?
Interogați mai întâi înregistrările existente folosind identificatori unici (email, domeniu). Actualizați dacă există, creați dacă nu.
Pot șterge înregistrări prin API?
Pot șterge înregistrări prin API?
Da, utilizați mutații de tip delete (GraphQL) sau cereri DELETE (REST).
Există un SDK pentru Python sau Node.js?
Există un SDK pentru Python sau Node.js?
În prezent nu, dar ambele API-uri funcționează cu orice client HTTP, în orice limbaj.