Migration checklist
Work down the list. Each step links to the section that explains it.
The seventeen steps
Section titled “The seventeen steps”- Prepare a dedicated API user (see 2.1): not shared with anyone, permissions on the profile of its default workplace, no two-step verification, IP whitelist with the public IPv4 addresses of your servers (recommended), no password expiry.
- Request the API key once with
POST /getapikeyand store it as a secret (see 2.2). Removedoctor,pass,key,country,serverandsystemkeyfrom every request. Do not call/getapikeyon every start-up. - Point everything at
https://api.flowww.net/v2and drop the regional host logic. SendclinicIDexplicitly on every call, and the same one for all the calls of a flow (see 4.3). - Swap the parser: XML → JSON, and move the success check from
<Result>to the HTTP status code. LogerrorCodeanderrorDescriptionwhen present (see 4.4). - Handle the new failure modes:
400with a numericerrorCode(business rules, permissions —15—, suspended clinic —436),403(the plan does not grant API access),409(conflicts),429(concurrency or quota — they are handled differently),502/503. Never loop on401: it locks the user. - Make retries safe: calls that create something are not idempotent. After a timeout or a
502, read the resource back and send only what is missing (see 4.6). - Check the permissions of the API user against the ones each endpoint documents.
- Review each customer’s configuration with them: required client fields for sales, cash-desk rules, discount authorisation, duplicate checks, manual budget prices, purchasing centre… (see Settings that can block the sale, and each section). Test against a copy of their real configuration.
- Convert the data you send: country and province ISO codes → numeric ids; budget validity date →
dd/MM/yyyy; budget prices → VAT included; V1 payment methods → V2paymethodID. - Decide the duplicate policy: send
ClientForceEmail: 0onPOST /clientunless you check duplicates yourself (see command 08). - Decide the consent model — legacy
ClientEnableRGPDor the sixClientConsent*channels. Not both (see command 08). - Handle merged clients: on
404for a stored client id, search the client again and update your records (see 4.7). - Re-plan the multi-step flows (sales, orders, budgets): keep the id returned by the first call, confirm the result with a
GETat the end (some calls answer200even when a clinic rule prevented the change), and define what you do when step 3 of 5 fails. - Recount your quota: a V1 sale was 1 request; a V2 sale is 5–8 (see 4.8).
- Review the gaps flagged in this guide — cost price on order lines, manual shipment per line, comment timestamps, voucher expiry at sale time, order paging, stage-change history — and decide the workaround for each one before you cut over.
- Plan the move to webhooks for anything you poll today (Ultimate subscription — see 4.9).
- Run both in parallel against a test system before switching production, and keep the V1 path available until the new one has run a full business cycle.
V2 is much wider than V1 {#wider}
Section titled “V2 is much wider than V1 {#wider}”This guide summarises the public flowww API documentation. Where a V1 parameter has no V2 equivalent it is flagged as a gap rather than silently mapped — check those cases against your own integration before cutting over. For the full reference of each endpoint (all fields, all responses, all error codes) see the API V2 section of the documentation.