Flux WsOne (Beone)

Une caisse déjà branchée sur les web services Beone WsOne fonctionne avec Remizo sans modification : il suffit de changer l’URL de base vers le moteur du workspace. L’adaptateur WsOne est servi sur le même port que l’API native, avec la même clé d’API (portée wsone).

Conventions de l’adaptateur

• Noms de champs exacts de WsOne (ReceiptRequest, DetailsRequest, TransactionItemRequest…).
• Montants décimaux (54.90) convertis en centimes (5490) — échelle amountScale, 2 par défaut.
• Date transactionDate au format DD/MM/YYYY HH24:MI:SS, heure locale du magasin.
• Types d’identifiant : 1 carte, 10 compte web, 30 wallet, 99 prospect.
• Toujours HTTP 200 : l’erreur est portée par responseCode.
• Le magasin (EntityRequest.entityIdentifier) est le storeCode ; cashdeskNumber → posId ; receiptNumber → ticketNumber.
• Le mapping est configurable par workspace (configuration d’adaptateur dans le studio), par exemple pour dériver le rayon de universReference.

Correspondance des 8 appels

#	Appel WsOne	Chemin	Équivalent natif	Effet
1	verifyTransaction	POST /rest/transactionWebService/verifyTransaction	POST /v1/transactions/simulate	Simulation, rien n’est écrit.
2	sendTransaction	POST /rest/transactionWebService/sendTransaction	POST /v1/transactions/evaluate	Ticket en attente ; identifié ensuite par (magasin, caisse, numéro, date).
3	validTransaction	POST /rest/transactionWebService/validTransaction	POST /v1/transactions/{id}/commit	Validation ; seul ReceiptRequest est lu, l’identifiant est retrouvé par la clé de ticket.
4	sendAndValidTransaction	POST /rest/transactionWebService/sendAndValidTransaction	POST /v1/transactions/commit	Évaluation et validation en un appel.
5	refundTransaction	POST /rest/transactionWebService/refundTransaction	POST /v1/transactions/{id}/refund	Remboursement total (sans DetailsRequest) ou partiel (articles remboursés, quantités positives).
6	cancelTransactionsNotValidated	POST /rest/transactionWebService/cancelTransactionsNotValidated	POST /v1/transactions/cancel-pending	Annule les tickets en attente du magasin (et de la caisse si précisée).
7	getAvailableOffers	POST /rest/2.0/personWebService/getAvailableOffers	POST /v1/customers/lookup (offres)	Offres disponibles pour le client identifié.
8	getAccounts	POST /rest/2.0/personWebService/getAccounts	POST /v1/customers/lookup (soldes)	Un AccountResponse par type de compteur.

Correspondance des champs

WsOne	Ticket Remizo
ReceiptRequest.allTaxesIncludedAmount	header.totals.grossCents (× 100)
ReceiptRequest.preTaxAmount	header.totals.preTaxCents
ReceiptRequest.discountAmount	header.totals.posDiscountCents
ReceiptRequest.cashdeskNumber	header.posId
ReceiptRequest.receiptNumber	header.ticketNumber
ReceiptRequest.transactionDate	header.timestamp et header.businessDate
ReceiptRequest.EntityRequest.entityIdentifier	header.storeCode
ReceiptRequest.IdentifierRequest	customer.identifiers[0] (1 → card, 10 → web_account, 30 → wallet, 99 → prospect)
ReceiptRequest.AccountAdvantageRequest[]	paiement en points (options.pointsBurn)
DetailsRequest.OfferNumberRequest[].offerNumber	coupons[].code
TransactionItemRequest.allTaxesIncludedUnitPrice	lines[].unitPriceCents
TransactionItemRequest.quantity	lines[].qty
TransactionItemRequest.discountAmount	lines[].posDiscountCents
TransactionItemRequest.mainReference	lines[].ref
TransactionItemRequest.ean / name	lines[].ean / lines[].name
TransactionItemRequest.universReference	lines[].univers
TransactionItemRequest.storeReference	lines[].attributes.storeReference

1. verifyTransaction / 2. sendTransaction / 4. sendAndValidTransaction

Même corps de requête pour les trois :

{
  "ReceiptRequest": {
    "allTaxesIncludedAmount": 54.90, "preTaxAmount": 45.75, "discountAmount": 0, "currency": "EUR",
    "cashdeskIpAddress": "10.42.0.3", "cashdeskNumber": "03", "receiptNumber": "000123",
    "transactionDate": "09/11/2026 10:42:13",
    "EntityRequest": { "entityIdentifier": "S042" },
    "IdentifierRequest": { "identifierType": "1", "identifierValue": "2600000012345" },
    "AccountAdvantageRequest": []
  },
  "DetailsRequest": {
    "nbItems": 2, "nbOfferNumbers": 1,
    "OfferNumberRequest": [ { "offerNumber": "2609000001234" } ],
    "TransactionItemRequest": [
      { "allTaxesIncludedUnitPrice": 4.95, "discountAmount": 0, "ean": "3017620422003", "mainReference": "NUT750",
        "name": "Pâte à tartiner 750g", "preTaxUnitPrice": 4.69, "quantity": 2, "storeReference": "S042-NUT750", "universReference": "ALIM" },
      { "allTaxesIncludedUnitPrice": 45.00, "discountAmount": 0, "ean": "4006381333931", "mainReference": "STB001",
        "name": "Stylo bille", "preTaxUnitPrice": 37.50, "quantity": 1, "storeReference": "S042-STB001", "universReference": "MAISON" }
    ]
  }
}

Réponse (HTTP 200) :

{
  "responseCode": "000", "infos": "OK",
  "ReceiptResponse": {
    "allTaxesIncludedAmount": 54.90, "preTaxAmount": 45.75, "discountAmount": 5.49, "newAllTaxesIncludedAmount": 49.41,
    "currency": "EUR", "cashdeskNumber": "03", "receiptNumber": "000123", "transactionDate": "09/11/2026 10:42:13",
    "transactionIdentifier": "6f1c2a9e-3b7d-4e0a-9c1f-2d3e4f5a6b7c",
    "EntityResponse": { "entityIdentifier": "S042", "entityName": "Paris Bastille" },
    "IdentifierResponse": { "identifierType": "1", "identifierValue": "2600000012345" },
    "OldAccountResponse": [ { "name": "POINTS", "value": 120, "unit": "pts" } ],
    "NewAccountResponse": [ { "name": "POINTS", "value": 169, "unit": "pts" } ]
  },
  "DetailsResponse": {
    "nbOffers": 2,
    "OfferResponse": [
      { "used": true, "edited": false, "name": "-10% dès 50 €", "value": 10, "type": 2, "order": 1, "offerNumber": "WELCOME10" },
      { "used": true, "edited": false, "name": "1 point par euro", "value": 49, "type": 3, "order": 2, "offerNumber": "PTS-BASE" }
    ]
  }
}

Avec verifyTransaction, transactionIdentifier est vide (rien n’est enregistré).

Types d’OfferResponse

type	Signification	value
1	remise en €	montant décimal
2	remise en %	pourcentage
3	points	nombre de points
4	coupon émis (edited: true, couponCode, couponUrl si rendu)	valeur faciale
5	message (message)	—

used: false + reason : offre refusée (mode explication).

3. validTransaction

Seul ReceiptRequest est nécessaire (identification et montants définitifs) ; DetailsRequest est ignoré s’il est présent. Le moteur retrouve la transaction par sa clé de ticket. Réponse : même structure, soldes définitifs. Un ticket déjà validé renvoie 003.

5. refundTransaction

ReceiptRequest.originalReceiptNumber + originalTransactionDate + cashdeskNumber identifient le ticket d’origine ; receiptNumber est le numéro du ticket de remboursement. Sans DetailsRequest, le remboursement est total ; sinon TransactionItemRequest[] liste les articles remboursés (quantités positives).

6. cancelTransactionsNotValidated

{ "EntityRequest": { "entityIdentifier": "S042" }, "cashdeskNumber": "03" }

{ "responseCode": "000", "infos": "OK", "nbCancelled": 2 }

7. getAvailableOffers / 8. getAccounts

{ "IdentifierRequest": { "identifierType": "1", "identifierValue": "2600000012345" }, "EntityRequest": { "entityIdentifier": "S042" } }

getAccounts :

{ "responseCode": "000", "infos": "OK",
  "IdentifierResponse": { "identifierType": "1", "identifierValue": "2600000012345" },
  "AccountResponse": [ { "name": "POINTS", "value": 169, "unit": "pts" }, { "name": "CASHBACK", "value": 3.50, "unit": "EUR" } ] }

getAvailableOffers renvoie OfferResponse[] (mêmes champs que ci-dessus, used: false).

Codes responseCode

Code	Signification
000	OK
001	identifiant inconnu (client ou carte)
002	requête invalide
003	ticket en double (déjà validé)
004	transaction introuvable
005	transaction non validable (annulée ou expirée)
006	magasin inconnu
007	solde insuffisant
100	moteur indisponible
999	erreur interne

Format de réponse

Les exemples ci-dessus suivent le contrat api/engine.openapi.yaml. Les échanges WsOne réels de la première enseigne servent de fichiers de référence aux tests de l’adaptateur (engine/testdata/wsone/) : en cas d’écart constaté, c’est le comportement WsOne d’origine qui fait foi et le contrat est corrigé.