# Supplying Jurisdiction Data

`jurisdictionalData` is an optional top-level field of the merchant's plaintext
`ReceiptPayload`. The SDK encrypts that payload independently for every matched
owner device. Cheqi's backend stores and routes only the encrypted copies.

After decryption, the owner device combines the merchant payload with
server-known supplier, customer, payment, and store context and invokes the
Rust receipt engine locally.

## 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 | Server-known `paymentMeans` context from recipient resolution; use `merchantId` and `paymentTerminalId` for optional card MID/TID |
| 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.

Legacy input names `profile` and `profileVersion` remain accepted for encrypted
payloads created by older SDKs. New integrations must use `regime` and
`regimeVersion`.

## 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.

Every owner device generates and stores its CHEQI document locally. Only the
device holding the downstream distribution lease generates the formats
currently accepted by third parties, encrypts one envelope per recipient, and
submits ciphertext.

Generating a missing UBL document later is a wallet export fallback. It uses
CHEQI JSON stored locally on the device; the backend does not store plaintext
CHEQI JSON.

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)