Overview
Migrating from V1 to V2
Help for moving an integration from API V1 to API V2. This page covers what changes for every command; the sections below take the V1 commands one by one: what the command did, the V2 endpoint that replaces it, a field-by-field mapping and a working before/after example.
1. What changes, at a glance
Section titled “1. What changes, at a glance”| API V1 | API V2 | |
|---|---|---|
| Host | One per region: euapi, mxapi, brapi, usapi, clapi or rcapi + .flowww.net | One host for everyone: https://api.flowww.net/v2 |
| Endpoint | Always /v1/fwa_external_get.asp, the operation goes in ?cmd=NN | REST: one path per resource, the HTTP verb carries the intent |
| Auth | doctor, pass, key, country on every request, in the query string | Authorization: Bearer YOUR_API_KEY. The key is requested once from POST /getapikey |
| Request body | application/x-www-form-urlencoded, repeated numbered keys (ShoppingCart_1_Id…) | application/json |
| Response | XML, always HTTP 200, success in <Result>1</Result> | JSON, real HTTP status codes (200/201/400/401/403/404/409/429/5xx) |
| Errors | <ResultError>100018</ResultError> | {"message":"…","errorCode":"…"} with the matching status code |
| Clinic | ClinicID in the query string, name varies per command | ?clinicID=, same name everywhere, optional on most endpoints |
| Permissions | Login and password only | Every endpoint also requires the matching app permission on the user behind the key |
| Webhooks | Not supported: changes can only be detected by polling | POST /webhooks (Ultimate subscription) |
2. Step 0 — the API user and the API key
Section titled “2. Step 0 — the API user and the API key”2.1 Prepare a dedicated API user
Section titled “2.1 Prepare a dedicated API user”In V1 every request carried the login and password of a user. In V2 the key is bound to one user, and everything the integration does runs as that user: its permissions, its visibility restrictions and its name in the audit trail. Before requesting the key, prepare a user only for the integration:
- Do not share it with a person or with another integration. If the system allows only one open session per user, the integration logging in disconnects anyone else using the same account, and parallel workers on the same account compete with each other (429).
- Grant the permissions of every endpoint you will call on the permission profile of the user’s default workplace. That profile applies whatever
clinicIDyou send. Each endpoint in the API V2 reference lists the permission it needs. - Disable two-step verification (OTP) for that user, or
/getapikeyis refused. - Add your servers to the user’s IP whitelist if it has one, with their public IPv4 address — only a valid IPv4 is accepted, and the address the gateway reads is the public one your requests leave from, not the private one of the machine. Otherwise both
/getapikeyand every call are refused with 403. Treat it as a convenience, not as a security boundary. - Exempt it from password expiry. When the password changes or expires, every call returns 401 (see 4.4) until you request the key again.
- Check the user’s appointment-book visibility: a user restricted to their own appointments only sees those through the API too.
2.2 Request the key once
Section titled “2.2 Request the key once”Request the key once and store it as a secret (an environment variable or a secrets manager). /getapikey does not consume quota.
curl --location 'https://api.flowww.net/v2/getapikey' \--header 'Content-Type: application/json' \--data '{ "login": "integration@yourcompany.com", "password": "********", "systemkey": "8762574"}'{ "api_key": "u_6J_zxOZaYpgaxqFn2u27_q_CbQIIMORnJnpzhsYxA" }From then on, every call carries the header Authorization: Bearer YOUR_API_KEY.
Calling /getapikey again while the key is active does not issue a new one: it answers 409 “An active API key already exists…”. To replace the key (for example if it leaked), send "regenerate": true: a new key is issued and the old one is revoked immediately.
| /getapikey answer | Meaning | What to do |
|---|---|---|
| 200 | Key issued. | Store it. |
| 409 | This user already has an active key. | Keep using it, or send "regenerate": true. |
| 403 | “Invalid credentials…” | Wrong login or password. Check them. Repeated failures can lock the user. |
| 403 | “Invalid systemkey…” | The system key does not match. Check it. |
| 403 | Mentioning the plan. | The system has no Legend or Ultimate subscription. Contact flowww. |
| 403 | Mentioning OTP. | Two-step verification is enabled on the user. See 2.1. Disable it for that user. |
| 403 | “Access denied from this IP address…” | The IP of your server is not in the user’s IP whitelist. See 2.1. Add that server’s public IPv4 address to it. |
| 502 | Temporary problem reaching the system. | Retry later. |