# Supplying Jurisdiction Data

`jurisdictionalData` is an optional top-level field of `ReceiptPayload`. Supply
country-specific values from your POS, fiscal device, or authority integration.
The SDK encrypts them with the rest of the receipt.

## Example request fragment

```json
{
  "jurisdictionalData": {
    "countryCode": "US",
    "additionalFields": [
      {
        "code": "US:REGION",
        "value": "CA"
      }
    ]
  }
}
```

Only add this object when the selected country/regime has information without a
canonical receipt field. Merge it into the same `ReceiptPayload` that contains
`documentNumber`, amounts, products, taxes, and other merchant-supplied receipt
content.

Do not duplicate canonical receipt data
Use `jurisdictionalData` only for a value that has no suitable place in the
normal receipt or generation context. Do not repeat document numbers, dates,
party identities, payment means, products, prices, discounts, taxes, totals,
original-document references, or barcodes as country extension fields.

## Use canonical fields first

| Information | Canonical location |
|  --- | --- |
| Receipt/invoice number | `documentNumber` |
| Issue date | `issueDate` |
| Transaction/tax-point date | `transactionDate` |
| Purchase/delivery date | `purchaseDate` |
| Supplier legal identity and registrations | Server-known `supplier` context |
| Customer legal identity and registrations | Server-known `customerParty` context |
| Products, quantities, unit prices, and discounts | `products[]`, `discounts[]`, and `charges[]` |
| Tax rate, base, amount, and exemption | Receipt and product `taxes[]` |
| Currency and totals | `currency` and receipt total fields |
| Payment method, card, IBAN, merchant ID, or payment terminal ID | Encrypted `ReceiptPayload.paymentDetails`; put optional card MID/TID in `paymentDetails.merchantId` and `paymentDetails.paymentTerminalId`. |
| Original or related document | `identifiers[]`; use `originatorDocumentReference` for a credit note |
| QR or barcode payload | Top-level `barcodes[]` |
| Common fiscal evidence | Named fields under `fiscalization` |


Only after checking this table should you add a namespaced
`additionalFields[]` value. For example, Portugal's ATCUD has no generic
receipt field and therefore remains a Portuguese extension.

All example rates, amounts, identifiers, wording, and authority values are
illustrative. They are not defaults and must not replace current values from
your tax, POS, fiscal-device, or authority integration.

## `jurisdictionalData` fields

| Field | Required | Description |
|  --- | --- | --- |
| `countryCode` | Recommended | ISO 3166-1 alpha-2 issuance country. Explicit country wins over supplier-country fallback. |
| `regime` | No | External fiscal, authority, or regulated-system regime, such as `DE_KASSENSICHV`. Do not use it for ordinary document types. |
| `regimeVersion` | Recommended with `regime` | Version of Cheqi's data contract for the selected regime. |
| `fiscalization` | No | Final evidence returned by a POS, fiscal device, certified system, or authority integration. |
| `legalTexts` | No | Exact jurisdictional wording, with a stable code, optional BCP 47 language tag, and optional semantic `displayRole`. |
| `additionalFields` | No | Extensible country-specific values using the codes defined on each country page. |


New integrations should always set `countryCode`. Supplier-country fallback
exists for compatibility. If both are present, the explicit jurisdiction
country takes precedence.

Use `regime` and `regimeVersion` for external regime metadata.

## Fiscalization fields

Use common slots whenever one exists:

| Field | Description |
|  --- | --- |
| `system` | Fiscal regime, device, or provider identifier. |
| `status` | `FISCALIZED`, `NOT_REQUIRED`, `PENDING`, or `FAILED`. |
| `fiscalDocumentNumber` | Number allocated by the fiscal system. |
| `fiscalDeviceId` | Fiscal device, module, control unit, or certificate identifier. |
| `cashRegisterId` | Merchant cash-register identifier. |
| `businessPremiseId` | Registered business location or premise. |
| `operatorId` | Cashier or operator identifier. |
| `transactionId` | Fiscal transaction identifier. |
| `sequenceNumber` | Register or document sequence. |
| `authorityReference` | Authority submission, response, or registration reference. |
| `softwareId` | Certified or registered software identifier. |
| `verificationCode` | Authority- or device-produced verification value. |
| `signature` | Opaque signature or seal. |
| `signatureAlgorithm` | Algorithm label supplied by the producing system. |
| `verificationUrl` | Authority or provider verification URL. |
| `timestamp` | ISO 8601 fiscalization timestamp. |
| `additionalFields` | Country-specific fiscal values without a common slot. |


Do not duplicate a common value under a country code. For example, put a
register ID in `fiscalization.cashRegisterId`, not in a second
`DE:REGISTER_ID` field.

Do not create a `fiscalization` object merely to say that the selected country
regime is not fiscalized. Omit it when no external fiscal operation occurred.
Use `NOT_REQUIRED` only when the status itself is meaningful data produced by
the merchant's workflow.

## Status and operation order

For a receipt that depends on an external fiscal operation:

1. Complete the device/provider/authority operation.
2. Obtain its final evidence.
3. Set `status` to `FISCALIZED`.
4. Generate the receipt on the owner device.


Final receipt generation rejects `PENDING` and `FAILED`. `FISCALIZED` requires
at least one of `fiscalDocumentNumber`, `transactionId`, `authorityReference`,
`verificationCode`, or `signature`.

Use `NOT_REQUIRED` only when the merchant's own compliance logic has selected a
flow that does not require external fiscalization.

## Extension-field rules

The country pages define the authoritative extension codes. Examples:

```text
PT:ATCUD
GR:MYDATA_MARK
US:REGION
CH:VAT_INCLUDED
```

Codes:

- use uppercase country namespaces;
- may contain `A-Z`, `0-9`, `_`, `-`, `.`, and `:`;
- may be at most 64 characters;
- must be unique, case-insensitively, within their array.


Unknown future fields remain accepted, but integrations should reuse a
documented code when it already represents the value.

## Machine-readable codes

QR and barcode payloads are top-level receipt fields:

```json
{
  "barcodes": [
    {
      "type": "QR_CODE",
      "data": "exact-payload-produced-by-the-pos-or-authority",
      "label": "Fiscal verification"
    }
  ],
  "jurisdictionalData": {
    "countryCode": "DE",
    "regime": "DE_KASSENSICHV",
    "regimeVersion": "2026-07"
  }
}
```

The engine treats `data` as opaque. It preserves and references the payload but
does not construct, sign, parse, or normalize it.

## Legal text

```json
{
  "legalTexts": [
    {
      "code": "REVERSE_CHARGE_NOTICE",
      "text": "Exact wording supplied by the merchant system",
      "languageCode": "en-IE",
      "displayRole": "NOTICE"
    }
  ]
}
```

Use `displayRole` to tell a receiving or rendering application how the exact
text is intended to appear:

| Value | Meaning |
|  --- | --- |
| `DOCUMENT_HEADING` | A regulated document title or heading, for example the Belgian GKS ticket heading |
| `NOTICE` | A required legal or tax notice |
| `FOOTER` | A required footer line returned by a fiscal system |


The role is semantic: Cheqi preserves it but does not select the text, language,
or position for the merchant. Do not translate or paraphrase required wording
inside Cheqi.

`legalTexts` is not the merchant's free receipt message. That message is
configured on the company in the Cheqi app and remains available as CHEQI
`note` and UBL `cbc:Note`. Do not put it in the receipt payload.

## Output mapping

| Input | CHEQI JSON | UBL |
|  --- | --- | --- |
| `regime` + `regimeVersion` | Preserved in `jurisdictionalData` | `JURISDICTION_REGIME` and `JURISDICTION_REGIME_VERSION` document references |
| `legalTexts` | Preserved exactly, including `displayRole` | Cheqi jurisdictional-legal-text UBL extension |
| `additionalFields` | Preserved exactly | `cac:AdditionalDocumentReference` |
| `fiscalization` | Preserved exactly | Namespaced `cac:AdditionalDocumentReference` entries |
| `barcodes` | Preserved exactly | Machine-readable document references |
| `paymentMeans.merchantId` + `paymentMeans.paymentTerminalId` | Preserved exactly | Native `cac:Payment/cbc:MerchantID` and `cbc:PaymentTerminalID` in UBL PurchaseReceipt |


The engine writes the legal text to `ext:UBLExtensions` in UBL PurchaseReceipt,
Invoice, and CreditNote:

```xml
<ext:UBLExtensions>
  <ext:UBLExtension>
    <ext:ExtensionAgencyID>CHEQI</ext:ExtensionAgencyID>
    <ext:ExtensionVersionID>1</ext:ExtensionVersionID>
    <ext:ExtensionURI>urn:cheqi:ubl:extension:jurisdictional-legal-text:1</ext:ExtensionURI>
    <ext:ExtensionContent>
      <cheqi:JurisdictionalLegalTexts>
        <cheqi:LegalText
            code="REVERSE_CHARGE_NOTICE"
            displayRole="NOTICE"
            languageCode="en-IE">Exact wording supplied by the merchant system</cheqi:LegalText>
      </cheqi:JurisdictionalLegalTexts>
    </ext:ExtensionContent>
  </ext:UBLExtension>
</ext:UBLExtensions>
```

This deliberately does not use `cbc:Note`, so jurisdictional wording cannot
overwrite or become confused with the company-configured receipt message.

Cheqi regime identifiers are not written to UBL `cbc:ProfileID`. That element
is reserved for a genuine UBL customization/business-process profile and is
not inferred from country receipt data.

Cheqi keeps the generated documents encrypted during delivery to authorized
recipients.

The same jurisdiction structure is available on credit-note payloads.

## Related

- [Country capabilities and examples](/countries/profiles)
- [Country coverage and boundaries](/countries/overview)
- [Receipt creation](/receipts/creation)
- [Credit notes](/creditnote/credit-notes)