Transactions · API Platon

Endpoint

POST /platon/transactions

Soumettez une transaction de caisse structurée pour générer et remettre un ticket dématérialisé. Le ticket peut contenir le détail des lignes produits, la TVA par produit et un ou plusieurs paiements par carte.

Exemple de requête

cURL

                                   }       }]     }],              }],       }   }'

d">curl --request POST \ '{BASE_URL}/platon/transactions' \ --header 'Authorization: Bearer {YOUR_API_TOKEN}' \ --header 'Content-Type: application/json' \ --data '{ "requestId": "0efc54d1-a04c-46f1-94d2-ee58fd740485", "amount": "37", "shopId": 1, "externalTransactionRef": "698547865872", "tillId": 1, "timezone": "Europe/Paris", "mode": "email", "currencySymbol": "€", "shopName": "Main Street", "shopStreet": "149 Av. de Bretagne", "shopCity": "Lille", "shopPostalCode": "59000", "receipts": [{ "products": [{ "name": "Keyboard", "price": "15", "quantity": "1", "genCode": "895471234", "family": "Electronics", "vat": { "label": "VAT 20%", "amount": "3", "rate": "20%" "creditCardPayments": [{ "cardNetwork": "VISA", "paymentDate": "2024-05-12", "paymentTime": "13:45", "merchantName": "Acme Corp", "maskedCardNumber": "*1234", "amount": "37", "currencySymbol": "€", "paymentType": "Credit" "customer": { "email": "customer@example.com"

Réponse

Une requête réussie renvoie le statut HTTP 201 Created avec un corps vide, ou une URL en texte brut lorsque la WebReceipt est activée sur votre compte. Cette URL pointe vers une page hébergée où le client peut consulter et télécharger son ticket.

Lorsque mode vaut email ou email_and_print, un email n'est envoyé au client que si une adresse email valide est présente dans le champ customer.email.

Modes de remise

Valeur	Description
`email`	Envoyer le ticket par email au client. Nécessite un `customer.email` valide.
`print`	Générer un ticket papier sur le terminal de caisse. Aucun email n'est envoyé.
`email_and_print`	Envoyer par email et générer un ticket papier simultanément.
`no_print`	Enregistrer la transaction sans remettre de ticket.

Référence du corps de requête

StructuredTransactionDTO

Champ	Type	Obligatoire	Description
`requestId`	`string`	Oui	UUID v4 utilisé pour l'idempotence. Les requêtes en double portant la même valeur sont ignorées.
`mode`	`string`	Oui	Mode de remise. Voir Modes de remise.
`receipts`	`StructuredReceipt[]`	Oui	Un ou plusieurs tickets, chacun contenant une liste de produits.
`amount`	`string`	Non	Montant total de la transaction. Peut être négatif (remboursement).
`shopId`	`number`	Non	Identifiant interne du magasin.
`externalTransactionRef`	`string`	Non	Votre propre référence pour cette transaction.
`externalReceiptRef`	`string`	Non	Votre propre référence pour ce ticket.
`tillId`	`number`	Non	Identifiant de la caisse.
`transactionDate`	`string`	Non	Date de la transaction au format ISO 8601.
`timezone`	`string`	Non	Nom de fuseau horaire IANA (ex. `Europe/Paris`).
`currencySymbol`	`string`	Non	Symbole monétaire (`€`, `$`) ou code ISO (`EUR`).
`companyName`	`string`	Non	Raison sociale du commerçant affichée sur le ticket.
`shopName`	`string`	Non	Nom du magasin affiché sur le ticket.
`shopPhone`	`string`	Non	Numéro de téléphone du magasin.
`shopStreet`	`string`	Non	Adresse du magasin.
`shopCity`	`string`	Non	Ville du magasin.
`shopPostalCode`	`string`	Non	Code postal du magasin.
`customer`	`Customer`	Non	Coordonnées, consentements et préférences du client.
`creditCardPayments`	`CreditCardPaymentDTO[]`	Non	Détail des paiements par carte. Plusieurs entrées sont possibles.
`vats`	`VatDTO[]`	Non	Récapitulatif de TVA pour l'ensemble de la transaction (par opposition à la TVA par produit).
`barcode`	`StructuredBarcode`	Non	Code-barres optionnel pour la validation ou la recherche du ticket.
`tags`	`string[]`	Non	Étiquettes de métadonnées personnalisées.

StructuredReceipt

Champ	Type	Obligatoire	Description
`products`	`StructuredProductDTO[]`	Non	Liste des produits figurant sur le ticket.

StructuredProductDTO

Champ	Type	Obligatoire	Description
`name`	`string`	Oui	Nom du produit.
`price`	`string`	Oui	Total de la ligne (prix × quantité).
`quantity`	`string`	Oui	Nombre d'unités achetées.
`genCode`	`string`	Oui	Code-barres ou identifiant du produit.
`family`	`string`	Oui	Catégorie du produit.
`guarantee`	`string`	Non	Durée de garantie (ex. `2 ans`).
`vatRate`	`string`	Non	Taux de TVA appliqué à ce produit (ex. `20%`).
`unitPrice`	`string`	Non	Prix unitaire, avant multiplication par la quantité.
`quantityUnit`	`string`	Non	Libellé d'unité pour la quantité (ex. `kg`, `L`).
`metadata`	`object`	Non	Métadonnées clé-valeur libres (les valeurs sont des tableaux de chaînes). À utiliser pour les coupons, remises ou attributs personnalisés.

CreditCardPaymentDTO

Rattachez un ou plusieurs paiements par carte au ticket. Chaque entrée représente une transaction carte.

Champ	Type	Obligatoire	Description
`cardNetwork`	`string`	Oui	Réseau de la carte (ex. `VISA`, `MasterCard`).
`paymentDate`	`string`	Oui	Date du paiement au format ISO (ex. `2024-05-12`).
`paymentTime`	`string`	Oui	Heure du paiement (ex. `13:45`).
`merchantName`	`string`	Oui	Nom commercial affiché.
`maskedCardNumber`	`string`	Oui	Numéro de carte masqué (ex. `*1234`). Les astérisques initiales sont ajoutées automatiquement si elles sont omises.
`amount`	`string`	Oui	Montant débité sur cette carte.
`currencySymbol`	`string`	Oui	Symbole monétaire ou code ISO.
`paymentType`	`string`	Oui	`Credit` ou `Debit`.
`paymentMethod`	`string`	Non	Mode d'utilisation de la carte (ex. `Contactless`, `PIN`).
`transactionReference`	`string`	Non	Identifiant unique de cette transaction carte.
`authorizationNumber`	`string`	Non	Code d'autorisation renvoyé par le réseau de la carte.
`terminalId`	`string`	Non	Identifiant du terminal de paiement.
`storeId`	`string`	Non	Identifiant du point de vente.
`merchantId`	`string`	Non	Identifiant du commerçant (ex. SIRET).
`merchantPostalCode`	`string`	Non	Code postal du commerçant.
`merchantCity`	`string`	Non	Ville du commerçant.
`bankCode`	`string`	Non	Code banque ou code de traitement.
`cardTransactionId`	`string`	Non	Identifiant interne de la transaction carte.
`merchantCustomHeader`	`string`	Non	Texte d'en-tête personnalisé affiché dans la partie commerçant du ticket.

StructuredBarcode

Champ	Type	Obligatoire	Description
`type`	`string`	Oui	Format du code-barres. Valeurs acceptées : `128`, `012`, `008`, `013`, `125`, `039`.
`value`	`string`	Oui	Données à encoder dans le code-barres.

Customer

Champ	Type	Obligatoire	Description
`email`	`string`	Non	Adresse email du client. Obligatoire pour les modes de remise par email.
`consents`	`Consent[]`	Non	Liste des consentements du client (ex. opt-in marketing).
`preferences`	`Preference[]`	Non	Préférences du client (ex. canal de remise du ticket préféré).
`custom`	`CustomField[]`	Non	Paires clé-valeur libres pour des attributs client personnalisés.