API transakcji

Transakcja to jedna szansa sprzedaży na Twojej tablicy lejka sprzedaży — 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)
Błędy i stronicowanie — zobacz Błędy i stronicowanie

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

{
  "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 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

curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

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

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)

{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }

Pobierz transakcję

GET /deals/{dealId}

curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Odpowiedź (200)

{ "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.

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)

{ "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ą.

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.

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ąć.

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.

curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"

Odpowiedź (200):

{
  "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").

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 — jak działają etapy, tagi etapów, kilka lejków i tablica.
API zadań — zadania mogą być powiązane z transakcją za pomocą deal_id.
Automatyzacje — kroki Znajdź transakcje i Znajdź transakcję odczytują te same dane w ramach przepływu pracy.

API transakcji #

Obiekt transakcji #

Lista transakcji #

Pobierz transakcję #

Utwórz transakcję #

Zaktualizuj transakcję #

Przenieś szansę sprzedaży do innego etapu #

Usuń szansę sprzedaży #

Lejki #

Lista lejków #

Utwórz lejek #

Aktualizuj lejek #

Usuń lejek #

Następne kroki #