API Documentation

Az API nem más, mint a Pinqo dashboardot hajtó App Router route handlerek összessége, így nincs külön felület, amit meg kéne tanulni. Public base URL: https://pinqoai.com.

Minden válasz tartalmaz egy x-request-id és egy x-duration-ms headert. Ha bármiben elakadsz, küldd át mindkettőt a support kéréssel, így azonnal megtaláljuk.

A felhasználói végpontokat (/api/audit, /api/chat, /api/billing) a session cookie hitelesíti, így minden böngészőből érkező kérés eleve a Supabase auth flow-n belül van.

A szerverközi hívások a webhook (Stripe-signature) és a cron (Authorization: Bearer $CRON_SECRET) végpontokon mennek. Külön API kulcsot (PAT) a v1-ben vezetünk be.

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

Ha túlléped a limitet, 429 Too Many Requests jön vissza egy Retry-After headerrel (másodpercben). A válasz törzse így néz ki:

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

Teljes Claude-alapú auditot futtat az elküldött workspace kontextusra. Cache-elt prompt, Sonnet 4.6. Számolj 20–40 másodperc futásidővel.

curl -X POST https://pinqoai.com/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 válasz text/plain, tokenenként streamelve, kliens oldalon a Fetch streams API-val olvasd be.

curl -N -X POST https://pinqoai.com/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-t nyit, és visszaadja a redirect URL-t.

curl -X POST https://pinqoai.com/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_…"
}

Elfogadott értékek: plan ∈ {starter,growth,agency,done,setup_pack}, currency ∈ {huf,gbp,eur}, interval ∈ {month,year}. A setup_pack egyszeri díj, ezért az interval figyelmen kívül marad.

Stripe Customer Portal session a kártyaadatok módosításához, a lemondáshoz és a számlákhoz. A bejelentkezett felhasználó Stripe customer ID-jával hívd.

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

POST /api/billing/webhook, ahol minden eseményt a Stripe signature alapján ellenőrzünk. A kezelt típusok:

• checkout.session.completed: jóváírja az ajánlót (metadata.referrer_code), és naplózza az eseményt
• customer.subscription.created / updated: naplózza az előfizetés állapotát
• customer.subscription.deleted: win-back emailt küld (Resend)
• invoice.payment_failed: dunning emailt küld Stripe Portal frissítő linkkel
• invoice.upcoming(havi, >30 nap): éves csomagra ösztönző emailt küld

Könnyűsúlyú health probe, ami az integrációk készültségét jelzi. Nem hív külső API-t, és publikus.

curl https://pinqoai.com/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"
}