**Versions de l’API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=fr)

# Tickets

OpenAPI 3.0.3 · API 2.0.0

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

## Opérations

## GET /forms-submit/{submissionId}/ticket-documents/preview

Lire la révision courante de préparation du PDF de billets

`preview_submission_ticket_document`

Exige tickets:share ET forms:read ET forms_submit:read. Les clés restreintes à des campagnes sont refusées. Réadmet l’organisation courante, l’inscription, le formulaire/la session, les produits/catégories/sièges et les identités natives de billets globalement uniques ; un matching Mongo multikey n’accorde aucune propriété. Une modification de billets existants peut demander le push natif de rafraîchissement Wallet. L’aperçu annonce walletRefreshMayBeRequested et requiredAdditionalScopes ; la génération exige aussi messages:send dans ce cas, avant journal/garde. La seule émission de billets manquants ne demande aucun rafraîchissement Wallet. walletRefresh=NOT_OBSERVED signifie qu’aucun résultat de notification n’a été observé ; ne jamais en déduire qu’aucun rafraîchissement n’est nécessaire. Le PDF natif est anonyme et ne contient aucun montant financier : aucun droit de lecture des paiements n’est requis ni déduit. Le PDF contient lui-même des URL QR natives sensibles donnant accès aux billets et des références courtes. Le JSON ne contient jamais d’UUID natif de billet, QR, URL publique de billet, jeton de commande ni octets de fichier. Les UUID de document identifient cet artefact privé de la façade, pas les billets d’entrée. Sélections : VALID_ENTRY (par défaut) désigne les billets d’entrée VALID courants ; ALL_UNITS inclut les billets unitaires non révoqués déjà USED ; ORDER peut être un récapitulatif sans droit d’entrée ; SINGLE utilise une référence opaque tkt_ résolue uniquement dans cette inscription, hors billets révoqués. Un PDF ne prouve jamais le paiement, une acceptation au-delà de l’état enregistré de l’inscription, la disponibilité actuelle de l’entrée ni un pointage réussi. Le rendu réutilise la disposition native de quatre billets par A4, les sièges courants et le repli linguistique de l’inscription/organisation. Helvetica natif ne peut pas imprimer tous les alphabets : les titres/libellés personnalisés non pris en charge sont omis et les libellés fixes se replient vers l’anglais/français ; aucun logo ni ressource distante n’est chargé. Les libellés peuvent utiliser l’ellipse de la disposition native fixe. Au plus 500 billets imprimables, 1000 lignes historiques, 500 produits, 200 catégories, 8 MiB de PDF. Les quantités canoniques strictes et références courantes des snapshots sont requises ; un historique ambigu est refusé. Les writers internes restent concurrents ; les révisions de source sont des observations qualifiées, pas des réservations transactionnelles. Lecture pure : aucune réconciliation de billet, création/révocation/restauration, appel au rendu, écriture de fichier ni prestataire. Passer selection et, uniquement pour SINGLE, reference. currentPrintableCount décrit les billets avant génération ; reconciliationRequired signifie que la commande explicite appliquera d’abord le plan natif, le compte final peut donc différer. Retourner expectedRevision inchangé dans la demande de génération suivante. Une source modifiée exige une nouvelle lecture et une commande voulue séparément, jamais une révision devinée.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "tickets:share",
  "additional": [
    "forms:read",
    "forms_submit:read"
  ]
}
```

### Paramètres

```json
{
  "name": "submissionId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-f-]{36}$",
    "format": "uuid"
  },
  "description": "UUID de l’inscription courante ; jamais un UUID natif de billet."
}
```

```json
{
  "name": "selection",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "VALID_ENTRY",
      "ALL_UNITS",
      "ORDER",
      "SINGLE"
    ],
    "default": "VALID_ENTRY"
  },
  "description": "Sélection native explicite du PDF ; VALID_ENTRY par défaut."
}
```

```json
{
  "name": "reference",
  "in": "query",
  "schema": {
    "type": "string",
    "pattern": "^tkt_[a-f0-9]{64}$"
  },
  "description": "Requis uniquement pour SINGLE ; référence opaque issue de la liste autorisée des billets de cette inscription."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat qualifié de document privé de billets.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentPreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

### OpenAPI

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

## POST /forms-submit/{submissionId}/ticket-documents

Préparer les billets pour télécharger leur PDF à la demande

`generate_submission_ticket_document`

Exige tickets:share ET forms:read ET forms_submit:read. Les clés restreintes à des campagnes sont refusées. Réadmet l’organisation courante, l’inscription, le formulaire/la session, les produits/catégories/sièges et les identités natives de billets globalement uniques ; un matching Mongo multikey n’accorde aucune propriété. Une modification de billets existants peut demander le push natif de rafraîchissement Wallet. L’aperçu annonce walletRefreshMayBeRequested et requiredAdditionalScopes ; la génération exige aussi messages:send dans ce cas, avant journal/garde. La seule émission de billets manquants ne demande aucun rafraîchissement Wallet. walletRefresh=NOT_OBSERVED signifie qu’aucun résultat de notification n’a été observé ; ne jamais en déduire qu’aucun rafraîchissement n’est nécessaire. Le PDF natif est anonyme et ne contient aucun montant financier : aucun droit de lecture des paiements n’est requis ni déduit. Le PDF contient lui-même des URL QR natives sensibles donnant accès aux billets et des références courtes. Le JSON ne contient jamais d’UUID natif de billet, QR, URL publique de billet, jeton de commande ni octets de fichier. Les UUID de document identifient cet artefact privé de la façade, pas les billets d’entrée. Sélections : VALID_ENTRY (par défaut) désigne les billets d’entrée VALID courants ; ALL_UNITS inclut les billets unitaires non révoqués déjà USED ; ORDER peut être un récapitulatif sans droit d’entrée ; SINGLE utilise une référence opaque tkt_ résolue uniquement dans cette inscription, hors billets révoqués. Un PDF ne prouve jamais le paiement, une acceptation au-delà de l’état enregistré de l’inscription, la disponibilité actuelle de l’entrée ni un pointage réussi. Le rendu réutilise la disposition native de quatre billets par A4, les sièges courants et le repli linguistique de l’inscription/organisation. Helvetica natif ne peut pas imprimer tous les alphabets : les titres/libellés personnalisés non pris en charge sont omis et les libellés fixes se replient vers l’anglais/français ; aucun logo ni ressource distante n’est chargé. Les libellés peuvent utiliser l’ellipse de la disposition native fixe. Au plus 500 billets imprimables, 1000 lignes historiques, 500 produits, 200 catégories, 8 MiB de PDF. Les quantités canoniques strictes et références courantes des snapshots sont requises ; un historique ambigu est refusé. Les writers internes restent concurrents ; les révisions de source sont des observations qualifiées, pas des réservations transactionnelles. Exige aussi l’activation explicite et indépendante tickets:generate. Écriture explicite : le journal et les gardes globales de source/billets doivent être acquittés durablement avant que le plan natif crée, restaure ou révoque des billets. Les baisses de quantité préservent les billets USED ; la branche native d’inscription inactive peut révoquer même des billets USED en conservant usedAt et l’historique. Aucun réarmement, pointage, validation d’inscription, encaissement ou email. Les billets existants modifiés peuvent demander le rafraîchissement Wallet : REQUESTED ne prouve pas sa livraison et UNAVAILABLE ne permet pas de rejouer les billets. Appeler d’abord preview_submission_ticket_document. Fournir exactement son expectedRevision, sa sélection et une nouvelle idempotencyKey UUID ; conserver cette clé et la requête identique pour lire le résultat sans réexécution. Cette commande prépare les billets et ne conserve que ses métadonnées : elle ne génère ni ne stocke de PDF et ne nécessite aucune clé de chiffrement PDF. SUCCEEDED signifie préparation/réconciliation réussie, sans preuve de rendu ou de livraison. bytes, digest et generatedAt restent toujours null. Le downloadPath REST authentifié génère le PDF à la demande ; les octets peuvent différer entre téléchargements. RUNNING, UNKNOWN ou journalRecorded=false n’autorisent aucune régénération métier automatique, nouvelle clé de réessai, suppression de garde ni contournement interne. NO_TICKETS signifie qu’aucun billet sélectionné n’est imprimable après réconciliation. REFUSED est un conflit connu avant effet ; obtenir une nouvelle intention utilisateur avant une nouvelle clé. Un échec de nettoyage accessoire conserve le résultat connu avec lockCleanup=UNAVAILABLE et peut demander une revue propriétaire.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "tickets:generate",
  "additional": [
    "tickets:share",
    "forms:read",
    "forms_submit:read"
  ]
}
```

### Paramètres

```json
{
  "name": "submissionId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-f-]{36}$",
    "format": "uuid"
  },
  "description": "UUID de l’inscription courante dans cette organisation."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_547fb9088a38af49927c"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat qualifié de document privé de billets.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "tickets:generate",
  "x-unisoft-additional-scopes": [
    "tickets:share",
    "forms:read",
    "forms_submit:read"
  ],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "preview.walletRefreshMayBeRequested is true",
      "scopes": [
        "messages:send"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /ticket-documents/{documentId}

Lire une commande de document de billets et sa disponibilité actuelle

`get_ticket_document`

Exige tickets:share ET forms:read ET forms_submit:read. Les clés restreintes à des campagnes sont refusées. Réadmet l’organisation courante, l’inscription, le formulaire/la session, les produits/catégories/sièges et les identités natives de billets globalement uniques ; un matching Mongo multikey n’accorde aucune propriété. Une modification de billets existants peut demander le push natif de rafraîchissement Wallet. L’aperçu annonce walletRefreshMayBeRequested et requiredAdditionalScopes ; la génération exige aussi messages:send dans ce cas, avant journal/garde. La seule émission de billets manquants ne demande aucun rafraîchissement Wallet. walletRefresh=NOT_OBSERVED signifie qu’aucun résultat de notification n’a été observé ; ne jamais en déduire qu’aucun rafraîchissement n’est nécessaire. Le PDF natif est anonyme et ne contient aucun montant financier : aucun droit de lecture des paiements n’est requis ni déduit. Le PDF contient lui-même des URL QR natives sensibles donnant accès aux billets et des références courtes. Le JSON ne contient jamais d’UUID natif de billet, QR, URL publique de billet, jeton de commande ni octets de fichier. Les UUID de document identifient cet artefact privé de la façade, pas les billets d’entrée. Sélections : VALID_ENTRY (par défaut) désigne les billets d’entrée VALID courants ; ALL_UNITS inclut les billets unitaires non révoqués déjà USED ; ORDER peut être un récapitulatif sans droit d’entrée ; SINGLE utilise une référence opaque tkt_ résolue uniquement dans cette inscription, hors billets révoqués. Un PDF ne prouve jamais le paiement, une acceptation au-delà de l’état enregistré de l’inscription, la disponibilité actuelle de l’entrée ni un pointage réussi. Le rendu réutilise la disposition native de quatre billets par A4, les sièges courants et le repli linguistique de l’inscription/organisation. Helvetica natif ne peut pas imprimer tous les alphabets : les titres/libellés personnalisés non pris en charge sont omis et les libellés fixes se replient vers l’anglais/français ; aucun logo ni ressource distante n’est chargé. Les libellés peuvent utiliser l’ellipse de la disposition native fixe. Au plus 500 billets imprimables, 1000 lignes historiques, 500 produits, 200 catégories, 8 MiB de PDF. Les quantités canoniques strictes et références courantes des snapshots sont requises ; un historique ambigu est refusé. Les writers internes restent concurrents ; les révisions de source sont des observations qualifiées, pas des réservations transactionnelles. Lecture uniquement de la commande privée au principal et à l’organisation. Aucune génération PDF, réconciliation ni appel prestataire. Lire séparément state, journalRecorded et availability. AVAILABLE signifie que la sélection préparée correspond encore aux sources courantes et peut être rendue au téléchargement ; cela ne prouve pas la disponibilité du moteur PDF. SOURCE_CHANGED refuse le téléchargement jusqu’à une nouvelle préparation demandée séparément. Aucun PDF n’est stocké ; bytes, digest et generatedAt restent null. Une lecture ultérieure peut retrouver le résultat persisté après perte de réponse sans réexécuter un propriétaire. Le chemin authentifié n’est pas un lien public de partage ni une promesse de livraison. RUNNING/UNKNOWN exige une revue dans l’application propriétaire ; conserver la clé d’origine.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "tickets:share",
  "additional": [
    "forms:read",
    "forms_submit:read"
  ]
}
```

### Paramètres

```json
{
  "name": "documentId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-f-]{36}$",
    "format": "uuid"
  },
  "description": "UUID du document de façade retourné par la génération ; ne donne pas accès à l’entrée."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat qualifié de document privé de billets.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

### OpenAPI

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

## GET /ticket-documents/{documentId}/pdf

Générer et télécharger un PDF privé de billets à la demande

`download_ticket_document_pdf`

Exige tickets:share ET forms:read ET forms_submit:read. Les clés restreintes à des campagnes sont refusées. Réadmet l’organisation courante, l’inscription, le formulaire/la session, les produits/catégories/sièges et les identités natives de billets globalement uniques ; un matching Mongo multikey n’accorde aucune propriété. Une modification de billets existants peut demander le push natif de rafraîchissement Wallet. L’aperçu annonce walletRefreshMayBeRequested et requiredAdditionalScopes ; la génération exige aussi messages:send dans ce cas, avant journal/garde. La seule émission de billets manquants ne demande aucun rafraîchissement Wallet. walletRefresh=NOT_OBSERVED signifie qu’aucun résultat de notification n’a été observé ; ne jamais en déduire qu’aucun rafraîchissement n’est nécessaire. Le PDF natif est anonyme et ne contient aucun montant financier : aucun droit de lecture des paiements n’est requis ni déduit. Le PDF contient lui-même des URL QR natives sensibles donnant accès aux billets et des références courtes. Le JSON ne contient jamais d’UUID natif de billet, QR, URL publique de billet, jeton de commande ni octets de fichier. Les UUID de document identifient cet artefact privé de la façade, pas les billets d’entrée. Sélections : VALID_ENTRY (par défaut) désigne les billets d’entrée VALID courants ; ALL_UNITS inclut les billets unitaires non révoqués déjà USED ; ORDER peut être un récapitulatif sans droit d’entrée ; SINGLE utilise une référence opaque tkt_ résolue uniquement dans cette inscription, hors billets révoqués. Un PDF ne prouve jamais le paiement, une acceptation au-delà de l’état enregistré de l’inscription, la disponibilité actuelle de l’entrée ni un pointage réussi. Le rendu réutilise la disposition native de quatre billets par A4, les sièges courants et le repli linguistique de l’inscription/organisation. Helvetica natif ne peut pas imprimer tous les alphabets : les titres/libellés personnalisés non pris en charge sont omis et les libellés fixes se replient vers l’anglais/français ; aucun logo ni ressource distante n’est chargé. Les libellés peuvent utiliser l’ellipse de la disposition native fixe. Au plus 500 billets imprimables, 1000 lignes historiques, 500 produits, 200 catégories, 8 MiB de PDF. Les quantités canoniques strictes et références courantes des snapshots sont requises ; un historique ambigu est refusé. Les writers internes restent concurrents ; les révisions de source sont des observations qualifiées, pas des réservations transactionnelles. Génère en mémoire la sélection préparée après admission du principal et des sources courantes. Aucune réconciliation de billet, écriture de journal, notification ou conservation de fichier. Exige une préparation SUCCEEDED aux sources inchangées ; sinon 409. Réadmet les droits et la révision après le rendu pour refuser toute source modifiée avant l’envoi des octets. Aucune URL signée/publique. Cache-Control:no-store, pièce jointe et nosniff s’appliquent. Aucune clé de chiffrement PDF requise. Un échec de rendu ou PDF invalide, trop volumineux ou incomplet renvoie 503 sans diagnostic brut ni modification de la préparation réussie. Un autre téléchargement authentifié peut réessayer le rendu sans effet sur les billets. Les octets peuvent différer entre téléchargements ; aucune empreinte binaire ni date de génération conservée n’est annoncée dans les métadonnées.

Le MCP renvoie le fichier privé réel dans une ressource embarquée avec son type MIME et son blob base64, ainsi que filename, byteLength et le SHA-256 des octets décodés. Utiliser la capacité fichiers de l’hôte pour enregistrer ou joindre ces octets sous le nom renvoyé et vérifier leur taille et leur SHA-256. L’URI unisoft identifie uniquement cette réponse. Elle ne constitue ni une URL publique ni une référence de téléchargement réutilisable. Fournir le fichier au destinataire autorisé, sans recopier le blob dans le texte du chat, publier un document financier ou inventer une URL de partage. Le propriétaire REST authentifié recontrôle l’organisation, les permissions et toutes les sources ou preuves d’export requises à chaque appel. REST conserve sa réponse binaire. Le fichier prouve uniquement la récupération de ces octets. Il ne prouve ni règlement bancaire, ni validité juridique du document, ni remise à un destinataire.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "tickets:share",
  "additional": [
    "forms:read",
    "forms_submit:read"
  ]
}
```

### Paramètres

```json
{
  "name": "documentId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-f-]{36}$",
    "format": "uuid"
  },
  "description": "UUID du document de façade, privé au principal et à l’organisation courants."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Octets frais du PDF admis généré par ce GET ; jamais conservés.",
  "content": {
    "application/pdf": {
      "schema": {
        "type": "string",
        "format": "binary"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Code d’erreur fixe ; aucune source privée, capacité d’accès, contenu de fichier ni diagnostic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TicketDocumentError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "tickets:share",
  "x-unisoft-additional-scopes": [
    "forms:read",
    "forms_submit:read"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-file": {
    "mimeType": "application/pdf",
    "maxBytes": 8388608
  }
}
```

## Schémas

```json
{
  "components": {
    "schemas": {
      "TicketDocumentPreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/TicketDocumentPreview"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "TicketDocumentPreview": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "submissionId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^[0-9a-f-]{36}$"
          },
          "formId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^[0-9a-f-]{36}$"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^tdocrev_[a-f0-9]{64}$"
          },
          "selection": {
            "type": "string",
            "enum": [
              "VALID_ENTRY",
              "ALL_UNITS",
              "ORDER",
              "SINGLE"
            ],
            "default": "VALID_ENTRY"
          },
          "currentPrintableCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 500
          },
          "reconciliationRequired": {
            "type": "boolean"
          },
          "reconcilesOnGenerate": {
            "enum": [
              true
            ],
            "type": "boolean"
          },
          "walletRefreshMayBeRequested": {
            "type": "boolean"
          },
          "requiredAdditionalScopes": {
            "type": "array",
            "maxItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "messages:send"
              ]
            }
          },
          "anonymous": {
            "enum": [
              true
            ],
            "type": "boolean"
          },
          "containsFinancialAmounts": {
            "enum": [
              false
            ],
            "type": "boolean"
          },
          "sourceReadAt": {
            "type": "string",
            "format": "date-time"
          },
          "consistentSnapshot": {
            "enum": [
              false
            ],
            "type": "boolean"
          }
        },
        "required": [
          "submissionId",
          "formId",
          "expectedRevision",
          "selection",
          "currentPrintableCount",
          "reconciliationRequired",
          "reconcilesOnGenerate",
          "walletRefreshMayBeRequested",
          "requiredAdditionalScopes",
          "anonymous",
          "containsFinancialAmounts",
          "sourceReadAt",
          "consistentSnapshot"
        ]
      },
      "TicketDocumentError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "TicketDocumentResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/TicketDocumentResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "TicketDocumentResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "documentId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^[0-9a-f-]{36}$"
          },
          "submissionId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^[0-9a-f-]{36}$"
          },
          "formId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^[0-9a-f-]{36}$"
          },
          "selection": {
            "type": "string",
            "enum": [
              "VALID_ENTRY",
              "ALL_UNITS",
              "ORDER",
              "SINGLE"
            ],
            "default": "VALID_ENTRY"
          },
          "state": {
            "type": "string",
            "enum": [
              "RUNNING",
              "SUCCEEDED",
              "NO_TICKETS",
              "REFUSED",
              "UNKNOWN"
            ]
          },
          "replayed": {
            "type": "boolean"
          },
          "journalRecorded": {
            "type": "boolean"
          },
          "availability": {
            "type": "string",
            "enum": [
              "NOT_GENERATED",
              "AVAILABLE",
              "SOURCE_CHANGED"
            ]
          },
          "lockCleanup": {
            "type": "string",
            "enum": [
              "RETAINED",
              "RELEASED",
              "UNAVAILABLE",
              "NOT_OBSERVED"
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "anonymous": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "containsFinancialAmounts": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "ticketCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 500,
            "nullable": true
          },
          "bytes": {
            "type": "integer",
            "minimum": 8,
            "maximum": 8388608,
            "nullable": true
          },
          "digest": {
            "type": "string",
            "pattern": "^sha256:[a-f0-9]{64}$",
            "nullable": true
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "downloadPath": {
            "type": "string",
            "pattern": "^/integrations/v2/ticket-documents/[0-9a-f-]{36}/pdf$",
            "nullable": true
          },
          "error": {
            "type": "string",
            "enum": [
              "TICKET_DOCUMENT_REVISION_CHANGED",
              "TICKET_DOCUMENT_OPERATION_IN_PROGRESS",
              "TICKET_DOCUMENT_UNCERTAIN",
              null
            ],
            "nullable": true
          },
          "walletRefresh": {
            "type": "string",
            "enum": [
              "NOT_NEEDED",
              "REQUESTED",
              "UNAVAILABLE",
              "NOT_OBSERVED"
            ]
          }
        },
        "required": [
          "documentId",
          "submissionId",
          "formId",
          "selection",
          "state",
          "replayed",
          "journalRecorded",
          "availability",
          "lockCleanup",
          "canRetry",
          "anonymous",
          "containsFinancialAmounts",
          "ticketCount",
          "bytes",
          "digest",
          "generatedAt",
          "downloadPath",
          "error",
          "walletRefresh"
        ]
      },
      "UnisoftRequest_547fb9088a38af49927c": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "pattern": "^[0-9a-f-]{36}$",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^tdocrev_[a-f0-9]{64}$"
          },
          "selection": {
            "type": "string",
            "enum": [
              "VALID_ENTRY",
              "ALL_UNITS",
              "ORDER",
              "SINGLE"
            ],
            "default": "VALID_ENTRY"
          },
          "reference": {
            "type": "string",
            "pattern": "^tkt_[a-f0-9]{64}$"
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision"
        ],
        "additionalProperties": false,
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "pattern": "^[0-9a-f-]{36}$",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^tdocrev_[a-f0-9]{64}$"
              },
              "selection": {
                "type": "string",
                "enum": [
                  "SINGLE"
                ]
              },
              "reference": {
                "type": "string",
                "pattern": "^tkt_[a-f0-9]{64}$"
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "selection",
              "reference"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "pattern": "^[0-9a-f-]{36}$",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^tdocrev_[a-f0-9]{64}$"
              },
              "selection": {
                "type": "string",
                "enum": [
                  "VALID_ENTRY",
                  "ALL_UNITS",
                  "ORDER"
                ]
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision"
            ],
            "additionalProperties": false
          }
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
