API manual

• An account on the Platinum or Accountant plan.
• An API token, created under Settings → Integrations. It is shown once, at creation.
• At least one entity with monitoring switched on — the API only answers about the tax ids you monitor.

You need nothing from ANAF. The certificate, the OAuth dance and the SPV polling stay on our side; you only talk to this API.

https://alertespv.ro/api/v1

The version has been in the path since the first line. New fields may appear in a response at any time, so read them by name and ignore the ones you do not know. Existing fields do not change meaning and do not disappear without a new version in the path.

Every response is JSON, with one exception: the XML download, which returns the file exactly as ANAF issued it.

The token travels in the "Authorization: Bearer …" header. There are no sessions, no cookies and no keys in the query string.

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

• A token always starts with "spva_", so a leaked one is recognisable in a log or a bad paste.
• Five active tokens per account at most. Revoking takes effect immediately.
• We do not keep the plaintext — if you lost it, create another and revoke the old one.
• The "last used" column under Settings → Integrations tells you whether a token is still in use before you revoke it.

The token opens every fiscal document on the account. Keep it on a server, in an environment variable — never in versioned code, in a mobile app, or in JavaScript running in a browser.

120 requests a minute per account. Over the limit the answer is 429, with a "Retry-After" header saying how many seconds to wait. The limit is far more than a daily sync needs and far less than a loop with a bug costs.

• Paginated lists accept "per_page" between 1 and 100; 100 by default.
• Ask for a page with "page". The number of pages is in "meta.last_page".
• Documents come back newest first, by their creation date at ANAF, then by id.

Returns everything your certificate can see — companies and individuals — together with the state of your plan's slots. An entity is listed even when it is not monitored; monitoring is what spends a 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 }
}

Starting spends a slot that does not come back immediately. The response says outright whether one was taken ("slot_taken"), because a script is exactly the caller most likely to start thirty entities without having read anything first.

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

• "slot_taken": false means the entity already held a slot — the call was idempotent, you were not charged twice.
• Stopping always answers "slot_released": false. A slot is released only at a subscription-month boundary, at least 30 days after it was taken, and only if monitoring was already off by then.
• An entity belonging to another account answers 403, not 404.

The documents of the tax ids you monitor, with the summary extracted from the XML. A "cif" that is not among them is silently ignored as a filter — the list stays within what you are allowed to see.

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

• "type" and "details" come from ANAF exactly as it words them: "FACTURA PRIMITA", "FACTURA TRIMISA", "ERORI FACTURA". Treat them as text, not as a closed enumeration.
• "summary" is null when the document has not been archived yet, or when the XML is not an invoice we can read (an error report with no content, an unrecognised format).
• "summary.kind" is "invoice", "credit_note", "errors" or "unsupported".
• "counterpartyRole" says which party is the other one: "supplier" on a received invoice, "customer" on one you issued. The same invoice has different roles for the two companies, when both are monitored.
• Amounts are strings, not numbers: "990.08" stays exactly that. Do not put them through a float on the way into an accounting system.
• "anaf_id" plus "cif" identify the document at ANAF; "id" is its identifier here.

Returns the XML exactly as ANAF issued it, as a download named "{cif}-{anaf_id}.xml". It is not JSON and it is not modified in any way — it is the copy we archived.

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

The usual shape of a daily sync: ask for the documents in a date range, remember what you already took by "id", and download the XML only for the archived ones.

# Yesterday, every monitored tax id, first page.
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}'

If you want to hear about documents the moment they appear rather than on the hour, use webhooks. The API is for syncing and for asking; the webhook is for being told.