{
"swagger": "2.0",
"info": {
"title": "fiskaly eReceipt backend",
"description": "Imprint: [fiskaly.com/impressum](https://fiskaly.com/impressum) | Privacy Policy: [fiskaly.com/datenschutz](https://fiskaly.com/datenschutz)\n\n# Introduction\n\nThe eReceipt API allows merchants to issue electronic receipts for end users instead of traditional paper based receipts.\n\n## Versioning\n\nThe fiskaly eReceipt backend follows [Semantic Versioning](https://semver.org).\n\nThe version number has a pattern of `MAJOR.MINOR.PATCH`. We increment the\n\n- `MAJOR` version when we make incompatible API changes,\n- `MINOR` version when we add functionality in a backwards-compatible manner, and\n- `PATCH` version when we make backwards-compatible bug fixes.\n\nThe current `MAJOR` version `1` is reflected in the API's base URL: `/api/v1`.\n\n## Idempotent Requests\n\nThe fiskaly eReceipt backend is idempotent. [Idempotence](https://wikipedia.org/wiki/Idempotence) means you can send the same request several times safely. The result will be the same as if you have sent it only once.\n\nFor example, if you request to [sign a Receipt](#operation/signReceipt) but don't receive a response, you can send the request again with the same request body. The receipt is guaranteed to be signed only once.\n\n## UUIDv4\n\nThis API uses [UUIDv4](https://datatracker.ietf.org/doc/html/rfc4122). Some requests create new resources. To run such requests, generate a random UUIDv4. Then pass the UUIDv4 in the request body. This UUIDv4 will be assigned to the newly created resource.\n\nA good way to generate a UUIDv4 is to use a library in your programming language of choice (like [this](https://www.npmjs.com/package/uuid)) or an online generator (like [this](https://www.uuidgenerator.net/version4)). A UUIDv4 created this way will be random and unique throughout the system.\n\n## Request IDs\n\nThe fiskaly eReceipt backend associates a unique identifier with each request. You will find this request identifier in the response headers, under `request-id`.\nIf you need help with a request you have issued, please provide the request identifier. We will find your request and help you faster.\n\n## Metadata\n\nMost resources in the API (e.g. Cash Registers) have a `metadata` property. You can store any additional information in the `metadata`.\n\nYou can specify up to 20 key-value pairs in the `metadata` object. A key can be up to 40 characters long. A value can be up to 500 characters long.\n\n# Changes\n\n## MINOR and PATCH changes\n\n# Processes\n\n## Issuing an electronic receipt\n\nTo issue a receipt, simply use the create receipt operation to get a public link for the end user to access. This public link can be provided as either a QR code\nor whatever other mechanism is available to transfer it to the end user at the Point of Sale.\n\n# Resources\n\n## Receipt\n\nThe receipt is the core resource of the eReceipt API. It is represented in a schema closely resembling the DFKA EKaBS standard schema.\n\nThe receipt resource consists of the following data:\n\n- `schema`: the receipt data modelled as one of the supported schemas (currently only EKaBS)\n- `public_link`: link that can be provided to the end user\n- `assets`: references to static assets (e.g. PDF). Note that those are generated asynchronously and therefore might not be instantly accessible in some cases.\n- `user_association`: a set of properties that can be used to associate a receipt with an end user.\n\n# Errors and Status Codes\n\nThe fiskaly eReceipt backend uses standard [HTTP status codes](https://http.cat/) to indicate the success or failure of requests:\n\n## Status 2xx\n\nStatus codes in the `200-299` range indicate success.\n\n## Status 4xx\n\nStatus codes in the `400-499` range indicate errors that have been caused by the requesting application (e.g., a malformed request body has been sent). \n Retrying such requests with the same request body is pointless and _will_ result in the same status code again.\nSome `4xx` errors can be handled programmatically. The error response is in JSON format and is structured like this:\n\n```\n{\n\"status_code\": 400,\n\"error\": \"Bad Request\",\n\"code\": \"E_SOME_ERROR\",\n\"message\": \"Something bad happened\"\n}\n```\n\nThe response will contain an error code or other information that reveals the reason of the error. Change the request accordingly before retrying. Below you can find the most frequent errors and how to fix them.\n\n### How to handle 4xx errors\n\n\n \n 400 Bad Request\n
\n\n- \n \n \n E_FAILED_SCHEMA_VALIDATION\n \n
\n\n Your request doesn't comply with the defined schema. Fix you request body and parameters according to the error message and run the endpoint again.\n \n \n\n\n \n 401 Unauthorized \n
\n\n- \n \n \n E_AUTHENTICATION\n \n
\n\n The JWT token authentication failed for your request. The error message explains what went wrong. Run the [Authenticate API](/api/v1/_docs/#operation/authenticateApi) enpoint to get a new token and retry your original request.\n \n\n- \n \n \n E_PUBLIC_ACCESS_EXPIRED\n \n
\n\n The public access to this `Receipt` has expired. After the public link to the `Receipt` has expired, it is no longer possible to access it with the [Retrieve receipt (public)](/api/v1/_docs/#operation/retrieveReceiptPublic) endpoint.\n \n \n\n\n \n 404 Not Found \n
\n\n- \n \n \n E_RECEIPT_NOT_FOUND\n \n
\n\n No `Receipt` has been found for the `receipt_id` you used in the request. Run the [List all receipts](/api/v1/_docs/#operation/listReceipts) endpoint and check that your `Receipt` exists in the returned list.\n \n\n- \n \n \n E_PDF_LINK_MISSING\n \n
\n\n The PDF for the `Receipt` you are trying to access hasn't been created yet. Repeat the request later.\n \n \n\n## Status 5xx\n\nStatus codes in the `500-599` range indicate errors on the server side.\nThese errors are temporary.\nYou can **safely retry** (see [Idempotent Requests](#section/Introduction/Idempotent-Requests)) the same request after a delay.\nWe recommend an [exponential backoff](https://wikipedia.org/wiki/Exponential_backoff) for your retry logic.\nOtherwise you might run into a [`429 (Too Many Requests)`](https://http.cat/429) error.\n\n# Known issues\n\n- If you're experiencing any problems with the fiskaly eReceipt backend, please check [the fiskaly eReceipt backend status page](https://status.fiskaly.com) or forward to [Developer Support](mailto:dev-support@fiskaly.com).\n",
"version": "1.0.0",
"contact": {
"name": "fiskaly GmbH",
"url": "https://fiskaly.com",
"email": "info@fiskaly.com"
},
"x-logo": {
"url": "https://workspace.fiskaly.com/static/logo.svg",
"altText": "fiskaly Logo"
}
},
"definitions": {
"EkabsAddress": {
"type": "object",
"properties": {
"street": {
"description": "Street name and house number",
"type": "string",
"maxLength": 60
},
"postal_code": {
"description": "Postal code",
"type": "string",
"maxLength": 10
},
"city": {
"description": "City name",
"type": "string",
"maxLength": 62
},
"country_code": { "$ref": "#/definitions/EkabsCountryCode" }
},
"additionalProperties": false
},
"EkabsCountryCode": {
"description": "ISO 3166 alpha-3 country code",
"enum": [
"ALA",
"AFG",
"ALB",
"DZA",
"ASM",
"AND",
"AGO",
"AIA",
"ATA",
"ATG",
"ARG",
"ARM",
"ABW",
"AUS",
"AUT",
"AZE",
"BHS",
"BHR",
"BGD",
"BRB",
"BLR",
"BEL",
"BLZ",
"BEN",
"BMU",
"BTN",
"BOL",
"BIH",
"BWA",
"BVT",
"BRA",
"IOT",
"BRN",
"BGR",
"BFA",
"BDI",
"KHM",
"CMR",
"CAN",
"CPV",
"CYM",
"CAF",
"TCD",
"CHL",
"CHN",
"CXR",
"CCK",
"COL",
"COM",
"COD",
"COG",
"COK",
"CRI",
"CIV",
"HRV",
"CUB",
"CYP",
"CZE",
"DNK",
"DJI",
"DMA",
"DOM",
"ECU",
"EGY",
"SLV",
"GNQ",
"ERI",
"EST",
"ETH",
"FLK",
"FRO",
"FJI",
"FIN",
"FRA",
"GUF",
"PYF",
"ATF",
"GAB",
"GMB",
"GEO",
"DEU",
"GHA",
"GIB",
"GRC",
"GRL",
"GRD",
"GLP",
"GUM",
"GTM",
"GIN",
"GNB",
"GUY",
"HTI",
"HMD",
"HND",
"HKG",
"HUN",
"ISL",
"IND",
"IDN",
"IRN",
"IRQ",
"IRL",
"ISR",
"ITA",
"JAM",
"JPN",
"JOR",
"KAZ",
"KEN",
"KIR",
"PRK",
"KOR",
"KWT",
"KGZ",
"LAO",
"LVA",
"LBN",
"LSO",
"LBR",
"LBY",
"LIE",
"LTU",
"LUX",
"MAC",
"MKD",
"MDG",
"MWI",
"MYS",
"MDV",
"MLI",
"MLT",
"MHL",
"MTQ",
"MRT",
"MUS",
"MYT",
"MEX",
"FSM",
"MDA",
"MCO",
"MNG",
"MSR",
"MAR",
"MOZ",
"MMR",
"NAM",
"NRU",
"NPL",
"NLD",
"ANT",
"NCL",
"NZL",
"NIC",
"NER",
"NGA",
"NIU",
"NFK",
"MNP",
"NOR",
"OMN",
"PAK",
"PLW",
"PSE",
"PAN",
"PNG",
"PRY",
"PER",
"PHL",
"PCN",
"POL",
"PRT",
"PRI",
"QAT",
"REU",
"ROU",
"RUS",
"RWA",
"SHN",
"KNA",
"LCA",
"SPM",
"VCT",
"WSM",
"SMR",
"STP",
"SAU",
"SEN",
"SCG",
"SYC",
"SLE",
"SGP",
"SVK",
"SVN",
"SLB",
"SOM",
"ZAF",
"SGS",
"ESP",
"LKA",
"SDN",
"SUR",
"SJM",
"SWZ",
"SWE",
"CHE",
"SYR",
"TWN",
"TJK",
"TZA",
"THA",
"TLS",
"TGO",
"TKL",
"TON",
"TTO",
"TUN",
"TUR",
"TKM",
"TCA",
"TUV",
"UGA",
"UKR",
"ARE",
"GBR",
"USA",
"UMI",
"URY",
"UZB",
"VUT",
"VAT",
"VEN",
"VNM",
"VGB",
"VIR",
"WLF",
"ESH",
"YEM",
"ZMB",
"ZWE"
]
},
"EkabsCurrency": {
"description": "ISO 4217 currency code",
"enum": [
"AED",
"AFN",
"ALL",
"AMD",
"ANG",
"AOA",
"ARS",
"AUD",
"AWG",
"AZN",
"BAM",
"BBD",
"BDT",
"BGN",
"BHD",
"BIF",
"BMD",
"BND",
"BOB",
"BOV",
"BRL",
"BSD",
"BTN",
"BWP",
"BYN",
"BYR",
"BZD",
"CAD",
"CDF",
"CHE",
"CHF",
"CHW",
"CLF",
"CLP",
"CN",
"COP",
"COU",
"CRC",
"CUC",
"CUP",
"CVE",
"CZK",
"DJF",
"DKK",
"DOP",
"DZD",
"EGP",
"ERN",
"ETB",
"EUR",
"FJD",
"FKP",
"GBP",
"GEL",
"GHS",
"GIP",
"GMD",
"GNF",
"GTQ",
"GYD",
"HKD",
"HNL",
"HRK",
"HTG",
"HUF",
"IDR",
"ILS",
"INR",
"IQD",
"IRR",
"ISK",
"JMD",
"JOD",
"JPY",
"KES",
"KGS",
"KHR",
"KMF",
"KPW",
"KRW",
"KWD",
"KYD",
"KZT",
"LAK",
"LBP",
"LKR",
"LRD",
"LSL",
"LYD",
"MAD",
"MDL",
"MGA",
"MKD",
"MMK",
"MNT",
"MOP",
"MRO",
"MUR",
"MVR",
"MWK",
"MXN",
"MXV",
"MYR",
"MZN",
"NAD",
"NGN",
"NIO",
"NOK",
"NPR",
"NZD",
"OMR",
"PAB",
"PEN",
"PGK",
"PHP",
"PKR",
"PLN",
"PYG",
"QAR",
"RON",
"RSD",
"RUB",
"RWF",
"SAR",
"SBD",
"SCR",
"SDG",
"SSP",
"SEK",
"SGD",
"SHP",
"SLL",
"SOS",
"SRD",
"STD",
"SVC",
"SYP",
"SZL",
"THB",
"TJS",
"TMT",
"TND",
"TOP",
"TRY",
"TTD",
"TWD",
"TZS",
"UAH",
"UGX",
"USD",
"UYI",
"UYU",
"UZS",
"VEF",
"VND",
"VUV",
"WST",
"XAF",
"XCD",
"XOF",
"XPF",
"XSU",
"YER",
"ZAR",
"ZMW",
"ZWL"
]
},
"ReceiptSchemaEkabsV0": {
"type": "object",
"description": "This schema is an adaptation (for the Austrian legislation) of\n[EKaBS - Einheitlicher Standard für elektronische Kassenbelege](https://dfka.net/ekabs).\nThis is the recommended schema.",
"required": ["head", "data"],
"additionalProperties": true,
"properties": {
"head": {
"type": "object",
"description": "Header data of the receipt",
"required": ["number", "date"],
"dependencies": { "delivery_period_end": ["delivery_period_start"] },
"additionalProperties": true,
"properties": {
"id": {
"type": "string",
"description": "Unique id of the receipt"
},
"number": { "type": "string", "description": "Receipt number" },
"date": {
"type": "string",
"format": "date-time",
"description": "Receipt date"
},
"delivery_period_start": {
"type": "string",
"format": "date-time",
"description": "Start of the delivery period, which applies to the entire receipt"
},
"delivery_period_end": {
"type": "string",
"format": "date-time",
"description": "End of the delivery period, which applies to the entire receipt"
},
"seller": {
"type": "object",
"description": "Information about the seller / company",
"additionalProperties": true,
"required": ["name", "address", "tax_number"],
"properties": {
"name": {
"type": "string",
"description": "Seller / company name"
},
"tax_number": {
"type": "string",
"description": "Tax number or VAT-ID number"
},
"tax_exemption": {
"type": "boolean",
"description": "Set this is if the seller is exempt from turnover tax",
"default": false
},
"tax_exemption_note": {
"type": "string",
"description": "A note to be shown on the receipt if the seller is exempt from turnover tax"
},
"address": { "$ref": "#/definitions/EkabsAddress" }
}
},
"buyer_text": {
"type": "string",
"description": "Name and address of the buyer / customer as unstructured text field",
"examples": ["Erika Mustermann\nHeidestrasse 17\n51147 Köln"]
},
"buyer": {
"type": "object",
"description": "Buyer / customer information",
"required": ["name", "address"],
"additionalProperties": true,
"properties": {
"customer_number": {
"type": "string",
"description": "Customer number"
},
"name": {
"type": "string",
"description": "Buyer / customer name"
},
"tax_number": {
"type": "string",
"description": "Tax number of the buyer / customer"
},
"address": { "$ref": "#/definitions/EkabsAddress" }
}
}
}
},
"data": {
"type": "object",
"description": "The data of the receipt",
"required": [
"currency",
"full_amount_incl_vat",
"payment_types",
"vat_amounts",
"lines"
],
"additionalProperties": true,
"properties": {
"currency": { "$ref": "#/definitions/EkabsCurrency" },
"full_amount_incl_vat": {
"description": "The gross total of the receipt",
"allOf": [{ "$ref": "#/definitions/Numeric" }]
},
"payment_types": {
"type": "array",
"description": "List of payment amounts",
"additionalItems": true,
"items": {
"type": "object",
"description": "Payment amount",
"additionalProperties": true,
"required": ["name", "amount"],
"properties": {
"name": {
"type": "string",
"description": "Name of the payment"
},
"amount": {
"type": "number",
"description": "Payment amount in local currency"
},
"foreign_amount": {
"type": "number",
"description": "Payment amount in foreign currency"
},
"foreign_currency": { "$ref": "#/definitions/EkabsCurrency" }
},
"dependencies": {
"foreign_amount": ["foreign_currency"],
"foreign_currency": ["foreign_amount"]
}
}
},
"vat_amounts": {
"type": "array",
"description": "Totals per VAT as normally printed on receipt",
"additionalItems": true,
"items": {
"type": "object",
"required": ["percentage", "incl_vat", "excl_vat", "vat"],
"additionalProperties": true,
"properties": {
"percentage": {
"type": "number",
"description": "VAT percentage",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.01
},
"incl_vat": { "$ref": "#/definitions/Numeric" },
"excl_vat": { "$ref": "#/definitions/Numeric" },
"vat": { "$ref": "#/definitions/Numeric" }
}
}
},
"lines": {
"type": "array",
"description": "List of receipt lines",
"additionalItems": true,
"items": {
"type": "object",
"description": "Receipt line",
"required": ["text"],
"dependencies": {
"delivery_period_end": ["delivery_period_start"]
},
"additionalProperties": true,
"properties": {
"text": {
"type": "string",
"description": "Text of the receipt line"
},
"additional_text": {
"type": "string",
"description": "Additional information for the receipt line"
},
"vat_amounts": {
"type": "array",
"description": "Total amount of the line per VAT",
"additionalItems": true,
"items": {
"anyOf": [
{
"type": "object",
"description": "When the line is calculated based on the gross amount",
"required": ["percentage", "incl_vat"],
"additionalProperties": true,
"properties": {
"percentage": {
"type": "number",
"description": "VAT percentage",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.01
},
"incl_vat": {
"type": "number",
"description": "Gross amount",
"multipleOf": 0.00001
}
}
},
{
"type": "object",
"description": "When the line is calculated based on the net amount",
"required": ["percentage", "excl_vat", "vat"],
"additionalProperties": true,
"properties": {
"percentage": {
"type": "number",
"description": "VAT percentage",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.01
},
"excl_vat": {
"type": "number",
"description": "Net amount",
"multipleOf": 0.00001
},
"vat": {
"type": "number",
"description": "VAT amount (vat = incl_vat - excl_vat)",
"multipleOf": 0.00001
}
}
}
]
}
},
"item": {
"type": "object",
"description": "Product item details of the line",
"required": ["number", "quantity", "price_per_unit"],
"additionalProperties": true,
"properties": {
"number": {
"type": "string",
"description": "Product number"
},
"gtin": {
"type": "string",
"description": "Optional GTIN / EAN of the product",
"minLength": 1,
"maxLength": 50
},
"quantity": {
"type": "number",
"description": "Quantity",
"multipleOf": 0.001
},
"quantity_measure": {
"type": "string",
"description": "Quantity measure"
},
"price_per_unit": {
"type": "number",
"description": "Price per unit",
"multipleOf": 0.00001
}
}
},
"delivery_period_start": {
"type": "string",
"format": "date-time",
"description": "Start of the delivery period, which applies to a single line"
},
"delivery_period_end": {
"type": "string",
"format": "date-time",
"description": "End of the delivery period, which applies to a single line"
}
}
}
}
}
},
"misc": {
"type": "object",
"description": "Miscellaneous information",
"additionalProperties": true,
"properties": {
"footer_text": {
"type": "string",
"description": "Optional footer text of the receipt"
}
}
},
"security": {
"type": "object",
"description": "Security properties that are applicable for the country that the receipt was issued in",
"additionalProperties": false,
"properties": {
"tse": {
"type": "object",
"description": "Security properties that are relevant for the KassenSichV and created by a TSS (TSE)",
"additionalProperties": false,
"properties": {
"serial_number": {
"type": "string",
"description": "Serial number of the TSS"
},
"signature_algorithm": {
"type": "string",
"description": "Signature algorithm that was used by the TSS to sign the transaction"
},
"log_time_format": {
"type": "string",
"description": "Format of timestamps contained in logs created by the TSS"
},
"certificate": {
"type": "string",
"description": "The certificate that is associated with the TSS"
},
"timestamp_start": {
"type": "string",
"format": "date-time",
"description": "Timestamp that marks the start of the transaction"
},
"timestamp_end": {
"type": "string",
"format": "date-time",
"description": "Timestamp that marks the end of the transaction"
},
"first_order": {
"type": "string",
"format": "date-time",
"description": "Timestamp that marks the first order"
},
"transaction_number": {
"type": "number",
"description": "Current transaction number of the TSS when finishing the receipt"
},
"signature_number": {
"type": "number",
"description": "Current signature number of the TSS when finishing the receipt"
},
"process_type": {
"type": "string",
"description": "Process type of that transaction according to KassenSichV"
},
"process_data": {
"type": "string",
"description": "Process data of that transaction according to KassenSichV"
},
"signature": {
"type": "string",
"description": "Signature over the process data created by the TSS"
}
}
}
}
}
}
},
"Numeric": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{2}$",
"default": "0.00",
"examples": ["-123.45", "123.45"]
},
"Byte": { "type": "string", "format": "byte" },
"Uuid": {
"type": "string",
"format": "uuid",
"pattern": "[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}",
"example": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
"transform": ["toLowerCase"]
},
"Timestamp": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "A timestamp / point in time measured in seconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).",
"example": 1577833200
},
"Env": { "type": "string", "enum": ["TEST", "LIVE"], "example": "TEST" },
"Metadata": {
"type": "object",
"example": {
"my_property_1": "1234",
"my_property_2": "https://my-internal-system/path/to/resource/1234"
},
"maxProperties": 20,
"propertyNames": { "type": "string", "maxLength": 40 },
"additionalProperties": { "type": "string", "maxLength": 500 }
},
"OrganizationId": {
"type": "string",
"format": "uuid",
"pattern": "[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}",
"example": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
"transform": ["toLowerCase"],
"description": "ID of the Organization."
},
"Count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Number of available data items"
},
"RefreshToken": { "type": "string" },
"ApiKeyKey": {
"type": "string",
"description": "Key of the API Key and Secret."
},
"ApiKeySecret": {
"type": "string",
"description": "Secret of the API Key and Secret."
},
"Environment": {
"type": "string",
"enum": ["TEST", "LIVE"],
"example": "TEST"
},
"Version": { "type": "string", "default": "1.0.0", "example": "1.0.0" },
"Url": { "type": "string", "format": "uri" },
"RefreshTokenAuthentication": {
"type": "object",
"properties": {
"refresh_token": { "$ref": "#/definitions/RefreshToken" }
},
"required": ["refresh_token"],
"additionalProperties": false
},
"ApiKeyAuthentication": {
"type": "object",
"properties": {
"api_key": { "$ref": "#/definitions/ApiKeyKey" },
"api_secret": { "$ref": "#/definitions/ApiKeySecret" }
},
"required": ["api_key", "api_secret"],
"additionalProperties": false
},
"AuthenticationRequest": {
"oneOf": [
{ "$ref": "#/definitions/ApiKeyAuthentication" },
{ "$ref": "#/definitions/RefreshTokenAuthentication" }
]
},
"AuthenticationResponse": {
"type": "object",
"description": "Successful authentication.",
"properties": {
"access_token": { "type": "string" },
"access_token_claims": {
"type": "object",
"description": "Contains information about the claims that are embedded within the access token. Can be used to retrieve one's own `organization_id`.",
"properties": {
"env": { "$ref": "#/definitions/Env" },
"organization_id": { "$ref": "#/definitions/OrganizationId" }
},
"required": ["env"],
"additionalProperties": false
},
"access_token_expires_in": { "type": "integer" },
"access_token_expires_at": { "$ref": "#/definitions/Timestamp" },
"refresh_token": { "$ref": "#/definitions/RefreshToken" },
"refresh_token_expires_in": { "type": "integer" },
"refresh_token_expires_at": { "$ref": "#/definitions/Timestamp" }
},
"required": ["access_token"],
"additionalProperties": false
},
"SchemaObject": {
"type": "object",
"properties": {
"ekabs_v0": { "$ref": "#/definitions/ReceiptSchemaEkabsV0" }
},
"required": ["ekabs_v0"],
"additionalProperties": false
},
"UserAssociation": {
"type": "object",
"properties": { "masked_card_number": { "type": "string" } },
"required": ["masked_card_number"],
"additionalProperties": false
},
"CreateReceiptRequest": {
"type": "object",
"properties": {
"schema": { "$ref": "#/definitions/SchemaObject" },
"user_association": { "$ref": "#/definitions/UserAssociation" }
},
"required": ["schema"],
"additionalProperties": false
},
"PublicLink": {
"type": "object",
"properties": { "href": { "type": "string" } },
"required": ["href"],
"additionalProperties": false
},
"Assets": {
"type": "object",
"properties": { "pdf": { "type": "string" } },
"required": ["pdf"],
"additionalProperties": false
},
"ReceiptId": {
"type": "string",
"format": "uuid",
"pattern": "[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}",
"example": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
"transform": ["toLowerCase"],
"description": "Identifies a Receipt."
},
"CreateReceiptResponse": {
"type": "object",
"properties": {
"_id": { "$ref": "#/definitions/ReceiptId" },
"_type": {
"type": "string",
"enum": ["RECEIPT"],
"default": "RECEIPT"
},
"_env": { "$ref": "#/definitions/Env" },
"_version": { "$ref": "#/definitions/Version" },
"schema": { "$ref": "#/definitions/SchemaObject" },
"user_association": { "$ref": "#/definitions/UserAssociation" },
"public_link": { "$ref": "#/definitions/PublicLink" },
"assets": { "$ref": "#/definitions/Assets" }
},
"required": [
"schema",
"public_link",
"assets",
"_id",
"_type",
"_version",
"_env"
],
"additionalProperties": false
},
"RetrieveReceiptPublicResponse": {
"type": "object",
"properties": {
"_id": { "$ref": "#/definitions/ReceiptId" },
"_type": {
"type": "string",
"enum": ["RECEIPT"],
"default": "RECEIPT"
},
"_version": { "$ref": "#/definitions/Version" },
"schema": { "$ref": "#/definitions/SchemaObject" },
"assets": { "$ref": "#/definitions/Assets" }
},
"required": ["_id", "_type", "_version", "schema", "assets"],
"additionalProperties": false
},
"ReceiptRequestParams": {
"type": "object",
"properties": {
"receipt_id": {
"type": "string",
"format": "uuid",
"pattern": "[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}",
"example": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
"transform": ["toLowerCase"],
"description": "Identifies a Receipt."
}
},
"required": ["receipt_id"],
"additionalProperties": false
},
"RetrieveReceiptResponse": {
"type": "object",
"properties": {
"_id": { "$ref": "#/definitions/ReceiptId" },
"_type": {
"type": "string",
"enum": ["RECEIPT"],
"default": "RECEIPT"
},
"_version": { "$ref": "#/definitions/Version" },
"_env": { "$ref": "#/definitions/Env" },
"user_association": { "$ref": "#/definitions/UserAssociation" },
"public_link": { "$ref": "#/definitions/PublicLink" },
"schema": { "$ref": "#/definitions/SchemaObject" },
"assets": { "$ref": "#/definitions/Assets" }
},
"required": [
"_id",
"_type",
"_version",
"_env",
"schema",
"assets",
"public_link"
],
"additionalProperties": false
},
"ListReceiptsResponse": {
"type": "object",
"properties": {
"_type": {
"type": "string",
"const": "RECEIPT_LIST",
"example": "RECEIPT_LIST"
},
"_env": { "$ref": "#/definitions/Environment" },
"_version": { "$ref": "#/definitions/Version" },
"count": { "$ref": "#/definitions/Count" },
"data": {
"type": "array",
"items": { "$ref": "#/definitions/RetrieveReceiptResponse" }
}
},
"required": ["_type", "_version", "_env", "data", "count"],
"additionalProperties": false
},
"BaseCollectionQueryString": {
"type": "object",
"properties": {
"order": {
"type": "string",
"description": "Determines the sorting order.",
"enum": ["ASC", "DESC"],
"default": "ASC"
},
"limit": {
"description": "Limits the number of returned results.",
"type": "integer",
"maximum": 100,
"default": 100
},
"offset": {
"description": "Skips the specified number of results from the result set.",
"type": "integer",
"default": 0
}
},
"additionalProperties": false
}
},
"paths": {
"/auth": {
"post": {
"operationId": "authenticateApi",
"summary": "Authenticate API",
"description": "To access our API, you need to have a valid JWT token. This endpoint creates the token with your `api_key` and `api_secret`. \nIf you don't have an `api_key`, you can create one via the [fiskaly dashboard](https://dashboard.fiskaly.com).\nThe `api_secret` will be generated for you after you create the `api_key`.\nThe token must be sent with every following request in the `Authorization` header field using the `Bearer` authentication scheme.\nSee details [here](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1).",
"tags": ["Authentication"],
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"oneOf": [
{ "$ref": "#/definitions/ApiKeyAuthentication" },
{ "$ref": "#/definitions/RefreshTokenAuthentication" }
]
}
}
],
"responses": {
"200": {
"description": "Successful authentication.",
"schema": {
"type": "object",
"description": "Successful authentication.",
"properties": {
"access_token": { "type": "string" },
"access_token_claims": {
"type": "object",
"description": "Contains information about the claims that are embedded within the access token. Can be used to retrieve one's own `organization_id`.",
"properties": {
"env": { "$ref": "#/definitions/Env" },
"organization_id": {
"$ref": "#/definitions/OrganizationId"
}
},
"required": ["env"],
"additionalProperties": false
},
"access_token_expires_in": { "type": "integer" },
"access_token_expires_at": {
"$ref": "#/definitions/Timestamp"
},
"refresh_token": { "$ref": "#/definitions/RefreshToken" },
"refresh_token_expires_in": { "type": "integer" },
"refresh_token_expires_at": {
"$ref": "#/definitions/Timestamp"
}
},
"required": ["access_token"],
"additionalProperties": false
}
},
"401": {
"description": "Unauthorized",
"schema": {
"type": "object",
"description": "Unauthorized",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"status_code": { "type": "number", "example": 401 },
"error": { "type": "string", "example": "Unauthorized" }
},
"additionalProperties": false
}
}
}
}
},
"/receipt/{receipt_id}": {
"put": {
"operationId": "createReceipt",
"summary": "Create a receipt",
"description": "This endpoint creates a receipt.",
"tags": ["Receipts"],
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"properties": {
"schema": { "$ref": "#/definitions/SchemaObject" },
"user_association": { "$ref": "#/definitions/UserAssociation" }
},
"required": ["schema"],
"additionalProperties": false
}
},
{
"type": "string",
"format": "uuid",
"pattern": "[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}",
"example": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
"transform": ["toLowerCase"],
"description": "Identifies a Receipt.",
"required": true,
"in": "path",
"name": "receipt_id"
}
],
"security": [{ "JWT": [] }],
"responses": {
"200": {
"description": "Default Response",
"schema": {
"type": "object",
"properties": {
"_id": { "$ref": "#/definitions/ReceiptId" },
"_type": {
"type": "string",
"enum": ["RECEIPT"],
"default": "RECEIPT"
},
"_env": { "$ref": "#/definitions/Env" },
"_version": { "$ref": "#/definitions/Version" },
"schema": { "$ref": "#/definitions/SchemaObject" },
"user_association": { "$ref": "#/definitions/UserAssociation" },
"public_link": { "$ref": "#/definitions/PublicLink" },
"assets": { "$ref": "#/definitions/Assets" }
},
"required": [
"schema",
"public_link",
"assets",
"_id",
"_type",
"_version",
"_env"
],
"additionalProperties": false
}
}
}
},
"get": {
"operationId": "retrieveReceipt",
"summary": "Retrieve a receipt",
"description": "This endpoint retrieves a receipt for the Merchant. \nIt will return the receipt even after the public access to the receipt has expired.",
"tags": ["Receipts"],
"parameters": [
{
"type": "string",
"format": "uuid",
"pattern": "[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}",
"example": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
"transform": ["toLowerCase"],
"description": "Identifies a Receipt.",
"required": true,
"in": "path",
"name": "receipt_id"
}
],
"responses": {
"200": {
"description": "Default Response",
"schema": {
"type": "object",
"properties": {
"_id": { "$ref": "#/definitions/ReceiptId" },
"_type": {
"type": "string",
"enum": ["RECEIPT"],
"default": "RECEIPT"
},
"_version": { "$ref": "#/definitions/Version" },
"_env": { "$ref": "#/definitions/Env" },
"user_association": { "$ref": "#/definitions/UserAssociation" },
"public_link": { "$ref": "#/definitions/PublicLink" },
"schema": { "$ref": "#/definitions/SchemaObject" },
"assets": { "$ref": "#/definitions/Assets" }
},
"required": [
"_id",
"_type",
"_version",
"_env",
"schema",
"assets",
"public_link"
],
"additionalProperties": false
}
}
}
}
},
"/public/receipt/{receipt_id}": {
"get": {
"operationId": "retrieveReceiptPublic",
"summary": "Retrieve a receipt (public)",
"description": "This endpoint retrieves the publicly available receipt resource. \nIt can be called by the point of sale to display the receipt to the end user.",
"tags": ["Receipts"],
"parameters": [
{
"type": "string",
"format": "uuid",
"pattern": "[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}",
"example": "1c81cb86-c2e8-4074-afc3-a0601b2bf063",
"transform": ["toLowerCase"],
"description": "Identifies a Receipt.",
"required": true,
"in": "path",
"name": "receipt_id"
}
],
"responses": {
"200": {
"description": "Default Response",
"schema": {
"type": "object",
"properties": {
"_id": { "$ref": "#/definitions/ReceiptId" },
"_type": {
"type": "string",
"enum": ["RECEIPT"],
"default": "RECEIPT"
},
"_version": { "$ref": "#/definitions/Version" },
"schema": { "$ref": "#/definitions/SchemaObject" },
"assets": { "$ref": "#/definitions/Assets" }
},
"required": ["_id", "_type", "_version", "schema", "assets"],
"additionalProperties": false
}
}
}
}
},
"/receipt": {
"get": {
"operationId": "listReceipts",
"summary": "List all receipts",
"description": "This endpoint retrieves a list of receipts for the Merchant. \nIt will include a receipt into the result even after its public access has expired.",
"tags": ["Receipts"],
"parameters": [
{
"type": "string",
"description": "Determines the sorting order.",
"enum": ["ASC", "DESC"],
"default": "ASC",
"required": false,
"in": "query",
"name": "order"
},
{
"description": "Limits the number of returned results.",
"type": "integer",
"maximum": 100,
"default": 100,
"required": false,
"in": "query",
"name": "limit"
},
{
"description": "Skips the specified number of results from the result set.",
"type": "integer",
"default": 0,
"required": false,
"in": "query",
"name": "offset"
}
],
"responses": {
"200": {
"description": "Default Response",
"schema": {
"type": "object",
"properties": {
"_type": {
"type": "string",
"const": "RECEIPT_LIST",
"example": "RECEIPT_LIST"
},
"_env": { "$ref": "#/definitions/Environment" },
"_version": { "$ref": "#/definitions/Version" },
"count": { "$ref": "#/definitions/Count" },
"data": {
"type": "array",
"items": { "$ref": "#/definitions/RetrieveReceiptResponse" }
}
},
"required": ["_type", "_version", "_env", "data", "count"],
"additionalProperties": false
}
}
}
}
}
},
"host": "localhost:3000",
"basePath": "/api/v1",
"consumes": ["application/json"],
"produces": ["application/json"],
"securityDefinitions": {
"JWT": {
"description": "A JSON Web Token (JWT) used for access control and authorization.\n- Usage format: `Bearer `\n- Example HTTP header: `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`",
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"x-tagGroups": [
{ "name": "Authentication", "tags": ["Authentication"] },
{ "name": "Daily operations", "tags": ["Receipts"] }
]
}