Integrációk

Az integrációkkal a StickyPrompts a saját rendszereidben is tud műveleteket végezni. Az API-n keresztül kapcsolatokat hozhatsz létre, majd közvetlenül használhatod őket: SQL-t futtathatsz egy adatbázison, e-mailt küldhetsz, kereshetsz egy CRM-ben vagy frissítheted az adatait, és fájlokat mozgathatsz a Google Drive-ra és onnan vissza. Mindez ugyanaz a mechanizmus, amelyet az alkalmazás is használ, amikor valaki a chatben kér ilyesmit.

Minden útvonal a https://api.stickyprompts.com/api/v1 címhez képest értendő. A kulcs a tulajdonosa nevében jár el, így ugyanazok a megosztási és adminisztrátori szabályok érvényesek, mint az alkalmazásban.

Alapfogalmak

Szolgáltatók

Az útvonalakban szereplő :provider és a válaszokban szereplő provider pontosan ezeket a karakterláncokat használja:

A korlátok tulajdonosonként értendők: személyes kapcsolatoknál felhasználónként, megosztott kapcsolatoknál munkaterületenként.

Hatókör

Minden kapcsolat vagy personal (csak a tulajdonosa látja és használja), vagy workspace (a munkaterületen mindenki használhatja). Munkaterületi kapcsolatot csak a munkaterület tulajdonosai és adminjai hozhatnak létre, módosíthatnak és törölhetnek, és csak ők olvashatják a tárolt adatait. Bármelyik tag használhatja viszont: lekérdezhet rajta, küldhet rajta keresztül, olvashatja a CRM-rekordokat, írási hozzáféréssel pedig írhatja is őket. Az a kapcsolat, amelyet nem láthatsz, mindig 404-es, sosem 403-as állapotkóddal válaszol.

Hitelesítő adatok vagy OAuth

• Adatbázis-, e-mail- és CRM-kapcsolatokat egyetlen hívással hozhatsz létre, a hitelesítő adatokat a kérés törzsében küldve. A szerver előbb ellenőrzi őket a szolgáltatónál: megnyitja az adatbázis-kapcsolatot, hitelesít az SMTP-szerveren, vagy tesztüzenetet küld a Postmarkon, a Resenden vagy a SendGriden keresztül. Ezt egy tisztán API-alapú kliens is végig tudja vinni az elejétől a végéig.
• A Google Drive OAuth-t használ. A csatlakoztató hívás egy auth_url címet ad vissza; ezt egy embernek kell megnyitnia, és jóváhagynia a Google hozzájárulási képernyőjén. A kódod átadhatja a linket egy felhasználónak, majd addig kérdezheti le a GET /integration/connections?provider=google_drive végpontot, amíg a kapcsolat meg nem jelenik.

A titkos adatokat egyik végpont sem adja vissza soha.

Állapot

A kapcsolat status mezője active, needs_reauth, revoked vagy error lehet. Ha egy nem aktív kapcsolaton hívod meg bármelyik kapcsolati útvonalat, a válasz 409 {"error":"reconnect_required"}. Jelenleg csak a Google Drive-kapcsolatok kerülhetnek ki az active állapotból; ezeket az újracsatlakoztatással javíthatod.

Hibák

Katalógus és kapcsolatok

GET /integration

A szolgáltatók katalógusa: mire képes az egyes szolgáltató, és hány kapcsolatod van már vele.

[
  {
    "provider": "postgres",
    "display_name": "PostgreSQL",
    "capabilities": ["test_connection", "schema_browse", "query"],
    "availability": "available",
    "connection_count": 1,
    "max_connections": 0
  }
]

A max_connections: 0 korlátlan számú kapcsolatot jelent. A közös, egyetlen e-mail-kapcsolatra vonatkozó korlát itt nem jelenik meg.

GET /integration/ssh-tunnel/public-key

Az adatbázis-kapcsolatok SSH-átjárószerveren (jump host) keresztül privát adatbázist is elérhetnek. Add hozzá ezt a nyilvános kulcsot az átjárószerveren lévő SSH-felhasználó authorized_keys fájljához, és engedélyezd a StickyPrompts címét a tűzfaladon.

{ "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... stickyprompts" }

POST /integration/:provider/connect

Új kapcsolatot hoz létre (meglévőt sosem cserél le). A törzs egyetlen lapos objektum: a közös mezők és a szolgáltató saját mezői.

curl -X POST https://api.stickyprompts.com/api/v1/integration/postgres/connect \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northwind Retail DB",
    "scope": "workspace",
    "database_permission": "read_only",
    "host": "localhost",
    "port": 5432,
    "database": "retail",
    "schema": "public",
    "username": "sp_reader",
    "password": "********",
    "ssl_mode": "disable",
    "ssh_host": "bastion.northwind.example",
    "ssh_port": 22,
    "ssh_username": "stickyprompts"
  }'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/integration/postmark/connect",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={
        "name": "Northwind Mailer",
        "scope": "workspace",
        "default_from_email": "team@northwind.example",
        "default_from_name": "Northwind Team",
        "server_token": os.environ["POSTMARK_SERVER_TOKEN"],
    },
)
print(r.status_code, r.json())   # 200 {"connection_id": 42}

const res = await fetch("https://api.stickyprompts.com/api/v1/integration/pipedrive/connect", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Pipedrive - Sales",
    scope: "workspace",
    api_token: process.env.PIPEDRIVE_TOKEN,
    allow_write: true,
  }),
});
console.log(res.status, await res.json()); // 200 {"connection_id": 43}

A válasz 200 {"connection_id": 42}. A google_drive esetében viszont 200 {"auth_url": "..."} a válasz: a csatlakozás befejezéséhez egy embernek meg kell nyitnia ezt az URL-t.

GET /integration/connections

Minden kapcsolat, amelyet láthatsz (a sajátjaid és a munkaterületed megosztott kapcsolatai), a legújabbal kezdve. Szűrhetsz is a nem kötelező ?provider=<provider> paraméterrel.

[
  {
    "id": 42,
    "provider": "postgres",
    "name": "Northwind Retail DB",
    "description": "Demo retail data: stores, orders, products, customers.",
    "scope": "workspace",
    "status": "active",
    "account_name": "sp_reader@localhost:5432/retail",
    "connected_at": "2026-09-28T12:55:00Z",
    "database_permission": "read_only"
  }
]

Az account_name nem titkos címke: adatbázisoknál user@host:port/database, e-mailnél az alapértelmezett feladó, ActiveCampaignnél a fiók URL-je. A CRM írási hozzáférése nem szerepel ebben a listában; azt a GET .../crm/connection végpontból olvashatod ki.

PATCH /integration/connections/:connectionId

Átnevezés, az adatbázis-jogosultsági szint módosítása vagy a hitelesítő adatok cseréje. A name mezőt mindig küldd el (ha nem nevezed át a kapcsolatot, a jelenlegi nevet). A description mezőt a szerver mindig felülírja, így ha kihagyod, törlődik. A szolgáltatói mezők közül csak azok változnak, amelyeket elküldesz; ha bármelyik hitelesítő mező szerepel a kérésben, a szerver mentés előtt újra ellenőrzi az összefésült konfigurációt (sikertelenség esetén 422). Adatbázisoknál a "ssh_host": "" kikapcsolja az SSH-alagutat. Sikeres hívás után 200-as választ ad, üres törzzsel.

DELETE /integration/connections/:connectionId

Törli a kapcsolatot és a tárolt hitelesítő adatait. Google Drive esetén előbb a Google-nél is visszavonja a hozzáférést. A válasz 204.

POST /integration/connections/:connectionId/reconnect

Új OAuth-hozzájárulást indít egy Google Drive-kapcsolathoz; a kapcsolat azonosítója és neve megmarad. A válasz 200 {"auth_url": "..."}. A hitelesítő adatokkal csatlakozó szolgáltatók 501-es kóddal válaszolnak; ezeket PATCH kéréssel frissítsd.

Adatbázisok

Jogosultsági szintek

Hogy a lekérdezési végpont milyen SQL-t fogad el, azt a kapcsolat database_permission beállítása dönti el, függetlenül attól, mit enged az API-kulcs:

A read_only és a create_update szinten a szerver a teljes utasítást átvizsgálja tiltott kulcsszavak után, ezért egy olvasó lekérdezést is elutasít, ha az például egy oszlopnévben vagy egy karakterláncban az update szót tartalmazza. MySQL, MariaDB és PostgreSQL esetén a csak olvasási munkamenetek ráadásul csak olvasható módban nyílnak meg; SQL Servernél egyedül a kulcsszó-ellenőrzés véd. Mindenképpen olyan adatbázis-felhasználóval csatlakozz, amelynek csak azok a jogai vannak meg, amelyeket valóban meg akarsz adni.

GET /integration/connections/:connectionId/database/schema

A kapcsolat sémájában lévő összes tábla és nézet, az oszlopaikkal együtt:

{
  "schema": {
    "name": "public",
    "tables": [
      {
        "schema": "public",
        "name": "demo_orders",
        "columns": [
          { "name": "id", "data_type": "integer", "nullable": false },
          { "name": "customer_id", "data_type": "integer", "nullable": false },
          { "name": "status", "data_type": "text", "nullable": true }
        ]
      }
    ]
  }
}

GET /integration/connections/:connectionId/database/connection

A tárolt kapcsolati adatok, jelszó nélkül. Munkaterületi kapcsolatoknál csak a tulajdonosok és az adminok kérhetik le. Az üresen hagyott mezők 0 vagy "" értékkel jönnek vissza, pedig a csatlakozáskor alapértelmezett érték volt érvényben.

POST /integration/connections/:connectionId/database/query

curl -X POST https://api.stickyprompts.com/api/v1/integration/connections/42/database/query \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT c.name, SUM(o.total) AS revenue FROM demo_orders o JOIN demo_customers c ON c.id = o.customer_id GROUP BY c.name ORDER BY revenue DESC LIMIT 5"}'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/integration/connections/42/database/query",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={"query": "SELECT name, city FROM demo_customers ORDER BY name", "row_limit": 50},
)
data = r.json()
rows = [dict(zip(data["columns"], row)) for row in data["rows"]]

const res = await fetch(
  "https://api.stickyprompts.com/api/v1/integration/connections/42/database/query",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: "SELECT name, city FROM demo_customers ORDER BY name" }),
  },
);
const { columns, rows, truncated } = await res.json();

Válasz egy SELECT utasításra:

{
  "columns": ["name", "revenue"],
  "rows": [["Hawthorne Goods", "18240.00"], ["Cedar & Pine Outfitters", "15110.50"]],
  "row_count": 2,
  "truncated": false
}

A truncated: true azt jelenti, hogy a row_limit korláton túl is voltak sorok. A numerikus oszlopok gyakran karakterláncként érkeznek. A többi utasítás (amelyet a magasabb szintek engedélyeznek) csak a row_count mezőt adja vissza, vagyis az érintett sorok számát. Az adatbázis által dobott SQL-hibák 500-as kóddal térnek vissza, az adatbázis hibaüzenete nélkül, ezért a lekérdezéseket előbb egy adatbázis-kliensben próbáld ki.

E-mail

A levelek mindig a csatlakoztatott fiók saját hitelesítő adataival mennek ki; a StickyPrompts nem biztosít saját feladót.

GET /integration/connections/:connectionId/email/connection

A feladóbeállítások (provider, default_from_email, default_from_name, default_reply_to, SMTP esetén pedig a hoszt, a port, a felhasználónév és a titkosítás is). Tokeneket és jelszavakat soha nem ad vissza. Munkaterületi kapcsolatoknál csak a tulajdonosok és az adminok kérhetik le.

POST /integration/connections/:connectionId/email/send

curl -X POST https://api.stickyprompts.com/api/v1/integration/connections/41/email/send \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "email": "sales@northwind.example", "name": "Sales team" }],
    "subject": "Pipedrive: Deals at Proposal Made",
    "html_body": "<p>2 deals at Proposal Made, worth $28,788.</p>",
    "text_body": "2 deals at Proposal Made, worth $28,788."
  }'

A válasz 200 {"message_id": "<...>", "provider": "postmark"}. Az üzenetazonosító a szolgáltatótól származik, így könnyen megtalálod vele az üzenetet a szolgáltató irányítópultján.

CRM

Olvasni minden CRM-kapcsolaton lehet. Az íráshoz (kontaktok hozzáadása és szerkesztése, üzletek létrehozása) a kapcsolaton engedélyezni kell az allow_write beállítást.

Kontakt: email (minden írásnál kötelező, szerkesztéskor pedig ez alapján keresi meg a szerver a kontaktot), first_name, last_name, phone, company, custom_fields (szolgáltatófüggő), list_ids (Brevo, ActiveCampaign) és tag_ids (ActiveCampaign). Az eredmény formája: {"remote_id", "provider", "contact"}.

Üzlet (deal): title, value, currency, contact_email (egy meglévő kontakthoz kell tartoznia) és stage (tetszőleges szöveges címke). Az eredmény formája: {"remote_id", "provider", "deal"}.

GET /integration/connections/:connectionId/crm/connection

{"provider": "pipedrive", "allow_write": true} (ActiveCampaignnél az api_url mezővel kiegészítve).

GET /integration/connections/:connectionId/crm/contacts

Kontaktok keresése a kötelező query paraméterrel, valamint nem kötelező, szögletes zárójeles jelöléssel megadott szolgáltatói szűrőkkel, például ?query=priya&filters[organization_id]=1. A Pipedrive és az ActiveCampaign szabad szöveges keresést végez; a Brevo egyetlen pontos e-mail-címre vagy azonosítóra keres rá.

GET /integration/connections/:connectionId/crm/contacts/list

Kontaktok böngészése. Add meg a limit értékét (alapértelmezés: 50), majd lapozz a cursor (Pipedrive: az előző next_cursor értéke) vagy az offset (ActiveCampaign, Brevo) paraméterrel. A válasz: {"contacts": [...], "has_more": true, "next_cursor": "..."}.

POST /integration/connections/:connectionId/crm/contacts

Kontaktot ad hozzá. Mindig újat hoz létre, akkor is, ha az e-mail-cím már létezik, ezért előbb keress rá.

{ "email": "priya.raman@hawthornegoods.example", "first_name": "Priya", "last_name": "Raman", "company": "Hawthorne Goods" }

PATCH /integration/connections/:connectionId/crm/contacts

Szerkeszti a megadott email címhez tartozó kontaktot; csak az elküldött mezők változnak (egy mező törléséhez küldj "" értéket). Új kontaktot sosem hoz létre, ilyenkor a válasz: 404 "no matching contact was found in the crm to update".

GET /integration/connections/:connectionId/crm/deals

Üzletek keresése a cím vagy a hozzájuk kapcsolt kontakt e-mail-címe alapján a query paraméterrel, valamint szolgáltatói szűrőkkel (Pipedrive esetén: status, person_id, organization_id, exact_match).

GET /integration/connections/:connectionId/crm/deals/list

Üzletek böngészése, a kontaktokhoz hasonló lapozással. A Pipedrive-szűrők között van a stage_id, a status, az owner_id és a pipeline_id.

POST /integration/connections/:connectionId/crm/deals

{ "title": "Cedar & Pine - Scale plan, 42 stores", "value": 4788, "currency": "USD", "contact_email": "marcus.webb@cedarpine.example", "stage": "Proposal Made" }

Ha egyik kontakthoz sem tartozik ez az e-mail-cím, a válasz 404.

GET /integration/connections/:connectionId/crm/lists, /crm/tags

Listák (Brevo, ActiveCampaign) és címkék (ActiveCampaign) [{"id": "12", "name": "Newsletter"}] formában, szűrőkhöz és a kontaktok list_ids / tag_ids mezőjéhez. A többi szolgáltató 501-es kóddal válaszol.

Google Drive

A tárhelyútvonalak mindig a saját, személyes Drive-kapcsolatodon dolgoznak, és a szolgáltatót az útvonalban kapják meg: /integration/google_drive/storage/.... A mappák és elemek azonosítója root vagy egy Drive-azonosító.

GET /integration/:provider/storage/entries

Egy mappa tartalmának listázása: folder_id (alapértelmezés: root), page_token, page_size (1-200, alapértelmezés: 100), kind (folder vagy file). A válasz: {"entries": [...], "next_page_token": "", "breadcrumbs": [...]}. Minden elemnek van id, name, kind, mime_type, size, modified_at, web_url, importable és import_name mezője (a Docs- és Drawings-fájlokat PDF-ként, a Sheets-fájlokat XLSX-ként, a Slides-fájlokat PPTX-ként importálja a rendszer).

GET /integration/:provider/storage/search

A kötelező query paraméter, valamint ugyanazok a lapozási paraméterek és szűrők.

GET /integration/:provider/storage/entry/:entryId

POST /integration/:provider/storage/import

1-20 Drive-elemet (entry_ids) másol át a StickyPromptsba normál fájlként, igény szerint egy projekthez (project_id) csatolva. Minden elem a többitől függetlenül sikerül vagy hiúsul meg, ezért mindig ellenőrizd a failed mezőt: {"files": [...], "failed": [{"entry_id": "...", "error": "..."}]}. Fájlonként legfeljebb 100 MB.

POST /integration/:provider/storage/export

Egy saját StickyPrompts-fájlodat (file_id) másolja egy Drive-mappába (folder_id, a root is megengedett), igény szerint a name mezővel átnevezve.

Kapcsolódó oldalak