# Fiscomm API

> Fiscalization API for Serbia (fiscal receipts via the Tax Administration, PURS/SUF). You send order data and get back a fiscal receipt — number (PFR), QR, PDF and a verification link. No physical device. Base URL for both test and production: https://api.fiscomm.rs (the account you authenticate as — a demo account or your production account — decides the environment (same host and API for both)). Auth is a Bearer API key bound to a single shop.

## Getting started
- [Full guide (single file)](https://api.fiscomm.rs/llms-full.txt): Everything below inlined — auth, first receipt, errors, idempotency, sandbox vs production, in one file.
- [Authentication](https://fiscomm.rs/za-programere/dokumentacija/autentikacija/): Bearer API key per shop; verify with POST /auth/verify-api-token or GET /auth/api-key/me.
- [Demo account vs production account](https://fiscomm.rs/za-programere/dokumentacija/#environments): Same host and API; the account's certificate decides everything — a demo account uses a test certificate (sandbox, non-fiscal receipts, test tax labels), a production account uses your real certificate.
- [Training receipts](https://fiscomm.rs/za-programere/dokumentacija/#training): `invoiceType=training` issues a non-fiscal test receipt on any account; use `normal` on a production account for real receipts.

## Core concepts
- [Tax labels](https://fiscomm.rs/za-programere/dokumentacija/#tax-rates): Never hardcode; pull from GET /receipt/tax-rates. Labels/rates differ per shop and between sandbox and production.
- [Idempotency & lost responses](https://fiscomm.rs/za-programere/dokumentacija/#idempotency): `orderNumber` unique per shop+company+type (~14 days); resend with `settings.returnIfOrderNumberExists=true`; verify via fiscalization-lookup.
- [Response shape](https://fiscomm.rs/za-programere/dokumentacija/#response): `{correlationId, receipt}`; correlationId is per request (absent in bulk); the QR image (`qrCodeFileUrl`) is only in the archive, not the issue response.

## Endpoints
- [Issue a receipt](https://api.fiscomm.rs/docs#tag/receipt): POST /receipt/{invoiceType}/sale | /refund (invoiceType: normal|training|advance|proforma|copy).
- [Advance chain](https://api.fiscomm.rs/docs#tag/receipt): POST /receipt/advance/finalize (creates ADVANCE/REFUND + NORMAL/SALE).
- [Full refund](https://api.fiscomm.rs/docs#tag/receipt): POST /receipt/{invoiceNumber}/refund/full (needs orderNumber + items + buyerId).
- [Bulk](https://api.fiscomm.rs/docs#tag/receipt): POST /receipt/{invoiceType}/{transactionType}/bulk (up to 30; one bulk per shop at a time).
- [Async + webhook](https://api.fiscomm.rs/docs#tag/receipt): POST /receipt/{invoiceType}/{transactionType}/async.
- [Tax rates](https://api.fiscomm.rs/docs#tag/receipt): GET /receipt/tax-rates.
- [Drafts](https://api.fiscomm.rs/docs#tag/receipt): POST/GET/PUT/DELETE /receipt/drafts[/{id}] (create requires `draftName`).
- [Send by email](https://api.fiscomm.rs/docs#tag/receipt): POST /receipt/send-email → {success, correlationId}.
- [Archive](https://api.fiscomm.rs/docs#tag/archive): GET /archive/receipts, GET /archive/receipts/{invoiceNumber}, POST /archive/receipts/fiscalization-lookup.
- [Auth](https://api.fiscomm.rs/docs#tag/auth): POST /auth/verify-api-token, GET /auth/api-key/me.

## Errors
- [Error catalog](https://fiscomm.rs/za-programere/dokumentacija/#errors): Every error is `{status, code, message, userMessage?, details?, correlationId}`. Codes: ERR_00202 validation, ERR_00701 items≠payments, ERR_01010 rejected by the Tax Administration, ERR_00101 invalid key, ERR_00002 internal. Always send `correlationId` to support.

## SDKs
- [TypeScript SDK](https://github.com/Fiscomm/fiscomm-sdk-ts): `npm install github:Fiscomm/fiscomm-sdk-ts`.
- [PHP SDK](https://github.com/Fiscomm/fiscomm-sdk-php): `composer require fiscomm/sdk:dev-main`.

## Reference
- [OpenAPI spec (machine-readable)](https://api.fiscomm.rs/openapi.json): Full schema; `npx api install https://api.fiscomm.rs/openapi.json`.
- [Interactive API reference](https://api.fiscomm.rs/docs): Rendered endpoints with request/response schemas.
- Support: podrska@fiscomm.rs