---
updatedAt: 2026-04-21T06:16:37.000Z
agentTools:
projectIndex: https://b2brouter.readme.io/llms.txt
---
# Download a tax report
Download a tax report in the format that is sent to the Tax Authority.
Note that if the Tax Authority requires the tax report to be cleared (such as in Zatca) or chained (such as in Verifactu and TicketBAI) the XML will only contain all the information after the tax report is chained or cleared. Given the the asynchronous nature of this process, there is no guarantee that when you download the tax reports will be prepared. This process usually only takes a few seconds.
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"title": "B2Brouter API",
"description": "The B2Brouter API allows you to send and receive electronic documents.",
"version": "2026-06-26",
"contact": {
"name": "Service Delivery Team",
"email": "servicedelivery@b2brouter.net"
}
},
"servers": [
{
"url": "https://api-staging.b2brouter.net",
"description": "Test server"
},
{
"url": "https://api.b2brouter.net",
"description": "Production server"
}
],
"tags": [
{
"name": "Tax Reports",
"description": "Related tax reports"
}
],
"paths": {
"/tax_reports/{id}/download": {
"get": {
"operationId": "new-download-tax-report",
"tags": [
"Tax Reports"
],
"summary": "Download a tax report",
"description": "Download a tax report in the format that is sent to the Tax Authority.\nNote that if the Tax Authority requires the tax report to be cleared (such as in Zatca) or chained (such as in Verifactu and TicketBAI) the XML will only contain all the information after the tax report is chained or cleared. Given the the asynchronous nature of this process, there is no guarantee that when you download the tax reports will be prepared. This process usually only takes a few seconds.",
"parameters": [
{
"$ref": "#/components/parameters/api_version_header"
},
{
"$ref": "#/components/parameters/tax_report_id"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/xml": {
"schema": {
"type": "object",
"properties": {
"tax_report": {
"$ref": "#/components/schemas/TaxReport"
}
}
}
}
}
},
"403": {
"description": "Unauthorized"
},
"404": {
"description": "Tax Report not found"
}
},
"security": [
{
"api_key": []
}
]
}
}
},
"components": {
"securitySchemes": {
"api_key": {
"type": "apiKey",
"description": "API Key of your account",
"name": "X-B2B-API-Key",
"in": "header"
}
},
"parameters": {
"api_version_header": {
"name": "X-B2B-API-Version",
"in": "header",
"description": "Specifies the version of the API to use in this request. If not specified uses the API-Version set in the group conifguration\nB2Brouter UI Application -> Developers -> API Keys -> API Version\n",
"required": false,
"schema": {
"type": "string",
"example": "2026-06-26",
"default": "2026-06-26"
}
},
"tax_report_id": {
"name": "id",
"in": "path",
"description": "A unique internal identifier of the Tax Report in B2Brouter.\n",
"required": true,
"example": 4053100,
"schema": {
"type": "integer"
}
}
},
"schemas": {
"Tax": {
"type": "object",
"nullable": true,
"description": "Represents a tax as an object",
"properties": {
"name": {
"type": "string",
"description": "Tax Name",
"example": "IVA"
},
"base": {
"type": "number",
"format": "decimal",
"description": "The base amount that may be used to calculate the Tax Amount",
"example": 100,
"readOnly": true
},
"amount": {
"type": "number",
"format": "decimal",
"description": "The amount of the tax.",
"readOnly": true,
"example": 21
},
"category": {
"type": "string",
"enum": [
"E",
"NS",
"Z",
"S",
"H",
"AA",
"AAA",
"AE",
"G",
"O",
"K"
],
"example": "S",
"description": "Taxes categories\n * `E` - Exempt\n * `NS` - NotSubject\n * `Z` - ZeroRated\n * `S` - Standard\n * `H` - High Rate\n * `AA` - Low Rate\n * `AAA` - Super Low Rate\n * `AE` - Reverse\n * `G` - Free export item, VAT not charged\n * `O` - Services outside scope of tax\n * `K` - VAT exempt for EEA intra-community supply of goods and services\n",
"writeOnly": true
},
"percent": {
"type": "number",
"format": "float",
"description": "Tax %",
"example": 21
},
"comment": {
"type": "string",
"description": "Tax comment",
"nullable": true,
"example": "IVA 21%"
}
}
},
"AllowanceChargeBase": {
"type": "object",
"description": "Base schema for allowance charges containing common fields",
"properties": {
"id": {
"type": "integer",
"example": 12345,
"description": "A unique internal identifier of the AllowanceCharge in B2Brouter. It can be used to update or destroy an existing AllowanceCharge.\n"
},
"allowance_charge_indicator": {
"type": "string",
"description": "Indicates whether this is an allowance (discount) or charge.\n\nID: `BT-20`, `BT-21` for document level or `BT-140`, `BT-141` for line level\n",
"enum": [
"allowance",
"charge"
],
"example": "allowance"
},
"amount": {
"type": "number",
"format": "decimal",
"description": "The amount of the allowance or charge, without VAT.\nEither amount or percentage must be provided, but not both.\n\nID: `BT-92`, `BT-99` for document level or `BT-136`, `BT-141` for line level\n",
"example": 50,
"nullable": true
},
"percentage": {
"type": "number",
"format": "decimal",
"description": "The percentage that may be used to calculate the allowance or charge amount.\nEither amount or percentage must be provided, but not both.\n\nID: `BT-94`, `BT-101` for document level or `BT-138`, `BT-144` for line level\n",
"example": 10.5,
"nullable": true
},
"description": {
"type": "string",
"maxLength": 255,
"description": "The reason for the allowance or charge, expressed as text.\n\nID: `BT-97`, `BT-104` for document level or `BT-139`, `BT-145` for line level\n",
"example": "Volume discount",
"nullable": true
},
"is_reimbursable_expense": {
"type": "boolean",
"description": "[FacturaE Only]\n\nIndicates whether the charge is a reimbursable expense (Spanish \"suplidos\").\nOnly applicable to charges, not allowances.\n",
"default": false
},
"base_amount": {
"type": "number",
"format": "decimal",
"description": "The base amount used to calculate percentage-based allowances or charges.\nThis is calculated automatically from the adjustable record.\n",
"example": 1000,
"readOnly": true
},
"calculated_amount": {
"type": "number",
"format": "decimal",
"description": "The final calculated amount of the allowance or charge.\nFor fixed amounts, this equals the amount field.\nFor percentages, this is calculated from percentage and base_amount.\n",
"example": 105,
"readOnly": true
},
"currency": {
"type": "string",
"description": "The currency of the allowance or charge amounts.\nInherited from the associated invoice.\n",
"example": "EUR",
"readOnly": true
},
"_destroy": {
"type": "boolean",
"description": "Set to true to delete this allowance or charge when updating.\nUsed in nested attribute updates.\n",
"writeOnly": true
}
},
"required": [
"allowance_charge_indicator"
]
},
"AllowanceCharge": {
"allOf": [
{
"$ref": "#/components/schemas/AllowanceChargeBase"
},
{
"type": "object",
"description": "Represents an allowance (discount) or charge on an invoice or invoice line",
"properties": {
"apply_taxes": {
"type": "boolean",
"description": "Indicates whether taxes should be applied to this allowance or charge.\nDefaults to `true` for allowances. For charges, defaults to `true` if the company has the \"apply taxes to charge\" setting enabled, `false` otherwise.\n"
},
"tax_attributes": {
"allOf": [
{
"$ref": "#/components/schemas/Tax"
}
],
"description": "Tax to be applied to this allowance or charge.\nOnly applicable when apply_taxes is true.\nIf not specified and apply_taxes is true, will inherit from invoice taxes.\n",
"writeOnly": true
},
"tax": {
"allOf": [
{
"$ref": "#/components/schemas/Tax"
}
],
"description": "The tax applied to this allowance or charge.\nOnly present when apply_taxes is true.\n",
"readOnly": true
}
}
}
]
},
"TaxBreakdowns": {
"type": "object",
"description": "Represents a TaxBreakdown, referred to as \"Desglose\" in the Verifactu system. A TaxBreakdown contains all the detailed information about the tax category applied to a specific operation. It includes the tax base, the tax amount, and other relevant information necessary for tax reporting.\n",
"properties": {
"id": {
"type": "integer",
"example": 355040,
"description": "An internal identifier that is unique to each **Tax Breakdown** within B2Brouter.\n",
"readOnly": true
},
"kind": {
"type": "string",
"enum": [
"charged",
"withheld"
],
"example": "charged",
"writeOnly": true
},
"date": {
"type": "string",
"format": "date",
"example": "2025-04-10",
"writeOnly": true
},
"name": {
"type": "string",
"example": "IVA",
"nullable": true
},
"currency": {
"type": "string",
"example": "EUR",
"writeOnly": true
},
"original_currency": {
"type": "string",
"example": "EUR",
"writeOnly": true
},
"category": {
"type": "string",
"enum": [
"E",
"NS",
"Z",
"S",
"H",
"AA",
"AAA",
"AE",
"G",
"O",
"K",
null
],
"example": "S",
"description": "Taxes categories\n * `E` - Exempt\n * `NS` - NotSubject\n * `Z` - ZeroRated\n * `S` - Standard\n * `H` - High Rate\n * `AA` - Low Rate\n * `AAA` - Super Low Rate\n * `AE` - Reverse\n * `G` - Free export item, VAT not charged\n * `O` - Services outside scope of tax\n * `K` - VAT exempt for EEA intra-community supply of goods and services\n",
"nullable": true
},
"special_regime_key": {
"type": "string",
"example": "01",
"nullable": true,
"enum": [
"01",
"02",
"03",
"04",
"05",
"06",
"07",
"08",
"09",
"10",
"11",
"12",
"13",
"14",
"15",
"17",
"18",
"19",
"20",
"51",
"52",
"53",
"54",
null
],
"description": "VAT regime key and operations with tax significance.\n\n- [Verifactu codes](https://developer.b2brouter.net/docs/verifactu#special-regime-key-codes).\n- TicketBAI codes: `01`,`02`,`03`,`04`,`05`,`06`,`07`,`08`,`09`,`10`,`11`,`14`,`15`,`17`,`18`,`19`,`51`,`52`,`53`,`54`.\n"
},
"non_exempt": {
"type": "boolean",
"example": true
},
"non_exemption_code": {
"type": "string",
"example": "S1",
"description": "Reason code for No Exempt. \n[Verifactu codes](https://developer.b2brouter.net/docs/verifactu#non-exemption-codes)\n",
"nullable": true
},
"no_subject": {
"type": "boolean",
"example": false,
"default": false
},
"no_subject_code": {
"type": "string",
"nullable": true,
"enum": [
"N1",
"N2",
"OT",
"RL",
"IE",
"VT",
"np II",
null
],
"description": "Reason code for No Suject. \n- [Verifactu codes](https://developer.b2brouter.net/docs/verifactu#non-subject-codes)\n- TicketBAI codes: `OT`, `RL`, `IE`, `VT`.\n\nThis field is required when `no_subject` is set to true.\n"
},
"exempt": {
"type": "boolean",
"example": false
},
"exemption_code": {
"type": "string",
"nullable": true,
"enum": [
"E1",
"E2",
"E3",
"E4",
"E5",
"E6",
"zw",
null
],
"description": "Reason code for VAT Exemption. \n[Verifactu and TicketBAI codes](https://developer.b2brouter.net/docs/verifactu#exemption-codes).\n\nThis field is required when `exempt` is set to true.\n"
},
"kind_equivalence_surcharge": {
"type": "string",
"nullable": true,
"writeOnly": true
},
"scope": {
"type": "string",
"enum": [
"domestic",
"international"
],
"example": "domestic",
"writeOnly": true
},
"type_operation": {
"type": "string",
"enum": [
"services",
"goods",
null
],
"example": "services",
"nullable": true
},
"amend": {
"type": "boolean",
"example": false,
"writeOnly": true
},
"withheld": {
"type": "boolean",
"example": false,
"default": false,
"writeOnly": true
},
"investment_good": {
"type": "boolean",
"example": false,
"default": false,
"writeOnly": true
},
"comment": {
"type": "string",
"nullable": true,
"writeOnly": true
},
"percent": {
"type": "number",
"format": "decimal",
"example": 21,
"nullable": true
},
"taxable_base": {
"type": "number",
"format": "decimal",
"example": 123
},
"tax_amount": {
"type": "number",
"format": "decimal",
"example": 25.83
},
"tax_amount_equivalence_surcharge": {
"type": "number",
"format": "decimal",
"example": 0,
"writeOnly": true
},
"taxable_base_at_cost": {
"type": "number",
"format": "decimal"
}
},
"xml": {
"name": "tax_breakdown"
}
},
"TaxReportLine": {
"type": "object",
"required": [
"quantity",
"description",
"price",
"tax_inclusive_amount"
],
"description": "A group of business terms providing information on individual Tax Report lines. This is used when creating TicketBAI and KSeF Tax Reports.",
"properties": {
"id": {
"type": "integer",
"example": 435453,
"description": "A unique identifier for this TaxReportLine across all the system.",
"readOnly": true
},
"quantity": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "Invoiced quantity.",
"example": 1
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"description": "The price of an item, exclusive of VAT.",
"example": 10
},
"description": {
"type": "string",
"description": "Item Name.",
"maxLength": 65535,
"nullable": true,
"example": "Item 1"
},
"discount_amount": {
"anyOf": [
{
"type": "number",
"nullable": true
},
{
"type": "string"
}
],
"description": "Discount amount. \nFor KSeF it's the discount unit price.\n",
"example": 1
},
"charge_amount": {
"anyOf": [
{
"type": "number",
"nullable": true
},
{
"type": "string"
}
],
"description": "Charge amount.",
"example": 4
},
"tax_inclusive_amount": {
"anyOf": [
{
"type": "number",
"nullable": true
},
{
"type": "string"
}
],
"description": "The total amount of the line including taxes.",
"example": 121
},
"tax_exclusive_amount": {
"anyOf": [
{
"type": "number",
"nullable": true
},
{
"type": "string"
}
],
"description": "The total amount of the line excluding taxes.",
"example": 100
},
"tax_amount": {
"anyOf": [
{
"type": "number",
"nullable": true
},
{
"type": "string"
}
],
"description": "The total tax amount of the line.",
"example": 21
},
"position": {
"type": "integer",
"description": "Position/sequence number of the line in the document. Specific to KSeF (Polish tax reporting).",
"example": 1,
"nullable": true
},
"unit_code": {
"type": "string",
"description": "Unit of measure code for the invoiced quantity. Specific to KSeF (Polish tax reporting).",
"example": "PCE",
"nullable": true
},
"tax_code": {
"type": "string",
"enum": [
"23",
"22",
"8",
"7",
"5",
"4",
"3",
"0 WDT",
"0 EX",
"0 KR",
"zw",
"oo",
"np I",
"np II"
],
"description": "Tax category/code for this line item. Specific to KSeF (Polish tax reporting).\n\nValid values for KSeF:\n* `23` - Standard VAT rate 23%\n* `22` - Standard VAT rate 22%\n* `8` - Reduced VAT rate 8%\n* `7` - Reduced VAT rate 7%\n* `5` - Reduced VAT rate 5%\n* `4` - Reduced VAT rate 4%\n* `3` - Reduced VAT rate 3%\n* `0 WDT` - Intra-Community Supply 0% (Wewnątrzwspólnotowa Dostawa Towarów)\n* `0 EX` - Export 0%\n* `0 KR` - Domestic zero-rated 0%\n* `zw` - Exempt from VAT (zwolniona)\n* `oo` - Reverse charge domestic (odwrotne obciążenie)\n* `np I` - Not subject to VAT - cross-border services (nie podlega)\n",
"example": "23",
"nullable": true
},
"ksef_amended": {
"type": "boolean",
"description": "Indicates if this line is part of an amendment/correction. Specific to KSeF (Polish tax reporting).",
"example": false,
"nullable": true
},
"item_seller_identifier": {
"type": "string",
"nullable": true,
"description": "An identifier, assigned by the Seller, for the item.\nUsed for TicketBAI and KSeF Tax Reports.",
"example": "SELLER-123"
},
"item_standard_identifier": {
"type": "string",
"nullable": true,
"description": "An item identifier based on a registered scheme (e.g. GTIN).\nUsed for TicketBAI and KSeF Tax Reports.",
"example": "05012345678900"
}
}
},
"TaxReport": {
"type": "object",
"description": "Represents a TaxReport object, such as the ones generated by Verifactu",
"properties": {
"id": {
"type": "integer",
"example": 6560,
"description": "An internal identifier that is unique to each **Tax report** within B2Brouter.\n"
},
"type": {
"type": "string",
"example": "Verifactu",
"enum": [
"Verifactu",
"TicketBai",
"Sdi",
"MyInvois",
"Zatca",
"Ksef",
"SiiDocument"
]
},
"book_type": {
"type": "string",
"enum": [
"Expedida",
"Recibida",
"Inversion",
"Intracomunitaria",
"Metalico",
"Seguro",
"Viajesagencia",
"Cobro",
"Pago"
],
"description": "Required when `type` is `SiiDocument`. Selects which SII book the record belongs to. Drives both the AEAT envelope (e.g. `SuministroLRFacturasEmitidas` for `Expedida`) and the validation rules applied at create time.\n* `Expedida` — issued invoices * `Recibida` — received invoices * `Inversion` — capital goods (bienes de inversión) * `Intracomunitaria` — intra-EU operations * `Metalico` — cash transactions (≥ €6,000 / counterparty / period) * `Seguro` — insurance operations * `Viajesagencia` — travel agency special regime * `Cobro` — payments received against issued invoices (A0 only;\n PATCH and DELETE return 422 — AEAT XSD has no A1/B variants)\n* `Pago` — payments made against received invoices (A0 only)"
},
"invoice_id": {
"type": "integer",
"example": 77,
"description": "An internal identifier that is unique to each **Invoice** within B2Brouter.\n",
"nullable": true
},
"state": {
"type": "string",
"example": "registered",
"enum": [
"new",
"processing",
"signed",
"sending",
"sent",
"acknowledged",
"deposited",
"clearing",
"registered",
"registered_with_errors",
"error",
"refused",
"annullating",
"annulled",
"invalid"
],
"description": "States for a Tax Report (not every authority uses every state):\n * `new` - The TaxReport is created and validated, ready for further actions.\n * `processing` - Initial state of a TaxReport. The report is being signed and validated.\n * `signed` - The report is signed and validated and ready for transmission.\n * `sending` - The report is in the queue for transmission.\n * `sent` - The report was successfully transmitted.\n * `acknowledged` - The authority acknowledged receipt (e.g. DGFiP deposit ack).\n * `deposited` - The report was deposited on the authority platform (DGFiP Flux 1).\n * `clearing` - The report is awaiting clearance by the authority.\n * `registered` - The TaxReport has been registered by the Tax Authority.\n * `registered_with_errors` - Registered, but the authority returned per-record errors (SII `AceptadoConErrores`).\n * `error` - There was an error during submission, or it was rejected by the Tax Authority.\n * `refused` - The authority refused the submission.\n * `annullating` - An annullation (baja) is in progress.\n * `annulled` - The report was annulled.\n * `invalid` - The report failed validation checks.\n",
"readOnly": true
},
"qr": {
"type": "string",
"description": "The QR code codified in base64 of the tax report.\n",
"readOnly": true,
"nullable": true
},
"xml_base64": {
"type": "string",
"description": "The XML representation of the tax report codified in base64.\n",
"readOnly": true,
"nullable": true
},
"identifier": {
"type": "string",
"description": "Unique identifier for the tax report, usually assigned or provided by the Tax Authority.\nIn the case of Verifactu, this field contains the URL hosted by the AEAT that allows the Buyer to check\nthat the invoice has been properly submitted to the TA.\n",
"readOnly": true,
"nullable": true
},
"fingerprint": {
"type": "string",
"description": "The unique hash that identifies the tax report.\n",
"readOnly": true,
"nullable": true
},
"previous_id": {
"type": "integer",
"example": 6560,
"description": "Internal identifier of the **Tax report** in the previous link of the chain.\n",
"readOnly": true,
"nullable": true
},
"sent_at": {
"type": "string",
"format": "date-time",
"example": "2025-04-10T10:14:31Z",
"nullable": true,
"readOnly": true
},
"digested_at": {
"type": "string",
"format": "date-time",
"example": "2025-04-10T10:14:31Z",
"nullable": true,
"readOnly": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2025-04-10T10:14:21.157690000Z",
"readOnly": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2025-04-10T10:14:29.259065000Z",
"readOnly": true
},
"label": {
"type": "string",
"example": "Verifactu A/1"
},
"has_errors": {
"type": "boolean",
"example": false,
"description": "Indicates if there are any errors in the report.",
"readOnly": true
},
"errors": {
"type": "array",
"description": "Errors associated with the tax report. For tax-authority rejections (e.g. an\nunknown counterparty NIF in SII) this carries the authority's `error_code` and\n`error_description`. Always present in responses; empty when there are no errors.\n",
"readOnly": true,
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "4102",
"description": "The authority (or B2Brouter) error code.",
"readOnly": true
},
"description": {
"type": "string",
"example": "El NIF del primer registro no está identificado en el censo de la AEAT.",
"description": "Human-readable description of the error.",
"readOnly": true
}
}
}
},
"has_warnings": {
"type": "boolean",
"nullable": true,
"description": "Indicates if there are any warnings in the report.",
"readOnly": true
},
"from_net": {
"type": "string",
"nullable": true,
"readOnly": true
},
"from_net_id": {
"type": "string",
"nullable": true,
"readOnly": true
},
"to_net": {
"type": "string",
"example": "b2brouter",
"readOnly": true,
"nullable": true
},
"to_net_id": {
"type": "string",
"example": "A-TGEZLKMKVK9VVN",
"readOnly": true,
"nullable": true
},
"ledger_id": {
"type": "integer",
"example": 1096,
"description": "An internal identifier that is unique to each **Ledger** within B2Brouter.\n",
"readOnly": true,
"nullable": true
},
"tax_report_setting_id": {
"type": "integer",
"example": 624,
"description": "Internal identifier of the **TaxReportSetting** that governs this report. Resolved\nserver-side from the account and tax authority; any value sent on create/update is ignored.\n",
"readOnly": true
},
"document_type_code": {
"type": "string",
"example": "xml.tax_report.verifactu.alta"
},
"transport_type_code": {
"type": "string",
"example": "es.verifactu"
},
"annulled_by_id": {
"type": "integer",
"nullable": true,
"readOnly": true,
"description": "Internal identifier of the **Tax report** that annulled this one.\n"
},
"corrected_by_id": {
"type": "integer",
"nullable": true,
"readOnly": true,
"description": "Internal identifier of the **Tax report** that corrected this one.\n"
},
"generation_timestamp": {
"type": "string",
"format": "date-time",
"example": "2025-04-10T10:14:25.337580000Z",
"nullable": true
},
"tax_point_date": {
"type": "string",
"nullable": true
},
"invoice_date": {
"type": "string",
"format": "date",
"example": "2025-04-10",
"nullable": true
},
"invoice_number": {
"type": "string",
"example": "111234126332",
"nullable": true
},
"invoice_series_code": {
"type": "string",
"nullable": true
},
"fiscal_year": {
"type": "integer",
"nullable": true
},
"fiscal_period": {
"type": "string",
"nullable": true
},
"amended_number": {
"type": "string",
"nullable": true
},
"amended_series_code": {
"type": "string",
"nullable": true
},
"amended_date": {
"type": "string",
"nullable": true
},
"amended_line_extension": {
"type": "number",
"format": "decimal",
"nullable": true
},
"amended_tax_amount": {
"type": "number",
"format": "decimal",
"nullable": true
},
"amended_tax_exclusive": {
"type": "number",
"format": "decimal",
"nullable": true
},
"amended_tax_inclusive": {
"type": "number",
"format": "decimal",
"nullable": true
},
"amended_charge_total": {
"type": "number",
"format": "decimal",
"nullable": true
},
"amended_payable": {
"type": "number",
"format": "decimal",
"nullable": true
},
"amended_tax_amount_equivalence_surcharge": {
"type": "number",
"format": "decimal",
"nullable": true
},
"amend_type": {
"type": "string",
"nullable": true
},
"invoice_type_code": {
"type": "string",
"example": "F1",
"nullable": true,
"description": "Invoice type code. The available codes depend on the tax authority:\n\n**Verifactu and TicketBAI codes:**\n* `F1` - Factura (art. 6, 7.2 y 7.3 del RD 1619/2012)\n* `F2` - Factura Simplificada y Facturas sin identificación del destinatario (art. 6.1.d) RD 1619/2012\n* `F3` - Factura emitida en sustitución de facturas simplificadas facturadas y declaradas\n* `R1` - Factura Rectificativa (Error fundado en derecho y Art. 80 Uno Dos y Seis LIVA)\n* `R2` - Factura Rectificativa (Art. 80.3)\n* `R3` - Factura Rectificativa (Art. 80.4)\n* `R4` - Factura Rectificativa (Resto)\n* `R5` - Factura Rectificativa en facturas simplificadas\n\nSee [Verifactu documentation](https://developer.b2brouter.net/docs/verifactu#invoice-type-codes)\n\n**KSeF codes:**\n* `VAT` - Basic invoice\n* `KOR` - Corrective invoice\n* `ZAL` - Advance payment invoice (Article 106f sec. 4)\n* `ROZ` - Invoice per Article 106f sec. 3\n* `UPR` - Simplified invoice (Article 106e sec. 5 item 3)\n* `KOR_ZAL` - Corrective invoice for advance payment\n* `KOR_ROZ` - Corrective invoice for ROZ invoice\n\nSee [KSeF documentation](https://developer.b2brouter.net/docs/ksef#invoice-type-codes)\n"
},
"special_regime_key": {
"type": "string",
"example": "01",
"description": "Special regime key. This is only used when creating TicketBAI Tax Reports.",
"nullable": true
},
"special_regime_key_additional": {
"type": "string",
"example": "05",
"description": "Special regime key additional. This is only used when creating TicketBAI Tax Reports.",
"nullable": true
},
"type_operation": {
"type": "string",
"example": "services",
"description": "Type of operation. This is only used when creating TicketBAI Tax Reports.",
"nullable": true
},
"operation_type": {
"type": "string",
"nullable": true
},
"external_reference": {
"type": "string",
"nullable": true
},
"description": {
"type": "string",
"example": "Factura 111234126332",
"nullable": true
},
"annullation": {
"description": "Indicates whether the tax report represents an annulment of a previous report.\nTo cancel a tax report, use the [annullation endpoint](https://developer.b2brouter.net/v2025-10-13/reference/new-annulate-tax-report).\n",
"type": "boolean",
"example": false,
"default": false,
"readOnly": true
},
"correction": {
"description": "Indicates whether the tax report is a correction of a previous report",
"type": "boolean",
"example": false,
"readOnly": true
},
"ticket": {
"description": "Indicates whether the tax report corresponds to a simplified invoice (`invoice_type_code` field is F2 or R5).",
"type": "boolean",
"example": false,
"readOnly": true
},
"issued_by_third_party_or_receiver": {
"type": "boolean",
"example": false
},
"customer_party_name": {
"type": "string",
"example": "Ingent Grup Systems, SL",
"nullable": true
},
"customer_party_id": {
"type": "string",
"nullable": true
},
"customer_party_scheme": {
"type": "string",
"nullable": true
},
"customer_party_tax_id": {
"type": "string",
"example": "B63354243",
"nullable": true
},
"customer_party_tax_scheme": {
"type": "string",
"nullable": true
},
"customer_party_country": {
"type": "string",
"example": "es",
"nullable": true
},
"customer_party_address": {
"type": "string",
"example": "casa seva, 9",
"description": "Customer party address. This is only used when creating TicketBAI/KSeF Tax Reports.",
"nullable": true
},
"customer_party_postalcode": {
"type": "string",
"example": "08080",
"description": "Customer party postal code. This is only used when creating TicketBAI/KSeF Tax Reports.",
"nullable": true
},
"customer_party_city": {
"type": "string",
"example": "Warszawa",
"description": "Customer party city. This is only used when creating KSeF Tax Reports.",
"nullable": true
},
"customer_party_endpoint_id": {
"type": "string",
"nullable": true
},
"supplier_party_name": {
"type": "string",
"example": "B2Brouter Global S.L.",
"readOnly": true,
"nullable": true
},
"supplier_party_id": {
"type": "string",
"nullable": true,
"readOnly": true
},
"supplier_party_scheme": {
"type": "string",
"nullable": true,
"readOnly": true
},
"supplier_party_tax_id": {
"type": "string",
"example": "B63276174",
"readOnly": true,
"nullable": true
},
"supplier_party_tax_scheme": {
"type": "string",
"nullable": true,
"readOnly": true
},
"supplier_party_country": {
"type": "string",
"nullable": true,
"readOnly": true
},
"supplier_party_address": {
"type": "string",
"nullable": true,
"readOnly": true
},
"supplier_party_postalcode": {
"type": "string",
"nullable": true,
"readOnly": true
},
"supplier_party_city": {
"type": "string",
"nullable": true,
"readOnly": true
},
"supplier_party_endpoint_id": {
"type": "string",
"nullable": true,
"readOnly": true
},
"supplier_party_krs": {
"type": "string",
"nullable": true,
"description": "KRS (Krajowy Rejestr Sądowy) number of the supplier.\nSpecific to KSeF (Polish tax reporting)."
},
"supplier_party_regon": {
"type": "string",
"nullable": true,
"description": "REGON (statistical identification number) of the supplier.\nSpecific to KSeF (Polish tax reporting)."
},
"supplier_party_bdo": {
"type": "string",
"nullable": true,
"description": "BDO (waste database register) number of the supplier.\nSpecific to KSeF (Polish tax reporting)."
},
"supplier_contact_phone": {
"type": "string",
"nullable": true,
"description": "Supplier contact telephone number (BT-42).\nSpecific to KSeF (Polish tax reporting)."
},
"supplier_contact_email": {
"type": "string",
"nullable": true,
"description": "Supplier contact email address (BT-43).\nSpecific to KSeF (Polish tax reporting)."
},
"third_party_name": {
"type": "string",
"nullable": true,
"readOnly": true
},
"third_party_role": {
"type": "string",
"nullable": true,
"readOnly": true
},
"third_party_id": {
"type": "string",
"nullable": true,
"readOnly": true
},
"third_party_scheme": {
"type": "string",
"nullable": true,
"readOnly": true
},
"third_party_tax_id": {
"type": "string",
"nullable": true,
"readOnly": true
},
"third_party_tax_scheme": {
"type": "string",
"nullable": true,
"readOnly": true
},
"third_party_country": {
"type": "string",
"nullable": true,
"readOnly": true
},
"third_party_address": {
"type": "string",
"nullable": true,
"readOnly": true
},
"third_party_postalcode": {
"type": "string",
"nullable": true,
"readOnly": true
},
"third_party_city": {
"type": "string",
"nullable": true,
"readOnly": true
},
"third_party_endpoint_id": {
"type": "string",
"nullable": true,
"readOnly": true
},
"line_extension_amount": {
"type": "number",
"format": "decimal",
"nullable": true
},
"tax_amount": {
"type": "number",
"format": "decimal",
"example": 2583
},
"tax_amount_withheld": {
"type": "number",
"format": "decimal",
"example": 10,
"description": "Tax amount withheld. This is only used when creating TicketBAI Tax Reports.",
"nullable": true
},
"tax_exclusive_amount": {
"type": "number",
"format": "decimal",
"nullable": true
},
"tax_inclusive_amount": {
"type": "number",
"format": "decimal",
"example": 14883
},
"charge_total": {
"type": "number",
"format": "decimal",
"nullable": true
},
"payable_amount": {
"type": "number",
"format": "decimal",
"nullable": true
},
"tax_amount_equivalence_surcharge": {
"type": "number",
"format": "decimal",
"nullable": true
},
"currency": {
"type": "string",
"example": "EUR"
},
"original_currency": {
"type": "string",
"example": "EUR",
"nullable": true
},
"previously_refused": {
"type": "string",
"example": "S",
"description": "Specific of Verifactu",
"nullable": true
},
"simplified_art7273": {
"oneOf": [
{
"type": "string"
},
{
"type": "boolean"
}
],
"example": "S",
"description": "`FacturaSimplificadaArticulos7.2_7.3` flag.\nVerifactu: `'S'` or `'N'` (string).\nSII (`type: SiiDocument`, `book_type: Expedida` or `Recibida`): JSON boolean. Render as `S` when `true`; element is omitted when `false`."
},
"macrodata": {
"oneOf": [
{
"type": "string"
},
{
"type": "boolean"
}
],
"example": "N",
"description": "`Macrodato` flag — invoice total above the AEAT large-amount threshold.\nVerifactu: `'S'` or `'N'` (auto-computed from `tax_inclusive_amount` ≥ €100M).\nSII (`type: SiiDocument`, `book_type: Expedida` or `Recibida`): JSON boolean supplied by the client."
},
"coupon": {
"type": "string",
"example": "N",
"description": "Specific of Verifactu"
},
"reg_previo_ggee": {
"type": "boolean",
"default": false,
"description": "`RegPrevioGGEEoREDEMEoCompetencia` flag. Applies to `Expedida` and `Recibida`. Emits `S` when `true`; omitted when `false`.\nSpecific to SII."
},
"facturacion_disp_adicional_mercado_gas": {
"type": "boolean",
"default": false,
"description": "`FacturacionDispAdicionalTerceraYsextayDelMercadoOrganizadoDelGas` flag. Applies to `Expedida` only — the AEAT XSD defines this element on `FacturaExpedidaType`, not on the FacturaType base.\nSpecific to SII."
},
"sin_identif_destinatario_art_6_1_d": {
"type": "boolean",
"default": false,
"description": "`FacturaSinIdentifDestinatarioAritculo6.1.d` flag. `Expedida`-only per the AEAT XSD.\nSpecific to SII."
},
"fecha_contable": {
"type": "string",
"format": "date",
"nullable": true,
"example": "2026-04-15",
"description": "Accounting registration date (`FechaRegContable`). `Recibida`-only.\nDistinct from `tax_point_date` (which maps to `FechaOperacion`): the operation/service date can precede the accounting date by weeks if the invoice is booked later. If not set, the modern path falls back to `tax_point_date` then `invoice_date`.\nSpecific to SII."
},
"cuota_deducible_in_cents": {
"type": "integer",
"nullable": true,
"example": 2100,
"description": "Deductible quota for `Recibida` records (write side). When omitted, derived from the sum of `tax_breakdowns[*].tax_amount`. Real-world Recibida data often diverges from the breakdown sum (partial deductibility, regularization), so an explicit client value wins.\nSpecific to SII."
},
"cuota_deducible": {
"type": "number",
"format": "decimal",
"readOnly": true,
"description": "Read-side response field — deductible quota as decimal (EUR). Mirrors `cuota_deducible_in_cents` / 100.\nSpecific to SII Recibida."
},
"succession_party_name": {
"type": "string",
"nullable": true,
"description": "`EntidadSucedida` > `NombreRazon`. Used in business-succession reporting on `Expedida`, `Recibida`, `Inversion`, `Intracomunitaria`, `Metalico`, `Seguro`, `Viajesagencia`. Must be set together with `succession_party_tax_id`.\nSpecific to SII."
},
"succession_party_tax_id": {
"type": "string",
"nullable": true,
"description": "`EntidadSucedida` > `NIF`. Pairs with `succession_party_name`.\nSpecific to SII."
},
"billing_agreement_number": {
"type": "string",
"maxLength": 15,
"nullable": true,
"description": "`NumRegistroAcuerdoFacturacion`. Used on `Expedida`, `Recibida`, `Inversion`, `Intracomunitaria` records that fall under a pre-registered AEAT billing agreement.\nSpecific to SII."
},
"clave_declarado": {
"type": "string",
"enum": [
"D",
"R"
],
"nullable": true,
"description": "`ClaveDeclarado` enum. `Intracomunitaria`-only.\nSpecific to SII."
},
"plazo_operacion": {
"type": "string",
"maxLength": 3,
"nullable": true,
"description": "`PlazoOperacion` AEAT code. `Intracomunitaria`-only.\nSpecific to SII."
},
"facturas_o_documentacion": {
"type": "string",
"maxLength": 150,
"nullable": true,
"description": "`FacturasODocumentacion` free-text field. `Intracomunitaria`-only.\nSpecific to SII."
},
"identificacion_bien": {
"type": "string",
"maxLength": 40,
"nullable": true,
"description": "`IdentificacionBien` — capital good identifier. `Inversion`-only. Required when creating an `Inversion` record.\nSpecific to SII."
},
"fecha_inicio_utilizacion": {
"type": "string",
"format": "date",
"nullable": true,
"description": "`FechaInicioUtilizacion` — date the capital good entered use. `Inversion`-only. Required when creating an `Inversion` record.\nSpecific to SII."
},
"prorrata_anual_definitiva": {
"type": "string",
"format": "decimal",
"nullable": true,
"example": 95,
"description": "`ProrrataAnualDefinitiva` — definitive annual prorrata (0–100, 2 decimal places). `Inversion`-only. Required when creating an `Inversion` record.\nSpecific to SII."
},
"regularizacion_anual_deduccion_in_cents": {
"type": "integer",
"nullable": true,
"description": "`RegularizacionAnualDeduccion` in cents. `Inversion`-only, optional.\nSpecific to SII."
},
"identificacion_entrega": {
"type": "string",
"maxLength": 40,
"nullable": true,
"description": "`IdentificacionEntrega`. `Inversion`-only, optional.\nSpecific to SII."
},
"regularizacion_deduccion_efectuada_in_cents": {
"type": "integer",
"nullable": true,
"description": "`RegularizacionDeduccionEfectuada` in cents. `Inversion`-only, optional.\nSpecific to SII."
},
"csv": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "AEAT-assigned CSV (Código Seguro de Verificación) for the registered record. Set asynchronously after the AEAT submission succeeds.\nSpecific to SII."
},
"fecha_presentacion": {
"type": "string",
"format": "date-time",
"nullable": true,
"readOnly": true,
"description": "AEAT-assigned presentation timestamp (Madrid time zone). Set asynchronously after the AEAT submission succeeds.\nSpecific to SII."
},
"estado": {
"type": "string",
"nullable": true,
"readOnly": true,
"description": "Internal SII state (`Nuevo`, `Enviando`, `Correcto`, `Incorrecto`, `AceptadoConErrores`, `Error`). The CTC `state` field is the authoritative cross-authority signal; `estado` is exposed for SII-specific tooling that mirrors the legacy column.\nSpecific to SII."
},
"payments": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"properties": {
"fecha": {
"type": "string",
"format": "date"
},
"importe_in_cents": {
"type": "integer"
},
"medio": {
"type": "string"
},
"cuenta_o_medio": {
"type": "string"
}
}
},
"description": "Per-record payment events for `Cobro` and `Pago` — collections for `Cobro`, disbursements for `Pago` (the book type disambiguates the direction). Array of `{ fecha, importe_in_cents, medio, cuenta_o_medio }`.\nNot used by other book types — their nested data lives in flat columns above.\nSpecific to SII."
},
"payment_date": {
"type": "string",
"format": "date",
"example": "2025-04-10",
"nullable": true,
"description": "Payment date or payment due date for the invoice.\nSpecific to KSeF (Polish tax reporting).\nFor already paid invoices (Zaplacono=1), this represents the actual payment date (DataZaplaty). For unpaid invoices, this represents the payment due date (TerminPlatnosci)."
},
"payment_means_type_code": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 7,
"example": 6,
"description": "Payment means type code.\nSpecific to KSeF (Polish tax reporting).\nValid values for KSeF:\n * `1` - Cash \n * `2` - Card\n * `3` - Voucher\n * `4` - Check\n * `5` - Credit\n * `6` - Bank transfer\n * `7` - Mobile phone payment"
},
"payment_account_identifier": {
"type": "string",
"nullable": true,
"example": "PL61129030140002071219612874",
"description": "Payment account identifier.\nSpecific to KSeF (Polish tax reporting).\nA unique identifier of the financial payment account to which payment should be made. Can be an IBAN or local bank account number."
},
"payment_service_provider_identifier": {
"type": "string",
"nullable": true,
"example": "WBKPPLPP",
"description": "Payment service provider identifier.\nSpecific to KSeF (Polish tax reporting).\nBIC/SWIFT code or national clearing code of the payment service provider (bank) where the payment account is located."
},
"amended_ksef_number": {
"type": "string",
"example": "a1b2c3d4-e5f6-4789-ab12-cd34ef567890",
"nullable": true,
"description": "The KSeF number of the original invoice being amended. Used when creating an amendment/correction in KSeF. Specific to KSeF (Polish tax reporting)."
},
"order_total_amount": {
"type": "number",
"format": "decimal",
"nullable": true,
"description": "Total amount of the order (KSeF WartoscZamowienia field).\nRequired when `invoice_type_code` is `ZAL` or `KOR_ZAL`. Mapped automatically from the invoice when generating a tax report. Specific to KSeF (Polish tax reporting)."
},
"previous_advance_total": {
"type": "number",
"format": "decimal",
"nullable": true,
"description": "Total amount from the original advance payment invoice (KSeF P_15ZK field).\nRequired when `invoice_type_code` is `KOR_ZAL`. Stores the gross total of the ZAL invoice being corrected. Mapped automatically from the invoice's amend reference when generating from an invoice; set explicitly when creating via API.\nSpecific to KSeF (Polish tax reporting)."
},
"prepayment_references": {
"type": "array",
"description": "References to advance payment invoices (ZAL) settled by this ROZ invoice. Each entry maps to a `FakturaZaliczkowa` element in the KSeF FA(3) XML.\nRequired (non-empty) when `invoice_type_code` is `ROZ` or `KOR_ROZ`. Populated automatically from the invoice's prepayment references when generating from an invoice; set explicitly when creating via API.\nSpecific to KSeF (Polish tax reporting).",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "Internal identifier of the reference."
},
"number": {
"type": "string",
"nullable": true,
"description": "Invoice number of the advance payment invoice (KSeF NrFaZaliczkowej). Required when `registration_code` is absent."
},
"registration_code": {
"type": "string",
"nullable": true,
"description": "KSeF registration number of the advance payment invoice (KSeF NrKSeFFaZaliczkowej). Required when `number` is absent."
},
"_destroy": {
"type": "boolean",
"writeOnly": true,
"description": "Set to `true` to delete this reference (use with `id`)."
}
}
}
},
"payment_account_name": {
"type": "string",
"nullable": true,
"description": "Name of the payment account holder.\nSpecific to KSeF (Polish tax reporting)."
},
"purchase_order_reference": {
"type": "string",
"nullable": true,
"description": "Purchase order reference number.\nSpecific to KSeF (Polish tax reporting)."
},
"sales_order_reference": {
"type": "string",
"nullable": true,
"description": "Sales order reference number.\nSpecific to KSeF (Polish tax reporting)."
},
"purchase_order_date": {
"type": "string",
"format": "date",
"nullable": true,
"example": "2025-04-10",
"description": "Purchase order date (BT-92).\nSpecific to KSeF (Polish tax reporting)."
},
"despatch_advice_reference": {
"type": "string",
"nullable": true,
"description": "Despatch advice reference number (BT-16).\nSpecific to KSeF (Polish tax reporting)."
},
"tax_inclusive_amount_before_allowances_and_charges": {
"type": "number",
"format": "decimal",
"nullable": true,
"description": "Total amount including taxes, calculated before applying document-level allowances and charges.\nSpecific to KSeF (Polish tax reporting)."
},
"customer_party_jst": {
"type": "boolean",
"default": false,
"description": "KSeF Podmiot2 JST flag (Jednostka Samorządu Terytorialnego — Subordinate Local Government Unit).\ntrue: The buyer is a subordinate local government unit (requires Podmiot3 role=8). false: Does not apply (default).\nSpecific to KSeF (Polish tax reporting)."
},
"customer_party_gv": {
"type": "boolean",
"default": false,
"description": "KSeF Podmiot2 GV flag (Grupa VAT — VAT Group Member).\ntrue: The buyer is a member of a VAT group (requires Podmiot3 role=10). false: Does not apply (default).\nSpecific to KSeF (Polish tax reporting)."
},
"exchange_rate": {
"type": "number",
"format": "decimal",
"nullable": true,
"description": "Exchange rate used for currency conversion when the invoice currency differs from the tax authority's local currency (e.g., EUR invoice in Poland where local currency is PLN).\nFor KSeF (Poland): Required when invoice currency is not PLN.",
"example": 4.5123
},
"exchange_date": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Date of the exchange rate used for currency conversion.",
"example": "2025-04-10"
},
"tax_breakdowns": {
"type": "array",
"description": "One or more tax breakdowns (\"Desglose IVA\" in Verifactu)",
"items": {
"$ref": "#/components/schemas/TaxBreakdowns"
}
},
"tax_report_lines": {
"type": "array",
"description": "One or more tax report lines. This is used when creating TicketBAI and KSeF Tax Reports.",
"items": {
"$ref": "#/components/schemas/TaxReportLine"
}
},
"allowance_charges": {
"type": "array",
"description": "One or more allowance charges. This is used when creating KSeF Tax Reports.",
"items": {
"$ref": "#/components/schemas/AllowanceCharge"
}
}
}
}
}
}
}
```