Developer Guidelines

Use this guide to design and operate integrations that remain reliable as records, access and workloads change. Endpoint references define the supported contract; this page explains how to use it in a production integration.

Architecture and access boundaries

Run authenticated production requests from a trusted backend. Keep credentials in secret configuration and enforce your application's user access before returning data to a browser or report viewer. The API Explorer supports manual testing with your own key; it is not an authentication mechanism for a deployed application.

Maintain an explicit mapping between your client or programme identifiers and Requidex record IDs. Use IDs for joins and synchronisation, rather than display names. Check each endpoint's accepted identifiers; a reference or short ID accepted by one endpoint is not necessarily accepted by another.

For multi-company or MSP applications, include the company or agency access context in cache keys, stored extracts, jobs and downstream authorisation. A shared backend key must not allow one client to read another client's data through your application.

Credentials and configuration

Give each integration a named owner and a dedicated, least-privilege key. Confirm its environment, company or agency assignments, scopes, expiry, IP allowlist and quotas. API Key Info provides a useful initial credential and configuration check.

Use a stable outbound public IP when an allowlist is configured, accounting for proxies and gateways. Monitor authentication failures and credential expiry. Keep credentials out of prompts, URLs, source control, application telemetry and error reports.

Agree test data and any test environment with Requidex. The documented production URL and API Explorer use live data; do not assume a separate sandbox is available.

Construct requests explicitly

• Use the versioned HTTPS base URL, verify TLS certificates and set explicit connection and request timeouts
• Reuse HTTP connections where supported by your runtime, and bound concurrency across workers sharing the same key
• Send only documented parameters and fields, using proper query-string and JSON encoding
• Validate required identifiers, real calendar dates, amounts and allowed values before sending requests
• Preserve the distinction between an omitted field, an empty value and null; update semantics are endpoint-specific

Prefer a small set of reusable API-client functions for authentication, request construction, response parsing and error classification. Keep resource-specific rules, such as invoice state transitions, close to the workflow that uses them.

Extract and synchronise data

Apply supported filters and fields at the API boundary. Fetch each dataset once for a refresh and reuse the result instead of having multiple reports download the same pages independently.

For paginated lists, keep filters, page size and sorting unchanged while incrementing page. Read pagination metadata and complete the required pages before treating a collection as complete. Pagination is not a snapshot: concurrent updates can move records across boundaries, so upsert or deduplicate by record ID.

When an endpoint supports filtering by updatedAt, use a controlled checkpoint strategy for incremental polling. The documented date filters take calendar dates rather than arbitrary timestamp cursors; choose the overlap accordingly and deduplicate re-read records. Advance a checkpoint only after the full batch has been processed successfully. Creation-date filters do not capture later edits.

Treat a failed request, a lost permission and an empty result as different outcomes. A 403 or 404 is not sufficient evidence that an existing record should be deleted from your system. Use documented deletion events and an agreed reconciliation process for removals.

See Querying for shared formats and Integration Workflows for resource combinations.

Use summary endpoints carefully

Use server-side summaries for totals and rankings where the documented measures match your reporting requirement. Summary responses return at most 500 groups and have no continuation token. Their meta.total is the number of groups returned after limiting, not the total source-record count or all possible groups.

Choose filters and dimensions that fit within that limit, or split the report into non-overlapping company sets or date ranges. Label the date basis, filters, currency context and retrieval time on the result.

Do not add together measures that overlap by design. Distinct-worker counts can overlap across groups; requisition demand can appear in several agency groups; multi-project invoice groups contain full invoice values rather than an allocation. Invoice summaries separate currency, while other summaries do not automatically separate or convert it. Follow each summary endpoint's aggregation notes.

Keep operational measures distinct: charge value is not cash paid, a pending status has resource-specific meaning, and a missing numeric value is not automatically zero.

Use returned financial totals according to their documented meaning rather than reconstructing them from a subset of fields. Preserve currency and numeric precision in storage, and handle unfamiliar response statuses explicitly instead of mapping them silently to a known business state.

Implement writes as business workflows

Enable writes only where your integration needs them, with the correct scope, key type and business permissions. Validate the request locally and apply the required approvals before sending it. Prefer explicit user or workflow intent over automatic retries triggered by a generic error handler.

Record a correlation between the operation in your system and the Requidex record or response. If a request times out, inspect the current state before deciding whether to retry. Do not assume a general Idempotency-Key header or universal deduplication behaviour; use only guarantees stated by the endpoint.

For example, repeating an invoice's paid state does not replace its existing payment details or attachment. A worker-creation match returns 409 WORKER_MATCH_REQUIRES_REVIEW and requires review in Requidex. File-array updates can replace an entire file set. These are workflow rules, not transient errors.

Classify failures and control retries

Failure	Integration response
Network failure or timeout on a read	Retry with a bounded backoff policy and an overall deadline
Timeout on a write	Check the resulting record state before retrying; the operation may have succeeded
400 validation failure	Correct the request or business state; do not repeat it unchanged
401 or 403	Stop affected processing and investigate credentials, scope, access or feature requirements
404	Check the path, ID and current access; do not infer deletion automatically
409 worker-match review	Follow the review workflow rather than attempting another worker creation
429 RATE_LIMITED	Respect Retry-After when present and reduce request pressure
429 DAILY_RATE_LIMITED	Pause until the daily reset; avoid repeatedly consuming work on a blocked key
Transient 5xx on a read	Retry with bounded exponential backoff and jitter, then surface a persistent failure

Coordinate retries and concurrency across the whole integration, not just an individual process. Put limits on attempts, elapsed time and queue growth. Preserve failed work for investigation or controlled replay instead of silently dropping it.

See Responses and Errors and Rate Limits for response codes, quotas and reset behaviour.

Receive webhooks reliably

Verify signatures against raw request bytes using the webhook's signing secret. Validate the delivery timestamp, check the event type and required fields, and deduplicate by event ID. Persist or enqueue accepted work before acknowledging it with 2xx.

Perform slower record reads and downstream processing asynchronously. Support duplicate and out-of-order arrival, and make downstream updates repeatable. Delivery retries are bounded; keep periodic reconciliation for records that matter to the integration.

The payload identifies a record rather than supplying a full state transition or historical snapshot. Fetch its current state through the permitted detail endpoint. Deleted-record events cannot be followed by a successful read of the removed record. Test deliveries use test: true and the record ID test.

Do not confuse business events with delivery attempts. Automatic AfP payment notices send both issued and processed events; retries of either event reuse its event ID. The webhook reference defines those conditions and receiver requirements.

Handle files and temporary URLs

Follow File Uploads for the upload-then-attach sequence. Request the URL with the correct record, purpose, MIME type and size; upload the raw bytes using the returned headers; then attach the upload token with the same API credentials before expiry.

Do not forward your Requidex API key to the upload host. Treat upload tokens and temporary URLs as secrets, and exclude them from logs and analytics. Store record IDs for later retrieval rather than retaining an expiring URL as the permanent file reference.

Validate the endpoint's replacement semantics before updating document arrays. After an uncertain update, inspect the current record before attempting to upload or attach the file again.

Operate reporting refreshes efficiently

Use one extraction stage per dataset and refresh period, then reuse the persisted result for dependent reports. Avoid overlapping scheduled refreshes, and retain the last complete result when a refresh fails. Show stale or incomplete data explicitly rather than replacing it with an apparent zero.

Power Query references do not guarantee a single API download. Referenced queries can be evaluated independently; Table.Buffer buffers within an execution rather than sharing one downloaded result across every query. For reuse across reports, use an appropriately controlled persisted extract or dataflow. Microsoft documents this behaviour in referenced queries and multiple source requests.

To investigate duplicate requests, refresh one output query at a time and compare it with a full refresh. Check dependencies, previews and refresh schedules before increasing quotas or changing extraction logic.

Monitor and support the integration

Record the job or operation ID, HTTP method and path, UTC time, response status, error code, request duration and x-request-id where available. Include a key name or prefix rather than the key itself. Redact credentials, temporary URLs and unnecessary personal or financial data.

Monitor failed requests, repeated access errors, quota usage, queue age, webhook failures and time since the last complete synchronisation. Give failures an owner and an escalation route. Avoid marking a job successful when only part of its dataset or downstream work completed.

For support, provide a concise reproduction, the relevant time range and request identifiers, expected versus actual behaviour, and a redacted parameter example. Never send a full key, signing secret or personal document in a normal support message.

Release and maintain the integration

Before enabling a production workflow, verify the relevant behaviours with approved test data:

Area	Evidence to retain
Access isolation	Each client or agency can see only its permitted records, including through caches and reports
Data collection	Required pages are completed, duplicates are handled and partial failures preserve a known complete baseline
Writes	Validation, permissions, repeated requests and uncertain outcomes follow the endpoint's documented rules
Webhooks	Signature failures, duplicates, delayed delivery, receiver restarts and failed downstream processing are handled
Operations	Quota exhaustion, credential expiry, monitoring and recovery have an assigned owner
Compatibility	The deployed client is checked against the specification and endpoint notes used for that release

Keep a copy of the validated OpenAPI specification, review the Changelog, and tolerate additional response fields without discarding validation of the fields you actually use. Plan credential replacement and dependency updates as part of normal maintenance. Reassess scopes and retained data when the integration's purpose changes or it is retired.