Kauppojen API

Kauppa on yksi myyntimahdollisuus myyntiputkessasi — se sisältää otsikon, arvon, vaiheen, jossa se on, sekä valinnaisesti siihen liittyvän yhteyshenkilön ja sille määritetyn tiimin jäsenen. Tämä opas käsittelee kauppojen lukemista ja hallintaa API:n kautta.

Perus-URL — https://api.youraiconnector.com/v1
Todennus — API-avaimesi (katso Todennus)
Virheet ja sivutus — katso Virheet ja sivutus

Kaikki alla olevat esimerkit näyttävät ?apiKey=-kyselymuodon cURL-muodossa ja X-API-Key-otsikon JavaScriptissä ja Pythonissa – kumpi tahansa toimii jokaisessa päätepisteessä.

Kauppa-objekti

{
  "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 on yksi putkivaiheidesi tunnisteista – lue ne käyttämällä GET /pipelines (katso Putket alta). Vaihetunnisteet ovat yksilöllisiä kaikissa putkissa, joten pipeline_id johdetaan vaiheesta ja se on vain luku -muotoinen: default on pääputkesi, ja se on null, kun vaihetta ei enää ole olemassa. Aikaleimat ovat ISO 8601 -muodossa.

Kauppa tallentaa vain yllä näkyvät kentät. Kun luot tai päivität kaupan, kaikki muut kentät hylätään 400-virheellä, joka nimeää kyseisen kentän, joten mitään lähettämääsi tietoa ei katoa hiljaisesti. Säilytä ylimääräiset tiedot linkitetyn yhteyshenkilön mukautetuissa kentissä.

Listaa kaupat

GET /deals — palauttaa tilisi kaupat, uusimmat ensin.

Kyselyparametrit (kaikki valinnaisia): stage (vaihetunniste), pipeline_id (vain kyseisen putken kaupat), contact_id, limit (oletus 50, enintään 200), cursor (edellisen sivun next_cursor-arvosta).

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

Vastaus (200)

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

Hae kauppa

GET /deals/{dealId}

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

Vastaus (200)

{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }

Kauppa, jota ei ole olemassa tai joka kuuluu toiselle tilille, palauttaa 404.

Luo kauppa

POST /deals — title ja stage ovat pakollisia; stage on oltava yksi myyntiputkesi vaihetunnisteista.

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

Vastaus (201)

{ "success": true, "deal_id": "deal_abc123" }

Päivitä kauppa

PUT /deals/{dealId} — lähetä vain ne kentät, jotka haluat muuttaa (title, description, notes, value, stage, status, priority, contact_id, …). value täytyy olla numero.

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

Vastaus (200): { "success": true, "deal_id": "deal_abc123" }

Siirrä kauppa toiseen vaiheeseen

POST /deals/{dealId}/move — runko { "new_stage_id": "stage-3", "new_position": 0 }. Sijainti 0 asettaa kortin sarakkeen yläreunaan.

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 }'

Vastaus (200): { "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }

Poista kauppa

DELETE /deals/{dealId} — poistaa kaupan. Tätä toimintoa ei voi kumota.

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

Vastaus (200): { "success": true }

Putket

Jokaisella tilillä on pääputki (id: "default"); voit lisätä jopa yhdeksän muuta putkea, joista jokaisella on omat vaiheensa. Vaihetunnisteiden ja käynnistystunnisteiden on oltava yksilöllisiä kaikissa tilin putkissa, ja jokainen putki voi merkitä yhden vaiheen won-vaiheeksi ja yhden lost-lopputulokseksi.

Listaa putket

GET /pipelines – jokainen putki, pääputki ensin, ja jokaisen vaiheet lajiteltuna sijainnin mukaan.

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

Vastaus (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" }
        ]
      }
    ]
  }
}

Luo putki

POST /pipelines – runko { "id"?, "name", "stages"?, "settings"? }. Jätä id tyhjäksi, jos haluat, että se luodaan automaattisesti. Jokainen vaihe käyttää samoja kenttiä kuin Vaiheet-valintaikkuna: id, name, color, position, valinnainen trigger_tag (tunnistepolku, users/{uid}/tags/{tagId}), default_value, auto_move_after_days + auto_move_to_stage (saman putken vaihe) ja outcome ("won" tai "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" }
    ]
  }'

Vastaus (201): { "success": true, "data": { "pipeline": { ... } } }. Vaihetunniste tai käynnistystunniste, jota toinen putki jo käyttää, on 400, joka nimeää kyseisen putken; jo olemassa oleva tunniste on 409.

Päivitä putki

PUT /pipelines/{pipelineId} – runko { "name"?, "stages"?, "settings"? }. stages korvaa koko listan, kuten Vaiheet-valintaikkunassa. Käytä default pääputkelle. Itse putken tunnistetta ei voi muuttaa.

Poista putki

DELETE /pipelines/{pipelineId} – poistaa ylimääräisen putken (pääputkea ei voi poistaa). Jos sen vaiheissa on vielä kauppoja, kutsu vastaa 409 virheellä deal_count; lisää ?delete_deals=true poistaaksesi kyseiset kaupat yhdessä putken kanssa. Tätä ei voi kumota.

Vastaus (204).

Seuraavat vaiheet

Myyntiputki — miten vaiheet, vaihetunnisteet, useat myyntiputket ja näkymä toimivat.
Tehtävien API — tehtävät voidaan linkittää kauppaan käyttämällä deal_id.
Automaatiot — Etsi kauppoja- ja Etsi kauppa -vaiheet lukevat samaa tietoa työnkulun sisällä.

Kauppojen API #

Kauppa-objekti #

Listaa kaupat #

Hae kauppa #

Luo kauppa #

Päivitä kauppa #

Siirrä kauppa toiseen vaiheeseen #

Poista kauppa #

Putket #

Listaa putket #

Luo putki #

Päivitä putki #

Poista putki #

Seuraavat vaiheet #