# API-käyttöoikeus

API (Application Programming Interface) on tapa, jolla eri ohjelmistojärjestelmät voivat kommunikoida keskenään. <span data-t="appName">Your AI Connector</span>-rajapinnan avulla voit (tai kehittäjäsi voi) luoda yhteystietoja, lähettää viestejä, hallita listoja ja vastaanottaa saapuvia viestejä mukautetuista kanavista automaattisesti – ilman, että sinun tarvitsee käyttää hallintapaneelia.


**Miksi käyttää APIa?** Jos haluat yhdistää sovelluksen työkaluun, jolla ei ole sisäänrakennettua integraatiota, tai jos sinun on automatisoitava toistuvia tehtäviä laajassa mittakaavassa, API on oikea tapa toimia.

::: note
**Huomautus:** Tämä sivu on luonteeltaan teknisempi. Jos olet yrityksen omistaja etkä kehittäjä, kannattaa ehkä jakaa tämä sivu tekniselle tiimillesi tai freelance-kehittäjälle.
:::


---

## API-avaimen luominen

::: note
**Huomautus:** API-käyttöoikeus on maksullinen ominaisuus, joka on saatavilla tietyissä tilauspaketeissa. Jos tilauksesi ei sisällä sitä, API-pyynnöt hylätään `403`-vastauksella. Tarkista tilauksesi tai ota yhteyttä tukeen, jos olet epävarma siitä, onko API-käyttöoikeus käytössä.
:::


1. Napsauta vasemmasta sivupalkista **Asetukset** (rataskuvake).
2. Napsauta Asetukset-sivupalkin **Integraatiot**-ryhmän alta **API-avain**.


3. Jos sinulla ei vielä ole avainta, napsauta **Generate API key**.
4. Jos sinulla on jo avain, se näkyy peitettynä kohdassa **Your key**. Jos avain tukee sitä, napsauta **Show** nähdäksesi sen ja sitten **Copy** kopioidaksesi sen – näet vahvistusilmoituksen.
5. Säilytä avain turvallisessa paikassa – tarvitset sitä jokaisessa API-pyynnössä.


::: note
**Huomautus:** Joillakin tileillä näkyy "Your key can't be displayed" Show/Copy-ohjaimen sijaan – tämä koskee avaimia, jotka on luotu ennen kuin sovellus pystyi näyttämään ne uudelleen. Avain toimii edelleen normaalisti; tarvitset **Regenerate**-toimintoa (avainkortin alapuolella, samassa osiossa) vain, jos sinun on todella nähtävä selväkielinen avain uudelleen. Uudelleenluonti mitätöi vanhan avaimen välittömästi ja katkaisee kaikki sitä käyttävät integraatiot, kunnes liität uuden avaimen – päivitä integraatiosi heti sen jälkeen.
:::


::: warning
**Tärkeää:** API-avaimesi on kuin salasana – se antaa täyden pääsyn tilillesi. Älä jaa sitä julkisesti tai julkaise sitä missään, missä muut voivat nähdä sen. Jos uskot, että avaimesi on vaarantunut, luo se välittömästi uudelleen.
:::


> **Tiimin jäsenet:** API-avain kuuluu tilin omistajalle, joten jos olet kirjautunut sisään kutsuttuna tiimin jäsenenä (mukaan lukien järjestelmänvalvoja), osiossa näkyy huomautus avaimen sijaan. Kirjaudu sisään tilin omistajana nähdäksesi, kopioidaksesi tai luodaksesi avaimen uudelleen – tämä koskee myös rajattuja avaimia.

> **Mistä se löytyy:** **API-avain** on oma osionsa Asetukset → Integraatiot -kohdassa, erillään **Webhookeista**. Jos opas tai kollega kehottaa etsimään avainta "Webhookit"-kohdasta, katso sen sijaan viereisestä osiosta.

---

## Perus-URL

Kaikissa API-pyynnöissä käytetään seuraavaa verkko-osoitteen perusosaa:

```
https://api.youraiconnector.com/v1/
```

---

## Todennus

Jokaisen pyynnön on sisällettävä API-avaimesi, jotta alusta tietää, että kyseessä olet sinä. Yksinkertaisin tapa on lisätä se verkko-osoitteen loppuun:

```
https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
```

Voit myös lähettää avaimen pyynnön otsikkotietona (header) URL-osoitteen sijaan (suositellaan tuotantokäyttöön, jotta avain ei päädy palvelinlokeihin):

```
X-API-Key: YOUR_API_KEY
```
```
Authorization: Bearer YOUR_API_KEY
```

Kaikkien pyyntöjen on käytettävä suojattua yhteyttä (HTTPS). Suojaamattomat (HTTP) pyynnöt hylätään.

> **Etsitkö täydellisiä kehittäjäoppaita?** Tämä sivu on nopea johdanto yleisimpiin toimintoihin. Täydelliset, vaiheittaiset oppaat — jokainen resurssi cURL-, JavaScript- ja Python-esimerkein — löytyvät kohdista [Getting Started with the API](../api/getting-started.md) ja [API Reference](../api/reference.md).

---

## Yleiset API-toiminnot

### Luo yhteystieto

**Pyyntö:**

```http
POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}
```

**Pakolliset kentät:** `phoneNumber` (maakoodilla) on aina pakollinen yhteystiedon luomiseksi. Pelkkä sähköpostiosoite ei riitä – pyyntö ilman kelvollista puhelinnumeroa hylätään. Sähköpostiosoite on valinnainen.

**Vastaus:**

```json
{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}
```

Tallenna `data.contactId` – tarvitset sitä "Lisää yhteystieto listalle" -kutsussa.

::: note
**Huomautus:** Jos yhteystieto samalla puhelinnumerolla on jo olemassa, API ei luo tai palauta kyseistä yhteystietoa – se palauttaa `{ "success": false, "error_code": 409 }`. Etsi olemassa oleva yhteystieto ensin käyttämällä `GET https://api.youraiconnector.com/v1/contacts?phoneNumber=...`.
:::


---

### Lisää yhteystieto listaan

```http
POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}
```

Löydät listan tunnisteen sovelluksesta kohdasta **Yhteystiedot → Listat** listan rivivalikosta (**Kopioi listan tunniste**).

---

### Päivitä yhteystieto

```http
PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}
```

Vain sisällyttämäsi kentät muuttuvat. Tämä on myös tapa ladata mukautettujen kenttien arvoja massana tuonnin jälkeen — katso [Custom Fields, Lead Profile & Notes](../get-started/custom-contact-fields.md#bulk-loading-custom-fields). Täydelliset tiedot löytyvät [Contacts API](../api/contacts.md) -osiosta.

---

### Lähetä viesti (mukautettu kanava)

```http
POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}
```

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `customData.fromId` | Kyllä | Yhteystiedon tunnus alustallasi |
| `customData.customChannel` | Kyllä | Mukautetun kanavasi nimi |
| `customData.body` | Kyllä | Lähetettävä viestiteksti |
| `customData.campaignId` | Ei | Ohjaa viesti tiettyyn kampanjaan |
| `customData.firstName` | Ei | Yhteystiedon etunimi (käytetään uutta yhteystietoa luotaessa) |
| `customData.lastName` | Ei | Yhteystiedon sukunimi |
| `customData.email` | Ei | Yhteystiedon sähköpostiosoite |

::: note
**Huomautus:** tämä päätepiste on tarkoitettu mukautettujen kanavien viestintään. WhatsApp-, SMS-, Instagram- ja Messenger-viestit lähetetään lähetysten, kampanjoiden ja tekoälyagenttien kautta.
:::


---

### Vastaanota saapuvia viestejä (mukautettu kanava)

Vastaanota viestejä ulkoisista järjestelmistä mukautettuna kanavana. Näin integraatiot, kuten GoHighLevel, lähettävät viestejä <span data-t="appName">Your AI Connector</span>-palveluun. Katso täydelliset tiedot kohdasta [Mukautetut kanavat](../messaging-channels/custom-channels.md).

```http
POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}
```

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `customData.messageSid` | Kyllä | Tämän viestin yksilöllinen tunniste (estää kaksoiskappaleet). Voit käyttää myös `customData.id`. |
| `customData.fromId` | Kyllä | Lähettäjän tunniste ulkoisessa järjestelmässäsi. |
| `customData.toId` | Kyllä | Yrityksesi tunniste. |
| `customData.body` | Kyllä | Viestin teksti. |
| `customData.channel` | Ei | Lähteen nimi (esim. `"email"`, `"livechat"`, `"custom"`). |
| `customData.status` | Ei | Viestin tila. Oletusarvo on `"received"`. |
| `messageType` | Ei | `"text"` tekstiviesteille, `"reaction"` emojireaktioille. |

---

## Yleiskatsaus käytettävissä olevista toiminnoista

| Toiminto | Metodi | Osoite | Kuvaus |
|---|---|---|---|
| Luo yhteystieto | `POST` | `/contacts` | Lisää uusi yhteystieto tilillesi |
| Hae yhteystiedon tiedot | `GET` | `/contacts?phoneNumber=X` tai `/contacts?email=X` | Etsi yhteystieto puhelinnumeron tai sähköpostin perusteella |
| Päivitä yhteystieto | `PUT` | `/contacts/{contactId}` | Päivitä mikä tahansa kenttä olemassa olevassa yhteystiedossa |
| Lisää yhteystieto listalle | `POST` | `/contacts/lists` | Lisää olemassa oleva yhteystieto tietylle listalle |
| Lähetä viesti | `POST` | `/send_custom_channel_message` | Lähetä viesti mukautetun kanavan kautta |
| Vastaanota viesti | `POST` | `/incoming_custom_channel_message` | Vastaanota viesti ulkoisesta järjestelmästä |

---

## Nopeusrajoitukset

The API enforces rate limits to ensure platform stability. Exceeding your limit returns `429 Too Many Requests` — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in [import feature](../get-started/importing-contacts.md) or email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) for guidance.

---

## Parhaat käytännöt

- **Säilytä API-avaimesi turvallisesti** – käytä salasananhallintaohjelmaa tai palvelinpuolen asetuksia, älä koskaan asiakaspuolen koodia, jonka verkkosivuston vierailija voisi lukea.
- **Lisää aina maakoodi** puhelinnumeroihin (`+1` Yhdysvallat, `+44` Iso-Britannia, `+31` Alankomaat).
- **Käsittele virheet asianmukaisesti** – tarkista tilakoodit ja lue kaikki palautetut virheilmoitukset.
- **Käsittele kaksoiskappaleet** – sama puhelinnumero palauttaa `{ "success": false, "error_code": 409 }` uuden yhteystiedon sijaan. Etsi yhteystieto ensin, jos haluat muokata sitä.
- **Testaa pienellä tietoaineistolla** ennen massatoimintojen suorittamista.

---

## Virhevastaukset

```json
{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}
```

| Status Code | Meaning |
|---|---|
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request — check your parameters |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — your plan doesn't include API access, or you lack permission |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Server error — email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) if this persists |

---

## Seuraavat vaiheet

- [Webhooks](webhooks.md) – vastaanota reaaliaikaisia ilmoituksia sovelluksesta (erillinen osio API-avaimestasi).
- [Yhdistä tekoälyavustajat (MCP)](connect-ai-clients.md) – käytä samaa API-avainta antaaksesi Clauden hallita tiliäsi.
- [Facebook-liidilomakkeet](facebook-lead-forms.md) – käytä API-rajapintaa automaatioalustojen kanssa liidien keräämiseen.
- [GoHighLevel-integraatio](ghl-integration.md) – esimerkki täydellisestä kaksisuuntaisesta API-integraatiosta.