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

Setup & master data

Everything on this page is done once per entity, not per transaction: registering authority credentials, setting the entity's defaults and enabling reporting obligations. Most customers do it in the dashboard or through the MCP server and never touch these endpoints; they are listed here so an automated onboarding flow can do the same.

The day-to-day integration is only the transaction endpoints: send an invoice, track its status and, for reporting regimes, review and confirm a period.

ℹ
Use an entity-scoped API key (csk_live_* or csk_test_*) for every write on this page. With an organisation-scoped key, pass the entity in the x-entity-id header.
Setup

Authority credentials

Some authorities need a credential that belongs to your entity. Register it once; after that every send to that country uses it. Every route supports POST (register or update), GET (read back, secrets are never returned) and DELETE. The same operations exist as MCP tools (set_pl_credentials and so on) and in the dashboard.

CountryAuthority / what is registeredEndpoint
ArgentinaAFIP/v1/ar/credentials
Brazile-CNPJ A1 certificate (also PATCH /v1/br/settings)/v1/br/credentials
EgyptETA/v1/eg/credentials
FranceTax number and platform connection/v1/fr/credentials, /v1/fr/platform-connect-link
GreeceAADE myDATA/v1/gr/credentials
HungaryNAV Online Számla/v1/hu/credentials
IsraelITA/v1/il/credentials
ItalyRegime Fiscale (a profile field, not a credential)PUT /v1/it/profile
JordanJoFotara/v1/jo/credentials
MalaysiaMyInvois intermediary authorisation/v1/my/credentials
MexicoSAT e.firma (only for sat_pull receiving)/v1/mx/credentials
PolandKSeF token/v1/pl/credentials
PortugalAT series and webservice sub-user/v1/pt/credentials
RomaniaANAF e-Factura/v1/ro/credentials

Countries not in this table need no credential of their own: your API key and the entity's registered tax number are enough. A send to a country that does need one is stopped with a clear error naming the missing credential.

Field-level request and response shapes are in the API reference.

Setup

Country set-up details

Poland (KSeF)

Poland needs a per-entity KSeF token. Generate it in the KSeF Taxpayer Portal (Zarządzanie tokenami) with both the sending (Wysyłka faktur) and the invoice access (Dostęp do faktur) permissions; the token is shown once. Register it with Clearvo here or on the setup page:

HTTP
POST https://api.clearvo.io/v1/pl/credentials
x-api-key: csk_live_••••••••
Content-Type: application/json

{
  "nip":         "1234567890",
  "token":       "<token from ksef.mf.gov.pl>",
  "environment": "production"
}

The NIP in supplier.taxId on every invoice must match the NIP registered here, otherwise the invoice is rejected with NIP_MISMATCH before KSeF is contacted.

Portugal (AT)

Call POST /v1/pt/credentials once per entity with your nif plus one of two options.

Option A: Clearvo registers the series. In Portal das Finanças create a webservice sub-user (Gestão de Utilizadores) with the WFA (invoice-data communication) and WSE (series communication) permissions and send it as NIF/n with its password. Clearvo registers one FT, NC and ND series for you.

HTTP
POST /v1/pt/credentials
x-api-key: csk_live_••••••••
x-entity-id: ent_•••• (organisation keys only)
Content-Type: application/json

{
  "nif":      "500000000",
  "subUser":  "500000000/1",
  "password": "••••••••"
}

Option B: use series you already hold. Send each series and the ATCUD validation code AT issued for it (Portal das Finanças → Faturação → Séries). Each document type you issue needs its own series.

HTTP
POST /v1/pt/credentials
x-api-key: csk_live_••••••••
Content-Type: application/json

{
  "nif":                      "500000000",
  "invoiceSeries":            "A2026",
  "invoiceValidationCode":    "AAJFJ7X5",
  "creditNoteSeries":         "NC2026",
  "creditNoteValidationCode": "BBKGK8Y6"
}

GET /v1/pt/credentials returns the stored series and validation codes (they print on every document); the password is never returned. Then enable the pt_efatura obligation (see Reporting obligations) so every document is communicated to AT automatically.

France

France has no secret to store. Register the entity's French VAT number with POST /v1/fr/credentials (the check digits are verified immediately), then have the customer connect its company once on the secure page of our French e-invoicing partner. The customer signs in with an emailed code, picks its legal representative, confirms the agreement and completes a short identity check. When you have no dashboard to send the customer to, create the link from the API:

HTTP
POST /v1/fr/platform-connect-link
x-api-key: csk_live_••••••••
x-entity-id: ent_•••• (organisation keys only)
Content-Type: application/json

{
  "returnUrl": "https://app.example.com/settings/france/return",
  "loginHint": "director@customer.example",
  "requestedCapability": "both"
}

The link is single use. The customer is sent back to your returnUrl with status=ok or status=error (and a reason where useful). Read platformConnection.state on GET /v1/fr/credentials to see where the connection stands:

platformConnection.stateMeaning
not_connectedNo link has been completed yet.
pending_verificationThe customer has connected; the identity or company check is not finished.
activeConnected and verified.
needs_reconnectThe authorisation lapsed or was withdrawn. Create a new link and have the customer connect again.
failedThe check was refused, or the customer connected a company other than the one registered (company_verification_failed or company_mismatch). Nothing is stored for a mismatch.

Use requestedCapability: "receive" for a customer that only receives invoices. A company without a French establishment cannot be connected this way: POST /v1/fr/platform-connect-link answers 409 FR_TAX_NUMBER_REQUIRED until a valid French tax number is registered.

Mexico (receiving)

Mexico is receive-only. Choose the ingestion mode per entity with PATCH /v1/entities/{id} and its mxIngestionMode field: sat_pull (default; Clearvo polls SAT on your behalf with the entity's e.firma) or client_push (your own system pushes each CFDI; no credential needed). For sat_pull the entity needs a registered Mexico tax registration (RFC) first; the e.firma's certificate RFC is cross-checked against it.

HTTP
POST https://api.clearvo.io/v1/mx/credentials
x-api-key: csk_live_••••••••
Content-Type: application/json

{
  "certificateBase64": "<base64 .cer, issued by SAT>",
  "keyBase64":         "<base64 .key, PKCS#8>",
  "password":          "<e.firma password>"
}

Day-to-day use of Mexico receiving is described in Country fields and behaviour.

Italy

Clearvo is the accredited intermediary for Italy, so there is no credential to register. The entity needs its Regime Fiscale set once with PUT /v1/it/profile; GET /v1/it/profile returns the current value and the list of valid codes. A send to Italy without it is stopped.

Setup

Entity defaults

Defaults that apply to every send for the entity, so individual requests do not have to repeat them. A value on the request always wins over the customer's stored default, which wins over the entity default.

DefaultWhere it is setWhat it does
defaultDeInvoiceFormatPATCH /v1/entities/{{id}}Germany: ZUGFERD (platform default), XRECHNUNG or PEPPOL. A request overrides it with countrySpecific.de.invoiceFormat; see Germany.
Peppol participant IDDashboard, or the entity recordNeeded to send over the Peppol network. Without a confirmed ID the invoice waits as WAITING_FOR_YOU with MISSING_SELLER_PEPPOL_ID.
Customer referencesreferences on POST /v1/customers, PATCH /v1/customers/{{id}}Identifiers that are not tax numbers (PEPPOL_PARTICIPANT_ID, LEITWEG_ID). GET /v1/customer-reference-types?country=DE lists the types and which countries each applies to.
Setup

Reporting obligations

A reporting obligation switches an e-reporting regime on for an entity. Obligations are user-enabled with an explicit start date; Clearvo never derives them from your registrations or invoice data. Regime codes: es_sii (Spain), fr_ereporting (France), pt_efatura (Portugal). How a regime works once enabled is on the E-Reporting page.

GET /v1/tax/reporting-obligations lists the current state; PATCH enables or changes it.

cURL — Enable an obligation
curl https://api.clearvo.io/v1/tax/reporting-obligations \
  -X PATCH \
  -H "x-api-key: csk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "obligations": {
      "es_sii": { "enabled": true, "effectiveFrom": "2026-01-01", "submissionMode": "batch_review" }
    }
  }'
FieldValuesDescription
enabledbooleanEnabling requires effectiveFrom. Disabling never requires it and is never gated on registration.
effectiveFromISO dateThe date the obligation starts applying. Required to enable. A date earlier than the legal start date for your size is accepted with a warning, not blocked.
submissionModeimmediate | batch_auto | batch_reviewDefaults to batch_review on first enable. batch_review: a period is filed only when you confirm it. batch_auto: an unconfirmed period is filed the day before its deadline. immediate (where the regime allows it) sends each transaction on its own. A change never affects an already-open batch. A mode the regime does not allow is rejected with SUBMISSION_MODE_NOT_ALLOWED.
vatRegimeregime-specificFrance only; see below.
⚠
Enabling a regime requires a current STANDARD tax registration in that country (a French VAT number registered with POST /v1/fr/credentials for fr_ereporting); otherwise the request is rejected with 400 REGISTRATION_REQUIRED and a fixUrl to add one through the Compliance Radar registration endpoint.

France: VAT regime

France needs vatRegime when you enable fr_ereporting. It decides the reporting period and deadline (see E-Reporting: France). You can also set it in the dashboard: the entity's Jurisdictions page, France row, VAT filing regime.

ValueMeaning
reel_normal_mensuelRégime réel normal, monthly VAT returns.
reel_normal_trimestrielRégime réel normal, quarterly VAT returns.
reel_simplifieRégime réel simplifié.
franchise_en_baseVAT exemption threshold scheme (franchise en base de TVA).

Check the entity's French registration at any time with GET /v1/fr/credentials: capabilities.ereporting.status is active, pending_activation or sandbox.