TicketBAI

Configure and inspect TicketBAI fiscalization for explicitly selected Basque territories.

The TicketBAI object

object

Attributes

idstring

Other attributes

document_idstring

sequenceinteger

previous_record_idstringnullable

source_record_idstringnullable

identifierstring

qr_urlstringnullable

cancellation_reasonstringnullable

xml_sha256string

authority_codesarray of strings

authority_receiptstringnullable

retryableboolean

created_atstring

updated_atstring

Upload TicketBAI signing and submission certificate

POST/fiscalization/ticketbai/settings/certificate

Requires an account API key or an account owner/admin session; entity-scoped keys cannot upload certificates. Upload a P12/PFX certificate and matching private key, at most 1 MiB. The private key is encrypted at rest. Uploading does not establish taxpayer representation or activate fiscalization.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Body parameters

filestring<binary>required

File to upload

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
import fs from 'fs';

const sdk = new SpaceInvoices('YOUR_API_KEY');

// Read file as Buffer
const fileBuffer = fs.readFileSync('/path/to/certificate.p12');
const file = new File([fileBuffer], 'certificate.p12', { type: 'application/x-pkcs12' });

const response = await sdk.ticketBai.uploadCertificate({
  file,
  passphrase: "cert-password"
}, { entity_id: 'YOUR_ENTITY_ID' });

console.log(response);

Response

Returns

certificate_expirystring

json

{
  "certificate_expiry": "certificate-expiry"
}

Get TicketBAI setup and readiness

GET/fiscalization/ticketbai/settings

Returns setup requirements for the selected entity. Readiness does not certify authority acceptance. Certificate material and producer credentials are never returned.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.ticketBai.getSettings({
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

Returns

enabledboolean

authorization_confirmedboolean

readyboolean

blockersarray of strings

certificate_expirystringnullable

has_issued_recordsboolean

json

{
  "enabled": true,
  "territory": "alava",
  "environment": "sandbox",
  "lroe_model": "140",
  "lroe_individual": {
    "given_name": "given-name",
    "surname1": "surname1",
    "surname2": "surname2"
  },
  "authorization_confirmed": true,
  "ready": true,
  "blockers": [
    "territory_required"
  ],
  "certificate_expiry": "certificate-expiry",
  "has_issued_records": true
}

Get TicketBAI delivery state and recent attempts

GET/fiscalization/ticketbai/records/{id}

Get TicketBAI delivery state and recent attempts

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstringrequired

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.ticketBai.getRecord('TICKETBAI_ID', {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

Returns

idstring

Other parameters

document_idstring

sequenceinteger

previous_record_idstringnullable

source_record_idstringnullable

identifierstring

qr_urlstringnullable

cancellation_reasonstringnullable

xml_sha256string

authority_codesarray of strings

authority_receiptstringnullable

retryableboolean

created_atstring

updated_atstring

json

{
  "id": "id",
  "document_id": "document-id",
  "document_type": "invoice",
  "operation": "issue",
  "territory": "alava",
  "environment": "sandbox",
  "sequence": 0,
  "previous_record_id": "previous-record-id",
  "source_record_id": "source-record-id",
  "identifier": "identifier",
  "qr_url": "https://example.com",
  "cancellation_reason": "cancellation-reason",
  "xml_sha256": "xml-sha256",
  "status": "pending",
  "authority_codes": [
    "authority-codes"
  ],
  "authority_receipt": "authority-receipt",
  "authority_record_state": "authority-record-state",
  "manual_resolution": {
    "outcome": "accepted",
    "evidence_sha256": "evidence-sha256",
    "resolved_at": "resolved-at"
  },
  "last_query": {
    "result": "found",
    "record_state": "record-state",
    "codes": [
      "codes"
    ],
    "queried_at": "queried-at"
  },
  "attempt_count": 0,
  "retryable": true,
  "created_at": "created-at",
  "updated_at": "updated-at",
  "recent_attempts": [
    {
      "id": "id",
      "kind": "submission",
      "status": "pending",
      "http_status": 0,
      "codes": [
        "codes"
      ],
      "started_at": "started-at",
      "finished_at": "finished-at"
    }
  ]
}

Prepare or activate TicketBAI

PUT/fiscalization/ticketbai/settings

Prepare disabled settings before supplying credentials. Activation requires an authorized certificate, deployment configuration and pilot access. Omitted or null enabled, territory and authorization fields preserve their values. The lroe_model and lroe_individual settings can be cleared with null. Taxpayer identity, territory, environment and ledger model freeze after the first issuance.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Body parameters

enabledbooleanoptionalnullable

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.ticketBai.updateSettings({
  enabled: true,
  territory: "alava",
  lroe_model: "140",
  lroe_individual: {
    given_name: "given-name",
    surname1: "surname1",
    surname2: "surname2"
  },
  authorization_confirmed: true
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

Returns

enabledboolean

authorization_confirmedboolean

readyboolean

blockersarray of strings

certificate_expirystringnullable

has_issued_recordsboolean

json

{
  "enabled": true,
  "territory": "alava",
  "environment": "sandbox",
  "lroe_model": "140",
  "lroe_individual": {
    "given_name": "given-name",
    "surname1": "surname1",
    "surname2": "surname2"
  },
  "authorization_confirmed": true,
  "ready": true,
  "blockers": [
    "territory_required"
  ],
  "certificate_expiry": "certificate-expiry",
  "has_issued_records": true
}

Download the original signed TicketBAI XML

GET/fiscalization/ticketbai/records/{id}/xml

Returns the exact stored signed bytes. Delivery attempts never regenerate this artifact.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstringrequired

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const blob = await sdk.ticketBai.downloadRecordXml('TICKETBAI_ID', {
  entity_id: "YOUR_ENTITY_ID"
});

const arrayBuffer = await blob.arrayBuffer();
const { writeFile } = await import('node:fs/promises');
await writeFile('download.bin', Buffer.from(arrayBuffer));
console.log('Saved download.bin');

Retry a safely retryable TicketBAI delivery

POST/fiscalization/ticketbai/records/{id}/retry

No request body. Resends stored bytes only for pending records or an explicit Álava/Gipuzkoa service-unavailable rejection (006). Unknown, accepted and other rejected outcomes return 409. A preceding unresolved record keeps this record pending.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstringrequired

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.ticketBai.retryRecord('TICKETBAI_ID', {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

Returns

idstring

Other parameters

document_idstring

sequenceinteger

previous_record_idstringnullable

source_record_idstringnullable

identifierstring

qr_urlstringnullable

cancellation_reasonstringnullable

xml_sha256string

authority_codesarray of strings

authority_receiptstringnullable

retryableboolean

created_atstring

updated_atstring

json

{
  "id": "id",
  "document_id": "document-id",
  "document_type": "invoice",
  "operation": "issue",
  "territory": "alava",
  "environment": "sandbox",
  "sequence": 0,
  "previous_record_id": "previous-record-id",
  "source_record_id": "source-record-id",
  "identifier": "identifier",
  "qr_url": "https://example.com",
  "cancellation_reason": "cancellation-reason",
  "xml_sha256": "xml-sha256",
  "status": "pending",
  "authority_codes": [
    "authority-codes"
  ],
  "authority_receipt": "authority-receipt",
  "authority_record_state": "authority-record-state",
  "manual_resolution": {
    "outcome": "accepted",
    "evidence_sha256": "evidence-sha256",
    "resolved_at": "resolved-at"
  },
  "last_query": {
    "result": "found",
    "record_state": "record-state",
    "codes": [
      "codes"
    ],
    "queried_at": "queried-at"
  },
  "attempt_count": 0,
  "retryable": true,
  "created_at": "created-at",
  "updated_at": "updated-at",
  "recent_attempts": [
    {
      "id": "id",
      "kind": "submission",
      "status": "pending",
      "http_status": 0,
      "codes": [
        "codes"
      ],
      "started_at": "started-at",
      "finished_at": "finished-at"
    }
  ]
}

Query the authority to reconcile TicketBAI delivery

POST/fiscalization/ticketbai/records/{id}/reconcile

No request body. Correlates issuer, invoice identity, signature and amount with the authority record. An absent result leaves delivery unresolved and never authorizes a resend. Álava queries reflect a daily refreshed view. Gipuzkoa production queries remain unavailable until the endpoint is verified. Query evidence is recorded separately from submission attempts.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstringrequired

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.ticketBai.reconcileRecord('TICKETBAI_ID', {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

Returns

idstring

Other parameters

document_idstring

sequenceinteger

previous_record_idstringnullable

source_record_idstringnullable

identifierstring

qr_urlstringnullable

cancellation_reasonstringnullable

xml_sha256string

authority_codesarray of strings

authority_receiptstringnullable

retryableboolean

created_atstring

updated_atstring

json

{
  "id": "id",
  "document_id": "document-id",
  "document_type": "invoice",
  "operation": "issue",
  "territory": "alava",
  "environment": "sandbox",
  "sequence": 0,
  "previous_record_id": "previous-record-id",
  "source_record_id": "source-record-id",
  "identifier": "identifier",
  "qr_url": "https://example.com",
  "cancellation_reason": "cancellation-reason",
  "xml_sha256": "xml-sha256",
  "status": "pending",
  "authority_codes": [
    "authority-codes"
  ],
  "authority_receipt": "authority-receipt",
  "authority_record_state": "authority-record-state",
  "manual_resolution": {
    "outcome": "accepted",
    "evidence_sha256": "evidence-sha256",
    "resolved_at": "resolved-at"
  },
  "last_query": {
    "result": "found",
    "record_state": "record-state",
    "codes": [
      "codes"
    ],
    "queried_at": "queried-at"
  },
  "attempt_count": 0,
  "retryable": true,
  "created_at": "created-at",
  "updated_at": "updated-at",
  "recent_attempts": [
    {
      "id": "id",
      "kind": "submission",
      "status": "pending",
      "http_status": 0,
      "codes": [
        "codes"
      ],
      "started_at": "started-at",
      "finished_at": "finished-at"
    }
  ]
}