API v1
The RaffsSync API is designed for predictable automation: stable endpoints, strict auth, idempotent requests, and DB-driven provider routing — without turning your integration layer into a folder factory.
Base URL (v1)
https://raffssync.io/api/v1/Versioning is part of the path so we can evolve the platform safely. When v2 arrives, v1 keeps working.
Companion docs
Authentication
RaffsSync API calls are authenticated. The exact method depends on whether the caller is:
- Customer systems (server-to-server)
- RaffsSync internal services (workers/dispatchers)
- Partners / certified providers (controlled access)
Common patterns include Bearer tokens or API keys. Wherever possible, use short-lived tokens + strict scope.
Core concepts
- Customer — top-level account holder
- Location — customer-facing term (internal: tenant)
- Provider — external platform (TakeApp, iSeller, Accurate, etc.)
- Route — a DB-defined interconnect template (event/operation → handler)
The platform scales by adding routes in the registry — not by creating new endpoint files.
Conventions
JSON
Content-Type: application/jsonIdempotency
Idempotency-Key: <stable-unique-key>If you retry, use the same idempotency key to prevent duplicates.
Correlation
X-Request-Id: <uuid>Optional but recommended for tracing.
Dispatch model
Most “real work” is performed through a dispatch pattern: your request specifies what you want done, and RaffsSync uses the DB-driven provider registry to determine how to perform it.
Example: outbound provider operation (concept)
{
"tenant_id": 29,
"provider": "takeapp",
"route_key": "orders.pull",
"payload": {
"since": "2026-02-01T00:00:00Z"
}
}Exact endpoints will be documented as each provider route group is finalised. The important part is the contract: provider + route_key + tenant context + payload.
Errors
API responses should return consistent JSON error shapes (code, message, details), and use standard HTTP status codes. If you want, we’ll lock a canonical error schema next.