Munkafolyamat API | Yaplet HU

Áttekintés

A Munkafolyamat indítás API lehetővé teszi hírlevél munkafolyamatok programozottan való aktiválását specifikus feliratkozókhoz. Ez hasznos automatizált sorozatok indításához az e-kereskedelmi platformodból, CRM-edből vagy bármely külső rendszerből, amikor specifikus események történnek (pl. elhagyott kosár, új vásárlás, fiók aktivitás).

Hitelesítés

Minden API kéréshez hitelesítés szükséges az API kulcsoddal.

API kulcs szükségesAdd meg a Y-API-Key fejlécet minden kérésben. Az API kulcsodat a vezérlőpult beállításokban találod a Beállítások > API menüpont alatt.

Végpont részletek

POST `https://yaplet.com/api/newsletter/workflow/start`

Munkafolyamat indítása egy specifikus feliratkozóhoz. A feliratkozónak hitelesített hírlevél kapcsolatnak kell lennie a szervezetedben, és a munkafolyamatnak aktívnak kell lennie API trigger típussal.

Kérés struktúra

Fejlécek

{
  "Content-Type": "application/json",
  "Y-API-Key": "YOUR_API_KEY"
}

Kérés törzs

{
  "email": "[email protected]",
  "workflow_id": "your-workflow-id",
  "key1": "value1",
  "key2": "value2"
}

Fontos: Az egyéni adatmezők legfelső szintű mezőkként kerülnek elküldésre az email és workflow_id mellett, nem beágyazva külön objektumba.

Válasz példák

Sikeres indítás

Állapot: 200 OK

{
  "success": true
}

Már sorba állított

Állapot: 200 OK

{
  "success": true,
  "message": "Workflow run already queued"
}

Ha a feliratkozónak már van függő futása ehhez a munkafolyamathoz, az API sikert ad vissza duplikátum létrehozása nélkül.

Kódpéldák

const response = await fetch("https://yaplet.com/api/newsletter/workflow/start", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Y-API-Key": "YOUR_API_KEY"
    },
    body: JSON.stringify({
        email: "[email protected]",       // Required
        workflow_id: "your-workflow-id",        // Required
        cartItems: "<html>...</html>",          // Optional custom data
        couponCode: "SAVE20",                   // Optional custom data
        orderTotal: "49.99"                     // Optional custom data
    })
});

const result = await response.json();
console.log("Response:", result);

curl -X POST "https://yaplet.com/api/newsletter/workflow/start" \\
  -H "Content-Type: application/json" \\
  -H "Y-API-Key: YOUR_API_KEY" \\
  -d '{
    "email": "[email protected]",
    "workflow_id": "your-workflow-id",
    "cartItems": "<html>...</html>",
    "couponCode": "SAVE20",
    "orderTotal": "49.99"
  }'

<?php

$url = "https://yaplet.com/api/newsletter/workflow/start";

$headers = [
    'Content-Type: application/json',
    'Y-API-Key: YOUR_API_KEY'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "email" => "[email protected]",       // Required
    "workflow_id" => "your-workflow-id",        // Required
    "cartItems" => "<html>...</html>",          // Optional custom data
    "couponCode" => "SAVE20",                   // Optional custom data
    "orderTotal" => "49.99"                     // Optional custom data
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $result = json_decode($response, true);
    echo "Response: " . print_r($result, true);
} else {
    throw new Exception("Error: " . $response);
}
?>

import requests

url = "https://yaplet.com/api/newsletter/workflow/start"

headers = {
    "Content-Type": "application/json",
    "Y-API-Key": "YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json={
    "email": "[email protected]",       # Required
    "workflow_id": "your-workflow-id",        # Required
    "cartItems": "<html>...</html>",          # Optional custom data
    "couponCode": "SAVE20",                   # Optional custom data
    "orderTotal": "49.99"                     # Optional custom data
})

if response.status_code == 200:
    result = response.json()
    print("Response:", result)
else:
    raise Exception(f"Error: {response.text}")

Mezőhivatkozás

Kötelező mezők

Mező	Típus	Leírás
`email`	`string`	A feliratkozó e-mail címe. Hitelesített hírlevél kapcsolatnak kell lennie a szervezetedben.
`workflow_id`	`string`	Az indítandó munkafolyamat UUID-je. A munkafolyamatnak aktívnak kell lennie és API trigger típussal kell rendelkeznie.
`Y-API-Key`	`header`	API hitelesítési kulcs. A kérés fejlécekben kell szerepelnie.

Opcionális mezők (egyéni adatok)

A kérés törzsben bármely további legfelső szintű mező egyéni adatként kezelődik és átadásra kerül a munkafolyamatba. Ezek az értékek elérhetővé válnak a későbbi E-mail és Webhook csomópontokban {{key}} helyettesítőkkel.

Korlátozás	Limit
Mezők maximális száma	20
Kulcs típus	Csak szöveg
Érték típus	Szöveg vagy szám

Az egyéni adat értékek biztonsági okokból tisztításra kerülnek. HTML tartalom engedélyezett, de XSS támadások megelőzésére tisztításra kerül.

Egyéni adatok használata munkafolyamatokban

Az API-n keresztül küldött egyéni adatok a munkafolyamat egészében elérhetők:

E-mail csomópontok: Használd a {{key}} helyettesítőket tárgysorokban és e-mail törzs tartalomban
Webhook csomópontok: Add meg a {{key}}-t webhook URL-ekben és törzs értékekben
Feltétel csomópontok: Értékeld ki az egyéni adat értékeket elágazási logikához

Példa: Ha couponCode: "SAVE20"-t küldesz az API hívásodban, a {{couponCode}}-ot használhatod az e-mail sablonodban a kuponkód megjelenítéséhez a feliratkozónak.

Hibakezelés

Gyakori hibakódok

Kód	Üzenet	Leírás
`401`	API key is required in Y-API-Key header	Hiányzó Y-API-Key fejléc
`401`	Invalid API key	A megadott API kulcs nem egyezik egyetlen rendszerbeli kulccsal sem
`403`	Unauthorized	A szervezetnek nincs Hírlevél munkafolyamatok engedélye
`404`	Contact not found	Az e-mail nem hitelesített hírlevél kapcsolat a szervezetedben
`404`	Workflow not found	A munkafolyamat nem létezik, nem aktív, vagy nincs API trigger típusa
`400`	Maximum of 20 custom fields allowed	Túl sok egyéni adatmező a kérésben
`400`	Custom data values must be strings or numbers	Érvénytelen egyéni adat értéktípus
`500`	Failed to start workflow	Váratlan szerverhiba

Előfeltételek

Az API használata előtt biztosítsd:

API kulcs generálva van - Menj a Beállítások > API menüpontra a létrehozáshoz
Kapcsolat létezik és hitelesítve van - A feliratkozó e-mailnek a hírlevél kapcsolataid között kell lennie "VERIFIED" állapottal
Munkafolyamat aktív - A cél munkafolyamatot aktiválni kell a munkafolyamat szerkesztőben
Munkafolyamatnak API triggere van - A munkafolyamat trigger típusának "API"-ra kell lennie állítva a trigger beállításokban

Ha a feliratkozó e-mail nem található vagy nincs hitelesítve, 404-es hibát kapsz. Győződj meg róla, hogy a kapcsolatok importálva és hitelesítve vannak, mielőtt munkafolyamatokat aktiválnál nekik.

Integrációs legjobb gyakorlatok

Kapcsolatok előzetes hitelesítése - Használd a Tömeges Upsert API-t a kapcsolatok létezésének biztosítására munkafolyamatok indítása előtt
Hibák elegáns kezelése - Ellenőrizd a válasz állapotkódokat és implementálj újrapróbálkozási logikát 500-as hibákhoz
Duplikált triggerek elkerülése - Az API megakadályozza a duplikált függő futásokat, de tervezd az integrációdat a szükségtelen hívások elkerülésére
Egyéni adatok minimalizálása - Csak olyan adatokat küldj, amelyeket a munkafolyamatod ténylegesen használ e-mail vagy webhook csomópontokban
Egyetlen kapcsolattal tesztelés - Ellenőrizd, hogy az integrációd helyesen működik, mielőtt éles forgalomra skáláznád