API Contracts

Syllecta keeps the public runtime API and the Cloud-to-Backoffice internal API in versioned contract files.

Public Cloud API

The public Cloud API contract lives in:

cloud-api/contracts/public-cloud-api.openapi.json

It covers:

• POST /v1/record
• PUT /v1/record
• GET /v1/record
• DELETE /v1/record
• POST /v1/webhooks/{provider}
• POST /v1/t/{tenantSlug}/webhooks/{provider}
• POST /v1/simulate/chargeback

Run the drift check from the Cloud API package:

npm run contract:verify

Internal Backoffice API

The internal Cloud-to-Backoffice contract lives in:

backoffice/apps/api/contracts/cloud-internal.contract.json

It documents the internal endpoints used by Cloud API for tenant lookup, webhook persistence, usage emission, runtime settings, billing guardrails, simulation lifecycle, and execution history.

Run the drift check from the Backoffice API package:

npm run contract:verify

Error Shape

Public Nest-managed errors use the standard envelope:

{
  "message": "Invalid request",
  "error": "Bad Request",
  "statusCode": 400
}

Webhook verification can return a shorter provider-facing response before the request reaches normal application handling:

{
  "error": "invalid signature"
}

CI

Quality Gates runs both contract checks before tests and builds. If a route is renamed or removed without updating the contract, CI fails.

Related Guides

• Idempotent Records
• Webhooks
• Chargeback Simulation