# REST API pro CRM s podepsanými webhooky | AiCrm

> CRM s veřejným REST API: vytvářej a čti kontakty pomocí hlavičky X-Api-Key, až 20 klíčů pro integrace a odchozí webhooky podepsané HMAC-SHA256. Přidávání leadů z webu bez duplicit.

- **Zdroj (source):** https://aistohire.com/cs/aicrm-jednoduche-crm-s-api-pro-spravu-klientu-a-leadu-109/f/rest-api-crm-podepsane-webhooky
- **Platforma (platform):** AIstoHire
- **Jazyk (language):** cs

## Ve zkratce

- Veřejné REST API s více API klíči a podepsanými webhooky
- Přidávej zákazníky z webu, formuláře nebo backendu jediným HTTP voláním a každou změnu dostávej na svůj server podepsanou HMAC-SHA256.
- Přidání kontaktů jediným voláním
- Duplicity jsou vyloučené už návrhem
- Až 20 pojmenovaných klíčů

## Veřejné REST API s více API klíči a podepsanými webhooky

AiCrm, CRM aplikace od AIsToHire, nabízí veřejné REST API nad tvými vlastními kontakty. S klíčem v hlavičce `X-Api-Key` můžeš kontakty vytvářet, vypisovat, zobrazovat, aktualizovat a mazat a přidávat k nim aktivity, a to z formuláře na webu, chatbota, Zapu, skriptu v Pythonu nebo z vlastního backendu. Odpovědi jsou JSON ve tvaru `{ success, data }` a limit je 100 požadavků za minutu na klíč.

Přidání přes API nevytváří duplicity: pokud e-mail, který pošleš, už ve tvé databázi existuje, AiCrm aktualizuje kartu, kterou už máš (doplní chybějící telefon, jméno nebo firmu, spojí štítky) a zapíše do její časové osy nové odeslání s odpovědí HTTP 200; pokud je nový, vytvoří ho a vrátí 201. Každý kontakt, který přijde přes API, se automaticky označí jako `api-lead`, zachová štítky, které pošleš, a uloží původní `subId`, a také zemi, IP adresu a prohlížeč, ze kterých přišel.

Můžeš mít až 20 API klíčů s vlastním názvem, navíc k internímu klíči aplikace. Každé integraci tak dáš jiný klíč — webu, formuláři květnové kampaně, brigádníkovi, dodavateli — a když integrace skončí, zrušíš jen ten její, aniž bys sáhl na ostatní. Celá hodnota klíče se zobrazí jen jednou, při vytvoření; poté ji ve výpisu uvidíš jen maskovanou.

Opačným směrem upozorňují webhooky tvé systémy. Nastavíš až 10 cílů, u každého vybereš, které události odebírá (`customer.created`, `customer.updated`, `customer.deleted`, `activity.created`) a AiCrm pošle POST na tvou URL s hlavičkami `X-AiCrm-Event` a `X-AiCrm-Signature: sha256=…`, což je podpis HMAC-SHA256 těla pomocí tajného klíče daného webhooku, abys mohl ověřit, že je doručení pravé. Při uložení URL ochrana proti SSRF odmítne localhost, 127.0.0.0/8, 10.x, 192.168.x, 172.16-31.x, ::1, 0.0.0.0 a domény `.local` a `.internal`.

## Co obsahuje

- **Přidání kontaktů jediným voláním** — POST na `/api/apps/public/crm/customers` s e-mailem a štítky, které chceš, a lead je ve tvém CRM hned zařazený.
- **Duplicity jsou vyloučené už návrhem** — pokud e-mail už existuje, karta se aktualizuje a nové odeslání se zapíše do její časové osy místo vytvoření druhé karty.
- **Až 20 pojmenovaných klíčů** — jeden pro každou integraci, každý zrušitelný zvlášť. Když klíč unikne, smažeš jen ten a nic dalšího přestane fungovat.
- **Webhooky podepsané HMAC-SHA256** — ověříš hlavičku `X-AiCrm-Signature` svým tajným klíčem a víš, že upozornění přichází z tvého CRM, a ne od někoho třetího.
- **Součástí je ochrana proti SSRF** — aplikace odmítne doručovat webhooky na localhost nebo do soukromých rozsahů sítě, takže tvé CRM nelze zneužít ke zkoumání vnitřní sítě.
- **Plné CRUD, nejen přidávání** — výpis se stránkováním a filtry (vyhledávání, stav, štítky, země), zobrazení kontaktu s jeho aktivitou, úprava, smazání a zapisování aktivit.
- **Původ se zaznamenává automaticky** — každé přidání přes API uloží `subId`, který pošleš, plus zemi, IP adresu a prohlížeč, a označí se štítkem `api-lead`, abys ho mohl v aplikaci snadno vyfiltrovat.
- **Testování bez hádání** — aplikace obsahuje dokumentaci endpointů s ukázkou `curl`, kterou lze zkopírovat, a tlačítko pro odeslání testovacího doručení na každý webhook se stavem a časem posledního pokusu.

## Často kladené otázky

### Jak vytvořím kontakt v CRM ze svého webu?

Pošleš POST na `/api/apps/public/crm/customers` s hlavičkou `X-Api-Key` a JSON, který obsahuje alespoň e-mail nebo telefon. Můžeš poslat také jméno, telefon, firmu, zemi, stav, poznámky, štítky a `subId`, kterým označíš kampaň nebo formulář, odkud kontakt přišel. AiCrm vrátí 201, pokud kontakt vytvoří, a 200, pokud už existoval.

### Co se stane, když stejný e-mail přijde přes API dvakrát?

Nezduplikuje se. AiCrm vyhledá e-mail (nebo telefon, pokud e-mail neposíláš) a pokud ho najde, aktualizuje existující kartu: doplní pole, která byla prázdná, připojí nové štítky ke stávajícím a zapíše nové odeslání do její časové osy aktivit. Odpověď uvádí, že kontakt už existoval, a vrací jeho id.

### Kolik API klíčů mohu mít a mohu zrušit jen jeden?

Můžeš vytvořit až 20 klíčů s vlastním názvem, navíc k internímu klíči aplikace, který nelze smazat. Každý klíč se maže nezávisle, takže můžeš každé integraci dát jiný a zrušit ho bez vlivu na ostatní. Celá hodnota se zobrazí pouze v okamžiku vytvoření; poté je ve výpisu maskovaná. Všechny klíče sdílejí limit 100 požadavků za minutu na klíč.

### Jak ověřím, že webhook opravdu přichází z mého CRM?

Každé doručení nese hlavičku `X-AiCrm-Signature: sha256=<podpis>`, což je HMAC-SHA256 přesného těla požadavku vypočtený pomocí tajného klíče, který ti aplikace ukáže při vytvoření webhooku. Spočítej tento HMAC na svém serveru z přijatého těla a porovnej ho. Kromě toho se posílá hlavička `X-AiCrm-Event` s názvem události: `customer.created`, `customer.updated`, `customer.deleted` nebo `activity.created`.

### Co se stane, když můj endpoint webhooku nefunguje?

Doručení probíhá systémem best-effort: AiCrm čeká až 5 sekund a pokud selže, po vteřině a půl to zkusí ještě jednou. Neexistuje trvalá fronta opakování, takže při dlouhém výpadku tvého serveru můžeš o upozornění přijít; v takovém případě proveď synchronizaci pomocí GET na `/api/apps/public/crm/customers`. Aplikace ti ukáže stav a čas posledního pokusu u každého webhooku a testovací doručení můžeš spustit kdykoli.

- [AiCrm — Lehké CRM s API pro zakládání klientů z jakéhokoli systému](https://aistohire.com/cs/aicrm-jednoduche-crm-s-api-pro-spravu-klientu-a-leadu-109)

## O platformě

**AiCrm — Lehké CRM s API pro zakládání klientů z jakéhokoli systému** — aplikace pro AIstoHire. Dostupné v: https://aistohire.com/cs/aicrm-jednoduche-crm-s-api-pro-spravu-klientu-a-leadu-109/f/rest-api-crm-podepsane-webhooky

### Další jazyky

- `es`: https://aistohire.com/es/aicrm-crm-ligero-con-api-109/f/api-rest-crm-webhooks-firmados
- `en`: https://aistohire.com/aicrm-lightweight-crm-with-api-109/f/api-rest-crm-signed-webhooks
- `fr`: https://aistohire.com/fr/aicrm-crm-leger-avec-api-109/f/api-rest-crm-webhooks-signes
- `it`: https://aistohire.com/it/aicrm-crm-leggero-con-api-109/f/api-rest-crm-webhook-firmati
- `pt`: https://aistohire.com/pt/aicrm-crm-leve-com-api-109/f/api-rest-crm-webhooks-assinados
- `de`: https://aistohire.com/de/aicrm-leichtes-crm-mit-api-109/f/api-rest-crm-signierte-webhooks
- `bg`: https://aistohire.com/bg/aicrm-lesen-crm-s-api-za-upravlenie-na-klienti-i-liydove-109/f/rest-api-crm-podpisani-uebhukove
- `ja`: https://aistohire.com/ja/aicrm-lightweight-crm-with-api-109/f/crm-rest-api-signed-webhooks
- `nl`: https://aistohire.com/nl/aicrm-eenvoudige-crm-met-api-om-klanten-en-leads-te-beheren-109/f/rest-api-crm-ondertekende-webhooks
- `ko`: https://aistohire.com/ko/aicrm-api-gyeongnyang-crm-109/f/crm-rest-api-seomyeong-webhook
- `sv`: https://aistohire.com/sv/aicrm-enkelt-crm-med-api-for-att-hantera-kunder-och-leads-109/f/rest-api-crm-signerade-webhooks
- `da`: https://aistohire.com/da/aicrm-enkelt-crm-med-api-til-at-styre-kunder-og-leads-109/f/rest-api-crm-signerede-webhooks
- `ar`: https://aistohire.com/ar/aicrm-nzam-crm-bsit-ma-api-lidara-alamla-walamla-almhtmlin-109/f/crm-rest-api-webhooks
- `no`: https://aistohire.com/no/aicrm-enkelt-crm-med-api-for-a-styre-kunder-og-leads-109/f/rest-api-crm-signerte-webhooks
- `fi`: https://aistohire.com/fi/aicrm-yksinkertainen-crm-rajapinnalla-asiakkaille-ja-liideille-109/f/crm-rest-api-allekirjoitetut-webhookit
- `zh`: https://aistohire.com/zh/ai-crm-rest-api-webhooks-109/f/crm-rest-api-webhook
- `pl`: https://aistohire.com/pl/aicrm-prosty-crm-z-api-do-zarzadzania-klientami-i-leadami-109/f/api-rest-crm-podpisane-webhooki
- `he`: https://aistohire.com/he/aicrm-crm-pshot-am-api-lnihol-lkochot-vlidim-109/f/api-rest-crm-webhooks-chatumim
- `id`: https://aistohire.com/id/aicrm-crm-sederhana-dengan-api-untuk-mengelola-pelanggan-dan-lead-109/f/api-rest-crm-webhook-bertanda-tangan
