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
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:Î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:
Ambele API-uri acceptă:
- 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:
Cel mai potrivit pentru:
- 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.