**API versions** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=en)

# Receipts

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "description": "API"
  }
]
```

Recorded ordinary and fiscal receipts, with independently authorised document sources and existing PDF access.

## Operations

## GET /receipts

List ordinary and fiscal receipt records

`list_receipts`

Requires explicitly granted receipts:read; it is never a default permission. Lists existing ordinary and fiscal receipt records in the authenticated organisation. Filters combine with AND: kind, source paymentId, current source contactId, associationId, stored document period [from,before), and status. Use RFC 3339 instants with timezone for from/before; dates are compared as UTC instants. RECORDED means a stored record without a true deleted marker; WITHHELD includes cancellations and unpublished pending SEPA/KESHER records; UNKNOWN preserves an invalid deleted marker. Presence never proves PDF availability, email delivery, legal validity, capture or bank settlement. Queues without a stored document are absent; this endpoint does not predict eligibility or trigger issuance. Revalidates the current association and every linked payment/target/contact, plus the annual subscription, inside the organisation and campaign restriction. A historical reference or snapshot never grants authority. Annual documents have subscriptionId from paiement and actual paymentIds from paiements[]; grouped/annual records are omitted entirely when any source cannot be proven authorised. SERVICE legacy and unknown payment target types are withheld because this API has no admitted target owner. Receipt metadata includes document amountMinor in minor currency units only (5000 for EUR 50), and document currency only; missing or invalid historical values stay null, with no payment, organisation or snapshot fallback. No billing identity, reusable method, private configuration, provider response, URL or raw error is exposed. Returns stable kind then document UUID ascending order, default limit 50, maximum 200. Each call scans at most 1000 stored candidate records; an empty result can still have hasMore:true. Preserve filters and continue nextCursor until hasMore:false; count describes this page only, never the complete authorised total. A single document exceeding 200 source payments or allocation entries returns 409 RECEIPT_CATALOG_TOO_LARGE without partial authorisation; request owner review. Rejects unknown/repeated/structured query parameters, invalid UUIDs/dates/status/limit/cursor and non-empty request bodies with 400. No debit, refund, provider call, synchronisation, reconciliation, queue action, generation, regeneration or business mutation occurs; shared authentication may update API-key usage telemetry.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "kind",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  },
  "description": "Optional document kind; defaults to both kinds."
}
```

```json
{
  "name": "paymentId",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Filter by one actual source payment UUID, including a member of a group or annual receipt; never pass an annual subscription UUID here."
}
```

```json
{
  "name": "contactId",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Filter by a current same-organisation source-payment contact UUID, not a historical billing name."
}
```

```json
{
  "name": "associationId",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Filter by MAIN or a current issuing association UUID. Unknown/out-of-scope associations return no entries."
}
```

```json
{
  "name": "from",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Inclusive stored document datetime boundary, RFC 3339 instant with timezone. Documents with unknown datetime do not match a period."
}
```

```json
{
  "name": "before",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Exclusive stored document datetime boundary; must be after from when both are supplied."
}
```

```json
{
  "name": "status",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "RECORDED",
      "WITHHELD",
      "UNKNOWN"
    ]
  },
  "description": "Filter stored visibility status RECORDED, WITHHELD or UNKNOWN. This is not a financial or delivery state."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Maximum returned entries, from 1 to 200; only decimal integers are accepted."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "maxLength": 300
  },
  "description": "Opaque nextCursor from the previous result. Retain the same filters; continue even after an empty page with hasMore:true."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Authorised documentary metadata and bounded scan continuation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReceiptCatalogResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or unexpected query parameter, non-empty request body, UUID, period, status, limit or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing explicitly granted receipts:read scope or disabled organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "RECEIPT_CATALOG_TOO_LARGE: one document has more than 200 sources or allocation entries; owner review is required. No partial response is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: records could not be read. No financial or document operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/access

Read authorised access to an existing receipt PDF

`get_receipt_access`

Required scope: `receipts:read`, explicitly granted. Supply kind and id from the receipt catalogue. Accepts no query parameters or non-empty body. Revalidates the document and all current source payments, annual subscription, grouped members and linked targets inside the authenticated organisation and campaign restrictions; a stored snapshot or historical reference never widens access. Missing, deleted, inconsistent and out-of-scope records return 404. A fiscal receipt is distinct from an ordinary receipt. Metadata amountMinor is only the stored documentary amount in minor currency units; null amount or currency stays unknown, especially on older annual receipts. Document presence and access do not prove capture, bank settlement, legal validity or email delivery. Reads only an existing original: no generation, issuance, regeneration, synchronisation, queueing, provider call or business write. External documents remain UNAVAILABLE with EXTERNAL_ACCESS_REQUIRES_SAFE_OWNER until a provider-owned read port can validate tenant/configuration/destination; no arbitrary stored provider URL or unauthenticated legacy receipt URL is returned. Shared authentication may update API-key usage telemetry. Returns JSON with receipt metadata and access.status, reason, method, path, requiredScope, contentType and filename. AVAILABLE means a regular local file with a PDF header currently exists and is at most 25 MiB (26214400 bytes). GET access.path on the same trusted API origin using the same authorised credentials in headers (and X-Org-Id for root access). The PDF endpoint revalidates rights and storage, so availability can change. This tool reports metadata and access availability. Use download_receipt_pdf through MCP to retrieve the private file itself, or use the authenticated REST path. UNAVAILABLE has a null path/method and an actionable reason; never issue or regenerate a receipt to retry this read.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  },
  "description": "Document kind returned by the receipt catalogue. RECEIPT is an ordinary payment receipt; FISCAL_RECEIPT is a fiscal receipt, including annual documents."
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Document UUID returned by the receipt catalogue; this is not a payment or subscription identifier."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Receipt metadata and current access availability; UNAVAILABLE is a successful observation with no download path.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReceiptAccessResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_RECEIPT_KIND, INVALID_UUID, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY. Supply only the catalogue kind and document UUID.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing explicitly granted receipts:read scope or organisation access denied.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: missing, withheld, invalid-status, inconsistent or unauthorised document or current source. Annual and grouped receipts require every source to be authorised.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "RECEIPT_CATALOG_TOO_LARGE: source admission exceeds its safe bound of 200 source payments or allocation entries; request owner review, without truncating authorisation checks.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: document access could not be read; no document operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/pdf

Download the existing receipt PDF with authentication

`download_receipt_pdf`

Required scope: `receipts:read`, explicitly granted. Supply kind and id from the receipt catalogue. Accepts no query parameters or non-empty body. Revalidates the document and all current source payments, annual subscription, grouped members and linked targets inside the authenticated organisation and campaign restrictions; a stored snapshot or historical reference never widens access. Missing, deleted, inconsistent and out-of-scope records return 404. A fiscal receipt is distinct from an ordinary receipt. Metadata amountMinor is only the stored documentary amount in minor currency units; null amount or currency stays unknown, especially on older annual receipts. Document presence and access do not prove capture, bank settlement, legal validity or email delivery. Reads only an existing original: no generation, issuance, regeneration, synchronisation, queueing, provider call or business write. External documents remain UNAVAILABLE with EXTERNAL_ACCESS_REQUIRES_SAFE_OWNER until a provider-owned read port can validate tenant/configuration/destination; no arbitrary stored provider URL or unauthenticated legacy receipt URL is returned. Shared authentication may update API-key usage telemetry. Rechecks rights and reads an already stored regular local original with PDF header, maximum 25 MiB (26214400 bytes); symlinks, directories and other non-regular files are refused. Responds application/pdf with an attachment filename and no-store caching. If an admitted document has no usable original, returns 409 RECEIPT_PDF_UNAVAILABLE and a reason; retrieve access JSON or repair the existing original through its owner, without automatic document issuance. No redirect or provider fetch occurs.

MCP returns the actual private file as an embedded resource with MIME type and base64 blob, plus filename, byteLength and the SHA-256 of the decoded bytes. Use the host file capability to save or attach those bytes under the returned filename and verify size and SHA-256. The unisoft URI identifies this response only; it is not a public URL or a reusable download handle. Do not paste the blob into chat text, publicly upload a financial document or invent a sharing URL. The current authenticated REST owner rechecks organisation, permissions and every required source or export proof on each call. REST keeps its binary response. A file proves only that these bytes were retrieved, not payment settlement, document legal validity or delivery to a recipient.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  },
  "description": "Document kind returned by the receipt catalogue. RECEIPT is an ordinary payment receipt; FISCAL_RECEIPT is a fiscal receipt, including annual documents."
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Document UUID returned by the receipt catalogue; this is not a payment or subscription identifier."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Existing original PDF bytes; authenticated download, not JSON.",
  "content": {
    "application/pdf": {
      "schema": {
        "type": "string",
        "format": "binary"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_RECEIPT_KIND, INVALID_UUID, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY. Supply only the catalogue kind and document UUID.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing explicitly granted receipts:read scope or organisation access denied.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: missing, withheld, invalid-status, inconsistent or unauthorised document or current source. Annual and grouped receipts require every source to be authorised.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "RECEIPT_PDF_UNAVAILABLE with a fixed reason, or RECEIPT_CATALOG_TOO_LARGE when source admission exceeds 200 source payments or allocation entries. No document was generated or modified.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reason": {
            "type": "string",
            "enum": [
              "EXTERNAL_ACCESS_REQUIRES_SAFE_OWNER",
              "STORAGE_NOT_CONFIGURED",
              "PDF_UNAVAILABLE",
              "PDF_INVALID",
              "PDF_TOO_LARGE"
            ]
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: document access could not be read; no document operation was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-file": {
    "mimeType": "application/pdf",
    "maxBytes": 26214400
  }
}
```

## GET /abonnements/{id}/fiscal-grouping-preview

Preview native annual fiscal grouping candidates

`preview_annual_receipt_grouping`

Requires explicit receipts:read AND paiements:read AND abonnements:read. These are read-only annual grouping observations for an existing subscription UUID, not payment/document UUIDs or arbitrary payment groups. Supply required documentary year (1000–9999); the native receipt date/year rules apply, not stored record dates. preview_annual_receipt_grouping follows hooks/cerfa-year's native selector: existing annual subscription, FR/default issuer with noCerfa not true, COMPLETED payments not already linked to a fiscal receipt, positive fiscalContribution(payment,{annual:true}) in that year. Frozen fiscal snapshots override historical fallback. Unlike the unitary queue, the native annual selector does not exclude imported, finalized:false or ignoreCerfa payments; the preview describes that selector, not independent eligibility certification or permission to issue. All contributing payments, parent subscription, contacts and retained targets need current organisation/association/campaign authority. Only proven EUR histories are admitted because the native annual PDF owner has no explicit currency parameter. The whole source scan is bounded to 200 completed subscription payments and fails rather than truncating authority/totals. Unknown dates, currencies or snapshots are not zero or EUR defaults. No admitted candidates returns an owner-review refusal, not proof that no document exists. amountMinor is the candidate fiscal sum in minor EUR (5000 = EUR 50), distinct from the subscription nominal amount and issued documentary total. emissionSupported:false/TARGETED_ANNUAL_OWNER_REQUIRED means no targeted annual issuance command is currently offered; the exported annual daemon is global and must never be invoked for one caller. Do not use unitary issuance, new flags, payment import or internal routes to bypass that boundary. list_annual_receipt_groupings reads existing annual catalogue records for the exact subscription and year, independently reauthorising all sources; missing/inaccessible records are omitted. scanComplete refers only to this bounded authorised-record scan, never complete provider history or absence of an ongoing operation. Historical document amounts/currencies remain as recorded, including null. No generation, grouping write, fiscal-policy change, provider call or email occurs. Existing PDF access is separate; document presence proves neither capture, bank settlement, legal validity nor delivery. Accepts only year and no GET body.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:read",
  "additional": [
    "paiements:read",
    "abonnements:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "year",
  "in": "query",
  "required": true,
  "schema": {
    "type": "integer",
    "minimum": 1000,
    "maximum": 9999
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Authorised annual preview or recorded annual receipts.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/AnnualReceiptGroupingPreview"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID/year or unknown query/body input."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Required current grants missing."
}
```

#### HTTP 404

```json
{
  "description": "Subscription or source missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Unproven annual history/currency/snapshot, no admitted candidates or bound exceeded; request owner review without a truncated total or issuance fallback."
}
```

#### HTTP 500

```json
{
  "description": "Read unavailable; no business write was attempted."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-additional-scopes": [
    "paiements:read",
    "abonnements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /abonnements/{id}/fiscal-groupings

Read existing authorised annual fiscal groupings

`list_annual_receipt_groupings`

Requires explicit receipts:read AND paiements:read AND abonnements:read. These are read-only annual grouping observations for an existing subscription UUID, not payment/document UUIDs or arbitrary payment groups. Supply required documentary year (1000–9999); the native receipt date/year rules apply, not stored record dates. preview_annual_receipt_grouping follows hooks/cerfa-year's native selector: existing annual subscription, FR/default issuer with noCerfa not true, COMPLETED payments not already linked to a fiscal receipt, positive fiscalContribution(payment,{annual:true}) in that year. Frozen fiscal snapshots override historical fallback. Unlike the unitary queue, the native annual selector does not exclude imported, finalized:false or ignoreCerfa payments; the preview describes that selector, not independent eligibility certification or permission to issue. All contributing payments, parent subscription, contacts and retained targets need current organisation/association/campaign authority. Only proven EUR histories are admitted because the native annual PDF owner has no explicit currency parameter. The whole source scan is bounded to 200 completed subscription payments and fails rather than truncating authority/totals. Unknown dates, currencies or snapshots are not zero or EUR defaults. No admitted candidates returns an owner-review refusal, not proof that no document exists. amountMinor is the candidate fiscal sum in minor EUR (5000 = EUR 50), distinct from the subscription nominal amount and issued documentary total. emissionSupported:false/TARGETED_ANNUAL_OWNER_REQUIRED means no targeted annual issuance command is currently offered; the exported annual daemon is global and must never be invoked for one caller. Do not use unitary issuance, new flags, payment import or internal routes to bypass that boundary. list_annual_receipt_groupings reads existing annual catalogue records for the exact subscription and year, independently reauthorising all sources; missing/inaccessible records are omitted. scanComplete refers only to this bounded authorised-record scan, never complete provider history or absence of an ongoing operation. Historical document amounts/currencies remain as recorded, including null. No generation, grouping write, fiscal-policy change, provider call or email occurs. Existing PDF access is separate; document presence proves neither capture, bank settlement, legal validity nor delivery. Accepts only year and no GET body.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:read",
  "additional": [
    "paiements:read",
    "abonnements:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "year",
  "in": "query",
  "required": true,
  "schema": {
    "type": "integer",
    "minimum": 1000,
    "maximum": 9999
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Authorised annual preview or recorded annual receipts.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/AnnualReceiptGroupingRecords"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID/year or unknown query/body input."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Required current grants missing."
}
```

#### HTTP 404

```json
{
  "description": "Subscription or source missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Unproven annual history/currency/snapshot, no admitted candidates or bound exceeded; request owner review without a truncated total or issuance fallback."
}
```

#### HTTP 500

```json
{
  "description": "Read unavailable; no business write was attempted."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-additional-scopes": [
    "paiements:read",
    "abonnements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/cancellation-preview

Preview cancellation of one exact receipt

`preview_receipt_cancellation`

Requires explicit receipts:cancel AND receipts:read AND paiements:read, and an explicit user direction to cancel this exact document. This is document-only cancellation, never payment cancellation, refund, billing edit or fiscal-amount correction. First preview_receipt_cancellation with catalogue kind and document UUID; the preview is read-only. Only a currently authorised RECORDED local unitary document with one exact source payment is supported. Grouped, annual, external, already-withheld and already-cancelled/referenced histories need their owner. Fiscal cancellation additionally requires the exact complete unitary snapshot used by the native cancellation daemon, matching full documentary amount/currency and supported stored date; partial/missing historical snapshots are refused because the native daemon reads the total payment amount. Pass exact expectedRevision, a stable idempotencyKey and reason (3–500 characters) to request_receipt_cancellation. A durable principal/organisation journal and document claim precede the native-equivalent inline cancellation: mark the original deleted with its reason, detach its exact payment reference and set only that document queue's ignore flag to prevent automatic replacement. Payment state, money, association, billing and frozen fiscal split are preserved. A fiscal cancellation marker can subsequently be processed by the existing native cancellation-document/email daemon; no global daemon, PDF or mailer is called here. QUEUED acknowledges the cancellation request/markers, not a cancellation PDF issued, donor notified or replacement generated. A partial multi-document result is UNCERTAIN and is never automatically replayed. Read get_receipt_cancellation_request using the original UUID and same API principal/organisation after any doubt. Do not create another key, reset an ignore flag or call internal routes. Status independently reauthorises the frozen source payment and may return original metadata and the currently referenced replacement metadata. replacementRelation CURRENT_PAYMENT_DOCUMENT is an observed current payment reference, not proof of a formal legal replacement chain. A null original/replacement may reflect unavailable authority or no observed reference; it never authorises reissue. No correction of amount/identity or automatic replacement is exposed. Unknown body/query fields and GET bodies are refused; no bank settlement, capture, legal validity or email delivery is certified.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:cancel",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed cancellation preview or recorded request; inspect state and separately observed documents.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptCancellationPreview"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, reason, body or query."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Current explicit grants missing."
}
```

#### HTTP 404

```json
{
  "description": "Document, source or request missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Stale preview, idempotency conflict or unsupported cancellation history; no forced mutation or reissue."
}
```

#### HTTP 500

```json
{
  "description": "Unknown result; read the original request without replay."
}
```

#### HTTP 503

```json
{
  "description": "Durable request journal unavailable."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:cancel",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /receipts/{kind}/{id}/cancellation-requests

Request document-only cancellation with audit

`request_receipt_cancellation`

Requires explicit receipts:cancel AND receipts:read AND paiements:read, and an explicit user direction to cancel this exact document. This is document-only cancellation, never payment cancellation, refund, billing edit or fiscal-amount correction. First preview_receipt_cancellation with catalogue kind and document UUID; the preview is read-only. Only a currently authorised RECORDED local unitary document with one exact source payment is supported. Grouped, annual, external, already-withheld and already-cancelled/referenced histories need their owner. Fiscal cancellation additionally requires the exact complete unitary snapshot used by the native cancellation daemon, matching full documentary amount/currency and supported stored date; partial/missing historical snapshots are refused because the native daemon reads the total payment amount. Pass exact expectedRevision, a stable idempotencyKey and reason (3–500 characters) to request_receipt_cancellation. A durable principal/organisation journal and document claim precede the native-equivalent inline cancellation: mark the original deleted with its reason, detach its exact payment reference and set only that document queue's ignore flag to prevent automatic replacement. Payment state, money, association, billing and frozen fiscal split are preserved. A fiscal cancellation marker can subsequently be processed by the existing native cancellation-document/email daemon; no global daemon, PDF or mailer is called here. QUEUED acknowledges the cancellation request/markers, not a cancellation PDF issued, donor notified or replacement generated. A partial multi-document result is UNCERTAIN and is never automatically replayed. Read get_receipt_cancellation_request using the original UUID and same API principal/organisation after any doubt. Do not create another key, reset an ignore flag or call internal routes. Status independently reauthorises the frozen source payment and may return original metadata and the currently referenced replacement metadata. replacementRelation CURRENT_PAYMENT_DOCUMENT is an observed current payment reference, not proof of a formal legal replacement chain. A null original/replacement may reflect unavailable authority or no observed reference; it never authorises reissue. No correction of amount/identity or automatic replacement is exposed. Unknown body/query fields and GET bodies are refused; no bank settlement, capture, legal validity or email delivery is certified.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:cancel",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "reason": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision",
          "reason"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed cancellation preview or recorded request; inspect state and separately observed documents.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptCancellationRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, reason, body or query."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Current explicit grants missing."
}
```

#### HTTP 404

```json
{
  "description": "Document, source or request missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Stale preview, idempotency conflict or unsupported cancellation history; no forced mutation or reissue."
}
```

#### HTTP 500

```json
{
  "description": "Unknown result; read the original request without replay."
}
```

#### HTTP 503

```json
{
  "description": "Durable request journal unavailable."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:cancel",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /receipt-cancellation-requests/{requestId}

Read cancellation and current replacement reference

`get_receipt_cancellation_request`

Requires explicit receipts:cancel AND receipts:read AND paiements:read, and an explicit user direction to cancel this exact document. This is document-only cancellation, never payment cancellation, refund, billing edit or fiscal-amount correction. First preview_receipt_cancellation with catalogue kind and document UUID; the preview is read-only. Only a currently authorised RECORDED local unitary document with one exact source payment is supported. Grouped, annual, external, already-withheld and already-cancelled/referenced histories need their owner. Fiscal cancellation additionally requires the exact complete unitary snapshot used by the native cancellation daemon, matching full documentary amount/currency and supported stored date; partial/missing historical snapshots are refused because the native daemon reads the total payment amount. Pass exact expectedRevision, a stable idempotencyKey and reason (3–500 characters) to request_receipt_cancellation. A durable principal/organisation journal and document claim precede the native-equivalent inline cancellation: mark the original deleted with its reason, detach its exact payment reference and set only that document queue's ignore flag to prevent automatic replacement. Payment state, money, association, billing and frozen fiscal split are preserved. A fiscal cancellation marker can subsequently be processed by the existing native cancellation-document/email daemon; no global daemon, PDF or mailer is called here. QUEUED acknowledges the cancellation request/markers, not a cancellation PDF issued, donor notified or replacement generated. A partial multi-document result is UNCERTAIN and is never automatically replayed. Read get_receipt_cancellation_request using the original UUID and same API principal/organisation after any doubt. Do not create another key, reset an ignore flag or call internal routes. Status independently reauthorises the frozen source payment and may return original metadata and the currently referenced replacement metadata. replacementRelation CURRENT_PAYMENT_DOCUMENT is an observed current payment reference, not proof of a formal legal replacement chain. A null original/replacement may reflect unavailable authority or no observed reference; it never authorises reissue. No correction of amount/identity or automatic replacement is exposed. Unknown body/query fields and GET bodies are refused; no bank settlement, capture, legal validity or email delivery is certified.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:cancel",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed cancellation preview or recorded request; inspect state and separately observed documents.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptCancellationRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, reason, body or query."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Current explicit grants missing."
}
```

#### HTTP 404

```json
{
  "description": "Document, source or request missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Stale preview, idempotency conflict or unsupported cancellation history; no forced mutation or reissue."
}
```

#### HTTP 500

```json
{
  "description": "Unknown result; read the original request without replay."
}
```

#### HTTP 503

```json
{
  "description": "Durable request journal unavailable."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:cancel",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/delivery-preview

Preview resend to the proven documentary recipient

`preview_receipt_delivery`

Requires explicit receipts:send AND receipts:read AND paiements:read. First preview_receipt_delivery using the catalogue kind and document UUID (not a payment/subscription UUID). The preview returns a masked recipient and expectedRevision; it performs no mail or business write. Only a RECORDED local original with known documentary amount/currency/number and a usable existing PDF is supported. The stored documentary recipient must equal every current contributing payment recipient and, for annual documents, the current subscription recipient. A missing, changed or ambiguous recipient is refused; no arbitrary destination is accepted. Provider-owned originals require their safe delivery owner and are not fetched. Then pass the exact expectedRevision and one stable idempotencyKey to request_receipt_delivery. Rights, document sources, original and recipient are rechecked before a durable journal/claim and the native mailer.sendMailSystem idempotent outbox. The email contains the original native Unisoft document link, not a regenerated PDF or new number; the tool returns no public/provider URL or credentials and does not attach a PDF. QUEUED acknowledges a recorded email outbox only, never SENT or DELIVERED. Read get_receipt_delivery_request with the original request UUID and same API principal/organisation after a lost response. PENDING/UNCERTAIN never permits automatic replay, another key/principal or internal-route substitution. One external resend request is admitted per document; later requests require owner review. The status read does not send or poll a provider. A receipt and its minor-unit amount (5000 eur = EUR 50) are documentary observations, not proof of legal validity, capture, bank settlement or message delivery. No generation, cancellation, payment mutation or provider download is performed. Unknown request fields/query parameters and GET bodies are refused.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:send",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed delivery preview or recorded email request; inspect state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptDeliveryPreview"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or unknown input."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Current explicit grants missing."
}
```

#### HTTP 404

```json
{
  "description": "Source/request missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Original, recipient, preview revision or history requires owner review; no arbitrary address or regeneration fallback."
}
```

#### HTTP 500

```json
{
  "description": "Unknown result; read the original request without replay."
}
```

#### HTTP 503

```json
{
  "description": "Delivery configuration or durable request journal unavailable."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:send",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /receipts/{kind}/{id}/delivery-requests

Queue an existing receipt email without reissuance

`request_receipt_delivery`

Requires explicit receipts:send AND receipts:read AND paiements:read. First preview_receipt_delivery using the catalogue kind and document UUID (not a payment/subscription UUID). The preview returns a masked recipient and expectedRevision; it performs no mail or business write. Only a RECORDED local original with known documentary amount/currency/number and a usable existing PDF is supported. The stored documentary recipient must equal every current contributing payment recipient and, for annual documents, the current subscription recipient. A missing, changed or ambiguous recipient is refused; no arbitrary destination is accepted. Provider-owned originals require their safe delivery owner and are not fetched. Then pass the exact expectedRevision and one stable idempotencyKey to request_receipt_delivery. Rights, document sources, original and recipient are rechecked before a durable journal/claim and the native mailer.sendMailSystem idempotent outbox. The email contains the original native Unisoft document link, not a regenerated PDF or new number; the tool returns no public/provider URL or credentials and does not attach a PDF. QUEUED acknowledges a recorded email outbox only, never SENT or DELIVERED. Read get_receipt_delivery_request with the original request UUID and same API principal/organisation after a lost response. PENDING/UNCERTAIN never permits automatic replay, another key/principal or internal-route substitution. One external resend request is admitted per document; later requests require owner review. The status read does not send or poll a provider. A receipt and its minor-unit amount (5000 eur = EUR 50) are documentary observations, not proof of legal validity, capture, bank settlement or message delivery. No generation, cancellation, payment mutation or provider download is performed. Unknown request fields/query parameters and GET bodies are refused.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:send",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed delivery preview or recorded email request; inspect state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptDeliveryRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or unknown input."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Current explicit grants missing."
}
```

#### HTTP 404

```json
{
  "description": "Source/request missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Original, recipient, preview revision or history requires owner review; no arbitrary address or regeneration fallback."
}
```

#### HTTP 500

```json
{
  "description": "Unknown result; read the original request without replay."
}
```

#### HTTP 503

```json
{
  "description": "Delivery configuration or durable request journal unavailable."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:send",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /receipt-delivery-requests/{requestId}

Read receipt resend request without sending again

`get_receipt_delivery_request`

Requires explicit receipts:send AND receipts:read AND paiements:read. First preview_receipt_delivery using the catalogue kind and document UUID (not a payment/subscription UUID). The preview returns a masked recipient and expectedRevision; it performs no mail or business write. Only a RECORDED local original with known documentary amount/currency/number and a usable existing PDF is supported. The stored documentary recipient must equal every current contributing payment recipient and, for annual documents, the current subscription recipient. A missing, changed or ambiguous recipient is refused; no arbitrary destination is accepted. Provider-owned originals require their safe delivery owner and are not fetched. Then pass the exact expectedRevision and one stable idempotencyKey to request_receipt_delivery. Rights, document sources, original and recipient are rechecked before a durable journal/claim and the native mailer.sendMailSystem idempotent outbox. The email contains the original native Unisoft document link, not a regenerated PDF or new number; the tool returns no public/provider URL or credentials and does not attach a PDF. QUEUED acknowledges a recorded email outbox only, never SENT or DELIVERED. Read get_receipt_delivery_request with the original request UUID and same API principal/organisation after a lost response. PENDING/UNCERTAIN never permits automatic replay, another key/principal or internal-route substitution. One external resend request is admitted per document; later requests require owner review. The status read does not send or poll a provider. A receipt and its minor-unit amount (5000 eur = EUR 50) are documentary observations, not proof of legal validity, capture, bank settlement or message delivery. No generation, cancellation, payment mutation or provider download is performed. Unknown request fields/query parameters and GET bodies are refused.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:send",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed delivery preview or recorded email request; inspect state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptDeliveryRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or unknown input."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Current explicit grants missing."
}
```

#### HTTP 404

```json
{
  "description": "Source/request missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Original, recipient, preview revision or history requires owner review; no arbitrary address or regeneration fallback."
}
```

#### HTTP 500

```json
{
  "description": "Unknown result; read the original request without replay."
}
```

#### HTTP 503

```json
{
  "description": "Delivery configuration or durable request journal unavailable."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:send",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/provider-access

Read verified native KESHER original access

`get_provider_receipt_access`

Requires receipts:read AND paiements:read. Read-only access to the exact existing KESHER original, limited to native KESHER/KESHER.BIT payments and a currently authorised RECORDED unitary KESHER document. Only non-imported COMPLETED payments without a refund state or mixed fiscal amount and with automaticDocuments:true are admitted. Off-card, annual, grouped and other providers remain unsupported. The native KesherDocuments.validatePayment and verifiedDocument/GetTranData owner verifies current tenant/association configuration, project, transaction correlation, recorded amount/currency and the single live document reference; its ref must exactly match the stored original. No generation, reconciliation, operation preparation/completion, synchronisation, payment mutation or mail is run. Provider credentials, transaction payloads and provider URLs never enter the response. get_provider_receipt_access returns metadata plus a same-origin authenticated provider-pdf REST path, not a public/signed sharing link. VERIFIED_PROVIDER_REFERENCE verifies the provider reference; pdfAvailability:NOT_CHECKED does not promise a usable PDF. GET that path using the same trusted API origin/environment and the same authorised header credentials, never credentials in URLs. The binary endpoint repeats all current checks and downloads only the newly verified HTTPS provider URL on the native approved hosts, refuses redirects and nonstandard ports, applies a 15-second timeout/25 MiB cap, and requires PDF bytes. No arbitrary stored URL is fetched. Native provider transport itself is read-only, bounded and disallows redirects. 409 means unsupported/unproven original or changed source; 503 means provider/configuration/PDF read unavailable, without business effects. Do not issue/regenerate a replacement to retry access. Metadata monetary unknowns stay null; neither reference/PDF nor COMPLETED proves legal validity, capture or bank settlement. Use download_provider_receipt_pdf through MCP to retrieve the private original file. Unknown query parameters and GET bodies are rejected.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:read",
  "additional": [
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Verified provider reference and authenticated access instructions; PDF not yet probed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptProviderAccess"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid kind/UUID or unexpected read input."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Required current grants missing."
}
```

#### HTTP 404

```json
{
  "description": "Original/current source absent, withheld, inconsistent or outside authority."
}
```

#### HTTP 409

```json
{
  "description": "Provider original unsupported, unproven or source changed."
}
```

#### HTTP 500

```json
{
  "description": "Read unavailable; no business effect."
}
```

#### HTTP 503

```json
{
  "description": "Safe provider/configuration/PDF read unavailable."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-additional-scopes": [
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/provider-pdf

Download a verified native KESHER original PDF

`download_provider_receipt_pdf`

Requires receipts:read AND paiements:read. Read-only access to the exact existing KESHER original, limited to native KESHER/KESHER.BIT payments and a currently authorised RECORDED unitary KESHER document. Only non-imported COMPLETED payments without a refund state or mixed fiscal amount and with automaticDocuments:true are admitted. Off-card, annual, grouped and other providers remain unsupported. The native KesherDocuments.validatePayment and verifiedDocument/GetTranData owner verifies current tenant/association configuration, project, transaction correlation, recorded amount/currency and the single live document reference; its ref must exactly match the stored original. No generation, reconciliation, operation preparation/completion, synchronisation, payment mutation or mail is run. Provider credentials, transaction payloads and provider URLs never enter the response. get_provider_receipt_access returns metadata plus a same-origin authenticated provider-pdf REST path, not a public/signed sharing link. VERIFIED_PROVIDER_REFERENCE verifies the provider reference; pdfAvailability:NOT_CHECKED does not promise a usable PDF. GET that path using the same trusted API origin/environment and the same authorised header credentials, never credentials in URLs. The binary endpoint repeats all current checks and downloads only the newly verified HTTPS provider URL on the native approved hosts, refuses redirects and nonstandard ports, applies a 15-second timeout/25 MiB cap, and requires PDF bytes. No arbitrary stored URL is fetched. Native provider transport itself is read-only, bounded and disallows redirects. 409 means unsupported/unproven original or changed source; 503 means provider/configuration/PDF read unavailable, without business effects. Do not issue/regenerate a replacement to retry access. Metadata monetary unknowns stay null; neither reference/PDF nor COMPLETED proves legal validity, capture or bank settlement. Unknown query parameters and GET bodies are rejected.

MCP returns the actual private file as an embedded resource with MIME type and base64 blob, plus filename, byteLength and the SHA-256 of the decoded bytes. Use the host file capability to save or attach those bytes under the returned filename and verify size and SHA-256. The unisoft URI identifies this response only; it is not a public URL or a reusable download handle. Do not paste the blob into chat text, publicly upload a financial document or invent a sharing URL. The current authenticated REST owner rechecks organisation, permissions and every required source or export proof on each call. REST keeps its binary response. A file proves only that these bytes were retrieved, not payment settlement, document legal validity or delivery to a recipient.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:read",
  "additional": [
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Existing verified provider original PDF bytes, at most 25 MiB.",
  "content": {
    "application/pdf": {
      "schema": {
        "type": "string",
        "format": "binary"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid kind/UUID or unexpected read input."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Required current grants missing."
}
```

#### HTTP 404

```json
{
  "description": "Original/current source absent, withheld, inconsistent or outside authority."
}
```

#### HTTP 409

```json
{
  "description": "Provider original unsupported, unproven or source changed."
}
```

#### HTTP 500

```json
{
  "description": "Read unavailable; no business effect."
}
```

#### HTTP 503

```json
{
  "description": "Safe provider/configuration/PDF read unavailable."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-additional-scopes": [
    "paiements:read"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-file": {
    "mimeType": "application/pdf",
    "maxBytes": 26214400
  }
}
```

## GET /paiements/{id}/fiscal-receipt-preview

Inspect native fiscal-receipt eligibility

`preview_fiscal_receipt`

Requires explicit receipts:issue AND receipts:read AND paiements:read. An ordinary receipt and a fiscal receipt are different documents; paymentId/id is a payment UUID, requestId is the caller's original idempotency UUID, and a returned receipt.id is a document UUID. First call preview_fiscal_receipt and require eligible:true; pass its exact expectedRevision and one stable idempotencyKey to request_fiscal_receipt. Eligibility follows the native fiscal selector and getReceiptAmounts/fiscalContribution, including the frozen versioned policy; the command never turns cerfa on, changes the fiscal split or invents legal qualification. Only currently authorised ungrouped COMPLETED payments already marked cerfa:true, with a positive fiscal share, known currency/date, exact issuer and complete billing identity are supported. Formats FR, US, UK, CA, DE, CH and the native default follow the owner's configured model, not an independently certified tax verdict. Annual payments, NEDARIM, SEPA_XML, external formats, imports, refunds, existing fiscal documents, exclusions and prior fiscal failure markers require their owner. Preview is read-only and is an observation that can become stale. The POST journals and claims the payment durably before one exact organisation/BSON-CAS call to receipt_queue.reset(kind=cerfa). Native processing may later issue a numbered document and send its normal email unless dontSendReceipt prevents it; QUEUED acknowledges only queue admission, never ISSUED or DELIVERED. The status read revalidates current authority and may separately return current recorded receipt metadata. PENDING/UNCERTAIN, a lost response or missing PDF never permits automatic replay, a new idempotency key or credential substitution. Read the original request status using the same API principal and organisation. A null receipt is not evidence that no issuance is running. Amounts are minor currency units (5000 eur = EUR 50), not new money, legal validity, capture or bank settlement. No generator, provider, daemon or mailer is called directly by these endpoints. Unknown query fields and GET bodies are refused.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:issue",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed eligibility or recorded request; inspect the business state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/FiscalReceiptPreview"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, request body or unknown query/body fields."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Required current grants are missing."
}
```

#### HTTP 404

```json
{
  "description": "Source or request missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Stale preview, idempotency conflict or unsupported fiscal eligibility/history; request owner review without changing fiscal flags."
}
```

#### HTTP 500

```json
{
  "description": "Unknown result; inspect the original request without replay."
}
```

#### HTTP 503

```json
{
  "description": "Request journal unavailable; keep the original key and do not replay."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:issue",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /paiements/{id}/fiscal-receipt-requests

Request an eligible fiscal receipt through its queue

`request_fiscal_receipt`

Requires explicit receipts:issue AND receipts:read AND paiements:read. An ordinary receipt and a fiscal receipt are different documents; paymentId/id is a payment UUID, requestId is the caller's original idempotency UUID, and a returned receipt.id is a document UUID. First call preview_fiscal_receipt and require eligible:true; pass its exact expectedRevision and one stable idempotencyKey to request_fiscal_receipt. Eligibility follows the native fiscal selector and getReceiptAmounts/fiscalContribution, including the frozen versioned policy; the command never turns cerfa on, changes the fiscal split or invents legal qualification. Only currently authorised ungrouped COMPLETED payments already marked cerfa:true, with a positive fiscal share, known currency/date, exact issuer and complete billing identity are supported. Formats FR, US, UK, CA, DE, CH and the native default follow the owner's configured model, not an independently certified tax verdict. Annual payments, NEDARIM, SEPA_XML, external formats, imports, refunds, existing fiscal documents, exclusions and prior fiscal failure markers require their owner. Preview is read-only and is an observation that can become stale. The POST journals and claims the payment durably before one exact organisation/BSON-CAS call to receipt_queue.reset(kind=cerfa). Native processing may later issue a numbered document and send its normal email unless dontSendReceipt prevents it; QUEUED acknowledges only queue admission, never ISSUED or DELIVERED. The status read revalidates current authority and may separately return current recorded receipt metadata. PENDING/UNCERTAIN, a lost response or missing PDF never permits automatic replay, a new idempotency key or credential substitution. Read the original request status using the same API principal and organisation. A null receipt is not evidence that no issuance is running. Amounts are minor currency units (5000 eur = EUR 50), not new money, legal validity, capture or bank settlement. No generator, provider, daemon or mailer is called directly by these endpoints. Unknown query fields and GET bodies are refused.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:issue",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed eligibility or recorded request; inspect the business state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/FiscalReceiptRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, request body or unknown query/body fields."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Required current grants are missing."
}
```

#### HTTP 404

```json
{
  "description": "Source or request missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Stale preview, idempotency conflict or unsupported fiscal eligibility/history; request owner review without changing fiscal flags."
}
```

#### HTTP 500

```json
{
  "description": "Unknown result; inspect the original request without replay."
}
```

#### HTTP 503

```json
{
  "description": "Request journal unavailable; keep the original key and do not replay."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:issue",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /fiscal-receipt-requests/{requestId}

Read fiscal-receipt request status without replay

`get_fiscal_receipt_request`

Requires explicit receipts:issue AND receipts:read AND paiements:read. An ordinary receipt and a fiscal receipt are different documents; paymentId/id is a payment UUID, requestId is the caller's original idempotency UUID, and a returned receipt.id is a document UUID. First call preview_fiscal_receipt and require eligible:true; pass its exact expectedRevision and one stable idempotencyKey to request_fiscal_receipt. Eligibility follows the native fiscal selector and getReceiptAmounts/fiscalContribution, including the frozen versioned policy; the command never turns cerfa on, changes the fiscal split or invents legal qualification. Only currently authorised ungrouped COMPLETED payments already marked cerfa:true, with a positive fiscal share, known currency/date, exact issuer and complete billing identity are supported. Formats FR, US, UK, CA, DE, CH and the native default follow the owner's configured model, not an independently certified tax verdict. Annual payments, NEDARIM, SEPA_XML, external formats, imports, refunds, existing fiscal documents, exclusions and prior fiscal failure markers require their owner. Preview is read-only and is an observation that can become stale. The POST journals and claims the payment durably before one exact organisation/BSON-CAS call to receipt_queue.reset(kind=cerfa). Native processing may later issue a numbered document and send its normal email unless dontSendReceipt prevents it; QUEUED acknowledges only queue admission, never ISSUED or DELIVERED. The status read revalidates current authority and may separately return current recorded receipt metadata. PENDING/UNCERTAIN, a lost response or missing PDF never permits automatic replay, a new idempotency key or credential substitution. Read the original request status using the same API principal and organisation. A null receipt is not evidence that no issuance is running. Amounts are minor currency units (5000 eur = EUR 50), not new money, legal validity, capture or bank settlement. No generator, provider, daemon or mailer is called directly by these endpoints. Unknown query fields and GET bodies are refused.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:issue",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed eligibility or recorded request; inspect the business state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/FiscalReceiptRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, request body or unknown query/body fields."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Required current grants are missing."
}
```

#### HTTP 404

```json
{
  "description": "Source or request missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "Stale preview, idempotency conflict or unsupported fiscal eligibility/history; request owner review without changing fiscal flags."
}
```

#### HTTP 500

```json
{
  "description": "Unknown result; inspect the original request without replay."
}
```

#### HTTP 503

```json
{
  "description": "Request journal unavailable; keep the original key and do not replay."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:issue",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /paiements/{id}/receipt-requests

Request first ordinary-receipt queue admission

`request_ordinary_receipt`

Requires the explicitly granted receipts:issue scope AND receipts:read AND paiements:read. This is a request to the existing ordinary-receipt queue, not synchronous issuance. A payment UUID identifies the source; requestId is the original idempotency UUID and a document UUID is different. Only first admission of an ungrouped, currently authorised COMPLETED payment with an exact association, positive ordinary share, valid stored currency/date and complete printed billing identity is supported. Local FR, GR and CH (or the native default format) are admitted; NEDARIM, SEPA_XML, external documentary formats, imports, refund histories, groups, manual exclusions, existing documents and prior failures require their owner and are refused. Fiscal snapshots are authoritative; the command never changes amount, currency, association, fiscal choice, billing identity, finalisation or notification preferences. Native processing may subsequently produce a numbered document and send its normal email unless the stored dontSendReceipt preference prevents it. QUEUED means queue admission acknowledged, never ISSUED, email delivered, capture or bank settlement. A durable principal/organisation request journal and payment claim are acquired before the single native reset call. Another key or principal cannot restart that payment. PENDING/UNCERTAIN, including a lost response or final journal write, never permits automatic replay; read the original request status. No provider, PDF renderer or mailer is called directly by these endpoints. Current credentials, campaign restrictions and all retained source references are revalidated; historical snapshots grant no rights.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:issue",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Current source payment UUID, not a document or subscription UUID."
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid",
            "description": "Stable caller UUID for this exact ordinary-receipt request. Reuse it only to obtain its recorded result; never change it after uncertainty."
          }
        },
        "required": [
          "idempotencyKey"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Recorded queue request; inspect state and reason, not just success:true.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReceiptQueueRequestResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID/body, unknown fields/query parameters or a non-empty read body. Send only idempotencyKey in the POST body and no query parameters."
}
```

#### HTTP 401

```json
{
  "description": "Authentication is missing or invalid."
}
```

#### HTTP 403

```json
{
  "description": "Required explicit grants or current principal access are missing; do not substitute credentials."
}
```

#### HTTP 404

```json
{
  "description": "Request, payment, association or retained source is missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "IDEMPOTENCY_CONFLICT or receipt eligibility/history requires owner review. Do not change flags, fiscal choices or request keys to bypass the refusal."
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: no outcome can be inferred. Read the same request key before any further action."
}
```

#### HTTP 503

```json
{
  "description": "RECEIPT_JOURNAL_UNAVAILABLE or RECEIPT_JOURNAL_INVALID: the request journal is unavailable; no unjournalled reset is attempted. Keep the original request key."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:issue",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /receipt-requests/{requestId}

Read an ordinary-receipt queue request without replay

`get_ordinary_receipt_request`

Requires the explicitly granted receipts:issue scope AND receipts:read AND paiements:read. This is a request to the existing ordinary-receipt queue, not synchronous issuance. A payment UUID identifies the source; requestId is the original idempotency UUID and a document UUID is different. Only first admission of an ungrouped, currently authorised COMPLETED payment with an exact association, positive ordinary share, valid stored currency/date and complete printed billing identity is supported. Local FR, GR and CH (or the native default format) are admitted; NEDARIM, SEPA_XML, external documentary formats, imports, refund histories, groups, manual exclusions, existing documents and prior failures require their owner and are refused. Fiscal snapshots are authoritative; the command never changes amount, currency, association, fiscal choice, billing identity, finalisation or notification preferences. Native processing may subsequently produce a numbered document and send its normal email unless the stored dontSendReceipt preference prevents it. QUEUED means queue admission acknowledged, never ISSUED, email delivered, capture or bank settlement. A durable principal/organisation request journal and payment claim are acquired before the single native reset call. Another key or principal cannot restart that payment. PENDING/UNCERTAIN, including a lost response or final journal write, never permits automatic replay; read the original request status. No provider, PDF renderer or mailer is called directly by these endpoints. Current credentials, campaign restrictions and all retained source references are revalidated; historical snapshots grant no rights. Read-only journal observation for the same original API principal and organisation. Returns the recorded request and, when accessible, current receipt metadata. It does not rerun a reset, queue, generation, provider synchronisation or mail. A process stopped in PENDING remains unresolved; a receipt appearing later is observed independently and does not rewrite the original queue acknowledgment.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "receipts:issue",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Parameters

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Original idempotency UUID supplied to request_ordinary_receipt, with the same API principal and organisation."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Recorded queue request; inspect state and reason, not just success:true.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReceiptQueueRequestResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID/body, unknown fields/query parameters or a non-empty read body. Send only idempotencyKey in the POST body and no query parameters."
}
```

#### HTTP 401

```json
{
  "description": "Authentication is missing or invalid."
}
```

#### HTTP 403

```json
{
  "description": "Required explicit grants or current principal access are missing; do not substitute credentials."
}
```

#### HTTP 404

```json
{
  "description": "Request, payment, association or retained source is missing, inconsistent or outside current authority."
}
```

#### HTTP 409

```json
{
  "description": "IDEMPOTENCY_CONFLICT or receipt eligibility/history requires owner review. Do not change flags, fiscal choices or request keys to bypass the refusal."
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: no outcome can be inferred. Read the same request key before any further action."
}
```

#### HTTP 503

```json
{
  "description": "RECEIPT_JOURNAL_UNAVAILABLE or RECEIPT_JOURNAL_INVALID: the request journal is unavailable; no unjournalled reset is attempted. Keep the original request key."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:issue",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## Schemas

```json
{
  "components": {
    "schemas": {
      "ReceiptCatalogResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "meta"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ReceiptCatalogEntry"
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "count",
              "hasMore",
              "nextCursor"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 200
              },
              "hasMore": {
                "type": "boolean",
                "description": "True when another bounded scan can be made; it does not reveal an authorised total. A filtered or inaccessible batch can return no entries with hasMore:true."
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Opaque continuation in stable kind then document UUID ascending order. Keep the same filters and follow until hasMore:false, including after an empty page."
              }
            }
          }
        }
      },
      "ReceiptCatalogEntry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "kind",
          "status",
          "associationId",
          "annual",
          "subscriptionId",
          "paymentIds",
          "contactIds",
          "number",
          "year",
          "recordedAt",
          "amountMinor",
          "currency"
        ],
        "description": "Allowlisted metadata of one stored receipt, after complete current-source admission. No billing identity, snapshot, provider URL, private configuration or delivery proof is included.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Stable document UUID; distinct from payment and subscription identifiers. Use together with kind for document access."
          },
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT",
              "FISCAL_RECEIPT"
            ],
            "description": "RECEIPT is an ordinary receipt in recus; FISCAL_RECEIPT is a fiscal receipt in cerfas, including annual receipts."
          },
          "status": {
            "type": "string",
            "enum": [
              "RECORDED",
              "WITHHELD",
              "UNKNOWN"
            ],
            "description": "RECORDED means deleted is absent/null/false; WITHHELD means deleted:true, which can be cancellation or pending publication; UNKNOWN means an invalid stored deleted marker. No status asserts delivery, PDF availability or legal validity."
          },
          "associationId": {
            "type": "string",
            "description": "Current authorised issuing association, MAIN or an association UUID. Missing historical association means MAIN; an unknown secondary is never mapped to MAIN."
          },
          "annual": {
            "type": "boolean",
            "description": "True only for cerfaYear:true fiscal receipts. Its stored paiement is the subscription identifier, not a single payment."
          },
          "subscriptionId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Annual subscription identifier from the document paiement field; null on non-annual documents."
          },
          "paymentIds": {
            "type": "array",
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "All currently admitted source payment UUIDs, sorted. Annual receipts use paiements[]; grouped receipts require the complete current group. No partial group or annual total is returned."
          },
          "contactIds": {
            "type": "array",
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Distinct current source-payment contacts, after same-organisation readmission. IDs only; historical billing identities are never returned."
          },
          "number": {
            "type": "string",
            "nullable": true,
            "maxLength": 200,
            "description": "Stored non-negative integer num rendered as text; null when absent or invalid. External references are excluded because some are download capabilities."
          },
          "year": {
            "type": "integer",
            "nullable": true,
            "minimum": 1,
            "maximum": 9999,
            "description": "Stored documentary year, not inferred from current time or payment dates."
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Valid stored document datetime as an ISO instant. It records document storage, not bank settlement or confirmed email delivery. Invalid or unsupported historical values remain null."
          },
          "amountMinor": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Only stored document.amountMinor in minor currency units, for example 5000 for EUR 50. Missing, fractional, negative or unsafe values remain null. Never reconstructed from current payments, fiscal choices or snapshots."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$",
            "description": "Only the document's valid stored devise, normalised to lowercase. No organisation/payment fallback; annual or external historical documents can have null currency."
          }
        }
      },
      "ReceiptAccessResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "receipt",
              "access"
            ],
            "properties": {
              "receipt": {
                "$ref": "#/components/schemas/ReceiptCatalogEntry"
              },
              "access": {
                "$ref": "#/components/schemas/ReceiptPdfAccess"
              }
            }
          }
        }
      },
      "ReceiptPdfAccess": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "reason",
          "method",
          "path",
          "requiredScope",
          "contentType",
          "filename"
        ],
        "description": "Access to an already stored original PDF. Availability is checked at read time and can change before download; no new document or bearer link is created.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "AVAILABLE",
              "UNAVAILABLE"
            ],
            "description": "AVAILABLE means a regular local PDF passed the current storage probe; UNAVAILABLE means inspect reason. It is not a bank-settlement or legal-validity check."
          },
          "reason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "EXTERNAL_ACCESS_REQUIRES_SAFE_OWNER",
              "STORAGE_NOT_CONFIGURED",
              "PDF_UNAVAILABLE",
              "PDF_INVALID",
              "PDF_TOO_LARGE",
              null
            ],
            "description": "Null when available. EXTERNAL_ACCESS_REQUIRES_SAFE_OWNER needs a provider-owned read port that validates organisation, configuration and destination. STORAGE_NOT_CONFIGURED needs an absolute configured storage directory. PDF_UNAVAILABLE needs the stored original restored or storage access repaired. PDF_INVALID needs a valid stored original; PDF_TOO_LARGE exceeds the 25 MiB limit. Do not regenerate, synchronise or issue a document as a retry."
          },
          "method": {
            "type": "string",
            "nullable": true,
            "enum": [
              "GET",
              null
            ]
          },
          "path": {
            "type": "string",
            "nullable": true,
            "description": "When available, a relative /integrations/v2/receipts/{kind}/{id}/pdf path on this same trusted API origin. GET it with the same authorised credentials in Authorization or X-API-Key (and X-Org-Id for a root principal). This is an authenticated endpoint, not an anonymous or temporary sharing link; never put credentials in its URL."
          },
          "requiredScope": {
            "type": "string",
            "enum": [
              "receipts:read"
            ]
          },
          "contentType": {
            "type": "string",
            "enum": [
              "application/pdf"
            ]
          },
          "filename": {
            "type": "string",
            "description": "Suggested ASCII PDF filename derived only from the kind and document UUID."
          }
        }
      },
      "AnnualReceiptGroupingPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "subscriptionId",
          "associationId",
          "year",
          "paymentIds",
          "count",
          "amountMinor",
          "currency",
          "expectedRevision",
          "emissionSupported",
          "reason",
          "selection"
        ],
        "properties": {
          "subscriptionId": {
            "type": "string",
            "format": "uuid"
          },
          "associationId": {
            "type": "string"
          },
          "year": {
            "type": "integer",
            "minimum": 1000,
            "maximum": 9999
          },
          "paymentIds": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string",
            "enum": [
              "eur"
            ]
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "emissionSupported": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "reason": {
            "type": "string",
            "enum": [
              "TARGETED_ANNUAL_OWNER_REQUIRED"
            ]
          },
          "selection": {
            "type": "string",
            "enum": [
              "NATIVE_ANNUAL_SELECTOR"
            ]
          }
        }
      },
      "AnnualReceiptGroupingRecords": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "subscriptionId",
          "year",
          "receipts",
          "scanComplete",
          "coverage"
        ],
        "properties": {
          "subscriptionId": {
            "type": "string",
            "format": "uuid"
          },
          "year": {
            "type": "integer",
            "minimum": 1000,
            "maximum": 9999
          },
          "receipts": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ReceiptCatalogEntry"
            }
          },
          "scanComplete": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "coverage": {
            "type": "string",
            "enum": [
              "CURRENT_AUTHORISED_ANNUAL_RECORDS"
            ]
          }
        }
      },
      "ReceiptCancellationPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "kind",
          "documentId",
          "paymentId",
          "expectedRevision",
          "operation",
          "paymentUnchanged",
          "fiscalCancellationDocument"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT",
              "FISCAL_RECEIPT"
            ]
          },
          "documentId": {
            "type": "string",
            "format": "uuid"
          },
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "operation": {
            "type": "string",
            "enum": [
              "CANCEL_DOCUMENT"
            ]
          },
          "paymentUnchanged": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "fiscalCancellationDocument": {
            "type": "string",
            "enum": [
              "NATIVE_DAEMON",
              "NOT_APPLICABLE"
            ]
          }
        }
      },
      "ReceiptCancellationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "kind",
          "documentId",
          "paymentId",
          "state",
          "reason",
          "requestedAt",
          "updatedAt",
          "queueAcknowledged"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT",
              "FISCAL_RECEIPT"
            ]
          },
          "documentId": {
            "type": "string",
            "format": "uuid"
          },
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "REJECTED",
              "UNCERTAIN"
            ]
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "queueAcknowledged": {
            "type": "boolean",
            "nullable": true
          },
          "original": {
            "type": "object",
            "nullable": true,
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReceiptCatalogEntry"
              },
              {
                "enum": [
                  null
                ]
              }
            ]
          },
          "replacement": {
            "type": "object",
            "nullable": true,
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReceiptCatalogEntry"
              },
              {
                "enum": [
                  null
                ]
              }
            ]
          },
          "replacementRelation": {
            "type": "string",
            "nullable": true,
            "enum": [
              "CURRENT_PAYMENT_DOCUMENT",
              null
            ]
          }
        }
      },
      "ReceiptDeliveryPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "kind",
          "documentId",
          "expectedRevision",
          "recipient",
          "amountMinor",
          "currency",
          "documentNumber",
          "delivery",
          "originalOnly"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT",
              "FISCAL_RECEIPT"
            ]
          },
          "documentId": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "recipient": {
            "type": "string"
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string"
          },
          "documentNumber": {
            "type": "string"
          },
          "delivery": {
            "type": "string",
            "enum": [
              "EMAIL_LINK"
            ]
          },
          "originalOnly": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        }
      },
      "ReceiptDeliveryRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "kind",
          "documentId",
          "state",
          "reason",
          "requestedAt",
          "updatedAt",
          "queueAcknowledged"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "documentId": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT",
              "FISCAL_RECEIPT"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "REJECTED",
              "UNCERTAIN"
            ]
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "queueAcknowledged": {
            "type": "boolean",
            "nullable": true
          }
        }
      },
      "ReceiptProviderAccess": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "receipt",
          "access"
        ],
        "properties": {
          "receipt": {
            "$ref": "#/components/schemas/ReceiptCatalogEntry"
          },
          "access": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "status",
              "pdfAvailability",
              "method",
              "path",
              "requiredScopes",
              "contentType",
              "maxBytes"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "VERIFIED_PROVIDER_REFERENCE"
                ]
              },
              "pdfAvailability": {
                "type": "string",
                "enum": [
                  "NOT_CHECKED"
                ]
              },
              "method": {
                "type": "string",
                "enum": [
                  "GET"
                ]
              },
              "path": {
                "type": "string"
              },
              "requiredScopes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "contentType": {
                "type": "string",
                "enum": [
                  "application/pdf"
                ]
              },
              "maxBytes": {
                "type": "integer",
                "enum": [
                  26214400
                ]
              }
            }
          }
        }
      },
      "FiscalReceiptPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "paymentId",
          "eligible",
          "reason",
          "expectedRevision",
          "amountMinor",
          "currency",
          "format"
        ],
        "properties": {
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "eligible": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 1,
            "nullable": true
          },
          "currency": {
            "type": "string",
            "nullable": true
          },
          "format": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "FiscalReceiptRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "targetId",
          "state",
          "reason",
          "requestedAt",
          "updatedAt",
          "queueAcknowledged"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "targetId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "REJECTED",
              "UNCERTAIN"
            ]
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "queueAcknowledged": {
            "type": "boolean",
            "nullable": true
          },
          "receipt": {
            "type": "object",
            "nullable": true,
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReceiptCatalogEntry"
              },
              {
                "enum": [
                  null
                ]
              }
            ]
          }
        }
      },
      "ReceiptQueueRequestResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptQueueRequest"
          }
        }
      },
      "ReceiptQueueRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "paymentId",
          "kind",
          "state",
          "reason",
          "requestedAt",
          "updatedAt",
          "ordinaryAmountMinor",
          "currency",
          "queueAcknowledged",
          "receipt"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "REJECTED",
              "UNCERTAIN"
            ],
            "description": "Request journal state, not document state. QUEUED acknowledges native queue admission only. PENDING can include interrupted work; UNCERTAIN never permits replay."
          },
          "reason": {
            "type": "string",
            "nullable": true,
            "description": "Fixed reason for queue admission, refusal or uncertainty; no private owner error is returned."
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ordinaryAmountMinor": {
            "type": "integer",
            "minimum": 1,
            "nullable": true,
            "description": "Ordinary share admitted at request time, in minor currency units; 5000 eur means EUR 50. It is not an issued documentary amount or bank-settlement proof."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$"
          },
          "queueAcknowledged": {
            "type": "boolean",
            "nullable": true,
            "description": "True only for QUEUED, false for a recorded REJECTED request, null for PENDING/UNCERTAIN. Null is not evidence that the queue was unchanged."
          },
          "receipt": {
            "type": "object",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReceiptCatalogEntry"
              },
              {
                "enum": [
                  null
                ]
              }
            ],
            "nullable": true,
            "description": "Current separately authorised recorded document when observed by a status read, otherwise null. A null value does not prove no issuance is running. Its status and PDF access remain separate observations."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
