Skip to main content
POST
/
fiscal-portal-credentials
/
{credentialId}
/
validate
Validate credentials against the government portal
curl --request POST \
  --url https://api.openfiskal.com/v1/fiscal-portal-credentials/{credentialId}/validate \
  --header 'Authorization: Bearer <token>'
{
  "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.

Headers

​
OpenFiskal-Organization
string

Merchant organization ID. Required for platform integrators acting on behalf of a specific merchant. Omit when using an organization-scoped API key directly.

Path Parameters

​
credentialId
string
required

Response

Validation attempt completed (check state for outcome)

​
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>