Skip to main content
POST
/
organizations
/
{organizationId}
/
fiscal-portal-credentials
Provision portal credentials
curl --request POST \
  --url https://api.openfiskal.com/v1/organizations/{organizationId}/fiscal-portal-credentials \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "portal_type": "fisconline",
  "jurisdiction": "IT",
  "credentials": {
    "type": "<string>",
    "tax_id_number": "RSSMRA80A01H501U",
    "pin": "1234567890",
    "password": "<string>"
  },
  "label": "Acme S.r.l. – Fisconline"
}
'
{
  "id": "fpc_01HXYZ",
  "object": "<string>",
  "organization_id": "<string>",
  "portal_type": "fisconline",
  "jurisdiction": "IT",
  "state": "unvalidated",
  "created_at": "2023-11-07T05:31:56Z",
  "label": "<string>",
  "masked_credentials": {
    "tax_id_number": "RSSMRA80A01H501U",
    "participant_id": "1234567",
    "user_id": "user001",
    "pin": "****0",
    "password": "***********"
  },
  "expires_at": "2023-11-07T05:31:56Z",
  "last_validated_at": "2023-11-07T05:31:56Z",
  "validation_error": "PIN or password incorrect (AdE error code: 401)",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Platform API key sent as Authorization: Bearer ofk_platform_.... Platform integrators also pass OpenFiskal-Organization: org_xxx to act on behalf of a merchant.

Path Parameters

​
organizationId
string
required

Body

application/json
​
portal_type
enum<string>
required

Identifies the government portal and determines the expected credential shape.

  • fisconline — Italian AdE portal for natural persons and businesses. Used for RT commercial document transmission.
  • entratel — Italian AdE portal for accountants and large corporate filers. Functionally similar to Fisconline but separate authentication system.
  • finanz_online — Austrian BMF portal. Required for RKSV registration, TSE certificate management, and annual transmission reports.
Available options:
fisconline,
entratel,
finanz_online
​
jurisdiction
enum<string>
required

ISO 3166-1 alpha-2 country code

Available options:
IT,
AT
Example:

"IT"

​
credentials
object
required

Portal-specific credential fields. Shape is determined by portal_type. All values are stored encrypted and never returned after creation.

​
label
string | null

Optional human-readable label for internal reference

Example:

"Acme S.r.l. – Fisconline"

Response

Credentials provisioned

​
id
string
required
Example:

"fpc_01HXYZ"

​
object
string
required
Allowed value: "fiscal_portal_credential"
​
organization_id
string
required
​
portal_type
enum<string>
required
Available options:
fisconline,
entratel,
finanz_online
​
jurisdiction
enum<string>
required
Available options:
IT,
AT
​
state
enum<string>
required

Lifecycle state of the credentials.

  • unvalidated — provisioned but not yet tested against the portal. Fiscal transmission will be attempted but may fail.
  • valid — last validation succeeded. Credentials are working.
  • expiring_soon — credentials are valid but the password expiry is within the warning window (14 days for Fisconline/Entratel, 30 days for FinanzOnline). Renew at the government portal and rotate via PATCH.
  • expired — password has passed its expiry date. Fiscal transmission is blocked. Merchant must renew at the portal and rotate via PATCH.
  • invalid — last validation failed (wrong credentials, account locked, or portal-side issue). Transmission blocked. Investigate via validation_error.
Available options:
unvalidated,
valid,
expiring_soon,
expired,
invalid
​
created_at
string<date-time>
required
​
label
string | null
​
masked_credentials
object

Masked representations of the stored credential fields. Never contains raw secret values. Useful for confirming which values are on file without requiring re-entry.

​
expires_at
string<date-time> | null

Projected credential expiry date, calculated from the last validation timestamp and the known rotation period for this portal type (Fisconline/Entratel: 60 days; FinanzOnline: 365 days). null if the credential has never been validated.

​
last_validated_at
string<date-time> | null

Timestamp of the most recent successful validation attempt against the government portal.

​
validation_error
string | null

Human-readable error message from the last failed validation attempt. null if the last validation succeeded.

Example:

"PIN or password incorrect (AdE error code: 401)"

​
updated_at
string<date-time>