# API transakcji Transakcja to jedna szansa sprzedaży na Twojej tablicy [lejka sprzedaży](../deals/sales-pipeline.md) — zawiera tytuł, wartość, etap, na którym się znajduje, oraz opcjonalnie przypisany kontakt i członka zespołu. Ten przewodnik opisuje odczytywanie i zarządzanie transakcjami za pośrednictwem API. - **Podstawowy adres URL** — `https://api.youraiconnector.com/v1` - **Uwierzytelnianie** — Twój klucz API (zobacz [Uwierzytelnianie](authentication.md)) - **Błędy i stronicowanie** — zobacz [Błędy i stronicowanie](errors-and-pagination.md) Wszystkie poniższe przykłady pokazują formularz zapytania `?apiKey=` w cURL oraz nagłówek `X-API-Key` w JavaScript i Pythonie — oba działają w każdym punkcie końcowym. --- ## Obiekt transakcji ```json { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "description": "Asked for pricing on the annual plan.", "company": "Jane's Clinic", "notes": "Prefers a call after 5pm.", "stage": "stage-2", "pipeline_id": "default", "value": 4800, "probability": 60, "priority": "high", "status": "open", "source": "whatsapp", "position": 0, "contact_id": "ctc_9f8e7d", "assigned_to": "usr_4a2b", "tags": ["clinic"], "close_date": "2026-10-01T00:00:00.000Z", "created_at": "2026-09-05T09:12:00.000Z", "updated_at": "2026-09-05T09:40:00.000Z", "stage_entered_at": "2026-09-05T09:40:00.000Z" } ``` `stage` to identyfikator jednego z etapów Twojego lejka — odczytasz je za pomocą `GET /pipelines` (zobacz [Lejki](#pipelines) poniżej). Identyfikatory etapów są unikalne w obrębie wszystkich lejków, więc `pipeline_id` jest pochodną etapu i jest tylko do odczytu: `default` to Twój główny lejek, a jego wartość to `null`, gdy etap już nie istnieje. Sygnatury czasowe są w formacie ISO 8601. Transakcja przechowuje tylko pola pokazane powyżej. Podczas tworzenia lub aktualizacji transakcji każde inne pole zostanie odrzucone z komunikatem `400` wskazującym jego nazwę, dzięki czemu żadne wysłane dane nie zostaną utracone bez powiadomienia. Dodatkowe dane przechowuj w polach niestandardowych powiązanego kontaktu. --- ## Lista transakcji `GET /deals` — zwraca transakcje na Twoim koncie, od najnowszej. **Parametry zapytania** (wszystkie opcjonalne): `stage` (identyfikator etapu), `pipeline_id` (tylko transakcje w tym lejku), `contact_id`, `limit` (domyślnie 50, maks. 200), `cursor` (z `next_cursor` poprzedniej strony). **cURL** ```bash curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/deals?stage=stage-2&limit=50", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const { deals, next_cursor } = await res.json(); ``` **Python** ```python res = requests.get( "https://api.youraiconnector.com/v1/deals", headers={"X-API-Key": "YOUR_API_KEY"}, params={"stage": "stage-2", "limit": 50}, ) deals = res.json()["deals"] ``` **Odpowiedź** (`200`) ```json { "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null } ``` --- ## Pobierz transakcję `GET /deals/{dealId}` ```bash curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" ``` **Odpowiedź** (`200`) ```json { "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } } ``` Transakcja, która nie istnieje lub należy do innego konta, zwraca `404`. --- ## Utwórz transakcję `POST /deals` — `title` i `stage` są wymagane; `stage` musi być jednym z identyfikatorów etapów Twojego lejka. ```bash curl -X POST "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }' ``` **Odpowiedź** (`201`) ```json { "success": true, "deal_id": "deal_abc123" } ``` --- ## Zaktualizuj transakcję `PUT /deals/{dealId}` — wyślij tylko te pola, które chcesz zmienić (`title`, `description`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` musi być liczbą. ```bash curl -X PUT "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "value": 5200, "priority": "high" }' ``` **Odpowiedź** (`200`): `{ "success": true, "deal_id": "deal_abc123" }` --- ## Przenieś szansę sprzedaży do innego etapu `POST /deals/{dealId}/move` — treść `{ "new_stage_id": "stage-3", "new_position": 0 }`. Pozycja `0` umieszcza kartę na górze kolumny. ```bash curl -X POST "https://api.youraiconnector.com/v1/deals/deal_abc123/move?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "new_stage_id": "stage-3", "new_position": 0 }' ``` **Odpowiedź** (`200`): `{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }` --- ## Usuń szansę sprzedaży `DELETE /deals/{dealId}` — usuwa szansę sprzedaży. **Tej operacji nie można cofnąć.** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" ``` **Odpowiedź** (`200`): `{ "success": true }` --- ## Lejki Każde konto posiada główny lejek (`id: "default"`); możesz dodać do dziewięciu kolejnych, każdy z własnymi etapami. Identyfikatory etapów i tagi wyzwalające muszą być unikalne w obrębie wszystkich lejków na koncie, a każdy lejek może mieć oznaczony jeden etap jako `won` oraz jeden jako `lost`. ### Lista lejków `GET /pipelines` — wszystkie lejki, najpierw główny, każdy z etapami posortowanymi według pozycji. ```bash curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" ``` **Odpowiedź** (`200`): ```json { "success": true, "data": { "pipelines": [ { "id": "default", "name": "Sales", "position": 0, "is_default": true, "settings": { "sync_stage_tags": false }, "stages": [ { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null }, { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" } ] } ] } } ``` ### Utwórz lejek `POST /pipelines` — treść `{ "id"?, "name", "stages"?, "settings"? }`. Pomiń `id`, aby wygenerować go automatycznie. Każdy etap przyjmuje te same pola co okno dialogowe Etapy: `id`, `name`, `color`, `position`, opcjonalne `trigger_tag` (ścieżka tagu, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (etap tego samego lejka) oraz `outcome` (`"won"` lub `"lost"`). ```bash curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "reviews", "name": "Review requests", "stages": [ { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 }, { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" } ] }' ``` **Odpowiedź** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. Identyfikator etapu lub tag wyzwalający już użyty przez inny lejek to `400` wskazujący ten lejek; identyfikator, który już istnieje, to `409`. ### Aktualizuj lejek `PUT /pipelines/{pipelineId}` — treść `{ "name"?, "stages"?, "settings"? }`. `stages` zastępuje całą listę, podobnie jak w oknie dialogowym Etapy. Użyj `default` dla głównego lejka. Samego identyfikatora lejka nie można zmienić. ### Usuń lejek `DELETE /pipelines/{pipelineId}` — usuwa dodatkowy lejek (głównego nie można usunąć). Jeśli w jego etapach nadal znajdują się transakcje, wywołanie zwróci `409` wraz z `deal_count`; dodaj `?delete_deals=true`, aby usunąć te transakcje wraz z lejkiem. **Tej operacji nie można cofnąć.** **Odpowiedź** (`204`). --- ## Następne kroki - [Lejek sprzedaży](../deals/sales-pipeline.md) — jak działają etapy, tagi etapów, kilka lejków i tablica. - [API zadań](tasks.md) — zadania mogą być powiązane z transakcją za pomocą `deal_id`. - [Automatyzacje](../automations/automations.md) — kroki **Znajdź transakcje** i **Znajdź transakcję** odczytują te same dane w ramach przepływu pracy.