Manual API

• Un cont cu planul Platinum sau Contabil.
• Un token API, creat din Setări → Integrări. Se afișează o singură dată, la creare.
• Cel puțin o entitate cu monitorizarea pornită — API-ul răspunde numai despre CIF-urile pe care le monitorizezi.

Nu ai nevoie de nimic din partea ANAF. Certificatul, OAuth-ul și interogarea SPV rămân la noi; tu vorbești doar cu API-ul acesta.

https://alertespv.ro/api/v1

Versiunea este în cale de la prima zi. Câmpuri noi pot apărea oricând într-un răspuns, așa că citește-le pe nume și ignoră-le pe cele necunoscute. Câmpurile existente nu își schimbă înțelesul și nu dispar fără o versiune nouă în cale.

Toate răspunsurile sunt JSON, cu o singură excepție: descărcarea XML-ului, care întoarce fișierul așa cum l-a emis ANAF.

Tokenul se trimite ca antet „Authorization: Bearer …". Nu există sesiuni, cookie-uri sau chei în query string.

curl -s https://alertespv.ro/api/v1/entities \
  -H "Authorization: Bearer spva_cheia_ta" \
  -H "Accept: application/json"

• Tokenul începe întotdeauna cu „spva_", ca să fie recunoscut într-un log sau într-un paste greșit.
• Maximum 5 tokenuri active per cont. Revocarea este imediată.
• Nu îl păstrăm în clar — dacă l-ai pierdut, creezi altul și îl revoci pe cel vechi.
• Coloana „ultima folosire" din Setări → Integrări îți spune dacă un token mai e folosit înainte să îl revoci.

Tokenul deschide toate documentele fiscale ale contului. Ține-l pe server, într-o variabilă de mediu — niciodată în cod versionat, într-o aplicație mobilă sau în JavaScript rulat în browser.

120 de cereri pe minut per cont. Peste limită răspunsul este 429, cu antetul „Retry-After" care spune câte secunde să aștepți. Limita este mult peste ce cere o sincronizare zilnică și mult sub ce costă o buclă cu un bug.

• Listele paginate acceptă „per_page" între 1 și 100; implicit 100.
• Pagina se cere cu „page". Numărul total de pagini este în „meta.last_page".
• Ordinea documentelor este descrescătoare după data creării la ANAF, apoi după id.

Întoarce tot ce vede certificatul tău — firme și persoane fizice — împreună cu starea sloturilor din plan. O entitate există în listă chiar dacă nu este monitorizată; monitorizarea este ce consumă un slot.

{
  "data": [
    {
      "id": 12,
      "cif": "44674942",
      "kind": "company",
      "name": "EXEMPLU SRL",
      "monitored": true,
      "enabled": true,
      "last_polled_at": "2026-08-11T07:00:12+00:00",
      "slot_releasable_from": "2026-09-09"
    }
  ],
  "slots": { "used": 1, "limit": 25, "free": 24 }
}

Pornirea consumă un slot care nu se întoarce imediat. Răspunsul spune explicit dacă s-a luat unul („slot_taken"), pentru că un script este exact apelantul care pornește treizeci de entități fără să fi citit nimic înainte.

curl -s -X POST https://alertespv.ro/api/v1/entities/12/start \
  -H "Authorization: Bearer spva_cheia_ta" \
  -H "Accept: application/json"

• „slot_taken": false înseamnă că entitatea ocupa deja un slot — apelul a fost idempotent, nu ai plătit de două ori.
• Oprirea răspunde întotdeauna cu „slot_released": false. Slotul se eliberează abia la o graniță de lună de abonament, la cel puțin 30 de zile de la pornire, și numai dacă monitorizarea era oprită atunci.
• O entitate care aparține altui cont răspunde 403, nu 404.

Documentele CIF-urilor pe care le monitorizezi, cu sumarul extras din XML. Un „cif" care nu e printre ele este ignorat tăcut ca filtru — lista rămâne limitată la ce ai voie să vezi.

curl -s -G https://alertespv.ro/api/v1/documents \
  -H "Authorization: Bearer spva_cheia_ta" \
  --data-urlencode "cif=44674942" \
  --data-urlencode "from=2026-08-01" \
  --data-urlencode "to=2026-08-11" \
  --data-urlencode "per_page=50"

• „type" și „details" vin de la ANAF exact cum le dă el: „FACTURA PRIMITA", „FACTURA TRIMISA", „ERORI FACTURA". Tratează-le ca text, nu ca enumerare închisă.
• „summary" este null când documentul nu a fost arhivat încă sau când XML-ul nu este o factură pe care o putem citi (raport de erori fără conținut, format nerecunoscut).
• „summary.kind" este „invoice", „credit_note", „errors" sau „unsupported".
• „counterpartyRole" spune cine este partenerul: „supplier" la o factură primită, „customer" la una trimisă. Aceeași factură are roluri diferite pentru cele două firme, dacă ambele sunt monitorizate.
• Sumele sunt text, nu numere: „990.08" rămâne exact atât. Nu le trece prin float dacă le pui într-o contabilitate.
• „anaf_id" plus „cif" identifică unic documentul la ANAF; „id" este identificatorul lui la noi.

Întoarce XML-ul așa cum l-a emis ANAF, ca fișier de descărcat, cu numele „{cif}-{anaf_id}.xml". Nu este JSON și nu este modificat în niciun fel — este exact copia pe care o arhivăm.

curl -s -OJ https://alertespv.ro/api/v1/documents/8814/xml \
  -H "Authorization: Bearer spva_cheia_ta"

Tiparul obișnuit al unei sincronizări zilnice: ceri documentele dintr-un interval, ții minte ce ai luat deja după „id", și descarci XML-ul doar pentru cele arhivate.

# Ieri, toate CIF-urile monitorizate, prima pagina.
YESTERDAY=$(date -d yesterday +%F)

curl -s -G https://alertespv.ro/api/v1/documents \
  -H "Authorization: Bearer $ALERTESPV_TOKEN" \
  --data-urlencode "from=$YESTERDAY" \
  --data-urlencode "to=$YESTERDAY" \
  --data-urlencode "per_page=100" | jq '.data[] | {id, cif, type, archived}'

Dacă vrei să afli despre documente în momentul în care apar, nu la o oră fixă, folosește webhook-urile. API-ul este pentru sincronizări și pentru interogări la cerere; webhook-ul este pentru „spune-mi acum".