API Documentation

Az API a Pinqo dashboard mögött ugyanaz az App Router route handler-ek gyűjteménye. Public base URL: https://pinqo.ai.

A válaszok tartalmaznak x-request-id és x-duration-ms headert — ezt kérjük belinkelni a support kérésekbe.

A user-facing endpointokat (/api/audit, /api/chat, /api/billing) a session cookie hitelesíti — a böngészőből érkező kérések automatikusan részei a Supabase auth flow-nak.

Server-to-server hívásokhoz tervezett a webhook (Stripe-signature) és a cron (Authorization: Bearer $CRON_SECRET) endpoint. Külön API kulcs (PAT) a v1-re lesz bevezetve.

IP-alapú token bucket, scope-onként:

Limit-túllépéskor: 429 Too Many Requests + Retry-After header (másodperc). A response body:

{
  "error": "rate_limited",
  "message": "Túl sok kérés. Próbáld újra 60 másodperc múlva.",
  "retryAfter": 60
}

Lefuttat egy Claude-alapú teljes auditot az átadott workspace kontextuson. Cache-elt prompt, Sonnet 4.6. Várható futási idő: 20–40 másodperc.

curl -X POST https://pinqo.ai/api/audit/run \
  -H "Content-Type: application/json" \
  --cookie "sb-access-token=..." \
  -d '{
    "context": {
      "workspace": { "name": "Vitaflex", "currency": "HUF" },
      "topEntities": [ … ],
      "anomalies": [ … ]
    }
  }'

Response:

{
  "ok": true,
  "mode": "claude",
  "output": {
    "executive_summary": "…",
    "account_health_score": 78,
    "insights": [ … ]
  },
  "usage": {
    "promptTokens": 12483,
    "cachedTokens": 11200,
    "completionTokens": 2174,
    "costUsd": 0.018,
    "elapsedMs": 24180
  }
}

Streaming Claude-válasz egy insight kontextusra. A response text/plain, tokenenként streamelve. Fogadó oldalon használd a Fetch streams API-t.

curl -N -X POST https://pinqo.ai/api/chat/insight \
  -H "Content-Type: application/json" \
  --cookie "sb-access-token=..." \
  -d '{
    "insight": { "id": "…", "severity": "high", "metricEvidence": {…} },
    "messages": [{ "role": "user", "content": "Miért magas a CPM?" }]
  }'

X-Pinqo-Mode response header: claude vagy mock.

Stripe Checkout Session indítás. Visszaadja a redirect URL-t.

curl -X POST https://pinqo.ai/api/billing/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "growth",
    "currency": "huf",
    "interval": "year",
    "email": "user@example.com",
    "referrer": "PINQO-ABCD-1234"
  }'

Response:

{
  "ok": true,
  "url": "https://checkout.stripe.com/c/pay/cs_…",
  "id": "cs_test_…"
}

Engedélyezett értékek: plan ∈ {starter,growth,agency,done,setup_pack}, currency ∈ {huf,gbp,eur}, interval ∈ {month,year}. A setup_pack one-time, interval ignorált.

Stripe Customer Portal session — kártya update, lemondás, számlák. A bejelentkezett user adott Stripe customer ID-jával hívható.

curl -X POST https://pinqo.ai/api/billing/portal \
  -H "Content-Type: application/json" \
  --cookie "sb-access-token=..." \
  -d '{"customerId": "cus_…"}'

POST /api/billing/webhook — Stripe signature-rel hitelesített események. Kezelt típusok:

• checkout.session.completed — referrer attribuálás (metadata.referrer_code) + log
• customer.subscription.created / updated — előfizetés állapot log
• customer.subscription.deleted — win-back email (Resend)
• invoice.payment_failed — dunning email Stripe Portal update linkkel
• invoice.upcoming(havi, >30 nap) — annual upgrade nudge email

Lightweight health probe — integráció readiness státusz. Nem kér le külső API-t. Public.

curl https://pinqo.ai/api/health

Response:

{
  "ok": true,
  "version": "0.1.0",
  "env": "production",
  "uptime": 18420.5,
  "integrations": {
    "stripe": true, "claude": true, "resend": true,
    "meta_ads": true, "google_ads": true, "supabase": true
  },
  "readiness": { "ready": 6, "total": 6, "percent": 100 },
  "timestamp": "2026-05-25T19:48:11.221Z"
}