# Dostęp do API

API (Application Programming Interface) to sposób, w jaki różne systemy oprogramowania mogą się ze sobą komunikować. API <span data-t="appName">Your AI Connector</span> pozwala Tobie (lub Twojemu programiście) automatycznie tworzyć kontakty, wysyłać wiadomości, zarządzać listami i odbierać przychodzące wiadomości z niestandardowych kanałów — wszystko to bez korzystania z panelu nawigacyjnego.


**Dlaczego warto korzystać z API?** Jeśli chcesz połączyć aplikację z narzędziem, które nie posiada wbudowanej integracji, lub musisz zautomatyzować powtarzalne zadania na dużą skalę, API jest najlepszym rozwiązaniem.

::: note
**Uwaga:** Ta strona ma charakter bardziej techniczny. Jeśli jesteś właścicielem firmy, a nie programistą, być może warto udostępnić tę stronę swojemu zespołowi technicznemu lub niezależnemu programiście.
:::


---

## Generowanie klucza API

::: note
**Uwaga:** Dostęp do API jest płatną funkcją dostępną w wybranych planach. Jeśli Twój plan go nie obejmuje, żądania API będą odrzucane z odpowiedzią `403`. Sprawdź swój plan lub skontaktuj się z pomocą techniczną, jeśli nie masz pewności, czy dostęp do API jest włączony.
:::


1. W lewym pasku bocznym kliknij **Ustawienia** (ikona koła zębatego).
2. W pasku bocznym Ustawień, w grupie **Integracje**, kliknij **Klucz API**.


3. Jeśli nie masz jeszcze klucza, kliknij **Wygeneruj klucz API**.
4. Jeśli już go masz, jest on wyświetlany w formie zamaskowanej w sekcji **Twój klucz**. Jeśli Twój klucz na to pozwala, kliknij **Pokaż**, aby go odkryć, a następnie **Kopiuj**, aby go skopiować — zobaczysz komunikat potwierdzający.
5. Przechowuj klucz w bezpiecznym miejscu — będzie potrzebny do każdego żądania API.


::: note
**Uwaga:** Niektóre konta widzą komunikat "Twojego klucza nie można wyświetlić" zamiast kontrolki Pokaż/Kopiuj — dzieje się tak w przypadku kluczy utworzonych przed wprowadzeniem funkcji ponownego wyświetlania. Klucz nadal działa normalnie; opcji **Regeneruj** (poniżej karty klucza, w tej samej sekcji) potrzebujesz tylko wtedy, gdy faktycznie musisz ponownie zobaczyć tekst jawny. Regeneracja natychmiast unieważnia stary klucz i przerywa działanie każdej integracji, która z niego korzysta, dopóki nie wkleisz nowego — zaktualizuj swoje integracje zaraz po tym.
:::


::: warning
**Ważne:** Twój klucz API jest jak hasło — zapewnia pełny dostęp do Twojego konta. Nie udostępniaj go publicznie ani nie publikuj w miejscach, w których inni mogą go zobaczyć. Jeśli uważasz, że Twój klucz został przejęty, natychmiast go zregeneruj.
:::


> **Członkowie zespołu:** klucz API należy do właściciela konta, więc jeśli jesteś zalogowany jako zaproszony członek zespołu (w tym administrator), w sekcji zamiast klucza wyświetli się stosowna informacja. Zaloguj się jako właściciel konta, aby wyświetlić, skopiować lub wygenerować go ponownie — dotyczy to również kluczy o ograniczonym zakresie.

> **Gdzie go znaleźć:** **Klucz API** to osobna sekcja w Ustawienia → Integracje, oddzielona od **Webhooków**. Jeśli przewodnik lub współpracownik sugeruje szukanie klucza w sekcji "Webhooki", sprawdź sekcję obok.

---

## Podstawowy adres URL

Wszystkie żądania API korzystają z następującego podstawowego adresu internetowego:

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

---

## Uwierzytelnianie

Każde żądanie musi zawierać Twój klucz API, aby platforma wiedziała, że to Ty. Najprostszym sposobem jest dodanie go na końcu adresu internetowego:

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

Klucz możesz również wysłać w nagłówku żądania zamiast w adresie URL (zalecane w środowisku produkcyjnym, aby klucz nie trafiał do logów serwera):

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

Wszystkie żądania muszą korzystać z bezpiecznego połączenia (HTTPS). Żądania niezabezpieczone (HTTP) są odrzucane.

> **Szukasz pełnych przewodników dla programistów?** Ta strona to szybkie wprowadzenie obejmujące najczęstsze operacje. Pełne przewodniki krok po kroku — dotyczące każdego zasobu, z przykładami w cURL, JavaScript i Python — znajdziesz w sekcji [Rozpoczęcie pracy z API](../api/getting-started.md) oraz w [Dokumentacji API](../api/reference.md).

---

## Typowe operacje API

### Tworzenie kontaktu

**Żądanie:**

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

**Wymagane pola:** `phoneNumber` (wraz z kodem kraju) jest zawsze wymagany do utworzenia kontaktu. Sam adres e-mail nie wystarczy — żądanie bez prawidłowego numeru telefonu zostanie odrzucone. Adres e-mail jest opcjonalny.

**Odpowiedź:**

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

Zapisz `data.contactId` — będzie Ci potrzebny do wywołania „Dodawanie kontaktu do listy”.

::: note
**Uwaga:** jeśli kontakt o tym samym numerze telefonu już istnieje, API **nie** utworzy ani nie zwróci tego kontaktu — zwróci `{ "success": false, "error_code": 409 }`. Najpierw wyszukaj istniejący kontakt za pomocą `GET https://api.youraiconnector.com/v1/contacts?phoneNumber=...`.
:::


---

### Dodawanie kontaktu do listy

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

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

Identyfikator listy znajdziesz w aplikacji w sekcji **Kontakty → Listy**, w menu wiersza danej listy (**Kopiuj ID listy**).

---

### Aktualizacja kontaktu

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

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

Zmieniane są tylko uwzględnione pola. Jest to również sposób na masowe ładowanie wartości pól niestandardowych po imporcie — zobacz [Pola niestandardowe, profil leada i notatki](../get-started/custom-contact-fields.md#bulk-loading-custom-fields). Pełne szczegóły znajdują się w [API kontaktów](../api/contacts.md).

---

### Wyślij wiadomość (kanał niestandardowy)

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

| Pole | Wymagane | Opis |
|---|---|---|
| `customData.fromId` | Tak | Identyfikator kontaktu na Twojej platformie |
| `customData.customChannel` | Tak | Nazwa Twojego kanału niestandardowego |
| `customData.body` | Tak | Treść wiadomości do wysłania |
| `customData.campaignId` | Nie | Skieruj wiadomość do określonej kampanii |
| `customData.firstName` | Nie | Imię kontaktu (używane przy tworzeniu nowego kontaktu) |
| `customData.lastName` | Nie | Nazwisko kontaktu |
| `customData.email` | Nie | Adres e-mail kontaktu |

::: note
**Uwaga:** ten punkt końcowy służy do przesyłania wiadomości przez kanały niestandardowe. W przypadku WhatsApp, SMS, Instagrama i Messengera wiadomości są wysyłane za pośrednictwem transmisji, kampanii i agentów AI.
:::


---

### Odbieranie wiadomości przychodzących (kanał niestandardowy)

Odbieraj wiadomości z zewnętrznych systemów jako niestandardowy kanał. W ten sposób integracje takie jak GoHighLevel wysyłają wiadomości do <span data-t="appName">Your AI Connector</span>. Zobacz [Kanały niestandardowe](../messaging-channels/custom-channels.md), aby uzyskać pełne szczegóły.

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

| Pole | Wymagane | Opis |
|---|---|---|
| `customData.messageSid` | Tak | Unikalny identyfikator tej wiadomości (zapobiega duplikatom). Możesz również użyć `customData.id`. |
| `customData.fromId` | Tak | Identyfikator nadawcy w Twoim systemie zewnętrznym. |
| `customData.toId` | Tak | Twój identyfikator biznesowy. |
| `customData.body` | Tak | Treść wiadomości. |
| `customData.channel` | Nie | Etykieta źródła (np. `"email"`, `"livechat"`, `"custom"`). |
| `customData.status` | Nie | Status wiadomości. Domyślnie `"received"`. |
| `messageType` | Nie | `"text"` dla wiadomości tekstowych, `"reaction"` dla reakcji emoji. |

---

## Przegląd dostępnych operacji

| Akcja | Metoda | Adres | Opis |
|---|---|---|---|
| Utwórz kontakt | `POST` | `/contacts` | Dodaj nowy kontakt do swojego konta |
| Pobierz szczegóły kontaktu | `GET` | `/contacts?phoneNumber=X` lub `/contacts?email=X` | Wyszukaj kontakt według numeru telefonu lub adresu e-mail |
| Zaktualizuj kontakt | `PUT` | `/contacts/{contactId}` | Zaktualizuj dowolne pole w istniejącym kontakcie |
| Dodaj kontakt do listy | `POST` | `/contacts/lists` | Dodaj istniejący kontakt do określonej listy |
| Wyślij wiadomość | `POST` | `/send_custom_channel_message` | Wyślij wiadomość przez kanał niestandardowy |
| Odbierz wiadomość | `POST` | `/incoming_custom_channel_message` | Odbierz wiadomość z systemu zewnętrznego |

---

## Limity szybkości (Rate Limiting)

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.

---

## Dobre praktyki

- **Przechowuj klucz API bezpiecznie** — używaj menedżera haseł lub konfiguracji po stronie serwera, nigdy kodu po stronie klienta, który mógłby odczytać odwiedzający stronę.
- **Zawsze podawaj kod kraju** w numerach telefonów (`+1` dla USA, `+44` dla Wielkiej Brytanii, `+31` dla Holandii).
- **Obsługuj błędy w sposób elegancki** — sprawdzaj kody statusu i czytaj wszelkie zwracane komunikaty o błędach.
- **Obsługuj duplikaty** — zduplikowany numer telefonu zwróci `{ "success": false, "error_code": 409 }` zamiast nowego kontaktu. Jeśli musisz pracować z tym kontaktem, najpierw go wyszukaj.
- **Przetestuj na małym zbiorze danych** przed uruchomieniem operacji masowych.

---

## Odpowiedzi o błędach

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

---

## Następne kroki

- [Webhooks](webhooks.md) — otrzymuj powiadomienia w czasie rzeczywistym z aplikacji (osobna sekcja od Twojego klucza API).
- [Połącz asystentów AI (MCP)](connect-ai-clients.md) — użyj tego samego klucza API, aby pozwolić Claude zarządzać Twoim kontem.
- [Formularze kontaktowe Facebooka](facebook-lead-forms.md) — używaj API z platformami automatyzacji do pozyskiwania leadów.
- [Integracja z GoHighLevel](ghl-integration.md) — przykład pełnej dwukierunkowej integracji API.