# REST API do CRM z podpisanymi webhookami | AiCrm

> CRM z publicznym REST API: twórz i odczytuj kontakty z nagłówkiem X-Api-Key, do 20 kluczy na integrację i wychodzące webhooki podpisane HMAC-SHA256. Dodawanie leadów ze strony bez duplikatów.

- **Źródło (source):** https://aistohire.com/pl/aicrm-prosty-crm-z-api-do-zarzadzania-klientami-i-leadami-109/f/api-rest-crm-podpisane-webhooki
- **Platforma (platform):** AIstoHire
- **Język (language):** pl

## W skrócie

- Publiczne REST API z wieloma kluczami API i podpisanymi webhookami
- Dodawaj klientów ze strony, formularza lub backendu jednym wywołaniem HTTP i otrzymuj każdą zmianę na swoim serwerze, podpisaną HMAC-SHA256.
- Dodawanie kontaktów jednym wywołaniem
- Brak duplikatów z założenia
- Do 20 nazwanych kluczy

## Publiczne REST API z wieloma kluczami API i podpisanymi webhookami

AiCrm, aplikacja CRM z AIsToHire, udostępnia publiczne REST API do Twoich własnych kontaktów. Z kluczem w nagłówku `X-Api-Key` możesz tworzyć, listować, odczytywać, aktualizować i usuwać kontakty oraz dodawać aktywności do każdego z nich – z formularza na stronie, chatbota, Zapa, skryptu w Pythonie lub własnego backendu. Odpowiedzi to JSON w postaci `{ success, data }`, a limit wynosi 100 żądań na minutę na klucz.

Dodawanie przez API nie duplikuje: jeśli wysłany e-mail już istnieje w Twojej bazie, AiCrm aktualizuje kartę, którą już miałeś(-aś) (uzupełnia brakujący telefon, nazwę lub firmę, łączy tagi) i rejestruje nowe zgłoszenie na jej osi czasu, zwracając HTTP 200; jeśli jest nowy, tworzy go i zwraca 201. Każdy kontakt wchodzący przez API jest automatycznie oznaczany jako `api-lead`, zachowuje tagi, które wyślesz, i zapisuje źródłowy `subId` oraz kraj, IP i przeglądarkę, z których przyszedł.

Możesz mieć do 20 kluczy API z własną nazwą, nie licząc wewnętrznego klucza aplikacji. Dzięki temu dajesz inny klucz każdej integracji – stronie, formularzowi majowej kampanii, stażyście, dostawcy – i odwołujesz go osobno, gdy integracja się kończy, nie ruszając pozostałych. Pełna wartość klucza jest pokazywana tylko raz, przy tworzeniu; potem na liście widać ją tylko w postaci zamaskowanej.

W drugą stronę webhooki powiadamiają Twoje systemy. Konfigurujesz do 10 adresów docelowych, wybierasz, na jakie zdarzenia każdy się subskrybuje (`customer.created`, `customer.updated`, `customer.deleted`, `activity.created`), a AiCrm wykonuje POST na Twój URL z nagłówkami `X-AiCrm-Event` i `X-AiCrm-Signature: sha256=…`, czyli podpisem HMAC-SHA256 treści z sekretem tego webhooka, abyś mógł(-ogła) zweryfikować, że dostawa jest prawdziwa. Przy zapisie URL zabezpieczenie anty-SSRF odrzuca localhost, 127.0.0.0/8, 10.x, 192.168.x, 172.16-31.x, ::1, 0.0.0.0 oraz domeny `.local` i `.internal`.

## Co zawiera

- **Dodawanie kontaktów jednym wywołaniem** — POST na `/api/apps/public/crm/customers` z e-mailem i tagami, jakie chcesz, a lead jest już w Twoim CRM, sklasyfikowany.
- **Brak duplikatów z założenia** — jeśli e-mail już istnieje, karta jest aktualizowana, a nowe zgłoszenie zapisuje się na jej osi czasu zamiast tworzyć drugą kartę.
- **Do 20 nazwanych kluczy** — po jednym na integrację, odwoływalnych osobno. Jeśli klucz wycieknie, usuwasz tylko ten i nic poza nim przestaje działać.
- **Webhooki podpisane HMAC-SHA256** — weryfikujesz nagłówek `X-AiCrm-Signature` swoim sekretem i wiesz, że powiadomienie pochodzi z Twojego CRM, a nie od osoby trzeciej.
- **Zabezpieczenie anty-SSRF w zestawie** — aplikacja odmawia dostarczania webhooków na localhost lub do prywatnych zakresów sieci, więc Twojego CRM nie da się użyć do sondowania sieci wewnętrznej.
- **Pełny CRUD, a nie tylko dodawanie** — lista ze stronicowaniem i filtrami (wyszukiwanie, status, tagi, kraj), pobranie kontaktu z jego aktywnością, aktualizacja, usunięcie i rejestrowanie aktywności.
- **Źródło śledzone automatycznie** — każde dodanie przez API zapisuje przesłany `subId` oraz kraj, IP i przeglądarkę i jest oznaczone tagiem `api-lead`, by później łatwo je filtrować w aplikacji.
- **Testy bez zgadywania** — aplikacja zawiera dokumentację endpointów z przykładem `curl` do skopiowania i przycisk wysyłający testową dostawę do każdego webhooka, ze statusem i godziną ostatniej próby.

## Najczęściej zadawane pytania

### Jak utworzyć kontakt w CRM ze swojej strony?

Wysyłasz POST na `/api/apps/public/crm/customers` z nagłówkiem `X-Api-Key` i JSON-em zawierającym co najmniej e-mail lub telefon. Możesz też wysłać nazwę, telefon, firmę, kraj, status, notatki, tagi oraz `subId`, by zidentyfikować kampanię lub formularz źródłowy. AiCrm zwraca 201, jeśli tworzy kontakt, i 200, jeśli ten kontakt już istniał.

### Co się stanie, jeśli ten sam e-mail trafi przez API dwa razy?

Nie dubluje się. AiCrm szuka e-maila (lub telefonu, jeśli nie wyślesz e-maila) i jeśli go znajdzie, aktualizuje istniejącą kartę, uzupełniając pola, które były puste, łączy nowe tagi z tymi, które już miała, i rejestruje nowe zgłoszenie na jej osi czasu aktywności. Odpowiedź wskazuje, że kontakt już istniał, i zwraca jego id.

### Ile kluczy API mogę mieć i czy mogę odwołać tylko jeden?

Możesz utworzyć do 20 kluczy z własną nazwą, nie licząc wewnętrznego klucza aplikacji, którego nie da się usunąć. Każdy klucz usuwa się niezależnie, więc możesz dać inny każdej integracji i odwołać go bez wpływu na resztę. Pełna wartość jest pokazywana tylko w momencie tworzenia; potem na liście pojawia się zamaskowana. Wszystkie klucze mają limit 100 żądań na minutę na klucz.

### Jak sprawdzić, że webhook naprawdę pochodzi z mojego CRM?

Każda dostawa zawiera nagłówek `X-AiCrm-Signature: sha256=<podpis>`, czyli HMAC-SHA256 dokładnej treści żądania z użyciem sekretu, który aplikacja pokazuje przy tworzeniu webhooka. Oblicz ten HMAC na swoim serwerze dla odebranej treści i porównaj. Dodatkowo przesyłany jest nagłówek `X-AiCrm-Event` z nazwą zdarzenia: `customer.created`, `customer.updated`, `customer.deleted` lub `activity.created`.

### Co się dzieje, gdy mój endpoint webhooka nie działa?

Dostawa działa w trybie best-effort: AiCrm czeka do 5 sekund, a jeśli się nie uda, ponawia raz po półtorej sekundy. Nie ma trwałej kolejki ponowień, więc dłuższa awaria Twojego serwera może oznaczać utratę powiadomień; w takim przypadku uzgodnij dane wywołaniem GET na `/api/apps/public/crm/customers`. Aplikacja pokazuje status i godzinę ostatniej próby każdego webhooka, a testową dostawę możesz uruchomić w dowolnej chwili.

- [AiCrm — lekki CRM z API do dodawania klientów z dowolnego systemu](https://aistohire.com/pl/aicrm-prosty-crm-z-api-do-zarzadzania-klientami-i-leadami-109)

## O platformie

**AiCrm — lekki CRM z API do dodawania klientów z dowolnego systemu** — aplikacja od AIstoHire. Dostępne w: https://aistohire.com/pl/aicrm-prosty-crm-z-api-do-zarzadzania-klientami-i-leadami-109/f/api-rest-crm-podpisane-webhooki

### Inne języki

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