Integrate E-Reporting
This guide wires e-reporting into your order flow, from the first transaction to a filed period. It follows one example: an online shop selling to consumers in France, which France requires you to report as a daily aggregate. Other regimes (Spain, Portugal) use the same calls; the regime pages say what differs. For every field and status see E-Reporting.
Prerequisites
- The regime is switched on for your entity, with its start date, submission mode and (for France) VAT regime. This is one-off set-up: see Reporting obligations and French VAT regime.
- For France, a registered French VAT number and a connected platform: France set-up.
- A
csk_test_*key while you build. See Sandbox & testing.
Step 1 — Send every transaction
There is no separate e-reporting endpoint. Send each sale through POST /v1/send, the same call as an e-invoice, and Clearvo decides whether it is reported. Say that the customer is a consumer with customerType: "B2C".
curl https://api.clearvo.io/v1/send \
-X POST \
-H "x-api-key: csk_live_..." \
-H "Content-Type: application/json" \
-d '{
"documentType": "invoice",
"invoiceNumber": "WEB-78921",
"issueDate": "2026-09-14",
"currency": "EUR",
"country": "FR",
"customerType": "B2C",
"customer": { "name": "Camille Martin", "address": { "country": "FR" } },
"lines": [ { "description": "Order 78921", "quantity": 1, "unitPrice": 82.64, "taxRate": 20 } ]
}'
{
"status": "ACCUMULATED",
"mandate": "FR_EREPORTING",
"id": "txn_01H8X9K2M4QRT7VWYZ3ABCDEF",
"period": { "key": "2026-09-D2", "start": "2026-09-11", "end": "2026-09-20" },
"deadline": "2026-09-30",
"reviewRequired": true
}
ACCUMULATED means the transaction joined the period; nothing is sent for it individually. Store the id. Re-sending the same invoice number returns the stored result, so retries are safe (Idempotency). Which operations are reported, and how, is in E-Reporting: France.
Step 2 — Resolve missing information
If a fact the regime needs is missing (for example the customer's country), the transaction is not guessed at. It comes back as WAITING_FOR_YOU with reason: NEEDS_INFO and waits. Subscribe a webhook to invoice.status_changed with statuses: ["WAITING_FOR_YOU"] to hear about it (Webhooks), list what is parked with GET /v1/fr/transactions/needs-info, and resupply the field with PATCH /v1/fr/transactions/needs-info/{id}. Alternatively resubmit the same invoice complete. Resolve it before the period's deadline. Details: Needs-info handling.
Step 3 — Watch the period
Transactions are grouped into periods, one batch per direction (sales are Issued, purchases Received). List them:
curl "https://api.clearvo.io/v1/reporting-batches?status=ready_for_review" \
-H "x-api-key: csk_live_..."
While a period is open it keeps filling and cannot be confirmed. When it ends it freezes as ready_for_review and the reporting_batch.ready_for_review webhook fires once. Reminders (reporting_batch.deadline_approaching, deadline_passed, overdue_reminder) follow; they never file. See Period lifecycle.
Step 4 — Review and confirm
Read the batch, check the totals, exclude any record that does not belong (it moves to the next batch), then confirm exactly the version you read:
# 1. Read the batch and note its snapshotVersion
curl https://api.clearvo.io/v1/reporting-batches/{id} -H "x-api-key: csk_live_..."
# 2. Confirm exactly that version
curl -X POST https://api.clearvo.io/v1/reporting-batches/{id}/confirm \
-H "x-api-key: csk_live_..." \
-H "Content-Type: application/json" \
-d '{ "snapshotVersion": 3 }'
A 409 BATCH_STALE means something changed since you read it: read again and confirm the new version. 409 BATCH_STILL_OPEN means the period has not ended. If you would rather not confirm each period, submissionMode: "batch_auto" files automatically the day before the deadline; it is an explicit opt-in in set-up.
Step 5 — Handle the outcome
After you confirm, the batch is submitted and then filed once the platform answers. A rejected period shows needsAttention: correct the cause and resubmit the period as a whole. A needsAttention.code of TRANSPORT_HELD means some invoice-level rows are held back until the partner platform confirms how it accepts them; the rest of the period is filed normally (France).
Step 6 — Corrections and audit export
Never edit a reported transaction. Send a credit_note or debit_note as a new transaction with its own number and originalInvoiceRef; it nets into the period of its own date. To pull a full period of rows for audit, use GET /v1/fr/transactions/export (CSV or NDJSON; add mandate or country for another regime). See Export.
What's next
- Every field, status and regime: E-Reporting
- Issuing e-invoices as well: Integrate E-Invoicing
- Spain and Portugal: Spain, Portugal