New France e-invoicing mandate goes live September 2026 — our implementation is ready. See all mandates →
Integration Guide

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.

⚠
Filing is never automatic by default. Clearvo accumulates the period, tells you when it is ready and files it only when you confirm it. If the deadline passes before you confirm, nothing is filed.
Integration Guide

Prerequisites

Integration Guide

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
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 } ]
  }'
JSON Response — 200 ACCUMULATED
{
  "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.

Integration Guide

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.

Integration Guide

Step 3 — Watch the period

Transactions are grouped into periods, one batch per direction (sales are Issued, purchases Received). List them:

curl
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.

Integration Guide

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:

curl
# 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.

Integration Guide

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).

Integration Guide

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.

Integration Guide

What's next