Autentificare (Authentication)

Fiecare cerere către API-ul pentru Parteneri trebuie autentificată utilizând semnarea cererilor HMAC-SHA256. Aceasta asigură că cererile sunt autentice și nu au fost modificate în tranzit.

Anteturi obligatorii

Construcția semnăturii

Semnătura se calculează prin construirea unui șir de mesaj separat prin puncte și semnarea acestuia cu secretul cheii API:

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

Componentele mesajului, unite prin puncte (.):

1. timestamp — Marca temporală Unix în secunde (aceeași valoare ca antetul X-Timestamp)
2. nonce — Aceeași valoare trimisă în antetul X-Nonce
3. method — Metoda HTTP cu majuscule (de ex., GET, POST)
4. path — Calea completă a cererii (de ex., /v2/partners/products/tickets)
5. body — Corpul cererii JSON brut ca șir de caractere. Pentru cererile GET fără corp, utilizați un șir gol ""

Digestul HMAC rezultat trebuie codificat ca hex cu litere mici.

Exemple

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

Note importante

• X-Timestamp trebuie să fie în interval de 5 minute (300 secunde) față de ora serverului. Cererile cu mărci temporale expirate vor fi respinse cu eroarea 401.
• Fiecare valoare X-Nonce trebuie să fie unică și poate fi utilizată o singură dată. Reutilizarea unui nonce va rezulta într-o eroare 401.
• Utilizați întotdeauna corpul JSON brut, neformatat, pentru calculul semnăturii. Nu formatați și nu re-serializați corpul înainte de semnare.
• Semnătura trebuie să fie codificată hex cu litere mici. Nu utilizați base64.