---
title: Importați date prin API
description: Când și cum să utilizați API-urile Twenty pentru importuri de date la scară mare.
---

## 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**              |

<Note>Pentru seturi de date de ordinul sutelor de mii, API-ul este semnificativ mai rapid și mai fiabil decât importurile CSV multiple.</Note>

## 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 |

<Warning>
**Planificați importul în jurul acestor limite.**

Pentru 100.000 de înregistrări la debit maxim, așteptați-vă la aproximativ 17 minute de timp de import. Adăugați timp tampon pentru gestionarea erorilor și reîncercări.
</Warning>

## Începeți

### Pasul 1: Obțineți cheia API

1. Accesați **Setări → Dezvoltatori**
2. Faceți clic pe **+ Creați cheie API**
3. Dați cheii un nume descriptiv
4. Copiați imediat cheia API (nu va mai fi afișată).
5. Stocați-o în siguranță

<Warning>
**Păstrați cheia API secretă.**

Oricine are cheia dvs. API poate accesa și modifica datele din spațiul dvs. de lucru. Nu o includeți niciodată în repozitorii de cod și nu o distribuiți public.
</Warning>

### 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](/l/ro/developers/extend/api) |
| **REST**    | Operațiuni CRUD simple, tipare REST familiare                         | [Documentație API](/l/ro/developers/extend/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

**Pentru importuri, utilizați operațiuni în lot** pentru a maximiza debitul în limitele de rată.

### Pasul 3: Planificați ordinea de import

La fel ca la importurile CSV, **ordinea contează** pentru relații:

1. **Companii** mai întâi (fără dependențe)
2. **Persoane** în al doilea rând (pot fi legate de Companii)
3. **Oportunități** în al treilea rând (pot fi legate de Companii și Persoane)
4. **Sarcini/Note** (pot fi legate de oricare dintre cele de mai sus)
5. **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](/l/ro/user-guide/data-migration/capabilities/field-mapping))

### 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:

1. Accesați **Setări → API și webhook-uri**
2. Explorați **Metadata API**
3. Vizualizați toate obiectele standard și personalizate cu câmpurile lor

Documentația prezintă toate obiectele standard și personalizate, câmpurile acestora și tipurile de date așteptate.

## 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ă     |

**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

Contactați-ne la [contact@twenty.com](mailto:contact@twenty.com) sau explorați [Serviciile noastre de implementare](/l/ro/user-guide/getting-started/capabilities/implementation-services).

## Întrebări frecvente

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Cum gestionez duplicatele?">
    Interogați mai întâi înregistrările existente folosind identificatori unici (email, domeniu). Actualizați dacă există, creați dacă nu.
  </Accordion>

  <Accordion title="Pot șterge înregistrări prin API?">
    Da, utilizați mutații de tip delete (GraphQL) sau cereri DELETE (REST).
  </Accordion>

  <Accordion title="Există un SDK pentru Python sau Node.js?">
    În prezent nu, dar ambele API-uri funcționează cu orice client HTTP, în orice limbaj.
  </Accordion>
</AccordionGroup>

## Documentație API

Pentru detalii complete de implementare, exemple de cod și referință de schemă:

* [Documentație API](/l/ro/developers/extend/api)