Twenty bylo vytvořeno s ohledem na vývojáře, nabízíme výkonné API, které se přizpůsobí vašemu vlastnímu datovému modelu. Nabízíme čtyři typy API, které splňují různé potřeby integrace.
Přístup orientovaný na vývojáře
Twenty generuje API specificky pro váš datový model:
- Nejsou vyžadována dlouhá ID: Používejte v koncových bodech přímo názvy objektů a polí.
- Standardní a vlastní objekty jsou rovnocenně zpracovány: Vaše vlastní objekty mají stejnou podporu API jako vestavěné.
- Vyhrazené koncové body: Každý objekt a pole má svůj vlastní koncový bod API.
- Vlastní dokumentace: Generována specificky pro datový model vašeho pracovního prostoru.
Vaše personalizovaná dokumentace k API je dostupná v Nastavení → API & Webhooks po vytvoření API klíče. Protože Twenty generuje API odpovídající vašemu vlastnímu datovému modelu, dokumentace je jedinečná pro váš pracovní prostor.
Dva typy API
Core API
Přístupné na /rest/ nebo /graphql/
Pracujte se svými skutečnými záznamy (daty):
- Vytvářejte, čtěte, aktualizujte a mazejte Lidi, Společnosti, Příležitosti atd.
- Dotazujte a filtrujte data
- Spravování vztahů mezi záznamy.
Přístupné na /rest/metadata/ nebo /metadata/
Spravujte svůj pracovní prostor a datový model:
- Vytvářet, upravovat nebo mazat objekty a pole.
- Konfigurace nastavení pracovního prostoru.
- Definujte vztahy mezi objekty
REST vs GraphQL
Jak Core, tak Metadata API jsou k dispozici ve formátech REST a GraphQL:
| Formát | Dostupné operace |
|---|
| REST | CRUD, hromadné operace, operace upsert |
| GraphQL | Stejné + hromadné operace upsert, dotazy na vztahy v jednom volání |
Koncové body API
| Prostředí | Základní URL |
|---|
| Cloud | https://api.twenty.com/ |
| Vlastní hosting | https://{your-domain}/ |
Ověření
Každý požadavek na API vyžaduje klíč API v hlavičce:
Authorization: Bearer YOUR_API_KEY
Vytvořit API klíč
- Přejděte na Nastavení → APIs & Webhooks
- Klikněte na + Vytvořit klíč
- Nakonfigurujte:
- Název: Popisný název pro klíč
- Datum vypršení platnosti: Kdy klíč vyprší
- Klikněte na Uložit
- Zkopírujte ihned — klíč se zobrazí pouze jednou
Váš klíč API poskytuje přístup k citlivým datům. Nesdílejte ho s nedůvěryhodnými službami. Pokud je kompromitován, okamžitě ho deaktivujte a vygenerujte nový.
Přiřaďte roli klíči API
Pro vyšší bezpečnost přiřaďte konkrétní roli, abyste omezili přístup:
- Přejděte na Nastavení → Role
- Klikněte na roli, kterou chcete přiřadit
- Otevřete záložku Přiřazení
- V části API Keys klikněte na + Přiřadit ke klíči API
- Vyberte klíč API
Klíč zdědí oprávnění této role. Podrobnosti viz Oprávnění.
Spravovat API klíče
Znovu vygenerovat: Nastavení → APIs & Webhooks → Klikněte na klíč → Znovu vygenerovat
Smazat: Nastavení → APIs & Webhooks → Klikněte na klíč → Smazat
API Playground
Testujte svá API přímo v prohlížeči pomocí našeho vestavěného playgroundu — k dispozici pro REST i GraphQL.
Přístup do Playgroundu
- Přejděte na Nastavení → APIs & Webhooks
- Vytvořte klíč API (povinné)
- Klikněte na REST API nebo GraphQL API pro otevření playgroundu
Co získáte
- Interaktivní dokumentace: Generována pro váš specifický datový model
- Živé testování: Spouštějte reálná volání API vůči vašemu pracovnímu prostoru
- Průzkumník schématu: Procházejte dostupné objekty, pole a vztahy
- Tvůrce požadavků: Sestavujte dotazy s automatickým doplňováním
Playground odráží vaše vlastní objekty a pole, takže dokumentace je pro váš pracovní prostor vždy přesná.
Hromadné operace
REST i GraphQL podporují hromadné operace:
- Velikost dávky: Až 60 záznamů na požadavek.
- Operace: Vytváření, aktualizace a mazání více záznamů
Funkce pouze pro GraphQL:
- Hromadný upsert: Vytvoření nebo aktualizace v jednom volání
- Používejte množná čísla názvů objektů (např.
CreateCompanies místo CreateCompany)
Limity rychlosti
Požadavky na API jsou omezovány, aby byla zajištěna stabilita platformy:
| Limit | Hodnota |
|---|
| Požadavky | 100 volání za minutu |
| Velikost dávky | 60 záznamů na volání |
Pro maximalizaci propustnosti používejte hromadné operace — zpracujte až 60 záznamů v jediném volání API místo odesílání jednotlivých požadavků.
