Skip to content

Migration checklist

Work down the list. Each step links to the section that explains it.

  1. 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.
  2. Request the API key once with POST /getapikey and store it as a secret (see 2.2). Remove doctor, pass, key, country, server and systemkey from every request. Do not call /getapikey on every start-up.
  3. Point everything at https://api.flowww.net/v2 and drop the regional host logic. Send clinicID explicitly on every call, and the same one for all the calls of a flow (see 4.3).
  4. Swap the parser: XML → JSON, and move the success check from <Result> to the HTTP status code. Log errorCode and errorDescription when present (see 4.4).
  5. Handle the new failure modes: 400 with a numeric errorCode (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 on 401: it locks the user.
  6. 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).
  7. Check the permissions of the API user against the ones each endpoint documents.
  8. 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.
  9. 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 → V2 paymethodID.
  10. Decide the duplicate policy: send ClientForceEmail: 0 on POST /client unless you check duplicates yourself (see command 08).
  11. Decide the consent model — legacy ClientEnableRGPD or the six ClientConsent* channels. Not both (see command 08).
  12. Handle merged clients: on 404 for a stored client id, search the client again and update your records (see 4.7).
  13. Re-plan the multi-step flows (sales, orders, budgets): keep the id returned by the first call, confirm the result with a GET at the end (some calls answer 200 even when a clinic rule prevented the change), and define what you do when step 3 of 5 fails.
  14. Recount your quota: a V1 sale was 1 request; a V2 sale is 5–8 (see 4.8).
  15. 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.
  16. Plan the move to webhooks for anything you poll today (Ultimate subscription — see 4.9).
  17. 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.

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.