Avtentikacija

Vsaka zahteva do Partner API-ja mora biti avtenticirana z uporabo HMAC-SHA256 podpisovanja zahtev (request signing). To zagotavlja, da so zahteve avtentične in da med prenosom niso bile spremenjene.

Zahtevane glave

Konstruiranje podpisa

Podpis se izračuna z gradnjo sporočilnega niza, ločenega s pikami, in podpisovanjem z vašo API ključno skrivnostjo:

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

Komponente sporočila, združene s pikami (.):

1. timestamp — Unix časovni žig v sekundah (enaka vrednost kot v glavi X-Timestamp)
2. nonce — Enaka vrednost, poslana v glavi X-Nonce
3. method — HTTP metoda z velikimi črkami (npr. GET, POST)
4. path — Polna pot zahteve (npr. /v2/partners/products/tickets)
5. body — Surov JSON niz telesa zahteve. Za GET zahteve brez telesa uporabite prazen niz ""

Rezultirajoči HMAC povzetek mora biti kodiran kot šestnajstiške male črke (lowercase hex).

Primeri

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}"

Pomembne opombe

• X-Timestamp mora biti znotraj 5 minut (300 sekund) od strežniškega časa. Zahteve z zastarelimi časovnimi žigi bodo zavrnjene z napako 401.
• Vsaka vrednost X-Nonce mora biti edinstvena in se lahko uporabi samo enkrat. Ponovna uporaba nonce-a bo povzročila napako 401.
• Za izračun podpisa vedno uporabite surov, neformatiran JSON niz telesa. Telesa pred podpisovanjem ne polepšujte ali ponovno serializirajte.
• Podpis mora biti kodiran v šestnajstiškem zapisu z malimi črkami. Ne uporabljajte base64.