Custom Integration: API Reference

This is the endpoint reference for the FiscoBridge POS API, used by Custom Integrations to fiscalize invoices directly from your own software. For error responses and tax authority error codes, see API Errors and Error Codes.

Base URL and Authentication

https://pos.fiscobridge.com

Authenticate every request with the X-Api-Key header, using the Client ID and Client Secret from your Custom Integration (see Managing API Keys):

X-Api-Key: {clientId}:{clientSecret}

Each API key is bound to one certificate — invoices are signed with that certificate automatically. You cannot select a different certificate per request; to fiscalize for another company, create a Custom Integration (and key) for its certificate.

A missing, malformed, or revoked key — or a key whose certificate has been revoked — returns 401 Unauthorized.

Endpoints

Creating an Invoice

POST /api/invoices with a JSON body wrapping an invoiceRequest:

{
  "invoiceRequest": {
    "invoiceType": "Normal",
    "transactionType": "Sale",
    "cashier": "Maria",
    "buyerId": "123456789",
    "payment": [
      { "amount": 112.00, "paymentType": "Cash" }
    ],
    "items": [
      {
        "name": "Room service",
        "quantity": 2,
        "unitPrice": 56.00,
        "totalAmount": 112.00,
        "labels": ["A"]
      }
    ]
  }
}

invoiceRequest fields

payment[] fields

items[] fields

Success response

{
  "invoiceNumber": "ABC1234-XY7Z9Q8W-12345",
  "invoiceCounter": "12345/67890NS",
  "sdcDateTime": "2026-07-09T02:15:33Z",
  "totalAmount": 112.00,
  "verificationUrl": "https://vsdc.../v/?vl=...",
  "verificationQRCode": "R0lGODlh...",
  "journal": "        =========== FISCAL INVOICE ===========\n ...",
  "signedBy": "ABC1234",
  "signature": "...",
  "requestId": "your-request-id"
}

• verificationUrl — the public tax authority verification link (this is what the receipt QR code points to)
• verificationQRCode — the QR code as a base64-encoded GIF image, ready to print on the receipt (at least 42×42 mm)
• journal — the plain-text fiscal receipt
• totalAmount is negative for refunds and cancellations

Note: verificationQRCode and journal are returned on create/refund/cancel/copy and by the journal endpoint — they are not included in GET invoice lookups. Store them, or re-fetch via /api/invoices/{invoiceNumber}/journal.

Refund, Cancel, Copy

All three mint a new fiscal document referencing the original, and are only allowed for invoices with status Signed:

• POST /api/invoices/{invoiceNumber}/cancel — full reversal; the original's status becomes Cancelled
• POST /api/invoices/{invoiceNumber}/refund — optional body { "items": [...], "payment": [...] } for a partial refund; omit the body (or send {}) for a full refund. The original's status becomes Refunded
• POST /api/invoices/{invoiceNumber}/copy — issues a fiscal copy (invoiceType: Copy), no body

Each returns the same signed-invoice response shape as create.

Listing and Reading Invoices

GET /api/invoices supports query parameters: status, from, to, sourceFilter (pos or integration), page (default 1), pageSize (default 50), plus taxpayerId, locationId, certificateId filters. Results are newest-first and include invoiceNumber, invoiceCounter, sdcDateTime, totalAmount, invoiceType, transactionType, status, verificationUrl, externalInvoiceId, and source.

The response body is a plain array holding one page only — it is not the full result set. The X-Total-Count response header carries the total number of invoices matching your filters, so keep requesting page=2, page=3, … until you have read X-Total-Count records.

pageSize must be 1000 or less; a larger value is rejected with 400 Bad Request. Page through the result set rather than requesting it in one call.

GET /api/invoices/daily-report?fromDate=...&toDate=... returns per-type invoice counts and total sale/refund amounts. The range must be at most 62 days, and invoiceType/transactionType filters are accepted. Cancelled invoices are excluded.

GET /api/invoices/{invoiceNumber}/journal re-fetches { "journal": "...", "verificationQRCode": "..." } for a signed invoice from the tax authority's verification page. This calls an external service and can occasionally be slow or return empty fields — retry later if so.

Status and Tax Rates

GET /api/status returns the SDC status for your key's certificate, including the authoritative list of valid tax labels and rates — always read them from here rather than hardcoding, since rates can change. GET /api/status/environment-parameters returns your organization details and environment URLs; GET /api/status/attention returns any current tax authority notices.

Rate Limits and Quotas

• 180 requests per minute per IP — exceeding it returns 429 Too Many Requests
• Your plan's monthly invoice allowance applies — exceeding it returns 402 Payment Required (see Invoice Limits and Usage)

Conventions and Gotchas

• JSON property names are camelCase; dates are ISO 8601 and returned in UTC
• Enum fields accept either the name ("Cash") or the number (1) on input; responses return enum names as strings
• requestId is not an idempotency key — implement your own duplicate protection before retrying a create
• Amounts with more than 2 decimal places are rejected by the tax authority (error code 2804)
• Any invoiceNumber or certificateId you send in a create request body is ignored — the fiscal number is assigned by the tax authority and the certificate comes from your API key
• Use invoiceType: "Training" for end-to-end testing — training receipts are marked "NOT A FISCAL INVOICE" (but still count toward your monthly allowance)

Enums

invoiceType

transactionType

paymentType

status (in invoice lookups)

Next Steps

• API errors and error codes — HTTP statuses, error shapes, and all tax authority validation codes
• Custom Integration — Creating the integration and managing API keys
• Invoice types and transaction types — Which combinations are valid and when to use each