Automatizálás API

Áttekintés

Ez a végpont igény szerint elindít egy e-mail automatizálást egyetlen feliratkozóhoz. Akkor használd, amikor a saját rendszeredben történik valami, aminek egy sorozatot kell indítania — elhagyott kosár, új vásárlás, változás a fiók aktivitásában.

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 Beállítások → Szervezeti beállítások → API menüpontban hozod létre és találod meg.

Végpont részletek

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

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

A végpont címe, a workflow_id törzsmező és a válaszüzenetek mind megtartják a workflow szót. Ez szándékos: a funkció a képernyőn „Munkafolyamatokból” „E-mail automatizálásokká” lett átnevezve, de a technikai neveket békén hagytuk, hogy a meglévő integrációk változtatás nélkül tovább működjenek. Ne írd át őket a kódodban.

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 az automatizáláshoz, 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ó automatizálás UUID-je. Az automatizálásnak 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 az automatizálásnak. 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 egy automatizálásban

Az API-n keresztül küldött egyéni adatok az automatizálás 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 meg az E-mail automatizálások (`Newsletter.Automations`) jogosultsága
`404`	Contact not found. Make sure the email is a verified newsletter contact.	Az e-mail nem hitelesített hírlevél kapcsolat a szervezetedben
`404`	Workflow not found. Make sure the workflow exists, is active, and has API trigger type.	Az automatizálás nem létezik, nem aktív, vagy nincs API triggerre állítva
`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 → Szervezeti 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
Az automatizálás aktív - a cél automatizálást Aktívra kell kapcsolni az Automatizálás-építőben
Az automatizálás API triggert használ - a 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 automatizálást indítanál nekik.

Integrációs legjobb gyakorlatok

Kapcsolatok előzetes hitelesítése - győződj meg róla, hogy a kapcsolat létezik, mielőtt automatizálást indítanál neki; lásd az Importálás / Exportálás oldalt
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 az automatizálásod 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