Przejdź do głównej zawartości

Instrukcja dla agenta AI

Poniżej znajduje się kompletne zadanie dla agenta AI piszącego kod (albo dla programisty): co zbudować, każde żądanie, jak bezpiecznie powtarzać i co zrobić z każdym błędem. Skopiuj je i przekaż swojemu agentowi razem z dostępem do własnego systemu poleceń.

Ten sam tekst jest na stronie „API RevShare” w Twoim panelu marki.

suly.gg integration task
# Task: connect our referral program to suly.gg (revenue-share offer)
suly.gg is a marketplace where video creators promote offers. Our referral program runs there as a revenue-share
offer: creators join it on suly.gg, we give each of them a referral code and a link, and we report how much to pay each
creator. suly.gg pays creators from the offer budget we funded and takes its fee on top. suly.gg never computes our
revenue or the creators' share: our system decides every amount.
## Access
- Base URL: https://suly.gg/api/partner/v1
- Every request carries the header `Authorization: Bearer <KEY>`. The key looks like `suly_` + 43 characters. It is a
secret: read it from the environment variable `SULY_API_KEY` (or our secret store). Never log it, never commit it,
never send it anywhere except https://suly.gg/api/partner/v1. If it leaks, a human replaces it in the suly.gg cabinet and the old key stops
working at once (401).
- JSON in and out; send `Content-Type: application/json` with every POST. Unknown fields or query parameters are
refused with 400.
- Money is a string in US dollars with a dot and at most 6 decimals: `"12.5"`, `"0.01"`. Responses always have 6
decimals: `"12.500000"`. Never send money as a JSON number.
## Endpoints
1. `GET /program` → the offer:
`{ "offerId", "title", "status": "live" | "ended", "share": { "percent", "base" }, "budget": { "funded", "remaining" }, "feePercent" }`.
`share` is what we promised creators (display only). `budget.remaining` pays accruals plus the fee.
2. `GET /participants?status=pending|active|rejected|all&page=N` → `{ "participants": [...], "total", "page", "pageSize": 50 }`,
newest first. A participant:
`{ "participantId", "status": "pending" | "active" | "rejected", "creator": { "userId", "name" }, "channels": [{ "platform", "name", "handle", "url", "views", "periodDays", "countries": [{ "country", "share" }] }], "code", "link", "rejectReason", "info": { "text", "updatedAt" } | null, "joinedAt", "updatedAt", "accrued" }`.
`views`/`periodDays` are the channel's views for the last 28 (or 30) days, or null; `countries` is the audience
share in percent. `pending` = waiting for a code from us.
3. `GET /participants/{participantId}` → one participant.
4. `POST /participants/{participantId}/code` with exactly `{ "code": "1-100 chars", "link": "https://… up to 1000 chars" }`
→ the participant, now `active`. Posting again replaces the code or the link; the creator sees them at once.
5. `POST /participants/{participantId}/reject` with `{ "reason": "1-500 chars" }` → the participant, now
`rejected`. The creator sees the reason. A later code makes them active again.
6. `POST /participants/{participantId}/info` with exactly `{ "text": "up to 1000 chars" }` → the participant with
`info` set. A note to this creator in our own words, shown on their offer page with the time: line breaks, "- " lists
and `**bold**` are kept. It replaces the note before; an empty text removes it. No money moves; it also works for
pending and rejected participants and after the offer ended.
7. `POST /accruals` with
`{ "participantId", "amount": "0.01 to 1000000", "externalId": "1-100 chars of A-Z a-z 0-9 . _ : -", "comment": "optional, up to 200 chars" }`
→ `{ "accrualId", "participantId", "creatorName", "externalId", "amount", "fee", "charged", "comment", "createdAt" }`.
`charged` = `amount` + `fee` leaves the offer budget; the creator receives `amount` at once and it cannot be
reversed. The creator sees the comment (e.g. "October 2026").
8. `GET /accruals?page=N&participantId=…` → `{ "accruals": [...], "total", "page", "pageSize": 50 }`, newest first.
## What to build
1. **Onboarding job** (every 5-15 minutes): page through `GET /participants?status=pending`. For each participant,
create or find the referral code and link for this creator in our system, keyed by `participantId` (stable), and
send them with `POST /participants/{id}/code`. If the creator does not fit our program, send
`POST /participants/{id}/reject` with a short, polite reason.
2. **Payout job** (on our payout schedule): for every active participant, take the amount our system owes for the
period and send `POST /accruals`. Use a deterministic `externalId` for that payout in our system (for example
`2026-10:<participantId>`) and save it before sending. On a network error, a timeout or 503, send the same request
again with the same `externalId` and the same data: suly.gg pays it only once. Never reuse an `externalId` for
different data (409 `EXTERNAL_ID_CONFLICT`). Skip amounts below 0.01.
3. **Budget check** before every payout run: `GET /program` and compare `budget.remaining` with the sum of
`amount × (1 + feePercent / 100)`. If it is not enough, pay nothing more and alert a human to add budget to the
offer in the suly.gg cabinet; accruals beyond the budget fail with 409 `INSUFFICIENT_BUDGET`.
4. **Reconciliation**: `GET /accruals` lists what suly.gg paid; match it to our payouts by `externalId`.
5. **Status job** (daily, and after every payout run): for every active participant send
`POST /participants/{id}/info` with what the creator cannot see on suly.gg: referrals counted, the current level or
percent, amounts still open and when the next accrual is due. Plain facts, no promises; write it in the language of
our offer text. Skip the request when the text did not change.
## Errors
Every error is an HTTP status with `{ "code", "messageKey", "retryable", "correlationId" }`. Log the code and the
correlationId (never the key).
| Status | Code | What to do |
| --- | --- | --- |
| 400 | INVALID_INPUT | Fix the request; do not retry as is |
| 401 | NOT_AUTHENTICATED | The key is missing, wrong or replaced: stop and alert a human |
| 403 | FORBIDDEN | The business account is blocked on suly.gg: stop and alert a human |
| 404 | NOT_FOUND | No such participant in this offer |
| 409 | OFFER_ENDED | The offer was closed: stop both jobs (reading still works) |
| 409 | PARTICIPANT_NOT_ACTIVE | The participant has no code or was rejected: send a code first |
| 409 | CREATOR_BANNED | The creator is banned on suly.gg: do not pay |
| 409 | INSUFFICIENT_BUDGET | Not enough budget for amount + fee: stop payouts, alert a human |
| 409 | EXTERNAL_ID_CONFLICT | This externalId was used with other data: investigate, never overwrite |
| 429 or 503 | (rate limit) / DEPENDENCY_UNAVAILABLE | Retry later with backoff (retryable) |
## Rules
- Keep requests modest: sequential calls are enough; back off on 429 and 503.
- Send only what the creator needs: the code, the link, the amount and a short comment. No personal data of players.
- `amount` is what the creator receives; the suly.gg fee is charged on top from the budget.
## Smoke test
```bash
curl -s https://suly.gg/api/partner/v1/program -H "Authorization: Bearer $SULY_API_KEY"
curl -s "https://suly.gg/api/partner/v1/participants?status=pending" -H "Authorization: Bearer $SULY_API_KEY"
```