Programy poleceń

Endpointy „Programy poleceń” Zanfia Workspace API — ze schematami i przykładami kodu.

5 min czytaniaOstatnia aktualizacja: 10 wrz 2026

Programy poleceń (Marketing → Polecenia): program obejmuje jeden lub więcej Twoich produktów i nagradza uczestników za polecone zakupy według drabinki progów (kind: referral; warunki prowizyjne affiliate są zamodelowane, ale jeszcze nie działają). Programy startują jako inactive — aktywuj je przez PATCH. Uczestnicy to Twoi klienci: zapisz jednego po id klienta albo od razu wszystkich klientów produktów programu; każdy dostaje kod polecający, który wędruje jako ?ref= przez koszyk. Nagrody z approval: manual czekają w pendingRewards na Twoją decyzję; nieudane dostarczenia trafiają do failedDeliveries do ponowienia. Wszystkie endpointy wymagają nagłówka Authorization: Bearer — zobacz Uwierzytelnianie.

Lista programów poleceń

GET/referral-programs

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/referral-programs"

{  "programs": [    {      "id": "string",      "kind": "referral",      "name": "string",      "status": "active",      "productIds": [        "string"      ],      "attribution": {        "windowDays": 0,        "allowCouponAttribution": true,        "twoSidedDiscountId": "string"      },      "enrollment": "open",      "milestones": [        {          "id": "string",          "threshold": 0,          "recurring": true,          "approval": "automatic",          "reward": {            "type": "productAccess",            "productId": "string",            "priceId": "string",            "accessDays": 0          },          "emailTemplate": {            "subject": "string",            "html": "string"          }        }      ],      "commission": {        "type": "percent",        "value": 0,        "appliesTo": "firstOrder",        "holdDays": 0      },      "stats": {        "participants": 0,        "validReferrals": 0,        "invalidReferrals": 0,        "rewardsEarned": 0,        "rewardsPendingApproval": 0,        "rewardsDelivered": 0      },      "createdAt": "string",      "updatedAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

Utwórz program poleceń

POST/referral-programs

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Referrals 2.0 creator-side HTTP contract (products-service products.v1).

kind*ReferralProgramKind

Referrals 2.0 — workspace-native referral/affiliate programs.

Replaces the legacy per-product ProductReferralsDocument (engine in the deprecated apps/functions). Both shapes coexist in the same referral-programs collection during migration: legacy docs are keyed by productId and have no kind field; v2 docs are keyed by their own rprog_* id and always carry kind. Readers distinguish by kind.

Plan: plans/zanfia-2.0/referrals/rebuild-plan.md

Value in

"referral"
"affiliate"

name*string

productIds*array<string>

milestones?array<>

commission?|null

attribution?

enrollment?ReferralEnrollmentMode

How participants join an affiliate-kind program. Referral-kind programs are always effectively open to existing clients.

Value in

"open"
"inviteOnly"
"closed"

status?string

Value in

"active"
"inactive"

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs" \  -H "Content-Type: application/json" \  -d '{    "kind": "referral",    "name": "string",    "productIds": [      "string"    ]  }'

{  "program": {    "id": "string",    "kind": "referral",    "name": "string",    "status": "active",    "productIds": [      "string"    ],    "attribution": {      "windowDays": 0,      "allowCouponAttribution": true,      "twoSidedDiscountId": "string"    },    "enrollment": "open",    "milestones": [      {        "id": "string",        "threshold": 0,        "recurring": true,        "approval": "automatic",        "reward": {          "type": "productAccess",          "productId": "string",          "priceId": "string",          "accessDays": 0        },        "emailTemplate": {          "subject": "string",          "html": "string"        }      }    ],    "commission": {      "type": "percent",      "value": 0,      "appliesTo": "firstOrder",      "holdDays": 0    },    "stats": {      "participants": 0,      "validReferrals": 0,      "invalidReferrals": 0,      "rewardsEarned": 0,      "rewardsPendingApproval": 0,      "rewardsDelivered": 0    },    "createdAt": "string",    "updatedAt": "string"  }}

{  "error": "string",  "message": "string"}

Szczegóły programu (panel)

GET/referral-programs/{programId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

Response Body

`application/json`

curl -X GET "https://example.com/referral-programs/string"

{  "program": {    "id": "string",    "kind": "referral",    "name": "string",    "status": "active",    "productIds": [      "string"    ],    "attribution": {      "windowDays": 0,      "allowCouponAttribution": true,      "twoSidedDiscountId": "string"    },    "enrollment": "open",    "milestones": [      {        "id": "string",        "threshold": 0,        "recurring": true,        "approval": "automatic",        "reward": {          "type": "productAccess",          "productId": "string",          "priceId": "string",          "accessDays": 0        },        "emailTemplate": {          "subject": "string",          "html": "string"        }      }    ],    "commission": {      "type": "percent",      "value": 0,      "appliesTo": "firstOrder",      "holdDays": 0    },    "stats": {      "participants": 0,      "validReferrals": 0,      "invalidReferrals": 0,      "rewardsEarned": 0,      "rewardsPendingApproval": 0,      "rewardsDelivered": 0    },    "createdAt": "string",    "updatedAt": "string"  },  "participants": [    {      "id": "string",      "clientId": "string",      "refCode": "string",      "email": "string",      "firstName": "string",      "lastName": "string",      "status": "active",      "enrolledVia": "self",      "stats": {        "validReferrals": 0,        "invalidReferrals": 0,        "pendingReferrals": 0,        "rewardsEarned": 0,        "rewardsDelivered": 0,        "accruedCommission": 0,        "reversedCommission": 0      },      "createdAt": "string",      "updatedAt": "string"    }  ],  "pendingRewards": [    {      "id": "string",      "participantId": "string",      "refCode": "string",      "type": "referral",      "milestoneId": "string",      "milestoneOccurrence": 0,      "rewardType": "productAccess",      "approval": "automatic",      "rewardStatus": "pendingApproval",      "deliveredAt": "string",      "createdAt": "string",      "updatedAt": "string"    }  ],  "failedDeliveries": [    {      "id": "string",      "participantId": "string",      "refCode": "string",      "type": "referral",      "milestoneId": "string",      "milestoneOccurrence": 0,      "rewardType": "productAccess",      "approval": "automatic",      "rewardStatus": "pendingApproval",      "deliveredAt": "string",      "createdAt": "string",      "updatedAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

Aktualizuj program poleceń

PATCH/referral-programs/{programId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

status?string

Value in

"active"
"inactive"

productIds?array<string>

milestones?array<>

commission?|null

attribution?

enrollment?ReferralEnrollmentMode

How participants join an affiliate-kind program. Referral-kind programs are always effectively open to existing clients.

Value in

"open"
"inviteOnly"
"closed"

Response Body

`application/json`

curl -X PATCH "https://example.com/referral-programs/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "program": {    "id": "string",    "kind": "referral",    "name": "string",    "status": "active",    "productIds": [      "string"    ],    "attribution": {      "windowDays": 0,      "allowCouponAttribution": true,      "twoSidedDiscountId": "string"    },    "enrollment": "open",    "milestones": [      {        "id": "string",        "threshold": 0,        "recurring": true,        "approval": "automatic",        "reward": {          "type": "productAccess",          "productId": "string",          "priceId": "string",          "accessDays": 0        },        "emailTemplate": {          "subject": "string",          "html": "string"        }      }    ],    "commission": {      "type": "percent",      "value": 0,      "appliesTo": "firstOrder",      "holdDays": 0    },    "stats": {      "participants": 0,      "validReferrals": 0,      "invalidReferrals": 0,      "rewardsEarned": 0,      "rewardsPendingApproval": 0,      "rewardsDelivered": 0    },    "createdAt": "string",    "updatedAt": "string"  }}

{  "error": "string",  "message": "string"}

Archiwizuj program poleceń

POST/referral-programs/{programId}/archive

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs/string/archive"

{  "archived": true}

{  "error": "string",  "message": "string"}

Zapisz klienta do programu

POST/referral-programs/{programId}/participants

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

clientId*string

email*string

firstName?string|null

lastName?string|null

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs/string/participants" \  -H "Content-Type: application/json" \  -d '{    "clientId": "string",    "email": "string"  }'

{  "participant": {    "id": "string",    "clientId": "string",    "refCode": "string",    "email": "string",    "firstName": "string",    "lastName": "string",    "status": "active",    "enrolledVia": "self",    "stats": {      "validReferrals": 0,      "invalidReferrals": 0,      "pendingReferrals": 0,      "rewardsEarned": 0,      "rewardsDelivered": 0,      "accruedCommission": 0,      "reversedCommission": 0    },    "createdAt": "string",    "updatedAt": "string"  },  "alreadyEnrolled": true}

{  "error": "string",  "message": "string"}

Zapisz wszystkich klientów produktów programu

POST/referral-programs/{programId}/participants/enroll-all

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs/string/participants/enroll-all"

{  "enrolled": 0,  "alreadyEnrolled": 0,  "skippedWithoutAccount": 0}

{  "error": "string",  "message": "string"}

Zatwierdź lub odrzuć oczekującą nagrodę

POST/referral-programs/{programId}/rewards/{entryId}/resolve

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

entryId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

decision*string

Value in

"approve"
"reject"

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs/string/rewards/string/resolve" \  -H "Content-Type: application/json" \  -d '{    "decision": "approve"  }'

{  "decision": "approve",  "delivered": true}

{  "error": "string",  "message": "string"}

Ponów nieudane dostarczenie nagrody

POST/referral-programs/{programId}/rewards/{entryId}/retry-delivery

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

programId*string

entryId*string

Response Body

`application/json`

curl -X POST "https://example.com/referral-programs/string/rewards/string/retry-delivery"

{  "delivered": true}

{  "error": "string",  "message": "string"}

Czy ten artykuł był pomocny?

Powiązane artykuły

Coś się nie zgadza? Napisz do nas na support@zanfia.com.

Lista programów poleceń

200application/json

4XXapplication/json

Utwórz program poleceń

200application/json

4XXapplication/json

Szczegóły programu (panel)

200application/json

4XXapplication/json

Aktualizuj program poleceń

200application/json

4XXapplication/json

Archiwizuj program poleceń

200application/json

4XXapplication/json

Zapisz klienta do programu

200application/json

4XXapplication/json

Zapisz wszystkich klientów produktów programu

200application/json

4XXapplication/json

Zatwierdź lub odrzuć oczekującą nagrodę

200application/json

4XXapplication/json

Ponów nieudane dostarczenie nagrody

200application/json

4XXapplication/json

Powiązane artykuły

Przegląd API

Uwierzytelnianie i klucze API

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`