# CRM:n REST API ja allekirjoitetut webhookit | AiCrm

> CRM julkisella REST API:lla: luo ja hae kontakteja X-Api-Key-otsikolla, jopa 20 avainta integraatioita varten ja HMAC-SHA256:lla allekirjoitetut webhookit. Liidit verkkosivultasi ilman kaksoiskappaleita.

- **Lähde (source):** https://aistohire.com/fi/aicrm-yksinkertainen-crm-rajapinnalla-asiakkaille-ja-liideille-109/f/crm-rest-api-allekirjoitetut-webhookit
- **Alusta (platform):** AIstoHire
- **Kieli (language):** fi

## Lyhyesti

- Julkinen REST API, useita API-avaimia ja allekirjoitetut webhookit
- Lisää asiakkaat verkkosivultasi, lomakkeeltasi tai taustajärjestelmästäsi yhdellä HTTP-kutsulla ja vastaanota jokainen muutos palvelimellesi HMAC-SHA256:lla allekirjoitettuna.
- Kontaktin luonti yhdellä kutsulla
- Ei kaksoiskappaleita jo rakenteen puolesta
- Jopa 20 nimettyä avainta

## Julkinen REST API, useita API-avaimia ja allekirjoitetut webhookit

AiCrm, AIsToHiren CRM-sovellus, tarjoaa julkisen REST API:n omiin kontakteihisi. Avaimella `X-Api-Key`-otsikossa voit luoda, listata, hakea, päivittää ja poistaa kontakteja sekä lisätä toimintoja mihin tahansa niistä verkkosivusi lomakkeelta, chattibotistasi, Zapista, Python-skriptistä tai omasta taustajärjestelmästäsi. Vastaukset ovat JSON-muotoisia muodossa `{ success, data }`, ja raja on 100 pyyntöä minuutissa avainta kohden.

API:n kautta tehty lisäys ei kahdenna: jos lähettämäsi sähköposti on jo rekisterissäsi, AiCrm päivittää jo olemassa olevan kortin (täydentää puuttuvan puhelinnumeron, nimen tai yrityksen, yhdistää tunnisteet) ja kirjaa aikajanalle uuden lähetyksen palauttaen HTTP 200:n. Jos kontakti on uusi, se luodaan ja palautetaan 201. Jokainen API:n kautta tullut kontakti saa automaattisesti tunnisteen `api-lead`, säilyttää lähettämäsi tunnisteet ja tallentaa alkuperäisen `subId`:n sekä maan, IP-osoitteen ja selaimen, joilla se saapui.

Voit luoda jopa 20 omalla nimellä varustettua API-avainta sovelluksen sisäisen avaimen lisäksi. Näin annat eri avaimen jokaiselle integraatiolle – verkkosivulle, toukokuun kampanjan lomakkeelle, harjoittelijalle, toimittajalle – ja peruutat sen erikseen, kun integraatio päättyy, muita koskematta. Avaimen koko arvo näytetään vain kerran, luontihetkellä, ja sen jälkeen se näkyy listassa vain peitettynä.

Toiseen suuntaan webhookit ilmoittavat järjestelmillesi. Määrität jopa 10 kohdetta, valitset, mihin tapahtumiin kukin tilaa (`customer.created`, `customer.updated`, `customer.deleted`, `activity.created`), ja AiCrm tekee POST-pyynnön URL-osoitteeseesi otsikoilla `X-AiCrm-Event` ja `X-AiCrm-Signature: sha256=…`, joka on sisällön HMAC-SHA256-allekirjoitus kyseisen webhookin salaisuudella, jotta voit varmistaa toimituksen aitouden. URL-osoitetta tallennettaessa SSRF-suojaus hylkää localhostin, 127.0.0.0/8:n, 10.x:n, 192.168.x:n, 172.16-31.x:n, ::1:n, 0.0.0.0:n sekä `.local`- ja `.internal`-verkkotunnukset.

## Mitä se sisältää

- **Kontaktin luonti yhdellä kutsulla** — yksi POST-pyyntö osoitteeseen `/api/apps/public/crm/customers` sähköpostilla ja haluamillasi tunnisteilla, ja liidi on jo luokiteltuna CRM:ssäsi.
- **Ei kaksoiskappaleita jo rakenteen puolesta** — jos sähköposti on jo olemassa, kortti päivitetään ja uusi lähetys kirjataan sen aikajanalle toisen kortin luomisen sijaan.
- **Jopa 20 nimettyä avainta** — yksi kutakin integraatiota kohden, ja jokainen peruutettavissa erikseen. Jos yksi avain vuotaa, poistat sen, eikä mikään muu lakkaa toimimasta.
- **Webhookit allekirjoitetaan HMAC-SHA256** — lla: tarkistat `X-AiCrm-Signature`-otsikon salaisuudellasi ja tiedät, että ilmoitus tulee omasta CRM:ästäsi eikä ulkopuoliselta.
- **SSRF-suojaus mukana** — sovellus kieltäytyy toimittamasta webhookeja localhostiin tai yksityisiin verkkoalueisiin, joten CRM:äsi ei voi käyttää sisäisen verkon luotaamiseen.
- **Täysi CRUD, ei pelkkiä lisäyksiä** — listaus sivutuksella ja suodattimilla (haku, tila, tunnisteet, maa), kontaktin haku toimintoineen, päivitys, poisto ja toimintojen kirjaus.
- **Alkuperä jäljitetään automaattisesti** — jokainen API:n kautta tehty lisäys tallentaa lähettämäsi `subId`:n sekä maan, IP-osoitteen ja selaimen, ja se merkitään tunnisteella `api-lead`, jotta voit suodattaa sen myöhemmin sovelluksessa.
- **Testaus ilman arvailua** — sovelluksessa on päätepisteiden dokumentaatio kopioitavan `curl`-esimerkin kera sekä painike, jolla lähetät testitoimituksen kullekin webhookille, ja näet viimeisen yrityksen tilan ja ajan.

## Usein kysytyt kysymykset

### Miten luon kontaktin CRM:ään verkkosivultani?

Teet POST-pyynnön osoitteeseen `/api/apps/public/crm/customers` otsikolla `X-Api-Key` ja JSON-sisällöllä, jossa on vähintään sähköposti tai puhelinnumero. Voit lähettää myös nimen, puhelinnumeron, yrityksen, maan, tilan, muistiinpanot, tunnisteet ja `subId`:n, jolla yksilöit kampanjan tai lähdelomakkeen. AiCrm palauttaa 201, jos se luo kontaktin, ja 200, jos kontakti oli jo olemassa.

### Mitä tapahtuu, jos sama sähköposti tulee API:n kautta kahdesti?

Sitä ei kahdenneta. AiCrm hakee sähköpostin (tai puhelinnumeron, jos sähköpostia ei lähetetä) ja jos löytää sen, päivittää olemassa olevan kortin täyttämällä tyhjät kentät, yhdistää uudet tunnisteet jo olemassa oleviin ja kirjaa uuden lähetyksen sen toimintoaikajanalle. Vastauksesta näkyy, että kontakti oli jo olemassa, ja siinä palautetaan sen id.

### Kuinka monta API-avainta voin luoda, ja voinko peruuttaa vain yhden?

Voit luoda jopa 20 omalla nimellä varustettua avainta sovelluksen sisäisen avaimen lisäksi, jota ei voi poistaa. Jokainen avain poistetaan erikseen, joten voit antaa kullekin integraatiolle oman avaimen ja peruuttaa sen muihin vaikuttamatta. Avaimen koko arvo näytetään vain luontihetkellä, ja sen jälkeen se näkyy listassa peitettynä. Kaikilla avaimilla on sama raja: 100 pyyntöä minuutissa avainta kohden.

### Miten varmistan, että webhook todella tulee omasta CRM:ästäni?

Jokaisessa toimituksessa on otsikko `X-AiCrm-Signature: sha256=<allekirjoitus>`, joka on pyynnön täsmällisen sisällön HMAC-SHA256 käyttäen salaisuutta, jonka sovellus näyttää webhookin luonnin yhteydessä. Laske tämä HMAC palvelimellasi vastaanotetusta sisällöstä ja vertaa. Mukana kulkee myös otsikko `X-AiCrm-Event` tapahtuman nimellä: `customer.created`, `customer.updated`, `customer.deleted` tai `activity.created`.

### Mitä tapahtuu, jos webhook-päätepisteeni ei ole käytössä?

Toimitus on best-effort: AiCrm odottaa enintään 5 sekuntia ja jos se epäonnistuu, yrittää uudelleen puolentoista sekunnin kuluttua. Pysyvää uudelleenyritysjonoa ei ole, joten palvelimesi pitkä katko voi aiheuttaa ilmoitusten menetyksen. Siinä tapauksessa täsmäytä tiedot GET-pyynnöllä osoitteeseen `/api/apps/public/crm/customers`. Sovellus näyttää jokaisen webhookin viimeisen yrityksen tilan ja ajan, ja voit lähettää testitoimituksen milloin tahansa.

- [AiCrm — Kevyt CRM rajapinnalla asiakkaiden lisäämiseen mistä tahansa järjestelmästä](https://aistohire.com/fi/aicrm-yksinkertainen-crm-rajapinnalla-asiakkaille-ja-liideille-109)

## Tietoa alustasta

**AiCrm — Kevyt CRM rajapinnalla asiakkaiden lisäämiseen mistä tahansa järjestelmästä** — sovellus: AIstoHire. Saatavilla kielillä: https://aistohire.com/fi/aicrm-yksinkertainen-crm-rajapinnalla-asiakkaille-ja-liideille-109/f/crm-rest-api-allekirjoitetut-webhookit

### Muut kielet

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