Design a reliable integration

Accounting integrations must be correct under retries, timeouts, delayed web requests, and partial failures. Design for those cases before moving real financial data.

Use two identifiers

An external ID is not a substitute for idempotency. Store both the source ID and returned Wafeq ID in a tenant-scoped mapping table.

Make writes idempotent

For POST endpoints that expose the header:

X-Wafeq-Idempotency-Key: <stable-unique-value>

Recommended approach:

1. Derive or generate one key for the logical operation.
2. Persist it before sending the request.
3. Reuse it when the same request times out or receives a retryable error.
4. Generate a new key for a genuinely new operation.
5. Store the returned Wafeq ID atomically with the source record.

Do not create a second accounting document merely because the first response was lost.

Retry selectively

Set a retry limit and move exhausted operations to a queue that operators can inspect.

Page through complete datasets

List endpoints return count, next, previous, and results. Follow next until it is null.

Do not calculate later page URLs yourself when the response already provides them. This preserves all server-selected filters and page sizing.

Synchronize incrementally

Many list endpoints expose filters such as created_ts_after, created_ts_before, modified_ts_after, and modified_ts_before.

A safe pull loop:

1. Record a high-water timestamp before starting.
2. Request changes from the previous completed checkpoint through that timestamp.
3. Process every page and upsert by Wafeq ID.
4. Commit the new checkpoint only after all pages succeed.
5. Use a small overlap window and deduplicate by ID to protect against clock and commit timing.

Keep checkpoints per organization and object type.

Validate accounting relationships

Before sending a document:

• Confirm every related ID belongs to the connected organization.
• Validate currency and required exchange-rate context.
• Resolve accounts, tax rates, contacts, projects, cost centers, branches, and items.
• Keep invoice/payment and bill/payment allocations internally consistent.
• Reject source changes that would silently rewrite posted history.

Protect credentials and data

• Call Wafeq only from trusted server-side infrastructure.
• Keep API keys and OAuth client secrets, authorization codes, access tokens, and refresh tokens out of browser and mobile code.
• Store credentials per connected organization. Never share one tenant's connection state with another.
• For OAuth, persist the returned organization_id, granted scopes, token expiry, access token, and rotating refresh token.
• Refresh OAuth access before expiry and atomically replace both tokens returned by the refresh response.
• Treat an insufficient-scope 403 differently from an invalid or expired credential; the former requires a scope change and customer consent, not a retry loop.
• Redact Api-Key and Bearer authorization headers, client secrets, authorization codes, and refresh tokens from logs and error trackers.
• Log request IDs, source IDs, endpoint, status, latency, organization binding, and idempotency key—not sensitive payloads by default.
• Separate test and production organization connections.

Connection lifecycle

Design for credentials and customer consent to change:

• Reconnect or re-consent: send the customer through authorization again when the requested scopes change or a connection is revoked.
• Client-secret rotation: deploy the new secret for future token exchanges. Existing customer access tokens remain valid.
• Per-organization revocation: revoke a connected organization from the Developer Portal without affecting other customers.
• App deletion: deleting an app revokes every token issued for it.
• API-key replacement: create and deploy a replacement server-side, then revoke the old key after traffic has moved.

Provide operators with a clear view of which organization is connected, which authentication method it uses, its granted scopes, and the last successful refresh or request.

Reconciliation jobs

Run scheduled checks for:

• Source records without a Wafeq ID.
• Wafeq mappings whose records now return 404.
• Open invoices and bills whose balances changed.
• Payments whose allocations do not match the source.
• Sync checkpoints that have stopped advancing.

Reliable integrations make inconsistencies visible instead of silently creating compensating data.