Skip to content

4. Rules for every command

These hold whatever endpoint you call. Read them once before porting the first command; the command pages assume them.

  • Dates are dd/MM/yyyy across V2 — the same shape V1 used, with one exception: V1 command 40/41 took the budget validity date as yyyy-mm-dd. In V2 it is dd/MM/yyyy like everything else.
  • Amounts travel as JSON numbers, with a dot as the decimal separator (1000.00). Some responses return formatted strings with a comma ("20,00") — parse defensively.

V1 used 0/1 almost everywhere. V2 keeps 1/0 for most flags, but a few legacy fields use -1 for true, which is the flowww internal convention:

FieldTrueFalse
ClientTemp-1 (temporary)0 (permanent)
ClientVIP-10
ClientAppDisabled-10
DiscountAccumulated-1 (stacks)0 / omitted (replaces)
everything else (ClientFWA, ClientForceEmail, consents…)10

Every endpoint that can be scoped to a centre accepts ?clinicID=. It is the clinic the call runs from, as if the user had switched to that centre in the application; it is not a search filter. When omitted, the call runs from the API user’s default clinic. It is required where the documentation says so, for example on GET /paymethod.

  • Send it explicitly on every call, and always the same one for all the calls of a multi-step flow: a budget or a ticket created from one clinic cannot be edited from another.
  • Write it exactly as clinicID. A value that is not a number is rejected with 400 invalid-clinicid; a clinic that does not exist returns 400 with errorCode 714.

In V1, a 200 OK response did not mean the command had succeeded. You had to inspect the XML: <Result>1</Result> meant success; otherwise <ResultError> gave the reason for failure.

In V2, read the response in this order:

  1. Check the HTTP status. 200 or 201 means the call completed; 4xx can indicate invalid data, credentials, permissions, a conflict or a limit; 5xx points to a service problem.
  2. On failure, read the body if there is one. errorCode, errorDescription, message, error and field can help identify the cause. None of these fields is guaranteed in every response: some 401 and 429 responses, for example, have no errorCode.
  3. For a flow with several calls, verify the resource at the end. Some calls return 200 with an empty body, and others can finish without leaving the ticket or order in the expected state. Use a GET before treating the whole flow as complete.
HTTP statusHow to read itWhat to do
200 / 201The call completed. Some creations return 201; other operations return 200 with no body.Store the id if one is returned and verify the final state in multi-step flows.
400Invalid data, a business rule refused the operation, or the API user lacks the permission (errorCode 15; 436 is a suspended clinic).Check field, errorCode and errorDescription when present; fix the data, the configuration or the permission profile.
401The API key is missing or invalid, or its user’s credentials changed.Stop and check the key; do not retry in a loop.
403The plan does not grant API access, or /getapikey refused the credentials, the system key, the OTP or the IP whitelist. A missing permission is not a 403.Check the plan and the credentials; for a permission, see the 400 above.
404The resource or route does not exist; some list endpoints use 404 for no results.Interpret it in the context of the endpoint before treating it as a failure.
409A conflict, such as a duplicate client or a ticket that cannot be closed.Read the reason and resolve the conflict before repeating the call.
429Too many concurrent requests or the monthly quota is exhausted.Distinguish the two by the message; only the first can be retried after Retry-After (see 4.6).
502 / 503Temporary problem between the gateway and the system.If the call created something, first check whether it ran (see 4.6).

Always log the HTTP status and response body, even when it is not JSON or has no errorCode. For business errors, errorCode and errorDescription are especially useful for identifying the rule that applied.

4.5 The system’s settings decide more than before

Section titled “4.5 The system’s settings decide more than before”

V1 ran its own simplified logic and skipped many of the rules the clinic has configured. V2 runs the same operations as the application, so the clinic’s configuration applies in full: required client fields, cash-desk rules, duplicate checks, discount authorisation, closing rules, stock control… A request that V1 accepted can be refused in V2 because of how that system is configured, and the same request can behave differently in two systems.

Each section lists the settings known to affect that command. When a call fails with 400 and a numeric errorCode, read the errorDescription: it names the rule. The fix is usually to complete the data or to review that setting with the clinic, not to change the request. Test the integration against a copy of each customer’s real configuration, not only against a blank system.

V1 did each operation in one request. In V2 most operations take several, and none of the calls that create something is idempotent: repeating it creates it again (a second ticket, a duplicate line, a second payment).

AnswerDid the operation run?Retry?
429 “Too many concurrent requests…” (with Retry-After)No.Yes, after the indicated seconds, and lower your parallelism.
429 “API quota exceeded…”No.No. Wait for the monthly reset or change the plan.
503 (with Retry-After)No.Yes, after the indicated seconds.
502, timeout, connection lostMaybe.Only after checking: read the resource back (GET) and send only what is missing.
4xx business errorNo.Not as is: fix the data or the configuration first.

Every request counts against the quota, including the ones that fail. Responses carry the API-Quota-Limit, API-Quota-Used, API-Quota-Remaining and API-Quota-Reset headers.

When two clients are merged in flowww, the absorbed record is deleted. V1 commands 17 and 19 silently translated an old client id into the surviving one. V2 never does: an old id returns 404 on GET and PATCH, and a ticket for it cannot be created.

If your integration stores flowww client ids, handle that 404: search the client again (GET /client?clientData= by email, phone or ID number), store the new id, and retry. Subscribe to crm.client.merge (see 4.9) to learn about it as it happens.

V1 had no quota: you could call it as often as you liked and nothing was metered. V2 does meter, so this is a limit your integration did not have to live with before. Quota is calculated per system as licensed clinics × requests per plan: 100,000 requests per clinic and month on Ultimate, 10,000 on Legend. If the clinics of a system are on different plans, the most restrictive one applies to all of them. Because several V1 commands become several V2 calls (see 19, 39, 40), recount your monthly volume before switching.

Integrations that called command 120 (or 100, or 17) on a timer should subscribe instead. Register one HTTPS endpoint with POST /webhooks and pick the events you care about:

  • Clients — crm.client.created, crm.client.updated, crm.client.deleted, crm.client.merge
  • Diary — diary.appointment.saved, diary.appointment.moved, diary.appointment.deleted, diary.appointment.validated
  • Sales — sales.ticket.closed, sales.cashdesk.closed
  • plus shifts, user timetables, users and clinics

Some systems — typically franchises and multi-centre groups — are configured so that each client belongs to the clinic that created it. That setting is not visible in the API, but it decides what your calls find:

  • Reading, updating or deleting one client only works when the client belongs to the clinic of the call. From another clinicID the answer is 404, although the client exists and the same user can see it elsewhere.
  • A search returns only the clients of the clinics where the API user has a workplace, not those of the whole system — so GET /client?clientData= and POST /client/advanced-search can miss a client that is really there.
  • Merging two clients of different clinics needs an explicit confirmation.

Without that setting, every client of the system is visible from any clinic. If your V1 integration worked with a single user that saw everything, check which case you are in before switching, and give the API user a workplace in each clinic it has to reach. It affects command 17, 18, 24 and 42.

V1 took the ISO codes and resolved them itself. V2 expects the flowww id everywhere those fields appear — when you create or update a client (08, 18), when you read one (17) and when you filter a search by ClientCountryID or ClientProvinceID (24). The API gives you the catalogues:

CatalogueCallWhat comes back
CountriesGET /system/countriesAn array of CountryID, CountryName, CountryDialCode and CountryISO3166_1_alfa2 — it maps the V1 code straight to the id. Spain is 201.
ProvincesGET /system/provinces?countryID=201An array of ProvinceID and ProvinceName, the ones of that country. Madrid is 32.
CitiesGET /system/cities?provinceID=…An array of CityID and CityName. They are asked by province, not by country, and they do not carry the postal code. Not every country has its cities loaded: a province without any returns 404.

Read them once and cache them: they change rarely, and every call counts against your quota. If your V1 integration stored ISO codes, translate them once during the migration rather than on every call.

  • New commands land in V2. What you read in this guide keeps growing without you having to move anywhere.
  • What cannot simply land is a correction that changes a field already published — its type, its shape, the values it takes. Switching it overnight would break whoever is reading it today.
  • There are no new paths: there is no /v2.1. The correction is deployed on /v2, but it does not become the default until a deadline announced ahead of time in the changelog.
  • Until that date you decide when you see it, by sending the preview-version header with the year and month of the deadline. With it, the response comes back corrected; without it, exactly as it does today.
  • Once the date arrives, the correction becomes the normal behaviour and the header stops having any effect. Drop it whenever it suits you: it does no harm.
Trying a correction before its date
curl --location 'https://api.flowww.net/v2/budget/123456' \
--header 'Authorization: Bearer <api_key>' \
--header 'preview-version: 2026-03'

That way you test the change against your own data and from your own integration, without changing the base path or waiting for the day itself: when it comes, you have nothing left to deploy.

Two of those corrections are already known and documented where they bite: the decimal separator (4.1) and the -1 booleans (4.2).