api-referencePOST
Dostępne automatyczne śledzenie
Przy Stripe, LemonSqueezy lub Polar ten punkt końcowy nie jest potrzebny. Płatności są śledzone automatycznie po połączeniu dostawcy płatności.POST
https://analytics.flowsery.com/analytics/api/v1/paymentsRejestruje płatność i przypisuje przychód. Wymagane jest amount; transactionId oraz visitorUid lub sessionUid warto wysłać, jeśli są dostępne.
Bearer Token (token obszaru roboczego lub klucz API witryny)
Tokeny obszaru roboczego wymagają wskazania witryny
Tokeny API obszaru roboczego mają dostęp do wszystkich witryn w obszarze. Należy przekazaćwebsiteId lub domain, aby Flowsery wiedziało, której witryny dotyczy zapytanie lub zmiana. Klucze API witryn są już przypisane do jednej witryny, więc można to pominąć.Wskazanie witryny
| Parametr | Typ | Opis |
|---|---|---|
websiteId | string | ID witryny używane z tokenem API obszaru roboczego. Pole należy umieścić w treści JSON, chyba że podano domain. Należy pominąć przy uwierzytelnianiu kluczem API witryny. |
domain | string | Domena witryny używana z tokenem API obszaru roboczego, gdy nie podano websiteId. Pole należy umieścić w treści JSON. Należy pominąć przy uwierzytelnianiu kluczem API witryny. |
Treść żądania
| Parametr | Typ | Opis |
|---|---|---|
amountWYMAGANE | number | Wymagane. Kwota w głównych jednostkach waluty, np. 29.99. Z isRefund oznacza kwotę zwrotu. 0 rejestruje cel free_trial zamiast celu płatności. |
currency | string | Kod ISO 4217, np. "USD", "EUR" lub "GBP". Po pominięciu domyślnie "USD", a nie waluta witryny. |
transactionId | string | Własny identyfikator płatności. Musi być unikalny: powtórzony jest odrzucany z 409 Conflict, a nie deduplikowany. Wysłany ponownie z isRefund oznacza płatność jako zwróconą, a później pozwala ją usunąć. |
visitorUid | string | Opcjonalny identyfikator odwiedzającego Flowsery, zwykle z cookie _fs_vid odczytanego na własnym backendzie. |
sessionUid | string | Opcjonalny identyfikator sesji Flowsery, zwykle z cookie _fs_sid. |
email | string | Adres e-mail klienta. |
name | string | Imię i nazwisko klienta. |
customerId | string | Identyfikator klienta u dostawcy płatności. |
isRenewal | boolean | True dla płatności cyklicznych. Odnowienia liczą się jako przychód, ale pomijają automatyczny cel płatności. Domyślnie false. |
isRefund | boolean | True rejestruje zwrot. Z istniejącym transactionId aktualizuje zwróconą kwotę tej płatności zamiast dodawać rekord. Domyślnie false. |
timestamp | string | Czas płatności w ISO 8601, do uzupełniania danych wstecz. Domyślnie teraz. |
Odpowiedź po sukcesie zawiera tylko komunikat potwierdzający.
Błędy
Żądanie bez amount zwraca 400 Bad Request. transactionId już zapisany dla tej witryny zwraca 409 Conflict, chyba że isRefund ma wartość true.Przykładowe żądanie (Node.js)
const handler = async (req, res) => {
const _fs_vid = req.cookies._fs_vid;
const _fs_sid = req.cookies._fs_sid;
const response = await fetch(
"https://analytics.flowsery.com/analytics/api/v1/payments",
{
method: "POST",
headers: {
Authorization: `Bearer ${FLOWSERY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
websiteId: process.env.FLOWSERY_WEBSITE_ID,
amount: 29.99,
currency: "USD",
transactionId: "payment_456",
visitorUid: _fs_vid,
sessionUid: _fs_sid,
email: "buyer@example.com",
}),
}
);
res.status(200).send("Payment tracked");
};200
{
"status": "success",
"data": [{
"message": "Payment recorded successfully"
}]
}