Автентифікація (Authentication)

Кожен запит до Partner API повинен бути автентифікований за допомогою підпису запитів HMAC-SHA256. Це гарантує, що запити є справжніми та не були змінені під час передачі.

Обов'язкові заголовки

Побудова підпису (Signature Construction)

Підпис обчислюється шляхом побудови рядка повідомлення, розділеного крапками, та його підписання вашим секретним ключем API:

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

Компоненти повідомлення, з'єднані крапками (.):

1. timestamp — Мітка часу Unix у секундах (те саме значення, що й у заголовку X-Timestamp)
2. nonce — Те саме значення, що надіслане у заголовку X-Nonce
3. method — HTTP-метод у верхньому регістрі (наприклад, GET, POST)
4. path — Повний шлях запиту (наприклад, /v2/partners/products/tickets)
5. body — Необроблений рядок JSON тіла запиту. Для GET-запитів без тіла використовуйте порожній рядок ""

Отриманий HMAC-дайджест повинен бути закодований як шістнадцятковий рядок у нижньому регістрі.

Приклади

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

Важливі примітки

• X-Timestamp повинен бути в межах 5 хвилин (300 секунд) від часу сервера. Запити із застарілими мітками часу будуть відхилені з помилкою 401.
• Кожне значення X-Nonce повинно бути унікальним і може бути використане лише один раз. Повторне використання nonce призведе до помилки 401.
• Завжди використовуйте необроблений, неформатований рядок JSON тіла для обчислення підпису. Не форматуйте та не перетворюйте тіло перед підписанням.
• Підпис повинен бути закодований у шістнадцятковому форматі в нижньому регістрі. Не використовуйте base64.