واجهة نقرة البرمجية

const API = "https://api.nqra.link/api/v1";
const KEY = process.env.NQRA_API_KEY; // nq_live_…, from Developers → API keys

async function nqra(method, path, payload) {
  const res = await fetch(`${API}${path}`, {
    method,
    headers: { "content-type": "application/json", "x-api-key": KEY },
    body: payload ? JSON.stringify(payload) : undefined,
  });
  if (!res.ok) throw new Error((await res.json()).error.code);
  return res.status === 204 ? null : res.json();
}

curl -X POST "https://api.nqra.link/api/v1/links" \
  -H "x-api-key: $NQRA_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com/a-long-address"}'

curl "https://api.nqra.link/api/v1/links" -H "authorization: Bearer $ACCESS_TOKEN"

{ "error": { "code": "SLUG_TAKEN", "message": "Slug already taken." } }

HTTP/1.1 429 Too Many Requests
retry-after: 60

{ "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded." } }

await nqra("POST", "/links", {
  url: "https://rawafid.manhali.com/courses/python-basics",
  slug: "python-101",
  tags: ["courses"],
  maxClicks: 500,
});

{
  "slug": "python-101",
  "shortUrl": "https://nqra.link/python-101",
  "url": "https://rawafid.manhali.com/courses/python-basics",
  "title": null,
  "tags": [{ "id": "tag_…", "name": "courses", "color": "#0d6b88" }],
  "status": "active",
  "expiresAt": null,
  "maxClicks": 500,
  "clickCount": 0,
  "isActive": true,
  "safetyStatus": "pending",
  "createdAt": 1790000000000,
  "updatedAt": 1790000000000
}

await nqra("GET", "/links?limit=25&sort=clicks&tag=courses");

{
  "items": [{ "slug": "python-101", "url": "https://…", "clickCount": 1846, "tags": [{ "id": "tag_…", "name": "courses", "color": "#0d6b88" }], … }],
  "nextCursor": null
}

await nqra("PATCH", "/links/python-101", { isActive: false });
// → 200 with the updated link

await nqra("GET", "/stats/links/python-101?range=7d");

{
  "slug": "python-101",
  "range": "7d",
  "clickCount": 1846,
  "lastClickAt": 1790000000000,
  "totals": { "clicks": 412, "prevClicks": 368 },
  "series": { "values": [51, 62, …], "times": [1789395600000, …], "bucketMs": 86400000 },
  "countries": [{ "key": "IQ", "value": 244 }, …],
  "referrers": [{ "key": "instagram.com", "value": 118 }, …],
  …
}

await nqra("GET", "/stats/overview?range=30d");

{
  "range": "30d",
  "totals": { "clicks": 5120, "prevClicks": 4380, "lifetimeClicks": 18240, … },
  "series": { "values": [160, 171, …], "times": [1787400000000, …], "bucketMs": 86400000 },
  "topLinks": [{ "slug": "python-101", "clicks": 1846, "spark": [51, 62, …] }],
  "countries": [{ "key": "IQ", "value": 2210 }, …],
  …
}

await nqra("GET", "/tags");

[{ "id": "tag_…", "name": "courses", "color": "#0d6b88", "linksCount": 6 }]