Command 19 — Create a salemulti-step
This is the biggest change in the whole migration. V1 built the ticket, its lines and its payments in a single form post, with its own simplified rules. V2 builds it the way the application does — create the ticket, add lines, apply discounts and promotions, register payments, close it — and applies every rule the clinic has configured along the way. Read the whole section before porting: the happy path is short, but most of the work is in handling what can fail at each step.
Permissions
Section titled “Permissions”V2 checks an app permission on every call — V1 checked none — and a call whose permission is missing answers 400 with errorCode 15, the same status as an invalid payload (see 4.4). Grant these to the API user before porting the command; the names are the ones of the permission tree in flowww.
| Call | Permission |
|---|---|
POST /invoice/{TicketGID}/promotioncode/{code} | Sales - Tickets → Use promotion code |
POST /invoice/{TicketGID}/detail/product/{productID} | Sales - Tickets → Add product |
PATCH /invoice/{TicketGID}/detail/{TicketID} | Sales - Tickets → Edit price RRP |
POST /invoice/{TicketGID}/detail/{TicketID}/discount | Sales - Tickets → Apply discount on final value Sales - Tickets → Apply percentage discount Sales - Tickets → Apply catalog discount |
GET /invoice/{TicketGID} | Sales - Tickets → Edit |
POST /invoice/{TicketGID}/payment/{paymethodID} | Sales - Tickets → Add payment |
PATCH /invoice/{TicketGID} | Sales - Tickets → Close |
PATCH /invoice/{TicketGID}/user | Sales - Tickets → Modify seller |
POST /invoice | Sales - Tickets → Create |
POST /invoice/{TicketGID}/resend | Sales - Tickets → Ticket - Resend Ticket |
PATCH /client/{clientID} | Clients → Clients - Save |
DELETE /invoice/{TicketGID} | Sales - Tickets → Delete ticket |
DELETE /invoice/{TicketGID}/paymethod/{TicketPID} | Sales - Tickets → Delete payment |
DELETE /invoice/{TicketGID}/detail/{TicketID} | Sales - Tickets → Delete line |
POST /invoice/{TicketGID}/cancel | Sales - Tickets → Void invoice by difference Sales - Tickets → Void invoice by substitution |
POST /invoice/{id}/detail/advance | Sales - Tickets → Add a down payment |
PUT /client/{clientID}/voucher/{voucherID} | Sales - Vouchers → Edit |
The flow
Section titled “The flow”- 1
POST /invoice?clientID={id}&clinicID={n}
→201 {"TicketGID": 128}
Replaces theClientID/ClinicIDquery of cmd 19 - 2
POST /invoice/{TicketGID}/promotioncode/{code}
Only if there is a code. Not validated in V2: any code is accepted with 200.
ShoppingCart_PromoCode - 3
POST /invoice/{TicketGID}/detail/product/{productID}
Once per line, with{"ProductUnits": n, "ProductUserID": u}→{"TicketID": 642}
ShoppingCart_X_Id - 3b
PATCH /invoice/{TicketGID}/detail/{TicketID}
Manual price:{"TicketTotalAmount": p}, unit price with VAT included
ShoppingCart_X_Price - 3c
POST /invoice/{TicketGID}/detail/{TicketID}/discount
DiscountTypeis mandatory:Ppercentage,Vfinal value of the line,Da predefined discount id
ShoppingCart_X_Disc,_Disc_Acc - 4
GET /invoice/{TicketGID}
Read the total to pay before registering any payment
No V1 equivalent - 5
POST /invoice/{TicketGID}/payment/{paymethodID}
Once per payment line.TicketPAmountis mandatory, dot as decimal separator. Cash also needsTicketPCashGiven.
ShoppingCart_PayX_* - 6
PATCH /invoice/{TicketGID}
Closes the ticket, carrying{"TicketGFWA_Ref": "…"}
Closing the ticket +ShoppingCart_Ref - 7
GET /invoice/{TicketGID}
Check that nothing is pending and read the payment ids. Whether it is closed shows in the ticket list:GET /invoice→TicketGClosed: 1
No V1 equivalent
The same sale, before and after
Section titled “The same sale, before and after”curl --location 'https://euapi.flowww.net/v1/fwa_external_get.asp?cmd=19&doctor=USER_LOGIN&pass=USER_PASS&country=ES&key=SYSTEM_KEY&ClinicID=1&ClientID=93271' \ --data-urlencode 'ShoppingCart_PromoCode=' \ --data-urlencode 'ShoppingCart_Ref=WEB-8841' \ --data-urlencode 'ShoppingCart_1_Id=2983' \ --data-urlencode 'ShoppingCart_1_Price=1000' \ --data-urlencode 'ShoppingCart_Pay1_Amount=1000' \ --data-urlencode 'ShoppingCart_Pay1_Paymentmethod=5'
<Cmd19><Result>1</Result> <Ticket><TicketGID>128</TicketGID>…</Ticket></Cmd19>curl --location --request POST 'https://api.flowww.net/v2/invoice?clientID=93271&clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Length: 0'
→ 201 {"TicketGID": 128}curl --location --request POST 'https://api.flowww.net/v2/invoice/128/promotioncode/SUMMER25?clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Length: 0'curl --location 'https://api.flowww.net/v2/invoice/128/detail/product/2983?clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{"ProductUnits": 1}'
→ {"TicketID": 642}curl --location --request PATCH 'https://api.flowww.net/v2/invoice/128/detail/642?clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{"TicketTotalAmount": 1000.00}'curl --location 'https://api.flowww.net/v2/invoice/128?clinicID=1' \ --header 'Authorization: Bearer <api_key>'curl --location 'https://api.flowww.net/v2/invoice/128/payment/1?clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{"TicketPAmount": 1000.00, "TicketPCashGiven": 1000.00}'curl --location --request PATCH 'https://api.flowww.net/v2/invoice/128?clinicID=1' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{"TicketGFWA_Ref": "WEB-8841"}'curl --location 'https://api.flowww.net/v2/invoice/128?clinicID=1' \ --header 'Authorization: Bearer <api_key>'Always send the same clinicID on every call of the sale.
What changes compared with V1
Section titled “What changes compared with V1”| Topic | API V1 | API V2 |
|---|---|---|
| Atomicity | All or nothing: on any failure V1 removed the payments, the lines and the ticket. | Every call is saved on its own. A failure half-way leaves an open ticket behind — see Cleaning up. |
| Clinic rules | Skipped most of them (required client fields, cash-desk rules, payment limits, closing checks…). | Applies them all. See Settings that can block the sale. |
| Professional of the line | None. | The one you send in ProductUserID; if omitted, the API user. Send it if your commissions or statistics depend on it. |
| Who closes the sale | The V1 login user. | The ticket’s user (the API user by default). Change it with PATCH /invoice/{TicketGID}/user if needed. |
| Products | Disabled products could be sold, and the product id was translated to the clinic’s own catalogue. | The product must be enabled and belong to the tariff of the clinic you call from (errorCode 717 otherwise). Products that require lot or expiry data (traceability) cannot be sold through the API. |
| Units per line | Always 1. | ProductUnits, greater than 0. |
| Manual price | _Price was the unit price with VAT; the automatic discount still applied unless _Disc was sent. | PATCH …/detail/{TicketID} with the unit price, VAT included. It changes the price only: discounts and promotions already on the line stay. |
| Promotion code | Validated: an unknown or not applicable code was an error. | Not validated: any code is accepted with 200. Check the discount on the ticket (step 4) if the code matters. |
| Payment amount | A single payment could omit the amount (the total was used). | TicketPAmount is mandatory on every payment, with a dot as decimal separator. Read the total first (step 4). Some methods need more fields: cash TicketPCashGiven; cheque TicketPCheckNumber and TicketPSettlement; direct debit TicketPSettlement, TicketPClientCCCID and TicketPClientCCCBIC. |
| Closing | Direct; several of the application’s closing checks were skipped. | The application’s closing checks apply (pending appointments of the day, simplified-invoice limit, stock traceability…). |
| Response bodies | The whole ticket. | Payment and close answer 200 with an empty body. Read the ticket (step 7) to get the invoice number, the payment ids and the final state. |
| Confirmation email | Sent the sales email of the online shop when the clinic had it enabled. | The online-shop sales email is no longer sent. The ticket email on closing is sent in both versions, when the clinic has it enabled. There is no parameter to force it on POST /invoice or on the closing PATCH: to send a ticket that did not go out, call POST /invoice/{TicketGID}/resend (permission Sales · Tickets · Ticket · Resend Ticket). |
| Merged clients | An old id was translated to the surviving client. | Not translated: the call fails. See 4.7. |
Settings that can block the sale
Section titled “Settings that can block the sale”These rules come from the clinic’s configuration. V1 ignored most of them, so an integration that worked for years can start failing on the first V2 call. Review them with each customer before the switch.
| Rule configured in the clinic | Step | What you get | What to do |
|---|---|---|---|
| Client fields required to create a ticket (for example ID number, address or birth date) | 1 | 400 {"message":"The client is missing required fields: …","errorCode":"502"} with the list of fields | Complete the client with PATCH /client/{clientID} before creating the ticket, or have the clinic relax the rule. |
| Cash desk of the day already closed, when the clinic does not allow reopening it for new sales | 1 | 400 errorCode 50 | The clinic must reopen today’s cash desk, or allow partial cash desks. V1 attached the sale to the closed desk anyway. |
| Cash desks of previous days still open | 1 | 400 errorCode 142 | The clinic must close them. |
| Client pending regularisation (mandatory protocols) | 1 | 400 errorCode 145 | Complete the client in the application. |
| Per-user discount password | 3c | 403 errorCode 206 | With this rule on, no discount gets through the API: it asks for the user’s password, which the API does not send. Have the clinic turn it off. |
| Discount authorisation above a threshold | 3c | 403 errorCode 206 | The discount is not applied. Send the call again adding "GlobalPassword" to the body, with the clinic’s global discount password — or keep the discount under the threshold. |
| Discounts that cannot be combined | 3c | 400 errorCode 507 / 531 / 533 | 533: the line already has an advanced promotion — send DiscountAccumulated: -1. |
| Legal limit for cash payments of the country | 5 | 400 errorCode 555 | Split the amount into another payment method. |
| Appointments of the day pending validation | 6 | 400 errorCode 586 | Validate the client’s appointments of the day, or have the clinic change the rule. |
| Maximum amount of a simplified invoice (the total is over the country’s limit) | 6 | It closes anyway, as an ordinary invoice | The API confirms the ordinary invoice for you and answers with the real result. If that confirmation fails: 503 invoice-not-closed, and the ticket stays open — retry. |
| Automatic confirmation of packs and vouchers | 6 | 400 errorCode 616 | Have the clinic change the rule. |
| Stock with traceability | 3 / 6 | 400 errorCode 669 / 656 | Products that need lot or expiry data cannot be sold through the API. |
| Client fields required to close a ticket | 6 | 400 errorCode 280 | Complete the client and close again. |
| Cash desk of the ticket’s date closed (the ticket was created on an earlier day) | 6 | 409 errorCode 739 | Create and close the ticket on the same day. |
Errors, step by step
Section titled “Errors, step by step”Besides the common answers (401, 403, 429, 5xx — see 4.4), each step can answer:
| Step | Answer | Meaning | State left behind |
|---|---|---|---|
| 1 Create | 400 495 | The client does not exist (or was merged). | Nothing created. |
| 1 Create | 400 502 / 50 / 142 / 145 | See Settings. | Nothing created. |
| 3 Add line | 400 717 | Product disabled, of a type that cannot be sold, or not in the clinic’s tariff. | Ticket unchanged. |
| 3 Add line | 400 520 | Units must be greater than 0. | Ticket unchanged. |
| 3 Add line | 400 46 | The line could not be added (ticket closed or from another clinic). | Ticket unchanged. |
| 3b Price | 400 invalid-params | Negative price or line not found. | Line unchanged. |
| 3c Discount | 400 190 | Line or ticket not found, ticket closed, price 0, line paid with a voucher, or amount above the line total. | Line unchanged. |
| 3c Discount | 403 206 | The discount needs the clinic’s authorisation (see Settings). The error message explains how to send it. | Line unchanged. |
| 5 Payment | 400 (validation) | TicketPAmount missing, or not a number with a dot as decimal separator; dates not dd/MM/yyyy. | Nothing added. |
| 5 Payment | 400 48 | Unknown payment method id, or the ticket is closed or belongs to another clinic. | Nothing added. |
| 5 Payment | 400 173 / 174 | Gift voucher not found / expired. | Nothing added. |
| 5 Payment | 400 465 | Cash handed over (TicketPCashGiven) lower than the amount. | Nothing added. |
| 5 Payment | 400 489 | The advance has already been used, or its remaining balance is lower than the amount. | Nothing added. |
| 5 Payment | 400 555 | Cash limit, see Settings. | Nothing added. |
| 6 Close | 409 49 | The payments do not add up to the total, or the ticket is already closed. | Ticket open (or already closed). |
| 6 Close | 409 739 | Cash desk of the ticket’s date closed. | Ticket open. |
| 6 Close | 409 456 | The total is over the simplified-invoice limit and the client’s billing data is incomplete for the ordinary invoice. | Ticket open. |
| 6 Close | 503 invoice-not-closed | The total is over the simplified-invoice limit and the ordinary invoice could not be issued. Try again. | Ticket open. |
| 6 Close | 400 586 / 616 / 656 / 280 | See Settings. | Ticket open. |
| 6 Close | 400 (electronic invoicing) | The electronic-invoicing service of the country refused the invoice. | The ticket may already be closed. Do not repeat the close: read it (step 7). |
Cleaning up after a failure
Section titled “Cleaning up after a failure”V1 was all or nothing: any failure removed the payments, the lines and the ticket. In V2 each call is saved on its own, so a failure half-way leaves an open ticket behind — and an open ticket prevents closing the cash desk of the day.
DELETE /invoice/{TicketGID} only removes an open ticket with no payments or lines left. Read the ticket with GET /invoice/{TicketGID}, remove each payment first with DELETE /invoice/{TicketGID}/paymethod/{TicketPID}, then each line with DELETE /invoice/{TicketGID}/detail/{TicketID}. Finally, delete the empty ticket. Deleting a ticket that still has payments or lines fails.
A 409 with errorCode 376 means payments or lines remain, or the ticket is already closed. If it returns 514 (linked advances or deferred payments) or 574 (tips), automatic cleanup is insufficient: review the ticket in the application.
A 404 with errorCode 51 means the ticket does not exist or is no longer the clinic’s last one (another ticket was created after it), so it cannot be deleted. Remove its payments and lines and close it empty with PATCH /invoice/{TicketGID}, so it does not block the cash desk.
# Get PAYMENT_ID (TicketPID) and the TicketIDs with GET /invoice/128.curl --location --request DELETE 'https://api.flowww.net/v2/invoice/128/paymethod/PAYMENT_ID?clinicID=1' \ --header 'Authorization: Bearer <api_key>'curl --location --request DELETE 'https://api.flowww.net/v2/invoice/128/detail/642?clinicID=1' \ --header 'Authorization: Bearer <api_key>'curl --location --request DELETE 'https://api.flowww.net/v2/invoice/128?clinicID=1' \ --header 'Authorization: Bearer <api_key>'Keep in mind:
- It is not
POST /invoice/{TicketGID}/cancel. Cancel applies to closed tickets and issues a credit note, which is an accounting movement. Delete applies to an open ticket, which was never a sale. - To drop just one product or one payment and carry on with the sale, use the same detail calls. Read the
TicketPIDwithGET /invoice/{TicketGID}.
The best cleanup is still not needing one: check the client’s required fields and the product before step 1, and finish the same ticket on retry instead of starting a new one.
Payment methods
Section titled “Payment methods”V1 had its own 0–6 enumeration in ShoppingCart_PayX_Paymentmethod. V2 puts the method id in the path of POST /invoice/{TicketGID}/payment/{paymethodID}.
| V1 value | V2 paymethodID | Notes |
|---|---|---|
0 PayPal | 8 PayPal | — |
1 Credit/debit card (Visa/MC) | 7 VISA/MC | — |
2 Deferred payment | 3 Deferred payment | Due date: ShoppingCart_PayX_Settlement → TicketPSettlement (dd/MM/yyyy). |
3 Check | 4 Check | Check data in TicketPCheckNumber. Whether the check is confirmed automatically now follows the clinic’s setting (V1 always confirmed it). |
4 Debit card + Paymentbank | 5 Debit card + TicketPBankID | The bank moves from ShoppingCart_PayX_Paymentbank to TicketPBankID. |
5 Cash | 1 Cash | V2 requires TicketPCashGiven, the amount handed over. |
6 Points | 9 Points | Fails if the client does not have enough points. |
| — | 2, 6, 10, 11 | Also available: credit card (2), gift voucher (6, TicketPGiftVoucherCode), direct debit (10, TicketPClientCCCID, TicketPClientCCCBIC) and advances (11, TicketPAdvanceID). |
Everything else in the payload
Section titled “Everything else in the payload”| V1 parameter | API V2 | Notes |
|---|---|---|
ShoppingCart_Ref | TicketGFWA_Ref on PATCH /invoice/{id} | Your order number, stored with the ticket. Up to 64 characters (a longer value is dropped). It is not returned by GET /invoice/{id}. |
ShoppingCart_PromoCode | POST /invoice/{id}/promotioncode/{code} | Skip the call when there is no code. Apply it before the lines. |
ShoppingCart_X_Id | {productID} in the path | — |
ShoppingCart_X_Price | TicketTotalAmount on PATCH …/detail/{TicketID} | Unit price, VAT included. |
ShoppingCart_X_Disc | DiscountAmount + DiscountType: "P" | P = percentage, V = final value of the line, D = a predefined discount id. DiscountType is mandatory. |
ShoppingCart_X_Disc_Acc | DiscountAccumulated | V1 took 0/1. V2: -1 stacks on the existing discount, 0/omitted replaces it. Mandatory as -1 when the line already carries an advanced promotion (errorCode 533). |
ShoppingCart_X_VAT_Advance | AdvanceVAT on POST /invoice/{id}/detail/advance | Advances are their own call: {"AdvanceAmount": …, "AdvanceVAT": …}. V1 took the VAT as a percentage (21); V2 takes it as a fraction (21 % → 0.21). |
KeepOpened | — | Simply do not send step 6. A ticket stays open until you close it. |
ShoppingCart_X_VoucherExpiryDate | — | Gap: not available while building the ticket. Change the voucher’s expiry afterwards with PUT /client/{clientID}/voucher/{voucherID}. |
ShoppingCart_X_ExtraID / _Extra | — | Gap: no equivalent on the invoice line. |