> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agencyhandy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API AgencyHandy: programowe tworzenie nowego klienta

> Programowo dodawaj nowych klientów do swojej przestrzeni roboczej AgencyHandy, wysyłając żądanie do punktu końcowego bulk-client z imieniem, adresem e-mail i danymi kontaktowymi.

Punkt końcowy tworzenia klienta umożliwia dodawanie klientów bezpośrednio do przestrzeni roboczej AgencyHandy z zewnętrznego systemu. W przeciwieństwie do leadów, klienci są w pełni onboardowanymi kontaktami, którym można przypisywać zamówienia, faktury i projekty. Użyj tego punktu końcowego, aby synchronizować nowych klientów z systemu CRM, formularza onboardingowego lub innego źródła danych.

<Note>
  Przed użyciem tego punktu końcowego ukończ przewodnik [Pierwsze kroki](/pl/api/getting-started), aby uzyskać klucz API i identyfikator firmy. W przeciwieństwie do punktu końcowego tworzenia leada, tworzenie klienta **nie** wymaga oddzielnego kroku wyszukiwania identyfikatora roli.
</Note>

## Wymagania wstępne

* ✅ Klucz API wygenerowany z **Konfiguracja przestrzeni roboczej → Klucz API**
* ✅ Identyfikator firmy pobrany z `GET {{URL}}/accounts/companies`

***

## Punkt końcowy

```
POST {{URL}}/members/bulk-client
```

## Nagłówki

| Nagłówek       | Wartość                  |
| -------------- | ------------------------ |
| `x-api-key`    | Twój klucz API           |
| `companyId`    | Twój identyfikator firmy |
| `Content-Type` | `application/json`       |

## Ciało żądania

Ciało żądania jest **tablicą JSON**. Możesz utworzyć jednego lub więcej klientów w jednym żądaniu.

<ParamField body="firstName" type="string" required>
  Imię klienta.
</ParamField>

<ParamField body="lastName" type="string" required>
  Nazwisko klienta.
</ParamField>

<ParamField body="email" type="string" required>
  Adres e-mail klienta. Musi być unikalny w obrębie Twojej przestrzeni roboczej.
</ParamField>

<ParamField body="isConvertedClient" type="boolean" required>
  Ustaw na `false` dla zupełnie nowego klienta. Ustaw na `true` przy konwersji istniejącego leada na klienta.
</ParamField>

<ParamField body="status" type="string">
  Status klienta. Typowe wartości: `New`, `Active`. Domyślnie `New`, jeśli pominięte.
</ParamField>

<ParamField body="contactNo" type="string">
  Numer telefonu klienta.
</ParamField>

<ParamField body="source" type="string">
  Sposób pozyskania tego klienta. Przykładowe wartości: `website`, `referral`, `social`.
</ParamField>

<ParamField body="positionInBoard" type="number">
  Pozycja klienta w kolumnie tablicy. Domyślnie `1`.
</ParamField>

## Przykładowe żądanie

```bash cURL theme={null}
curl --request POST "https://api.agencyhandy.com/members/bulk-client" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyId: <YOUR_COMPANY_ID>" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'
```

## Odpowiedź sukcesu

```json theme={null}
{
  "message": "Client created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
```

<ResponseField name="message" type="string">
  Ciąg potwierdzający po sukcesie.
</ResponseField>

<ResponseField name="createdMembers" type="array">
  Tablica utworzonych obiektów klientów.
</ResponseField>

<ResponseField name="createdMembers[].\_id" type="string">
  Unikalny identyfikator nowo utworzonego klienta. Użyj tego identyfikatora przy przypisywaniu klienta do zamówień lub faktur przez API.
</ResponseField>

<ResponseField name="createdMembers[].name" type="string">
  Pełne imię i nazwisko klienta (imię + nazwisko).
</ResponseField>

<ResponseField name="createdMembers[].status" type="string">
  Status klienta, tak jak został zapisany.
</ResponseField>

<ResponseField name="createdMembers[].role" type="string">
  Rola przypisana do członka — będzie to `"client"`.
</ResponseField>

<Note>
  Nagłówek `companyId` dla tego punktu końcowego używa wielkiej litery **I** w `Id` — `companyId` — w przeciwieństwie do niektórych innych punktów końcowych, które używają `companyid` (wszystkie małe litery). Użyj dokładnej wielkości liter podanej powyżej, aby uniknąć błędów uwierzytelniania.
</Note>

<Tip>
  Przekaż wiele obiektów klientów w tablicy, aby zbiorczo tworzyć klientów w jednym wywołaniu API. Każdy obiekt musi posiadać unikalny adres `email`. Zduplikowane adresy e-mail spowodują błąd walidacji dla danego wpisu.
</Tip>