Getting started

curl -s "$EZAZ_API/partner/oauth/token" \
  -u "$EZAZ_CLIENT_ID:$EZAZ_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d "scope=venues:read availability:read reservations:read reservations:write"

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9…",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "availability:read reservations:read reservations:write venues:read"
}

HTTP/1.1 429 Too Many Requests
Retry-After: 17
Content-Type: application/problem+json

{ "status": 429, "code": "PARTNER_RATE_LIMITED", "detail": "Too many requests this minute." }

curl -s "$EZAZ_API/partner/v1/reservations" \
  -H "Authorization: Bearer $EZAZ_TOKEN" \
  -H "Idempotency-Key: 7d0c2f8e-5b1a-4f7e-9a63-2c4b8e1d0f95" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "venueId": "3f6c1a52-8d4e-4b7a-9c2f-5e1d0a9b7c31",
    "courtId": "9b2e7d14-6a3c-4f1e-8d5b-0c7a2e9f4b63",
    "start": "2026-10-10T17:00:00Z",
    "minutes": 90,
    "customer": { "name": "Omar Hassan", "phone": "+201001234567", "phoneVerified": true },
    "payment": { "method": "PREPAID_BY_PARTNER", "collected": { "amount": 120000, "currency": "EGP" } },
    "externalRef": "kb_8f2c41"
  }'

{ "method": "PAY_AT_VENUE" }
{ "method": "PREPAID_BY_PARTNER", "collected": { "amount": 120000, "currency": "EGP" } }
{ "method": "PACKAGE", "packageCreditId": "5a1e…" }  // needs "customer": { …, "phoneVerified": true }

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "COURT_TAKEN",
  "detail": "Someone just booked this court at that time. Pick another time or court."
}

GET /partner/v1/venues?limit=50
→ { "items": [ … ], "nextCursor": "c2a9…" }

GET /partner/v1/venues?limit=50&after=c2a9…
→ { "items": [ … ] }            # no nextCursor: that was the last page

GET /partner/v1/venues/{venueId}/courts/{courtId}/reviews?limit=20
→ [ …, { "id": "e41b…", "createdAt": "2026-10-02T18:00:00Z", … } ]

GET …/reviews?limit=20&before=2026-10-02T18:00:00Z&beforeId=e41b…

POST /ezaz/webhooks HTTP/1.1
Content-Type: application/json
Ezaz-Signature: t=1791651600,v1=5f0c…e2
Ezaz-Event-Id: 0b8e6a1c-2f4d-4e7b-9c1a-6d3f8e2b5a70
User-Agent: Ezaz-Webhooks/1

{
  "id": "0b8e6a1c-2f4d-4e7b-9c1a-6d3f8e2b5a70",
  "type": "reservation.cancelled",
  "createdAt": "2026-10-09T12:40:00Z",
  "data": {
    "reservationId": "d7f3…",
    "venueId": "3f6c…",
    "courtId": "9b2e…",
    "start": "2026-10-10T17:00:00Z",
    "end": "2026-10-10T18:30:00Z",
    "status": "CANCELLED",
    "payment": "PREPAID_BY_PARTNER",
    "externalRef": "kb_8f2c41",
    "cancelReason": "Court maintenance"
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 5 * 60;

/**
 * rawBody: the request body exactly as received (a Buffer or string), before any JSON parsing.
 * header: the Ezaz-Signature header. secret: your whsec_… signing secret.
 */
export function verifyEzazSignature(rawBody, header, secret, nowMs = Date.now()) {
  const parts = Object.fromEntries(
    String(header ?? "").split(",").map((part) => part.trim().split("=")),
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) return false;
  if (Math.abs(nowMs / 1000 - t) > TOLERANCE_SECONDS) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(parts.v1, "hex"));
}

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 5 * 60


def verify_ezaz_signature(raw_body: bytes, header: str, secret: str, now: float | None = None) -> bool:
    """raw_body: the request body exactly as received, before any JSON parsing."""
    try:
        parts = dict(part.strip().split("=", 1) for part in header.split(","))
        t = int(parts["t"])
        given = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs((time.time() if now is None else now) - t) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, given)

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

final class EzazWebhooks {

    private static final long TOLERANCE_SECONDS = 5 * 60;

    /** rawBody: the request body exactly as received, before any JSON parsing. */
    static boolean verify(byte[] rawBody, String header, String secret, Instant now) throws Exception {
        String t = null;
        String v1 = null;
        for (String part : header.split(",")) {
            String[] kv = part.trim().split("=", 2);
            if (kv.length == 2 && kv[0].equals("t")) t = kv[1];
            if (kv.length == 2 && kv[0].equals("v1")) v1 = kv[1];
        }
        if (t == null || v1 == null) return false;
        long timestamp;
        byte[] given;
        try {
            timestamp = Long.parseLong(t);
            given = HexFormat.of().parseHex(v1);
        } catch (IllegalArgumentException e) {
            return false;
        }
        if (Math.abs(now.getEpochSecond() - timestamp) > TOLERANCE_SECONDS) return false;
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        mac.update((timestamp + ".").getBytes(StandardCharsets.UTF_8));
        return MessageDigest.isEqual(mac.doFinal(rawBody), given);
    }
}

import 'dart:convert';

import 'package:crypto/crypto.dart';

const toleranceSeconds = 5 * 60;

/// [rawBody]: the request body exactly as received, before any JSON parsing.
bool verifyEzazSignature(List<int> rawBody, String header, String secret, {DateTime? now}) {
  final parts = <String, String>{};
  for (final part in header.split(',')) {
    final i = part.indexOf('=');
    if (i > 0) parts[part.substring(0, i).trim()] = part.substring(i + 1).trim();
  }
  final t = int.tryParse(parts['t'] ?? '');
  final given = parts['v1'];
  if (t == null || given == null) return false;
  final nowSeconds = (now ?? DateTime.now()).millisecondsSinceEpoch ~/ 1000;
  if ((nowSeconds - t).abs() > toleranceSeconds) return false;
  final expected = Hmac(sha256, utf8.encode(secret)).convert([...utf8.encode('$t.'), ...rawBody]).toString();
  return _constantTimeEquals(expected, given);
}

bool _constantTimeEquals(String a, String b) {
  if (a.length != b.length) return false;
  var diff = 0;
  for (var i = 0; i < a.length; i++) {
    diff |= a.codeUnitAt(i) ^ b.codeUnitAt(i);
  }
  return diff == 0;
}