Kumppani-API

Palvelinten välinen API kumppaneille: luo avain, lue myymäläsi asetukset ja sijainnit, luo asiakkaita, myönnä paketteja ja hallitse tilauslinkkejä omalta sivustoltasi tai Telegram-botistasi.

Kumppani-API:n avulla voit rakentaa CreateYourVPN:n päälle oman sivuston, oman asiakasportaalin tai Telegram-botin.

API kattaa asiakkaat, tilaukset, paketit ja myymälän asetukset. Infrastruktuuri, eli palvelimet, solmut, hallintapaneelit ja SSH-tunnukset, ei kuulu julkiseen sopimukseen.

Vain palvelinten välisiin integraatioihin. Säilytä API-avain omalla palvelimellasi äläkä lisää sitä frontend-koodiin. Pyynnöt, joissa on selaimen otsikot, hylätään koodilla 403 browser_forbidden.

Avaimen hankkiminen

Paneeli → tilivalikko → ”API”, ”Avaimet”-välilehti.

Anna avaimelle nimi (Telegram-botti, laskeutumissivu) ja ota käyttöön vain ne oikeudet, joita se tarvitsee.

Valitse ”Luo avain” ja kopioi koko arvo. Salaisuus näytetään vain kerran, koska palvelu tallentaa siitä ainoastaan tiivisteen.

Kumppanilla voi olla enintään 5 aktiivista avainta. Kun haluat vaihtaa avaimen, luo uusi, päivitä integraatio ja peru sitten vanha.

Todentaminen

Avain lähetetään bearer-tokenina:

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

Myös X-API-Key: cyv_live_… toimii, jos Authorization-otsikko on välityspalvelimen käytössä.

Avain on muotoa cyv_live_<key_id>_<secret>. Ensimmäinen puolisko (key_id) on julkinen: juuri se näkyy paneelissa, ja sen voi turvallisesti kertoa tuelle. Toinen puolisko on salaisuus.

Oikeudet (scopes)

Oikeus	Mitä se sallii
`config:read`	Myymälän asetusten, pakettien, sijaintien ja `/me`-tietojen lukeminen.
`users:read`	Asiakkaiden, heidän tilaustensa ja liikenteensä lukeminen.
`users:write`	Asiakkaiden luominen, pakettien myöntäminen, linkkien nollaaminen, asiakkaiden poistaminen.

config:read riittää integraatioille, jotka vain lukevat myymälän tietoja. Lisää users:read tai users:write vain, kun integraatio tarvitsee vastaavia asiakastoimintoja.

API-sopimus ja esimerkit

Täydellinen, ajettava sopimus on julkisessa Postman-kokoelmassa. Siinä ovat kaikki endpointit, oikeudet, parametrit, pyyntöjen rungot, vastausesimerkit ja pysyvät virhekoodit. Kokoelma luodaan backend-sopimuksesta, ja siinä ovat ajantasaiset pyyntö- ja vastausskeemat.

Avaa julkinen Postman-kokoelma

Tutustu kaikkiin endpointeihin ja kopioi kokoelma omaan työtilaasi.

Rajat

Raja lasketaan erikseen jokaiselle avaimelle, eikä se riipu pyynnön IP-osoitteesta.

120 pyyntöä minuutissa avainta kohden yhteensä.
10 pyyntöä minuutissa erikseen GET /users-kutsulle.

GET /users-kutsulla on oma rajansa, koska jokainen pyyntö lataa koko asiakaslistan. Säännöllisiin tarkistuksiin käytä GET /users/{id}-kutsua tai hakua externalId-tunnisteella.

Suositeltu tapa. Tallenna asiakkaan CreateYourVPN-tunniste luontipyynnön vastauksesta ja käytä myöhemmissä hauissa GET /users/{id}-kutsua. Oman asiakastunnisteesi voit liittää siihen externalId-kentällä.

Idempotenssi

Kolme toimintoa vaatii Idempotency-Key-otsikon: paketin myöntäminen, tilauslinkin nollaaminen ja asiakkaan poistaminen.

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

Kun pyyntö toistetaan samalla avaimella 24 tunnin sisällä, palautetaan tallennettu vastaus eikä toimintoa suoriteta uudelleen. Näin muutokset eivät monistu, kun integraatio yrittää uudelleen aikakatkaisun jälkeen.

Luo jokaiselle liiketoimintatapahtumalle (esimerkiksi yhdelle maksulle tai toiminnolle) oma avain ja käytä sitä tapahtuman kaikissa uusintayrityksissä.

Jos ensimmäinen yritys on vielä käynnissä tai sen lopputulos on hetkellisesti tuntematon, API palauttaa 409 conflict suorittamatta toimintoa uudelleen. Tarkista asiakkaan nykyinen tila ennen kuin yrität uudelleen.

Ajantasaiset pyyntö- ja vastausskeemat löydät yllä olevasta julkisesta Postman-kokoelmasta.