Resources

Partner integration checklist

Work through this checklist before your integration relies on Fictix in a real workflow. It covers what "production-ready" means for the API contract, auth and secrets, data quality, exports, simulation and runtime, and webhooks — the areas an integration team needs to confirm before launch.

API contract

  • /api/v1/demo-jobs is the primary external surface.
  • /api/v1/catalog/* endpoints return current service, entity, capability, and export-pack metadata.
  • /api/v1/demo-jobs/{job_ref}/status returns generated status, company summary, dataset summary, quality summary, and simulation summary.
  • /api/v1/demo-jobs/{job_ref}/quality returns validation checks and a certificate.
  • /api/v1/demo-jobs/{job_ref}/runtime-readiness reports static, trickle, and continuous-readiness state.
  • /api/v1/demo-jobs/{job_ref}/entities/{entity} supports canonical entity aliases.
  • /api/v1/demo-jobs/{job_ref}/entities/{entity}/export supports JSON and CSV.
  • /api/v1/demo-jobs/{job_ref}/bundle fails with 413 rather than returning oversized responses.
  • Runtime/native routes remain documented as advanced routes, not as the first integration path.

Auth and secrets

  • Customer onboarding begins in the Fictix Console, where project keys are created, rotated, and revoked.
  • Management auth is enabled for creating and controlling demo jobs.
  • Runtime API keys are generated per project.
  • Runtime API key prefixes are safe for display; full keys are not.
  • API keys are never written to frontend logs.
  • Webhook secrets are accepted on create and never returned.
  • Staging and production use separate credentials.
  • Local development credentials are not used in staging docs or examples.
  • Secret values are redacted from request, response, and error telemetry.

Data quality

  • Generated counterparty domains use reserved synthetic namespaces such as .example, .test, .invalid, or a Fictix-owned fake namespace.
  • Entity counts in project metadata match fetchable entities.
  • Canonical ledgers do not duplicate alias ledgers in export packs.
  • payments is treated as an alias of customer_payments.
  • bill_payments is treated as an alias of vendor_payments.
  • bank_transactions.bank_account_id resolves to an exported bank account.
  • invoice line item_id resolves to items.
  • bill line item_id resolves to items.
  • journal entries balance within a one-cent tolerance.
  • invoice totals reconcile against amount paid and balance.
  • bill totals reconcile against amount paid and balance.
  • payroll gross, tax, benefit, and net pay reconcile.
  • validation certificates are generated and exposed.

Export readiness

  • Runtime CSV export pack returns a real ZIP file.
  • ZIP contains all canonical ledgers that the UI advertises.
  • ZIP includes a README or schema document.
  • ZIP row counts reconcile against record_counts.
  • Duplicate alias files are omitted or explicitly documented.
  • Normalized line files are included when available:
    • invoice_lines.csv
    • bill_lines.csv
    • journal_entry_lines.csv
    • payment_applications.csv
  • CSV exports preserve stable headers.
  • JSON-in-CSV cells are documented when unavoidable.
  • Empty ledgers are either included intentionally or excluded consistently.

Simulation and runtime

  • Simulation can start from a generated job.
  • Simulation status returns current simulated time, mode, and state.
  • Advancing time respects maximum advance limits.
  • Step, pause, resume, dials, checkpoint, and restore routes are covered by tests.
  • Events are written when simulation or scenario actions mutate state.
  • Runtime reads remain tenant-scoped by project.
  • Native-shaped routes for supported services return deterministic data for the same seed and company state.
  • Runtime writes either mutate state consistently or return a documented unsupported-operation response.

Webhooks

  • Webhook creation requires the webhooks entitlement.
  • Callback URLs are SSRF-guarded.
  • Subscription secrets are not returned.
  • Delivery payloads are HMAC-SHA256 signed when a secret is configured.
  • Delivery worker is running in staging/production.
  • Durable outbox tables exist and migrations are applied.
  • Duplicate delivery is possible and documented.
  • Test event delivery works against a known receiver.
  • Delivery failures are visible in telemetry.

Observability

  • Errors include request ids or trace ids when available.
  • Webhook delivery failures include project id, event type, and sanitized error.

Partner launch gate

Do not launch a partner integration until all of the following are true:

  • create job works in staging with management auth
  • Console-created project can create/rotate a runtime key and make a server-side runtime request in staging
  • status reaches ready
  • quality certificate is present
  • entity pagination works for every advertised canonical entity
  • CSV export works for every advertised canonical entity
  • full CSV export pack downloads as ZIP
  • runtime API key can read native-shaped data for selected services
  • webhooks can deliver a signed test event
  • simulation can advance and produce inspectable events
  • test matrix and test run flows complete
  • the docs site points to the same contract version as the deployed API
Previous
Versions and compatibility
Next
AI agent integration