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.
- Authority credentials: the one-time registration some countries need
- Country set-up details: Poland, Portugal, France, Mexico and Italy
- Entity defaults: invoice format and Peppol ID
- Reporting obligations: enabling and configuring e-reporting
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.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.
| Country | Authority / what is registered | Endpoint |
|---|---|---|
| Argentina | AFIP | /v1/ar/credentials |
| Brazil | e-CNPJ A1 certificate (also PATCH /v1/br/settings) | /v1/br/credentials |
| Egypt | ETA | /v1/eg/credentials |
| France | Tax number and platform connection | /v1/fr/credentials, /v1/fr/platform-connect-link |
| Greece | AADE myDATA | /v1/gr/credentials |
| Hungary | NAV Online Számla | /v1/hu/credentials |
| Israel | ITA | /v1/il/credentials |
| Italy | Regime Fiscale (a profile field, not a credential) | PUT /v1/it/profile |
| Jordan | JoFotara | /v1/jo/credentials |
| Malaysia | MyInvois intermediary authorisation | /v1/my/credentials |
| Mexico | SAT e.firma (only for sat_pull receiving) | /v1/mx/credentials |
| Poland | KSeF token | /v1/pl/credentials |
| Portugal | AT series and webservice sub-user | /v1/pt/credentials |
| Romania | ANAF 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.
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:
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.
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.
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:
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.state | Meaning |
|---|---|
not_connected | No link has been completed yet. |
pending_verification | The customer has connected; the identity or company check is not finished. |
active | Connected and verified. |
needs_reconnect | The authorisation lapsed or was withdrawn. Create a new link and have the customer connect again. |
failed | The 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.
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.
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.
| Default | Where it is set | What it does |
|---|---|---|
defaultDeInvoiceFormat | PATCH /v1/entities/{{id}} | Germany: ZUGFERD (platform default), XRECHNUNG or PEPPOL. A request overrides it with countrySpecific.de.invoiceFormat; see Germany. |
| Peppol participant ID | Dashboard, or the entity record | Needed to send over the Peppol network. Without a confirmed ID the invoice waits as WAITING_FOR_YOU with MISSING_SELLER_PEPPOL_ID. |
| Customer references | references 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. |
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 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" }
}
}'
| Field | Values | Description |
|---|---|---|
enabled | boolean | Enabling requires effectiveFrom. Disabling never requires it and is never gated on registration. |
effectiveFrom | ISO date | The 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. |
submissionMode | immediate | batch_auto | batch_review | Defaults 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. |
vatRegime | regime-specific | France only; see below. |
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.
| Value | Meaning |
|---|---|
reel_normal_mensuel | Régime réel normal, monthly VAT returns. |
reel_normal_trimestriel | Régime réel normal, quarterly VAT returns. |
reel_simplifie | Régime réel simplifié. |
franchise_en_base | VAT 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.