Guide

Going live

Ten habits that separate a solid integration from a support ticket. Each one names the page that answers it, so a gap you find here has somewhere to go — and the last section is what to send us when something still does not add up.

The path from first conversation to production is four moves: talk to us, get your credential, make your first call, go live. This page is the fourth. By the time you reach it the mechanics already work — a credential exists, a token mints, requests come back with real records — and what is left is the operational shape of the integration: where the secret lives, how little a token is allowed to do, what happens when a request fails at three in the morning, and what you do the day the secret has to change.

None of it is a form to submit or a certification to pass. Work down the list; where an item is not settled yet, follow its link.

The ten checks

1. Secrets live in a secret manager. The clientSecret never appears in source control, in a config file that is in git, in a log line, in a ticket or in a chat message. It is shown exactly once, in the response that creates the credential, and Visena keeps only a one-way hash — it can never be displayed again. Credentials and tokens covers where it comes from and what to do when it is lost.
2. One credential per system and environment. Separate pairs for staging and production, each labelled after the system that holds it — erp-sync-prod, not api — so revoking one never takes down another. Credentials and tokens.
3. Tokens are cached and reused. Mint one token, hold it until roughly 60 seconds before its expires_in, then mint again. Never a token request per API call. The minimal cache is in Credentials and tokens.
4. Scopes are minimal. A job that only reads runs on scope=read. If that token leaks, the blast radius is exactly what you asked for, and a write attempted with it comes back 403. Read-only access shows the refusal happening.
5. Ids are stored verbatim. Masked ids such as xK9mQ2 are opaque strings: persist exactly what you received, never parse one for meaning, never generate one yourself. Concepts.
6. Writes prefer PATCH. Send only the fields you own, with Content-Type: application/merge-patch+json. A full PUT assembled from a partial copy of the record silently blanks everything you left out. Making requests puts the two side by side.
7. Creates are probe-first. Person and company syncs call the duplicate probe before they create, and handle 409 on companies: an organisation number that already exists means the record is there and the write is an update. The probes are documented on Company and Person.
8. Syncs use cursors and timelines. One full export through /cursor, then /timeline — or /document/changes for documents — against a watermark you persist. Nothing re-lists the whole dataset on a schedule. Lists, paging and sync explains which mode each job wants.
9. Retries are disciplined. Exponential backoff with jitter on network failures and 5xx, a single re-mint on 401, and never a blind retry of 400, 403, 409, 415 or 422 — the same request produces the same answer. The policy is in Errors and troubleshooting.
10. Rotation is rehearsed. You have run create-new → deploy → revoke-old at least once, calmly, before the day you have to do it in anger. Both credentials work during the switch, so there is no downtime window to negotiate. Credentials and tokens has the three moves.

When you need us

Reach us at sales@visena.com, or through your Visena integration contact — the named contact you have from the first conversation about the integration. Send the four things below and we can find the request on our side instead of asking you to reproduce it.

Before you write, check the symptom against the quick diagnosis table on Errors and troubleshooting: every request suddenly answering 401, reads working while writes return 403, a token request rejected with invalid_scope. Those have known causes and need no ticket.

Where to go next

This is the last guide page in the section. From here the documentation is reference: nine resources, one page each, with every parameter, response shape and status code. Every path in it is built the same way — /{instanceName}/api/v1/{locale}/person, singular, with no partner/ segment.

Read this page the week before you go live rather than the week after. Most of the ten items are cheap to fix while the integration is still pointed at staging, and expensive once a production job depends on them.