Autentifikacija

Kiekviena užklausa į partnerių API (Partner API) turi būti autentifikuota naudojant HMAC-SHA256 užklausų pasirašymą. Tai užtikrina, kad užklausos yra autentiškos ir nebuvo pakeistos perdavimo metu.

Reikalingos antraštės

Parašo sudarymas

Parašas apskaičiuojamas sudarant tašku atskirtą pranešimo eilutę ir pasirašant ją jūsų API rakto slaptuoju raktu:

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

Pranešimo komponentai, sujungti taškais (.):

1. timestamp — Unix laiko žyma sekundėmis (ta pati reikšmė kaip X-Timestamp antraštėje)
2. nonce — Ta pati reikšmė, siųsta X-Nonce antraštėje
3. method — HTTP metodas didžiosiomis raidėmis (pvz., GET, POST)
4. path — Pilnas užklausos kelias (pvz., /v2/partners/products/tickets)
5. body — Neapdorota JSON užklausos turinio eilutė. GET užklausoms be turinio naudokite tuščią eilutę ""

Gautas HMAC santraukos rezultatas turi būti užkoduotas mažosiomis šešioliktainėmis raidėmis.

Pavyzdžiai

API_KEY="your-api-key"
API_SECRET="your-api-secret"

# Signing key = SHA-256 hex digest of your API secret (as an ASCII string)
# $NF, not $2: OpenSSL prints "SHA2-256(stdin)= <hash>" but LibreSSL (the macOS
# default) prints the bare hash, where $2 is empty — that yields an empty signing
# key and a 401 with nothing to indicate why.
SIGNING_KEY=$(echo -n "${API_SECRET}" | openssl dgst -sha256 | awk '{print $NF}')

TIMESTAMP=$(date +%s)
NONCE=$(uuidgen | tr '[:upper:]' '[:lower:]')
METHOD="POST"
REQ_PATH="/v2/partners/webhooks"

# Compact JSON, no whitespace. Sign the exact string you send.
BODY='{"url":"https://yourapp.com/webhooks/vignetim","events":["order.completed"]}'

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

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

curl -X POST "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}" \
  -d "${BODY}"

Svarbios pastabos

• X-Timestamp turi būti ne senesnė nei 5 minutės (300 sekundžių) nuo serverio laiko. Užklausos su pasenusiomis laiko žymomis bus atmestos su 401 klaida.
• Kiekviena X-Nonce reikšmė turi būti unikali ir gali būti panaudota tik vieną kartą. Pakartotinis nonce naudojimas sukels 401 klaidą.
• Visada naudokite neapdorotą, neformatuotą JSON turinio eilutę parašo skaičiavimui. Neformatuokite ir neperserializuokite turinio prieš pasirašymą.
• Parašas turi būti šešioliktainiu formatu mažosiomis raidėmis. Nenaudokite base64.