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

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 (.):

1. timestamp -- Znacznik czasu Unix w sekundach (ta sama wartosc co w naglowku X-Timestamp)
2. nonce -- Ta sama wartosc wyslana w naglowku X-Nonce
3. method -- Metoda HTTP zapisana wielkimi literami (np. GET, POST)
4. path -- Pelna sciezka zapytania (np. /v2/partners/products/tickets)
5. 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"

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

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.