Uwierzytelnianie

Kazde zapytanie do API Partnerskiego musi byc uwierzytelnione za pomoca podpisywania zapytan HMAC-SHA256 (HMAC-SHA256 request signing). Zapewnia to, ze zapytania sa autentyczne i nie zostaly zmodyfikowane podczas transmisji.

Wymagane naglowki

Naglowek	Opis
`X-API-Key`	Twoj klucz API organizacji
`X-Timestamp`	Biezacy znacznik czasu Unix w sekundach (np. `1711000000`)
`X-Nonce`	Unikalny ciag znakow na zapytanie (zalecany UUID v4)
`X-Signature`	Podpis HMAC-SHA256 zapytania w formacie hex

Konstrukcja podpisu

Podpis jest obliczany poprzez zbudowanie ciagu wiadomosci rozdzielonego kropkami i podpisanie go sekretem klucza API:

message = "{timestamp}.{nonce}.{method}.{path}.{body}"
signature = HMAC-SHA256(apiKeySecret, message).hexDigest()

Skladniki wiadomosci, polaczone kropkami (.):

timestamp -- Znacznik czasu Unix w sekundach (ta sama wartosc co w naglowku X-Timestamp)
nonce -- Ta sama wartosc wyslana w naglowku X-Nonce
method -- Metoda HTTP zapisana wielkimi literami (np. GET, POST)
path -- Pelna sciezka zapytania (np. /v2/partners/products/tickets)
body -- Surowy ciag JSON tresci zapytania. Dla zapytan GET bez tresci uzyj pustego ciagu ""

Wynikowy skrot HMAC musi byc zakodowany jako male litery hex.

Przyklady

API_KEY="your-api-key"
API_SECRET="your-api-secret"
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen | tr '[:upper:]' '[:lower:]')
METHOD="GET"
REQ_PATH="/v2/partners/products/tickets"
BODY=""

MESSAGE="${TIMESTAMP}.${NONCE}.${METHOD}.${REQ_PATH}.${BODY}"

SIGNATURE=$(echo -n "${MESSAGE}" | \
  openssl dgst -sha256 -hmac "${API_SECRET}" | \
  awk '{print $2}')

curl -X GET "https://api.vignetim.com${REQ_PATH}" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Signature: ${SIGNATURE}"

Wazne uwagi

X-Timestamp musi byc w zakresie 5 minut (300 sekund) od czasu serwera. Zapytania z przestarzalymi znacznikami czasu zostana odrzucone z bledem 401.
Kazda wartosc X-Nonce musi byc unikalna i moze byc uzyta tylko raz. Ponowne uzycie nonce spowoduje blad 401.
Zawsze uzywaj surowego, niesformatowanego ciagu JSON tresci do obliczania podpisu. Nie formatuj ani nie serializuj ponownie tresci przed podpisaniem.
Podpis musi byc zakodowany w formacie hex malymi literami. Nie uzywaj base64.