Sandbox
The sandbox is a separate account linked to your production account. Each production account can have at most one sandbox. A credential's environment (production or sandbox) is the environment of the account that issued it, and it never changes. Sandbox secrets start with ck_test_ so you can tell them apart, but the prefix is informational only: the account that issued the credential determines the environment.
There is no separate sandbox host. You call the same base path (/api/v3) with sandbox credentials. The host https://sandbox.cademi.com.br is a regular production account and is not related to the sandbox.
Getting a sandbox
- An administrator of your production account provisions the sandbox from the Cademí dashboard. The new account starts with no plan and no secrets or external destinations configured, has the same administrators as production, and is seeded with a fixed set of test data: two published products, one showcase, three users with
@sandbox.invalidemail addresses, one fictitious delivery, tags, one custom field, and one legal term. Nothing is copied from production. - In the sandbox, issue credentials the same way you do in production. Sandbox credentials can access only the sandbox.
- Call
GET /sandboxto check the sandbox state. With production credentials, the response tells you whether a sandbox exists (statusisabsent,ready, orresetting), the version of the seeded test data, and when the sandbox was last reset. With sandbox credentials, it describes the sandbox itself. - To start over, call
POST /sandbox/resetswith sandbox credentials that have thesandbox.managepermission. TheIdempotency-Keyheader is required. The API responds with202and asandbox.resetoperation that tracks the reset. The reset deletes the sandbox data, including uploaded files, preserves credentials, administrators, limits, and the audit trail, and then seeds the test data again. Production is never affected.
See the Sandbox reference for the full request and response schemas.
What is simulated and what is real
| Feature | In the sandbox |
|---|---|
| API v3 (all resources), rate limits, audit trail, events, and operations | Real. The account and credential rate limits are half of the production defaults (Limits, quotas, and retention). |
Files (/uploads, /files) | Real, stored under the sandbox account. A reset deletes them. |
| Legacy webhooks | Not sent. |
| Emails and notifications | Not delivered. Send records remain visible in the Cademí dashboard. |
| Billing, custom domains and DNS, and other third-party services | Not called. The operation returns a neutral result. |
Failure scenarios for testing an integration
Each row explains how to trigger the response in the sandbox. For runnable test scenarios, which create data marked with meta.simulated and emit real events, use GET /sandbox/test-scenarios and POST /sandbox/test-scenarios/{scenario_id}/runs, described in Event streams.
| Response | How to trigger it |
|---|---|
401 credential_revoked | Revoke the credential and repeat the call. |
403 permission_denied | Issue a credential without the permission the operation requires (for example, without products.update) and call PATCH /products/{product_id}. |
403 production_only | Call POST /sandbox/resets with production credentials. |
404 not_found | Request a resource that is outside the scope of the current credentials. The response is identical to the one for a resource that does not exist. |
409 idempotency_in_progress | Send the same POST twice, in parallel, with the same Idempotency-Key. |
412 revision_mismatch | Send a PATCH with an If-Match value from an old revision. |
422 upload_integrity_mismatch | Create an upload session with purpose=pdf, upload bytes that do not start with %PDF-, and complete the session. |
422 too_many_items | Call POST /operations/batches with more items than the limit allows. |
429 rate_limit_exceeded | Exceed the credential's per-minute limit (half of the production default). The response body includes blocked_by, limits[], and retry_after_seconds. |
503 rate_limiter_unavailable | Returned only while the rate limiter is unavailable. You cannot trigger it from the client. |
failed operation | Call POST /operations/batches with a credential.revoke item that targets a credential that does not exist, then follow GET /operations/{operation_id}. |
409 state_conflict on reset | Request a second reset while the first one is queued or running. |