Go SDK

Кому нужен

SDK — для оператора сети, который управляет ею машиной: заводит партнёров, получает каталог и ссылки, передаёт клики и конверсии, запрашивает выплаты. Рекламодателю, который только сообщает о заказах, SDK не нужен — ему хватает постбэка.

Установка

Go 1.24 или новее:

go get go.recca.ru/sdk

Ключ сети

Один ключ адресует всю сеть: значение вида rtk_live_… передаётся заголовком X-Recca-Tenant-Key и живёт только на вашем сервере — в браузер он не попадает. Ключ выдаёт оператор платформы при подключении; там же настраивается список разрешённых адресов.

Первый вызов

client, err := cpa.New(os.Getenv("RECCA_CPA_KEY"), &cpa.ClientOptions{Environment: cpa.Sandbox})
if err != nil { log.Fatal(err) }

self, _, err := client.Self.Get(context.Background())
if err != nil { log.Fatal(err) }
log.Printf("сеть подключена, версия контракта %s", self.ContractVersion)

Нулевое значение Environment — это боевая сеть. Пока пробуете, указывайте cpa.Sandbox явно. Бюджет запросов ключа берите из ответа Self.Get, а не из документации.

Что покрывает

Права ключа выдаются по областям (cpa:partners:read, cpa:conversions:write и так далее); дверь без нужного права отвечает 403 INSUFFICIENT_SCOPE. Ошибки разбираются по коду — errors.Is(err, cpa.ErrWindowExpired) — а не по тексту; в каждом отказе есть request_id, назовите его в поддержке. Чтения повторяются клиентом сами, записи — только с ключом идемпотентности.

Вебхуки и приёмка

События cpa.* приходят на адрес, который вы задаёте методом Self.SetWebhook; пакет webhook проверяет подпись и отсекает повторы по event_id. Формат события и подписи — на странице вебхуков.

Пакет cpatest даёт стенд на httptest, отвечающий как настоящая дверь, и набор Conformance для приёмки: самопроверка, каталог, цепочка «партнёр, ссылка, клик, конверсия, повтор» и выплата. Приёмка работает только против песочницы и стенда — на боевом адресе набор отказывает до первого запроса.

Если Go у вас нет

Машина — обычный JSON API: тот же контракт доступен прямым HTTP с тем же заголовком ключа. SDK снимает с вас повторы, подписи и разбор конверта. Полная машинная спецификация передаётся оператором при подключении.

Полное руководство со всеми методами, ошибками и сценариями — в справке кабинета, статья «Настройка SDK».