Skip to content

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.

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.

CallPermission
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}/discountSales - 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}/userSales - Tickets → Modify seller
POST /invoiceSales - Tickets → Create
POST /invoice/{TicketGID}/resendSales - 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}/cancelSales - Tickets → Void invoice by difference
Sales - Tickets → Void invoice by substitution
POST /invoice/{id}/detail/advanceSales - Tickets → Add a down payment
PUT /client/{clientID}/voucher/{voucherID}Sales - Vouchers → Edit
  • 1POST /invoice?clientID={id}&clinicID={n}
    → 201 {"TicketGID": 128}
    Replaces the ClientID / ClinicID query of cmd 19
  • 2POST /invoice/{TicketGID}/promotioncode/{code}
    Only if there is a code. Not validated in V2: any code is accepted with 200.
    ShoppingCart_PromoCode
  • 3POST /invoice/{TicketGID}/detail/product/{productID}
    Once per line, with {"ProductUnits": n, "ProductUserID": u} → {"TicketID": 642}
    ShoppingCart_X_Id
  • 3bPATCH /invoice/{TicketGID}/detail/{TicketID}
    Manual price: {"TicketTotalAmount": p}, unit price with VAT included
    ShoppingCart_X_Price
  • 3cPOST /invoice/{TicketGID}/detail/{TicketID}/discount
    DiscountType is mandatory: P percentage, V final value of the line, D a predefined discount id
    ShoppingCart_X_Disc, _Disc_Acc
  • 4GET /invoice/{TicketGID}
    Read the total to pay before registering any payment
    No V1 equivalent
  • 5POST /invoice/{TicketGID}/payment/{paymethodID}
    Once per payment line. TicketPAmount is mandatory, dot as decimal separator. Cash also needs TicketPCashGiven.
    ShoppingCart_PayX_*
  • 6PATCH /invoice/{TicketGID}
    Closes the ticket, carrying {"TicketGFWA_Ref": "…"}
    Closing the ticket + ShoppingCart_Ref
  • 7GET /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
API V1 — one call
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>
API V2 — 1. Create the ticket
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}
2. Promotion code (only if there is one)
curl --location --request POST 'https://api.flowww.net/v2/invoice/128/promotioncode/SUMMER25?clinicID=1' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Length: 0'
3. Add the line
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}
3b. Set the price by hand (unit price, VAT included)
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}'
4. Read the total to pay
curl --location 'https://api.flowww.net/v2/invoice/128?clinicID=1' \
--header 'Authorization: Bearer <api_key>'
5. Register the payment (V1 method 5 = cash → V2 paymethodID 1 = Cash)
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}'
6. Close the ticket, carrying the external reference
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"}'
7. Confirm
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.

TopicAPI V1API V2
AtomicityAll 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 rulesSkipped 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 lineNone.The one you send in ProductUserID; if omitted, the API user. Send it if your commissions or statistics depend on it.
Who closes the saleThe V1 login user.The ticket’s user (the API user by default). Change it with PATCH /invoice/{TicketGID}/user if needed.
ProductsDisabled 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 lineAlways 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 codeValidated: 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 amountA 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.
ClosingDirect; 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 bodiesThe 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 emailSent 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 clientsAn old id was translated to the surviving client.Not translated: the call fails. See 4.7.

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 clinicStepWhat you getWhat to do
Client fields required to create a ticket (for example ID number, address or birth date)1400 {"message":"The client is missing required fields: …","errorCode":"502"} with the list of fieldsComplete 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 sales1400 errorCode 50The 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 open1400 errorCode 142The clinic must close them.
Client pending regularisation (mandatory protocols)1400 errorCode 145Complete the client in the application.
Per-user discount password3c403 errorCode 206With 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 threshold3c403 errorCode 206The 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 combined3c400 errorCode 507 / 531 / 533533: the line already has an advanced promotion — send DiscountAccumulated: -1.
Legal limit for cash payments of the country5400 errorCode 555Split the amount into another payment method.
Appointments of the day pending validation6400 errorCode 586Validate 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)6It closes anyway, as an ordinary invoiceThe 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 vouchers6400 errorCode 616Have the clinic change the rule.
Stock with traceability3 / 6400 errorCode 669 / 656Products that need lot or expiry data cannot be sold through the API.
Client fields required to close a ticket6400 errorCode 280Complete the client and close again.
Cash desk of the ticket’s date closed (the ticket was created on an earlier day)6409 errorCode 739Create and close the ticket on the same day.

Besides the common answers (401, 403, 429, 5xx — see 4.4), each step can answer:

StepAnswerMeaningState left behind
1 Create400 495The client does not exist (or was merged).Nothing created.
1 Create400 502 / 50 / 142 / 145See Settings.Nothing created.
3 Add line400 717Product disabled, of a type that cannot be sold, or not in the clinic’s tariff.Ticket unchanged.
3 Add line400 520Units must be greater than 0.Ticket unchanged.
3 Add line400 46The line could not be added (ticket closed or from another clinic).Ticket unchanged.
3b Price400 invalid-paramsNegative price or line not found.Line unchanged.
3c Discount400 190Line or ticket not found, ticket closed, price 0, line paid with a voucher, or amount above the line total.Line unchanged.
3c Discount403 206The discount needs the clinic’s authorisation (see Settings). The error message explains how to send it.Line unchanged.
5 Payment400 (validation)TicketPAmount missing, or not a number with a dot as decimal separator; dates not dd/MM/yyyy.Nothing added.
5 Payment400 48Unknown payment method id, or the ticket is closed or belongs to another clinic.Nothing added.
5 Payment400 173 / 174Gift voucher not found / expired.Nothing added.
5 Payment400 465Cash handed over (TicketPCashGiven) lower than the amount.Nothing added.
5 Payment400 489The advance has already been used, or its remaining balance is lower than the amount.Nothing added.
5 Payment400 555Cash limit, see Settings.Nothing added.
6 Close409 49The payments do not add up to the total, or the ticket is already closed.Ticket open (or already closed).
6 Close409 739Cash desk of the ticket’s date closed.Ticket open.
6 Close409 456The total is over the simplified-invoice limit and the client’s billing data is incomplete for the ordinary invoice.Ticket open.
6 Close503 invoice-not-closedThe total is over the simplified-invoice limit and the ordinary invoice could not be issued. Try again.Ticket open.
6 Close400 586 / 616 / 656 / 280See Settings.Ticket open.
6 Close400 (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).

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.

Give up on a sale
# 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 TicketPID with GET /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.

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 valueV2 paymethodIDNotes
0 PayPal8 PayPal—
1 Credit/debit card (Visa/MC)7 VISA/MC—
2 Deferred payment3 Deferred paymentDue date: ShoppingCart_PayX_Settlement → TicketPSettlement (dd/MM/yyyy).
3 Check4 CheckCheck data in TicketPCheckNumber. Whether the check is confirmed automatically now follows the clinic’s setting (V1 always confirmed it).
4 Debit card + Paymentbank5 Debit card + TicketPBankIDThe bank moves from ShoppingCart_PayX_Paymentbank to TicketPBankID.
5 Cash1 CashV2 requires TicketPCashGiven, the amount handed over.
6 Points9 PointsFails if the client does not have enough points.
—2, 6, 10, 11Also available: credit card (2), gift voucher (6, TicketPGiftVoucherCode), direct debit (10, TicketPClientCCCID, TicketPClientCCCBIC) and advances (11, TicketPAdvanceID).
V1 parameterAPI V2Notes
ShoppingCart_RefTicketGFWA_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_PromoCodePOST /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_PriceTicketTotalAmount on PATCH …/detail/{TicketID}Unit price, VAT included.
ShoppingCart_X_DiscDiscountAmount + DiscountType: "P"P = percentage, V = final value of the line, D = a predefined discount id. DiscountType is mandatory.
ShoppingCart_X_Disc_AccDiscountAccumulatedV1 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_AdvanceAdvanceVAT on POST /invoice/{id}/detail/advanceAdvances 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.