# REST API за CRM с подписани уебхукове | AiCrm

> CRM с публичен REST API: създавайте контакти с хедър X-Api-Key, до 20 ключа и уебхукове, подписани с HMAC-SHA256. Лийдове от сайта ви без дубликати.

- **Източник (source):** https://aistohire.com/bg/aicrm-lesen-crm-s-api-za-upravlenie-na-klienti-i-liydove-109/f/rest-api-crm-podpisani-uebhukove
- **Платформа (platform):** AIstoHire
- **Език (language):** bg

## Накратко

- Публичен REST API с няколко API ключа и подписани уебхукове
- Добавяйте клиенти от уебсайта, формуляра или бекенда си с едно HTTP извикване и получавайте всяка промяна на сървъра си, подписана с HMAC-SHA256.
- Добавяне на контакти с едно извикване
- Без дубликати по дизайн
- До 20 именувани ключа

## Публичен REST API с няколко API ключа и подписани уебхукове

AiCrm, CRM приложението на AIsToHire, предоставя публичен REST API върху вашите собствени контакти. С ключ в хедъра `X-Api-Key` можете да създавате, изброявате, разглеждате, актуализирате и изтривате контакти и да добавяте активности към всеки от тях — от формуляра на уебсайта си, от чатбота, от Zap, от скрипт на Python или от собствения си бекенд. Отговорите са JSON във формата `{ success, data }`, а лимитът е 100 заявки в минута на ключ.

Добавянето през API не дублира: ако имейлът, който изпращате, вече съществува във вашата база, AiCrm актуализира картата, която вече имате (допълва липсващия телефон, име или фирма, обединява етикетите) и записва ново постъпление в нейната хронология, като връща HTTP 200; ако е нов, го създава и връща 201. Всеки контакт, постъпил през API, се етикетира автоматично като `api-lead`, запазва етикетите, които изпращате, и записва `subId` на произхода, както и държавата, IP адреса и браузъра, от които е дошъл.

Можете да имате до 20 API ключа със собствено име, освен вътрешния ключ на приложението. Така давате различен ключ на всяка интеграция —уебсайта, формуляра на майската кампания, стажанта, доставчика— и го отменяте самостоятелно, когато интеграцията приключи, без да докосвате останалите. Пълната стойност на ключа се показва само веднъж, при създаването; след това се вижда само маскирана в списъка.

В обратната посока уебхуковете известяват вашите системи. Настройвате до 10 дестинации, избирате за кои събития се абонира всяка (`customer.created`, `customer.updated`, `customer.deleted`, `activity.created`) и AiCrm прави POST към вашия URL с хедърите `X-AiCrm-Event` и `X-AiCrm-Signature: sha256=…`, подписът HMAC-SHA256 на тялото с тайния ключ на този уебхук, за да проверите, че доставката е легитимна. При запазване на URL адреса защита срещу SSRF отхвърля localhost, 127.0.0.0/8, 10.x, 192.168.x, 172.16-31.x, ::1, 0.0.0.0 и домейните `.local` и `.internal`.

## Какво включва

- **Добавяне на контакти с едно извикване** — POST към `/api/apps/public/crm/customers` с имейла и етикетите, които желаете, и лийдът вече е във вашия CRM, класифициран.
- **Без дубликати по дизайн** — ако имейлът вече съществува, картата се актуализира и новото постъпление се записва в нейната хронология, вместо да се създава втора карта.
- **До 20 именувани ключа** — по един за всяка интеграция, отменяем поотделно. Ако даден ключ изтече, изтривате него и нищо друго не спира да работи.
- **Уебхукове, подписани с HMAC-SHA256** — проверявате хедъра `X-AiCrm-Signature` със своя таен ключ и знаете, че известието идва от вашия CRM, а не от трета страна.
- **Включена защита срещу SSRF** — приложението отказва да доставя уебхукове към localhost или към частни мрежови диапазони, така че вашият CRM не може да се използва за сондиране на вътрешна мрежа.
- **Пълен CRUD, не само добавяне** — списък с пагинация и филтри (търсене, статус, етикети, държава), преглед на контакт с неговата активност, актуализиране, изтриване и записване на активности към него.
- **Произходът се проследява автоматично** — всяко добавяне през API запазва `subId`, който изпращате, плюс държавата, IP адреса и браузъра, и се маркира с `api-lead`, за да го филтрирате по-късно в приложението.
- **Тестове без налучкване** — приложението включва документация на крайните точки с копируем пример за `curl` и бутон за изпращане на тестова доставка към всеки уебхук, със статуса и часа на последния опит.

## Често задавани въпроси

### Как да създам контакт в CRM от уебсайта си?

Правите POST към `/api/apps/public/crm/customers` с хедъра `X-Api-Key` и JSON, съдържащ поне имейл или телефон. Можете да изпратите и име, телефон, фирма, държава, статус, бележки, етикети и `subId`, за да идентифицирате кампанията или формуляра на произход. AiCrm връща 201, ако го създаде, и 200, ако този контакт вече е съществувал.

### Какво става, ако един и същ имейл постъпи два пъти през API?

Не се дублира. AiCrm търси имейла (или телефона, ако не изпращате имейл) и ако го намери, актуализира съществуващата карта, попълвайки празните полета, обединява новите етикети с тези, които вече е имала, и записва новото постъпление в хронологията на активността. Отговорът показва, че контактът вече е съществувал, и ви връща неговия id.

### Колко API ключа мога да имам и мога ли да отменя само един?

Можете да създадете до 20 ключа със собствено име, освен вътрешния ключ на приложението, който не може да се изтрие. Всеки ключ се изтрива независимо, така че можете да дадете различен на всяка интеграция и да го отмените, без да засегнете останалите. Пълната стойност се показва само в момента на създаването; след това се вижда маскирана в списъка. Всички ключове споделят лимита от 100 заявки в минута на ключ.

### Как да проверя, че един уебхук наистина идва от моя CRM?

Всяка доставка носи хедъра `X-AiCrm-Signature: sha256=<подпис>`, който е HMAC-SHA256 на точното тяло на заявката, изчислен със тайния ключ, който приложението ви показва при създаването на уебхука. Изчислете този HMAC на вашия сървър върху полученото тяло и го сравнете. Освен това пътува и хедърът `X-AiCrm-Event` с името на събитието: `customer.created`, `customer.updated`, `customer.deleted` или `activity.created`.

### Какво се случва, ако крайната точка на моя уебхук не работи?

Доставката е по принципа best-effort: AiCrm чака до 5 секунди и ако не успее, опитва отново след секунда и половина. Няма постоянна опашка за повторни опити, така че дълъг прекъс на вашия сървър може да ви накара да изгубите известия; в такъв случай синхронизирайте със GET към `/api/apps/public/crm/customers`. Приложението ви показва статуса и часа на последния опит за всеки уебхук и можете да пуснете тестова доставка, когато пожелаете.

- [AiCrm — Лек CRM с API за добавяне на клиенти от всяка система](https://aistohire.com/bg/aicrm-lesen-crm-s-api-za-upravlenie-na-klienti-i-liydove-109)

## За платформата

**AiCrm — Лек CRM с API за добавяне на клиенти от всяка система** — приложение на AIstoHire. Налично на: https://aistohire.com/bg/aicrm-lesen-crm-s-api-za-upravlenie-na-klienti-i-liydove-109/f/rest-api-crm-podpisani-uebhukove

### Други езици

- `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
- `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
- `cs`: https://aistohire.com/cs/aicrm-jednoduche-crm-s-api-pro-spravu-klientu-a-leadu-109/f/rest-api-crm-podepsane-webhooky
- `id`: https://aistohire.com/id/aicrm-crm-sederhana-dengan-api-untuk-mengelola-pelanggan-dan-lead-109/f/api-rest-crm-webhook-bertanda-tangan
