API — Rapoarte PDF

Disponibil: plan Consultant · Autentificare: API Key

Generarea rapoartelor este asincronă: trimiți o cerere, primești un job_id, polling-uiești statusul, apoi obții un URL temporar de descărcare (valabil 15 minute, maxim 3 utilizări).

Cost credite: 10 credite per PDF generat (deduse la status = completed)

---

POST /api/v1/reports/:companyId/pdf

Inițiază generarea unui raport PDF branded.

Request:

POST /api/v1/reports/uuid-companie/pdf
Authorization: Bearer scopo_<cheie>
Content-Type: application/json

{
  "date_from": "2026-06-01",
  "date_to": "2026-06-18",
  "min_score": 60,
  "watchlist_id": "uuid-optional"
}

Câmpuri:

Câmp	Tip	Obligatoriu	Descriere
date_from	string	✓	Data de start (format YYYY-MM-DD)
date_to	string	✓	Data de sfârșit (format YYYY-MM-DD)
min_score	integer	—	Scor minim (0–100); default: 0
watchlist_id	string	—	UUID — filtrare per watchlist (opțional)

Răspuns (202 Accepted):

{
  "job_id": "uuid-job",
  "status": "generating",
  "estimated_seconds": 20
}

---

GET /api/v1/reports/jobs/:jobId/status

Verifică statusul jobului de generare.

Request:

GET /api/v1/reports/jobs/uuid-job/status
Authorization: Bearer scopo_<cheie>

Răspuns:

{
  "job_id": "uuid-job",
  "status": "completed"
}

Status	Descriere
pending	Job în coadă
generating	PDF se generează
completed	PDF gata — apelează /download
failed	Generarea a eșuat — reîncearcă cererea

---

GET /api/v1/reports/jobs/:jobId/download

Obține URL-ul temporar de descărcare (disponibil doar când status = completed).

Request:

GET /api/v1/reports/jobs/uuid-job/download
Authorization: Bearer scopo_<cheie>

Răspuns:

{
  "download_url": "https://api.scopo.ro/api/v1/reports/download/token64chars",
  "expires_at": "2026-06-18T10:38:45Z"
}

---

GET /api/v1/reports/download/:token

Descarcă PDF-ul. Nu necesită autentificare — token-ul este credențialul de acces.

GET /api/v1/reports/download/token64chars

Răspuns: stream PDF (Content-Type: application/pdf, Content-Disposition: attachment)

Limitări token:

• Valabil 15 minute de la generare
• Maximum 3 descărcări per token
• La expirare sau depășirea limitei: 410 Gone cu DOWNLOAD_TOKEN_EXPIRED

---

Flux complet — exemplu

# 1. Inițiază generarea
JOB_ID=$(curl -s -X POST \
  "https://api.scopo.ro/api/v1/reports/uuid-companie/pdf" \
  -H "Authorization: Bearer scopo_..." \
  -H "Content-Type: application/json" \
  -d '{"date_from":"2026-06-01","date_to":"2026-06-18","min_score":60}' \
  | jq -r '.job_id')

# 2. Polling status (la fiecare 5s)
until [ "$(curl -s "https://api.scopo.ro/api/v1/reports/jobs/$JOB_ID/status" \
  -H "Authorization: Bearer scopo_..." | jq -r '.status')" = "completed" ]; do
  sleep 5
done

# 3. Obține URL descărcare
DOWNLOAD_URL=$(curl -s \
  "https://api.scopo.ro/api/v1/reports/jobs/$JOB_ID/download" \
  -H "Authorization: Bearer scopo_..." \
  | jq -r '.download_url')

# 4. Descarcă PDF-ul (fără auth)
curl -o raport.pdf "$DOWNLOAD_URL"

---

Rate limiting

Limită	Valoare
POST PDF	10 / oră
GET status	fără limită separată (intră în 60/min general)

---

Erori frecvente

Cod	Eroare	Cauză
401	API_KEY_INVALID	Cheie lipsă sau invalidă
403	COMPANY_ACCESS_DENIED	companyId nu aparține tenant-ului
403	PLAN_UPGRADE_REQUIRED	Plan < Consultant
410	DOWNLOAD_TOKEN_EXPIRED	Token expirat sau utilizat de mai mult de 3 ori
429	RATE_LIMIT_EXCEEDED	Depășit 10 req PDF/oră
402	API_CREDITS_EXHAUSTED	Credite insuficiente (necesare 10)

---

Vezi și

• Credite API — cost și sold
• Watchlists API — UUID-uri de watchlist
• Erori API — referință completă