Go SDK
Установка, методы и версии клиента для машинной интеграции CPA-сети.
SDK — Go-библиотека к машинной двери сети: партнёры, офферы, ссылки, клики, конверсии, выплаты и статистика через /federation/v1/cpa/*. Рекламодателю, который передаёт конверсии постбэком, SDK не нужен — ему нужен гайд по постбэкам.
| Задача | Дверь | Документ |
|---|---|---|
| сообщить сети о заказе (рекламодатель) | постбек, методы POST и GET /cpa/postback/* | «Постбэки и цели» |
| управлять сетью машиной (оператор) | /federation/v1/cpa/* | этот гайд |
Установка
Нужен Go; минимальная версия указана в go.mod библиотеки:
go get go.recca.ru/sdk
| Пакет | Что в нём |
|---|---|
go.recca.ru/sdk/cpa | клиент CPA-двери: опции, ошибки, короткие имена типов |
go.recca.ru/sdk/cpatypes | типы контракта: деньги, идентификаторы, параметры |
go.recca.ru/sdk/cpatest | стенд и приёмочный набор Conformance |
go.recca.ru/sdk/webhook | проверка подписи исходящих вебхуков |
go.recca.ru/sdk/postback | подпись и проверка входящего постбэка рекламодателя |
go.recca.ru/sdk/federation | клиент методов федерации (tenant API) — отдельный от CPA-двери; состав и изменения по версиям — в CHANGELOG библиотеки |
Исходный код и CHANGELOG библиотеки — в репозитории github.com/recca-ru/sdk-go.
Прежний путь go.recca.ru/cpa остаётся живым: версии Go необратимы, и тот, кто уже завендорил его, не ломается. Новый код берёт go.recca.ru/sdk/cpa.
Ключ сети
Один ключ адресует всю сеть: значение вида rtk_live_… передаётся заголовком X-Recca-Tenant-Key и живёт на вашем сервере — в браузер не попадает. Ключ выпускает сам владелец организации: в настройках организации, раздел «API-ключи». Там же выбираются права ключа (скоупы), срок действия и список разрешённых адресов (IP-allowlist). Значение ключа показывается один раз при выпуске — сохраните его сразу.
Self.Get отвечает ключу о нём самом: сеть, набор скоупов, версия контракта, среда и бюджет запросов в минуту — берите лимит оттуда, а не из документации.
Клиент
client, err := cpa.New(os.Getenv("RECCA_CPA_KEY"), &cpa.ClientOptions{Environment: cpa.Sandbox})
if err != nil { log.Fatal(err) }
conv, _, err := client.Conversions.Create(context.Background(), cpa.CreateConversionParams{
ClickID: clickID, ExternalID: "order-0751", Status: "approved", SumRUB: cpa.RUBPtr(10000)})
switch {
case errors.Is(err, cpa.ErrWindowExpired): log.Print("окно атрибуции истекло — не повторять")
case err != nil: log.Printf("не принято: %v", err) // в тексте ошибки — код и request_id
default: log.Printf("принято: %s, выплата %s ₽", conv.Status, conv.PayoutRUB)
}
⚠ Нулевое Environment — это боевая сеть. Пока пробуете, пишите Environment: cpa.Sandbox явно.
Опция ClientOptions | Что задаёт |
|---|---|
Environment | бой (по умолчанию) или песочница |
BaseURL | свой адрес двери: прокси, локальный стенд |
HTTPClient | собственный *http.Client |
UserAgent | подпись клиента в заголовке |
MaxRetries | потолок повторов транспорта |
Logger | журнал запросов |
LogHeaders | печатать в журнал и заголовки |
Методы
Двадцать методов; у оффера две проекции, разведённые именами методов, а не параметром. Скоуп — право ключа; без него дверь отвечает 403 INSUFFICIENT_SCOPE. «Повтор» — повторяет ли клиент запрос сам: чтения всегда, записи — только с ключом идемпотентности.
| Метод | Дверь | Скоуп | Повтор |
|---|---|---|---|
Self.Get | GET /federation/v1/cpa/self | cpa:self:read | да |
Self.SetWebhook | PUT /federation/v1/cpa/self/webhook | cpa:self:write | нет |
Partners.Upsert | POST /federation/v1/cpa/partners | cpa:partners:write | да |
Partners.List | GET /federation/v1/cpa/partners | cpa:partners:read | да |
Partners.Get | GET /federation/v1/cpa/partners/{external_id} | cpa:partners:read | да |
Partners.Balance | GET /federation/v1/cpa/partners/{external_id}/balance | cpa:partners:read | да |
Offers.ListForPartner | GET /federation/v1/cpa/offers?view=partner | cpa:offers:read | да |
Offers.ListForAdvertiser | GET /federation/v1/cpa/offers?view=advertiser&advertiser_id=… | cpa:offers:read | да |
Offers.GetForPartner | GET /federation/v1/cpa/offers/{id}?view=partner | cpa:offers:read | да |
Offers.GetForAdvertiser | GET /federation/v1/cpa/offers/{id}?view=advertiser&advertiser_id=… | cpa:offers:read | да |
Offers.Creatives | GET /federation/v1/cpa/offers/{id}/creatives | cpa:offers:read | да |
Links.Create | POST /federation/v1/cpa/links | cpa:links:write | да |
Clicks.Create | POST /federation/v1/cpa/clicks | cpa:clicks:write | нет |
Conversions.Create | POST /federation/v1/cpa/conversions | cpa:conversions:write | да |
Conversions.List | GET /federation/v1/cpa/conversions | cpa:conversions:read | да |
Conversions.Get | GET /federation/v1/cpa/conversions/{external_id} | cpa:conversions:read | да |
Conversions.Cancel | POST /federation/v1/cpa/conversions/{external_id}/cancel | cpa:conversions:reverse | да |
Payouts.Create | POST /federation/v1/cpa/payouts | cpa:payouts:write | да |
Payouts.List | GET /federation/v1/cpa/payouts | cpa:payouts:read | да |
Statistics.Get | GET /federation/v1/cpa/statistics | cpa:stats:read | да |
Операторских методов нет и не будет: офферы, условия и отметку «выплачено» заводит оператор в кабинете. Для запроса, которого нет среди методов, есть client.Do — тот же конверт, разбор ошибок и политика повтора.
Проекции оффера: методы ForAdvertiser требуют идентификатор рекламодателя аргументом — ListForAdvertiser(ctx, advertiserID, params) и GetForAdvertiser(ctx, offerID, advertiserID). Без него дверь проекцию не отдаст, чужой идентификатор получит 404: ставки чужих карточек не открываются перебором.
Описание методов
Во всех примерах c — клиент из раздела «Клиент», ctx — context.Context, ключ берётся из os.Getenv("RECCA_CPA_KEY"). Каждый метод возвращает (результат, *cpa.Response, error); в примерах вторая часть пропущена (_). Подробности HTTP-двери — в разделе 9.6 CPA-API. Суммы в SDK — cpa.RUB (int64, целые рубли), даты — cpa.Date (cpa.NewDate(y, m, d), cpa.ParseDate(s), cpa.DateOf(t)), указатели собираются помощниками cpa.Ptr(v) и cpa.RUBPtr(v). Поля с пометкой «опц.» можно не заполнять.
Self.Get
Self.Get(ctx) (*SelfInfo, *Response, error)
Дверь GET /federation/v1/cpa/self, скоуп cpa:self:read. Самоописание ключа и проба живости; в бюджет запросов не входит. Параметров нет.
Поле SelfInfo | Что значит |
|---|---|
ContractVersion | версия контракта |
Environment | среда: production, staging или sandbox |
NetworkID | непрозрачный идентификатор вашей сети |
Scopes | права ключа |
AgentBase | от чего считается нога рекрутёра: cpa.AgentLegFromMargin (margin) или cpa.AgentLegFromPayout (payout) |
AgentHold | указатель: Mode (cpa.AgentHoldFollowConversion или cpa.AgentHoldOwnDays) и Days (указатель, число дней при own_days) |
MinPayoutRUB | порог выплаты сети (указатель) |
RateLimitPerMin | ваш бюджет запросов в минуту |
WebhookConfigured | настроен ли адрес событий (указатель) |
Ошибки: ErrMissingTenantScope, ErrInsufficientScope, ErrFeatureNotAvailable, ErrProductPaused. Повтор: чтение, клиент повторяет сам.
info, _, err := c.Self.Get(ctx)
if err != nil {
log.Fatal(err)
}
log.Printf("среда %s, бюджет %d запросов в минуту", info.Environment, info.RateLimitPerMin)
Self.SetWebhook
Self.SetWebhook(ctx, SetWebhookParams) (*WebhookConfig, *Response, error)
Дверь PUT /federation/v1/cpa/self/webhook, скоуп cpa:self:write. Задаёт адрес событий cpa.*.
Поле SetWebhookParams | Тип | Обязательно | Ограничения |
|---|---|---|---|
URL | string | да | только HTTPS, адреса внутренних сетей и localhost не принимаются |
RotateSecret | bool | нет | true — выпустить новый секрет |
Поле WebhookConfig | Что значит |
|---|---|
URL | сохранённый адрес |
Events | []WebhookEvent: cpa.conversion.approved, cpa.conversion.declined, cpa.conversion.reversed, cpa.payout.paid |
Secret | *string; приходит только при первой установке и ротации |
Ошибки: ErrInvalidInput. Повтор: клиент не повторяет — секрет показывается один раз. Не получили ответ — вызовите снова с RotateSecret: true.
wh, _, err := c.Self.SetWebhook(ctx, cpa.SetWebhookParams{URL: "https://example.com/recca/webhook"})
if err != nil {
log.Fatal(err)
}
if wh.Secret != nil {
saveSecret(*wh.Secret) // сохраните сразу: повторно секрет не выдаётся
}
Partners.Upsert
Partners.Upsert(ctx, UpsertPartnerParams) (*Partner, *Response, error)
Дверь POST /federation/v1/cpa/partners, скоуп cpa:partners:write. Заводит партнёра по вашему идентификатору или обновляет его; на уже заведённом меняются только ваши поля (состояние и рекрутёр).
Поле UpsertPartnerParams | Тип | Обязательно | Ограничения |
|---|---|---|---|
ExternalID | PartnerExternalID | да | алфавит A-Za-z0-9_.:-, до 64 символов (cpa.MaxPartnerExternalIDLen) |
Role | PartnerRole | да | cpa.PartnerWebmaster; cpa.PartnerAgent устарел; cpa.PartnerAdvertiser дверь не принимает |
PartnerState | PartnerState | опц. | cpa.PartnerStateActive или cpa.PartnerStateInactive |
RecruiterExternalID | PartnerExternalID | опц. | уже заведённый партнёр сети |
DetachRecruiter | bool | опц. | true — открепить рекрутёра |
AgentPercent | *json.Number | опц. | только с устаревшей ролью agent |
Поле Partner | Что значит |
|---|---|
ExternalID, TenantReccaID | ваш идентификатор и наш непрозрачный |
Role, PartnerState, Status | роль, ваш признак и участие на нашей стороне (cpa.PartnerStatusActive, cpa.PartnerStatusPending, cpa.PartnerStatusSuspended) |
RecruiterExternalID | *PartnerExternalID, рекрутёр |
CreatedAt | момент заведения |
Ошибки: ErrInvalidInput, ErrPartnerNotFound (рекрутёр не заведён), ErrPIINotAccepted. Повтор: идемпотентен по ExternalID, клиент повторяет.
p, _, err := c.Partners.Upsert(ctx, cpa.UpsertPartnerParams{
ExternalID: "blg_8f3a",
Role: cpa.PartnerWebmaster,
PartnerState: cpa.PartnerStateActive,
})
if err != nil {
log.Fatal(err)
}
log.Printf("партнёр %s, участие: %s", p.ExternalID, p.Status)
Partners.List
Partners.List(ctx, ListPartnersParams) ([]Partner, *Response, error)
Дверь GET /federation/v1/cpa/partners, скоуп cpa:partners:read. Список партнёров, заведённых по API; кормит экран рекрутёра «мои блогеры».
Поле ListPartnersParams | Тип | Ограничения |
|---|---|---|
Role | PartnerRole | дверь принимает webmaster и agent; другое значение — ErrInvalidInput |
Status | PartnerStatus | участие на нашей стороне |
RecruiterExternalID | PartnerExternalID | фильтр «мои блогеры» |
PageParams | Limit, Offset | размер страницы и сдвиг |
Результат — []Partner (поля как у Partners.Upsert). Ошибки: ErrInvalidInput. Повтор: чтение, клиент повторяет.
list, _, err := c.Partners.List(ctx, cpa.ListPartnersParams{
RecruiterExternalID: "blg_8f3a",
PageParams: cpa.PageParams{Limit: 50},
})
if err != nil {
log.Fatal(err)
}
for _, p := range list {
log.Print(p.ExternalID)
}
Partners.Get
Partners.Get(ctx, externalID PartnerExternalID) (*Partner, *Response, error)
Дверь GET /federation/v1/cpa/partners/{external_id}, скоуп cpa:partners:read. Карточка партнёра: по ней видны оба поля права работать — PartnerState и Status. Результат — *Partner. Ошибки: ErrPartnerNotFound. Повтор: чтение.
p, _, err := c.Partners.Get(ctx, "blg_8f3a")
if errors.Is(err, cpa.ErrPartnerNotFound) {
log.Print("партнёра нет в сети")
return
}
_ = p
Partners.Balance
Partners.Balance(ctx, externalID PartnerExternalID) (*PartnerBalance, *Response, error)
Дверь GET /federation/v1/cpa/partners/{external_id}/balance, скоуп cpa:partners:read.
Поле PartnerBalance | Что значит |
|---|---|
AvailableRUB | то, что можно запросить к выплате сейчас |
OnHoldRUB | станет доступным по истечении холда |
PaidTotalRUB | выплачено за всё время |
MinPayoutRUB | порог сети |
CanRequest | можно ли подать заявку |
Ошибки: ErrPartnerNotFound. Повтор: чтение.
b, _, err := c.Partners.Balance(ctx, "blg_8f3a")
if err != nil {
log.Fatal(err)
}
log.Printf("доступно %d, в холде %d", b.AvailableRUB, b.OnHoldRUB)
Offers.ListForPartner
Offers.ListForPartner(ctx, ListOffersParams) ([]OfferPartnerView, *Response, error)
Дверь GET /federation/v1/cpa/offers?view=partner, скоуп cpa:offers:read. Каталог в проекции партнёра: ставки рекламодателя, маржи и капов в ней нет.
Поле ListOffersParams | Тип | Что значит |
|---|---|---|
AdvertiserID | string | опц.; наш идентификатор рекламодателя, сужает каталог |
PageParams | Limit, Offset | размер страницы и сдвиг |
Поле OfferPartnerView | Что значит |
|---|---|
ID, Name, AdvertiserID | оффер и его рекламодатель |
PayoutModel | cpa.RateCPA, cpa.RateCPL или cpa.RateRevShare |
PayoutRate | Rate: Kind (cpa.RateFixed или cpa.RatePercent), ValueRUB, ValuePercent |
Goals | []OfferGoalPartner: Code, Name, IsMilestone, PayoutRate, HoldDays, MultiplePerClick |
Geo | GeoRules: Mode (cpa.GeoAny, cpa.GeoAllow, cpa.GeoDeny) и Countries |
AllowedTraffic, DisallowedTraffic | виды трафика |
HoldDays, AttributionWindowDays | холд и окно атрибуции (указатели) |
Ошибки: ErrInvalidInput, ErrAdvertiserNotFound. Повтор: чтение.
offers, _, err := c.Offers.ListForPartner(ctx, cpa.ListOffersParams{PageParams: cpa.PageParams{Limit: 50}})
if err != nil {
log.Fatal(err)
}
for _, o := range offers {
log.Printf("%s: %s", o.ID, o.Name)
}
Offers.ListForAdvertiser
Offers.ListForAdvertiser(ctx, advertiserID string, ListOffersParams) ([]OfferAdvertiserView, *Response, error)
Дверь GET /federation/v1/cpa/offers?view=advertiser&advertiser_id=…, скоуп cpa:offers:read. Офферы витрин рекламодателя и его собственная ставка; payout_rate и маржа оператора не приходят никогда. Идентификатор рекламодателя — наш: берите его из поля AdvertiserID любого оффера. Идёт отдельным аргументом, поле AdvertiserID в ListOffersParams здесь заполнять не нужно.
Поле OfferAdvertiserView | Что значит |
|---|---|
ID, Name, AdvertiserID | как у партнёрской проекции |
PayoutModel | модель выплаты |
RevenueRate | Rate рекламодателя |
Goals | []OfferGoalAdvertiser: Code, Name, IsMilestone, RevenueRate, HoldDays, MultiplePerClick, Disabled (цель выключена оператором — новые конверсии получают ErrGoalDisabled) |
Geo | *GeoRules |
HoldDays, AttributionWindowDays | указатели |
Ошибки: ErrInvalidInput, ErrAdvertiserNotFound. Повтор: чтение.
offers, _, err := c.Offers.ListForAdvertiser(ctx, "shop_demo01", cpa.ListOffersParams{})
if errors.Is(err, cpa.ErrAdvertiserNotFound) {
log.Print("неизвестный рекламодатель")
return
}
_ = offers
Offers.GetForPartner
Offers.GetForPartner(ctx, offerID string) (*OfferPartnerView, *Response, error)
Дверь GET /federation/v1/cpa/offers/{id}?view=partner, скоуп cpa:offers:read. Условия одного оффера в проекции партнёра (поля как у Offers.ListForPartner). Ошибки: ErrOfferNotFound (оффера нет). Повтор: чтение.
o, _, err := c.Offers.GetForPartner(ctx, "off_demo01")
if err != nil {
log.Fatal(err)
}
log.Printf("модель выплаты: %s", o.PayoutModel)
Offers.GetForAdvertiser
Offers.GetForAdvertiser(ctx, offerID, advertiserID string) (*OfferAdvertiserView, *Response, error)
Дверь GET /federation/v1/cpa/offers/{id}?view=advertiser&advertiser_id=…, скоуп cpa:offers:read. Оффер в проекции рекламодателя; оба аргумента обязательны, advertiserID должен быть владельцем оффера, иначе ErrAdvertiserNotFound: ставки чужих карточек перебором не открываются. Поля результата — как у Offers.ListForAdvertiser. Ошибки: ErrInvalidInput, ErrAdvertiserNotFound. Повтор: чтение.
o, _, err := c.Offers.GetForAdvertiser(ctx, "off_demo01", "shop_demo01")
if err != nil {
log.Fatal(err)
}
log.Printf("ставка рекламодателя: %s", o.RevenueRate.Kind)
Offers.Creatives
Offers.Creatives(ctx, offerID string) ([]Creative, *Response, error)
Дверь GET /federation/v1/cpa/offers/{id}/creatives, скоуп cpa:offers:read. Посадочные и креативы оффера одним списком; посадочные идут первыми.
Поле Creative | Что значит |
|---|---|
ID, Title | идентификатор и название |
Kind | cpa.CreativeBanner, cpa.CreativeLanding, cpa.CreativeText, cpa.CreativeVideo или cpa.CreativeOther; ветвитесь по нему |
Description, URL, Text, MimeType | указатели на строки; URL пуст у текстового креатива, Text заполнен у cpa.CreativeText |
Width, Height | размеры (указатели) |
IsDefault | основная посадочная (указатель) |
CreatedAt | *time.Time |
Ошибки: ErrOfferNotFound (оффера нет). Повтор: чтение.
items, _, err := c.Offers.Creatives(ctx, "off_demo01")
if err != nil {
log.Fatal(err)
}
for _, it := range items {
log.Printf("%s: %s", it.Kind, it.Title)
}
Links.Create
Links.Create(ctx, CreateLinkParams) (*Link, *Response, error)
Дверь POST /federation/v1/cpa/links, скоуп cpa:links:write. Стабильная ссылка партнёра на оффер; идемпотентна по паре «партнёр + оффер».
Поле CreateLinkParams | Тип | Обязательно |
|---|---|---|
PartnerExternalID | PartnerExternalID | да |
OfferID | string | да |
Поле Link | Что значит |
|---|---|
Code | код ссылки |
TargetURL | адрес перехода на нашей стороне; берите из ответа как есть и не подменяйте посадочной оффера |
PartnerExternalID, OfferID, CreatedAt | пара и момент выпуска |
Ошибки: ErrPartnerNotFound, ErrPartnerNotActive, ErrInvalidInput. Повтор: идемпотентен, клиент повторяет.
link, _, err := c.Links.Create(ctx, cpa.CreateLinkParams{PartnerExternalID: "blg_8f3a", OfferID: "off_demo01"})
if err != nil {
log.Fatal(err)
}
log.Print(link.TargetURL)
Clicks.Create
Clicks.Create(ctx, CreateClickParams) (*Click, *Response, error)
Дверь POST /federation/v1/cpa/clicks, скоуп cpa:clicks:write. Регистрирует переход по вашей брендированной ссылке.
Поле CreateClickParams | Тип | Обязательно | Ограничения |
|---|---|---|---|
PartnerExternalID | PartnerExternalID | да | |
OfferID | string | да | |
ClientClickID | string | опц. | ваш ключ идемпотентности |
SubID, SubID2 … SubID5 | string | опц. | метки партнёра, до 200 символов (cpa.MaxSubIDLen); метки sub_id_6 … sub_id_10 через SDK не передаются — только прямым запросом к двери |
Country | string | опц. | ISO 3166-1 alpha-2 |
Поле Click | Что значит |
|---|---|
ClickID | *ClickID; nil при cpa.ClickTrafficback |
Status | cpa.ClickOpen или cpa.ClickTrafficback (переход принят, но к рекламодателю не отправлен — не ошибка запроса) |
Reason | *string, причина отбоя |
RedirectURL | *string; nil — вести некуда, покажите свою страницу |
ExpiresAt | конец окна атрибуции |
CreatedAt, OfferID, PartnerExternalID |
Ошибки: ErrPartnerNotFound, ErrPartnerNotActive, ErrIdempotentMismatch, ErrInvalidInput, ErrRateLimited. Повтор: клиент не повторяет — повтор это второй переход и двойной расход капа; защитите вызов своим ClientClickID.
click, _, err := c.Clicks.Create(ctx, cpa.CreateClickParams{
PartnerExternalID: "blg_8f3a",
OfferID: "off_demo01",
ClientClickID: "ck-0001",
SubID: "campaign-1",
Country: "RU",
})
if err != nil {
log.Fatal(err)
}
if click.Status == cpa.ClickTrafficback || click.RedirectURL == nil {
showOwnPage()
return
}
http.Redirect(w, r, *click.RedirectURL, http.StatusFound)
Conversions.Create
Conversions.Create(ctx, CreateConversionParams) (*ConversionDetail, *Response, error)
Дверь POST /federation/v1/cpa/conversions, скоуп cpa:conversions:write. Принимает результат; идемпотентна по тройке «сеть + номер заказа + цель».
Поле CreateConversionParams | Тип | Обязательно | Ограничения |
|---|---|---|---|
ClickID | ClickID | да | идентификатор перехода |
ExternalID | string | да | ваш номер заказа; префикс recca: зарезервирован (cpa.IsReservedExternalID) |
Status | string | да | подтверждение, ожидание или отмена; значения — как у постбэка |
Goal | *string | опц. | nil — цель по умолчанию |
SumRUB | *cpa.RUB | опц. | целые рубли; обязательна для процентных моделей |
SumRUBExact | *json.Number | опц. | сумма с копейками |
SubID | string | опц. | |
OccurredAt | *time.Time | опц. | не из будущего, не старше 90 дней |
Верхние границы заданы константами cpa.MaxExternalIDLen, cpa.MaxGoalLen, cpa.MaxSubIDLen и cpa.MaxSumRUB.
Поле ConversionDetail | Что значит |
|---|---|
встроенная Conversion | ExternalID, Goal, Status, PartnerExternalID, OfferID, AdvertiserID, PayoutRUB, SumRUB (*json.Number), SubID, CreatedAt, OccurredAt, HoldUntil |
RevenueRUB, MarginRUB | PayoutRUB + MarginRUB == RevenueRUB |
AgentLeg | нога рекрутёра: ExternalID, AmountRUB, Base, Percent, HoldUntil; nil, если её нет |
FraudFlags | пометки качества трафика |
Status — cpa.ConversionPending, cpa.ConversionHold, cpa.ConversionApproved, cpa.ConversionDeclined или cpa.ConversionNotFound.
Ошибки: ErrInvalidInput, ErrReservedExternalID, ErrOccurredAtOutOfWindow, ErrUnknownGoal, ErrGoalDisabled, ErrWindowExpired (повторять бессмысленно), ErrAlreadyConverted, ErrExternalIDConflict, ErrIllegalTransition, ErrIdempotentMismatch, ErrPIINotAccepted, ErrRateLimited. Повтор: идемпотентна, клиент повторяет.
conv, _, err := c.Conversions.Create(ctx, cpa.CreateConversionParams{
ClickID: "clk_a1b2c3",
ExternalID: "order-10421",
Status: "approved",
Goal: cpa.Ptr("sale"),
SumRUB: cpa.RUBPtr(5000),
})
switch {
case errors.Is(err, cpa.ErrWindowExpired):
log.Print("окно атрибуции истекло — не повторять")
case err != nil:
log.Printf("не принято: %v", err)
default:
log.Printf("принято: %s, выплата %d", conv.Status, conv.PayoutRUB)
}
Conversions.List
Conversions.List(ctx, ListConversionsParams) ([]Conversion, *Response, error)
Дверь GET /federation/v1/cpa/conversions, скоуп cpa:conversions:read.
Поле ListConversionsParams | Тип | Что значит |
|---|---|---|
PartnerExternalID | PartnerExternalID | неизвестный партнёр — ErrPartnerNotFound, а не пустой список |
AdvertiserID, OfferID | string | наши идентификаторы |
Status | ConversionStatus | фильтр по состоянию |
From, To | *time.Time | границы по времени события |
PageParams | Limit, Offset | размер страницы и сдвиг |
Результат — []Conversion (без тройки ставок и ноги рекрутёра: они в Conversions.Get). Ошибки: ErrInvalidInput, ErrPartnerNotFound, ErrAdvertiserNotFound. Повтор: чтение.
from := time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC)
list, _, err := c.Conversions.List(ctx, cpa.ListConversionsParams{
PartnerExternalID: "blg_8f3a",
Status: cpa.ConversionHold,
From: &from,
PageParams: cpa.PageParams{Limit: 50},
})
if err != nil {
log.Fatal(err)
}
log.Printf("конверсий в холде: %d", len(list))
Conversions.Get
Conversions.Get(ctx, GetConversionParams) (*ConversionDetail, *Response, error)
Дверь GET /federation/v1/cpa/conversions/{external_id}, скоуп cpa:conversions:read. Конверсия с тройкой ставок и ногой рекрутёра.
Поле GetConversionParams | Тип | Обязательно |
|---|---|---|
ExternalID | string | да |
Goal | *string | опц.; nil — цель по умолчанию |
Результат — *ConversionDetail (поля как у Conversions.Create). Ошибки: ErrInvalidInput, ErrConversionNotFound. Повтор: чтение.
conv, _, err := c.Conversions.Get(ctx, cpa.GetConversionParams{ExternalID: "order-10421", Goal: cpa.Ptr("sale")})
if err != nil {
log.Fatal(err)
}
log.Printf("статус %s, маржа %d", conv.Status, conv.MarginRUB)
Conversions.Cancel
Conversions.Cancel(ctx, CancelConversionParams) (*ConversionDetail, *Response, error)
Дверь POST /federation/v1/cpa/conversions/{external_id}/cancel, скоуп cpa:conversions:reverse. Отклоняет конверсию или оформляет возврат; отменённая конверсия терминальна.
Поле CancelConversionParams | Тип | Обязательно |
|---|---|---|
ExternalID | string | да |
Goal | *string | опц. |
Reason | string | опц.; без него записывается стандартная причина |
Результат — *ConversionDetail в состоянии cpa.ConversionDeclined. Ошибки: ErrConversionNotFound, ErrIllegalTransition, ErrReversalFailed (денежная операция не совершена, повторите), ErrInvalidInput. Повтор: идемпотентна, клиент повторяет.
conv, _, err := c.Conversions.Cancel(ctx, cpa.CancelConversionParams{
ExternalID: "order-10421",
Goal: cpa.Ptr("sale"),
Reason: "order returned",
})
if err != nil {
log.Fatal(err)
}
log.Print(conv.Status)
Payouts.Create
cpa.NewPayoutParams(partner PartnerExternalID, amount RUB, from, to Date) (PayoutParams, error)
Payouts.Create(ctx, PayoutParams) (*Payout, *Response, error)
Дверь POST /federation/v1/cpa/payouts, скоуп cpa:payouts:write. Заявка на выплату. Поля PayoutParams закрыты: параметры собираются только конструктором cpa.NewPayoutParams.
| Аргумент конструктора | Тип | Что значит |
|---|---|---|
partner | PartnerExternalID | партнёр, заведённый в сети |
amount | RUB | сумма в целых рублях, от 1; не меньше порога сети и не больше доступного |
from, to | Date | период; from не позже to |
Поле Payout | Что значит |
|---|---|
ID | идентификатор заявки |
PartnerExternalID, AmountRUB | партнёр и сумма |
Status | cpa.PayoutRequested, cpa.PayoutApproved, cpa.PayoutPaid или cpa.PayoutRejected |
PeriodFrom, PeriodTo | период |
CreatedAt, PaidAt | PaidAt — указатель |
Отметку «выплачено» ставит оператор в кабинете. Ошибки: ErrPartnerNotFound, ErrBelowMinPayout, ErrInsufficientBalance, ErrIdempotentMismatch, ErrInvalidInput. Повтор: личность заявки — сеть, партнёр и период; повтор с той же суммой возвращает ту же заявку, с другой суммой за тот же период — ErrIdempotentMismatch.
params, err := cpa.NewPayoutParams("blg_8f3a", 5000, cpa.NewDate(2026, 9, 1), cpa.NewDate(2026, 9, 30))
if err != nil {
log.Fatal(err)
}
payout, _, err := c.Payouts.Create(ctx, params)
if err != nil {
log.Fatal(err)
}
log.Printf("заявка %s: %s", payout.ID, payout.Status)
Payouts.List
Payouts.List(ctx, ListPayoutsParams) ([]Payout, *Response, error)
Дверь GET /federation/v1/cpa/payouts, скоуп cpa:payouts:read. История заявок.
Поле ListPayoutsParams | Тип | Что значит |
|---|---|---|
PartnerExternalID | PartnerExternalID | неизвестный партнёр — ErrPartnerNotFound |
Status | PayoutStatus | фильтр по состоянию |
PageParams | Limit, Offset | у этой двери страница меньше остальных: потолок 100, по умолчанию 20 |
Результат — []Payout. Ошибки: ErrInvalidInput, ErrPartnerNotFound. Повтор: чтение.
list, _, err := c.Payouts.List(ctx, cpa.ListPayoutsParams{PartnerExternalID: "blg_8f3a", Status: cpa.PayoutPaid})
if err != nil {
log.Fatal(err)
}
log.Printf("выплаченных заявок: %d", len(list))
Statistics.Get
Statistics.Get(ctx, StatisticsParams) ([]StatisticsRow, *Response, error)
Дверь GET /federation/v1/cpa/statistics, скоуп cpa:stats:read. Отчёт по времени события: досланная вчерашняя конверсия попадает во вчерашний день.
Поле StatisticsParams | Тип | Обязательно | Что значит |
|---|---|---|---|
GroupBy | StatisticsGroupBy | да | cpa.StatisticsByOffer, cpa.StatisticsByPartner или cpa.StatisticsByDay |
PartnerExternalID | PartnerExternalID | опц. | неизвестный партнёр — ErrPartnerNotFound |
AdvertiserID, OfferID | string | опц. | наши идентификаторы |
From, To | *Date | опц. | даты, To включительно; без From дверь берёт последние 30 дней |
Поле StatisticsRow | Что значит |
|---|---|
Key | оффер, партнёр или дата — по GroupBy |
Clicks, Conversions, Approved | переходы, конверсии, подтверждённые |
PayoutRUB, RevenueRUB | выплаты партнёрам и выручка группы |
Ошибки: ErrInvalidInput, ErrPartnerNotFound. Повтор: чтение.
from, to := cpa.NewDate(2026, 9, 1), cpa.NewDate(2026, 9, 30)
rows, _, err := c.Statistics.Get(ctx, cpa.StatisticsParams{GroupBy: cpa.StatisticsByDay, From: &from, To: &to})
if err != nil {
log.Fatal(err)
}
for _, r := range rows {
log.Printf("%s: %d переходов, %d конверсий", r.Key, r.Clicks, r.Conversions)
}
Ошибки
Ветвитесь по коду: errors.Is(err, cpa.ErrXxx), а не по тексту — текст меняется без предупреждения. В отказе всегда есть идентификатор запроса (request_id): называйте его в поддержке.
| Сентинел | Когда возникает |
|---|---|
cpa.ErrValidation | общий признак отказа, который клиент дал сам, до сети: request_id у такой ошибки в журналах Recca искать бесполезно |
cpa.ErrMissingTenantScope | ключа нет, он пуст или отозван |
cpa.ErrInsufficientScope | у ключа нет права на дверь |
cpa.ErrFeatureNotAvailable | продукт «CPA-сеть» не подключён |
cpa.ErrProductPaused | продукт сети на паузе |
cpa.ErrRateLimited | исчерпан бюджет запросов ключа |
cpa.ErrInternal | сбой на нашей стороне |
cpa.ErrInvalidInput | вход не прошёл проверку на стороне двери |
cpa.ErrPIINotAccepted | в свободном поле распознано персональное данное |
cpa.ErrReservedExternalID | номер заказа начинается с recca: |
cpa.ErrPartnerNotFound | партнёра с таким идентификатором нет в сети |
cpa.ErrPartnerNotActive | у партнёра снято право работать |
cpa.ErrAdvertiserNotFound | рекламодателя с таким идентификатором нет в сети |
cpa.ErrOfferNotFound | оффера нет в сети |
cpa.ErrConversionNotFound | конверсии с таким номером заказа и целью нет |
cpa.ErrPayoutNotFound | заявки на выплату нет |
cpa.ErrUnknownGoal | цель не объявлена у оффера |
cpa.ErrGoalDisabled | цель выключена оператором |
cpa.ErrWindowExpired | окно атрибуции клика истекло — повторять бессмысленно |
cpa.ErrOccurredAtOutOfWindow | время события вне допустимого окна |
cpa.ErrAlreadyConverted | клик уже платил на эту цель |
cpa.ErrExternalIDConflict | номер заказа занят чужим оффером сети |
cpa.ErrIllegalTransition | недопустимый переход состояния конверсии |
cpa.ErrIdempotentMismatch | повтор операции с другими параметрами |
cpa.ErrReversalFailed | отмена конверсии не завершилась на нашей стороне, денежная операция не совершена |
cpa.ErrBelowMinPayout | сумма заявки ниже порога выплаты сети |
cpa.ErrInsufficientBalance | на балансе партнёра недостаточно средств |
cpa.ErrMalformedResponse | ответ двери не удалось разобрать |
cpa.ErrIncompleteData | успешный ответ пришёл без полного набора полей |
Сам отказ — значение cpa.APIError: код, сообщение, HTTP-статус и request_id. Помощники: cpa.Retryable(code, status) и cpa.HTTPStatusFor(code).
Отказы несут error.details с именем поля — разбирайте его, а не текст сообщения.
Идемпотентность и повторы
| Правило | Поведение |
|---|---|
201 и 200 — оба успех | повтор исполнения возвращает 200 с тем же объектом |
| чтения | клиент повторяет сам |
| записи | повторяются только с ключом идемпотентности |
Clicks.Create | не повторяется: повтор — второй переход и расход капа; защититесь своим ClientClickID |
Self.SetWebhook | не повторяется: секрет показывается один раз |
Конверсии
Конверсия адресуется тройкой «сеть + номер заказа + цель»; номер заказа общий для всей сети. Без цели действует цель по умолчанию 1.
| Ситуация | Поведение |
|---|---|
прислали approved | заводится в холд; по истечении холда доступна к выплате |
| повтор: тот же заказ, уже исполненный статус | 200, та же конверсия, деньги не двигаются |
| переход: статус, которого ещё не было | сумму передавать можно: pending без суммы → approved с итоговой |
| отмена | терминальна; повтор отмены безопасен |
номер заказа начинается с recca: | отказ до сети — префикс занят платформой |
occurred_at старше 90 дней | отказ: событие вне окна |
Статистика считается по времени события (occurred_at), а не приёма: досланная пачкой вчерашняя конверсия попадает во вчерашний день.
Выплаты
Параметры заявки собираются только конструктором cpa.NewPayoutParams(partner, amount, from, to). Ключ идемпотентности — партнёр и период: повтор за тот же период с той же суммой вернёт ту же заявку, с другой суммой — отказ IDEMPOTENT_MISMATCH. Отметку «выплачено» ставит оператор.
Вебхуки
Адрес приёмника устанавливается методом Self.SetWebhook; секрет подписи приходит в ответе при первой установке и при ротации, и больше никогда. Не получили ответ — вызовите снова с ротацией.
| Событие | Когда приходит |
|---|---|
cpa.conversion.approved | конверсия подтверждена, в том числе по истечении холда |
cpa.conversion.declined | конверсия отменена |
cpa.conversion.reversed | по конверсии прошёл возврат |
cpa.payout.paid | выплата отмечена оплаченной |
Подпись — HMAC-SHA256 в заголовке, формат t=<метка>,v1=<подпись>. Приём:
r := webhook.Receiver{Secret: os.Getenv("RECCA_WEBHOOK_SECRET"), Seen: store}
env, err := r.Accept(ctx, req.Header.Get(webhook.HeaderName), rawBody)
switch {
case errors.Is(err, webhook.ErrDuplicate):
w.WriteHeader(200) // уже обработано — ответить 200 и НЕ делать работу снова
return
case err != nil:
w.WriteHeader(400)
return
}
⚠⚠ Повтор доставки несёт законную свежую подпись — проверка подписи его пропускает и обязана пропускать. Защищает только дедупликация по event_id: храните виденные идентификаторы 30 дней; для боя — уникальный индекс в вашей базе, а не память процесса.
Стенд и приёмка
cpatest.NewServer(t) — стенд на httptest, отвечающий на все двери контракта конвертом контракта; вне тестов — cpatest.Start().
| Инструмент | Что доказывает |
|---|---|
Requests() | ваш код собирает верные запросы: метод, путь, строку запроса, тело |
PrepareError(code) | отказ ровно на один следующий запрос |
HoldError(code) + ClearError() | отказ на каждом запросе до снятия — для клиента с повторами |
Conformance(t, client, opts) | приёмочный набор: самопроверка, каталог, «партнёр → ссылка → клик → конверсия → повтор», выплата |
Conformance работает только против песочницы и стенда: на боевом адресе — отказ до первого запроса, флага «разрешить прод» нет и не будет. Сценарии приёмки из контракта включаются опцией Scenarios — каждой цепочке выделяется свой оффер.
Ограничения двери
| Ограничение | Значение |
|---|---|
| бюджет запросов | у ключа, в минуту; точное значение — Self.Get |
| окно события | occurred_at не старше 90 дней |
| личные данные | свободные поля их не принимают: 400 PII_NOT_ACCEPTED |
префикс recca: | зарезервирован в номерах заказов |
Машина — обычный JSON API: если Go у вас нет, тот же контракт доступен прямым HTTP с тем же заголовком ключа; SDK снимает с вас повторы, подписи и разбор конверта. Машинная спецификация методов — в разделе OpenAPI.