Recca Разработчикам
Меню

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.GetGET /federation/v1/cpa/selfcpa:self:readда
Self.SetWebhookPUT /federation/v1/cpa/self/webhookcpa:self:writeнет
Partners.UpsertPOST /federation/v1/cpa/partnerscpa:partners:writeда
Partners.ListGET /federation/v1/cpa/partnerscpa:partners:readда
Partners.GetGET /federation/v1/cpa/partners/{external_id}cpa:partners:readда
Partners.BalanceGET /federation/v1/cpa/partners/{external_id}/balancecpa:partners:readда
Offers.ListForPartnerGET /federation/v1/cpa/offers?view=partnercpa:offers:readда
Offers.ListForAdvertiserGET /federation/v1/cpa/offers?view=advertiser&advertiser_id=…cpa:offers:readда
Offers.GetForPartnerGET /federation/v1/cpa/offers/{id}?view=partnercpa:offers:readда
Offers.GetForAdvertiserGET /federation/v1/cpa/offers/{id}?view=advertiser&advertiser_id=…cpa:offers:readда
Offers.CreativesGET /federation/v1/cpa/offers/{id}/creativescpa:offers:readда
Links.CreatePOST /federation/v1/cpa/linkscpa:links:writeда
Clicks.CreatePOST /federation/v1/cpa/clickscpa:clicks:writeнет
Conversions.CreatePOST /federation/v1/cpa/conversionscpa:conversions:writeда
Conversions.ListGET /federation/v1/cpa/conversionscpa:conversions:readда
Conversions.GetGET /federation/v1/cpa/conversions/{external_id}cpa:conversions:readда
Conversions.CancelPOST /federation/v1/cpa/conversions/{external_id}/cancelcpa:conversions:reverseда
Payouts.CreatePOST /federation/v1/cpa/payoutscpa:payouts:writeда
Payouts.ListGET /federation/v1/cpa/payoutscpa:payouts:readда
Statistics.GetGET /federation/v1/cpa/statisticscpa: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ТипОбязательноОграничения
URLstringдатолько HTTPS, адреса внутренних сетей и localhost не принимаются
RotateSecretboolнет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ТипОбязательноОграничения
ExternalIDPartnerExternalIDдаалфавит A-Za-z0-9_.:-, до 64 символов (cpa.MaxPartnerExternalIDLen)
RolePartnerRoleдаcpa.PartnerWebmaster; cpa.PartnerAgent устарел; cpa.PartnerAdvertiser дверь не принимает
PartnerStatePartnerStateопц.cpa.PartnerStateActive или cpa.PartnerStateInactive
RecruiterExternalIDPartnerExternalIDопц.уже заведённый партнёр сети
DetachRecruiterboolопц.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ТипОграничения
RolePartnerRoleдверь принимает webmaster и agent; другое значение — ErrInvalidInput
StatusPartnerStatusучастие на нашей стороне
RecruiterExternalIDPartnerExternalIDфильтр «мои блогеры»
PageParamsLimit, 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ТипЧто значит
AdvertiserIDstringопц.; наш идентификатор рекламодателя, сужает каталог
PageParamsLimit, Offsetразмер страницы и сдвиг
Поле OfferPartnerViewЧто значит
ID, Name, AdvertiserIDоффер и его рекламодатель
PayoutModelcpa.RateCPA, cpa.RateCPL или cpa.RateRevShare
PayoutRateRate: Kind (cpa.RateFixed или cpa.RatePercent), ValueRUB, ValuePercent
Goals[]OfferGoalPartner: Code, Name, IsMilestone, PayoutRate, HoldDays, MultiplePerClick
GeoGeoRules: 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модель выплаты
RevenueRateRate рекламодателя
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идентификатор и название
Kindcpa.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ТипОбязательно
PartnerExternalIDPartnerExternalIDда
OfferIDstringда
Поле 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ТипОбязательноОграничения
PartnerExternalIDPartnerExternalIDда
OfferIDstringда
ClientClickIDstringопц.ваш ключ идемпотентности
SubID, SubID2 … SubID5stringопц.метки партнёра, до 200 символов (cpa.MaxSubIDLen); метки sub_id_6 … sub_id_10 через SDK не передаются — только прямым запросом к двери
Countrystringопц.ISO 3166-1 alpha-2
Поле ClickЧто значит
ClickID*ClickID; nil при cpa.ClickTrafficback
Statuscpa.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ТипОбязательноОграничения
ClickIDClickIDдаидентификатор перехода
ExternalIDstringдаваш номер заказа; префикс recca: зарезервирован (cpa.IsReservedExternalID)
Statusstringдаподтверждение, ожидание или отмена; значения — как у постбэка
Goal*stringопц.nil — цель по умолчанию
SumRUB*cpa.RUBопц.целые рубли; обязательна для процентных моделей
SumRUBExact*json.Numberопц.сумма с копейками
SubIDstringопц.
OccurredAt*time.Timeопц.не из будущего, не старше 90 дней

Верхние границы заданы константами cpa.MaxExternalIDLen, cpa.MaxGoalLen, cpa.MaxSubIDLen и cpa.MaxSumRUB.

Поле ConversionDetailЧто значит
встроенная ConversionExternalID, Goal, Status, PartnerExternalID, OfferID, AdvertiserID, PayoutRUB, SumRUB (*json.Number), SubID, CreatedAt, OccurredAt, HoldUntil
RevenueRUB, MarginRUBPayoutRUB + 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ТипЧто значит
PartnerExternalIDPartnerExternalIDнеизвестный партнёр — ErrPartnerNotFound, а не пустой список
AdvertiserID, OfferIDstringнаши идентификаторы
StatusConversionStatusфильтр по состоянию
From, To*time.Timeграницы по времени события
PageParamsLimit, 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ТипОбязательно
ExternalIDstringда
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ТипОбязательно
ExternalIDstringда
Goal*stringопц.
Reasonstringопц.; без него записывается стандартная причина

Результат — *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.

Аргумент конструктораТипЧто значит
partnerPartnerExternalIDпартнёр, заведённый в сети
amountRUBсумма в целых рублях, от 1; не меньше порога сети и не больше доступного
from, toDateпериод; from не позже to
Поле PayoutЧто значит
IDидентификатор заявки
PartnerExternalID, AmountRUBпартнёр и сумма
Statuscpa.PayoutRequested, cpa.PayoutApproved, cpa.PayoutPaid или cpa.PayoutRejected
PeriodFrom, PeriodToпериод
CreatedAt, PaidAtPaidAt — указатель

Отметку «выплачено» ставит оператор в кабинете. Ошибки: 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ТипЧто значит
PartnerExternalIDPartnerExternalIDнеизвестный партнёр — ErrPartnerNotFound
StatusPayoutStatusфильтр по состоянию
PageParamsLimit, 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ТипОбязательноЧто значит
GroupByStatisticsGroupByдаcpa.StatisticsByOffer, cpa.StatisticsByPartner или cpa.StatisticsByDay
PartnerExternalIDPartnerExternalIDопц.неизвестный партнёр — ErrPartnerNotFound
AdvertiserID, OfferIDstringопц.наши идентификаторы
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.