🧪 Sandbox Environment

A SolaBill beta integration environment for authentication, ordinary invoice drafts, customer webhooks, errors, and retry logic. Regulated provider testing occurs only when approved, customer-scoped Orchida sandbox credentials are provisioned.

Versioned Beta API Synthetic Data Only Controlled Failure Tests No Production Claims Orchida Access Required

🌐

Base URL

SolaBill client API calls use the /api/v1/ prefix. Draft creation never sends network traffic; provider submission requires a separately approved Orchida sandbox connection.

🔑

Authentication

🔄

Data Lifecycle

Use synthetic data and design idempotent tests. Reset timing and retention depend on the controlled deployment; never assume a 24-hour purge.

📡

Regulated Transport Boundary

The legacy transport simulator is local research only and disabled in partnership sandbox/production. Orchida owns regulated PINT-AE validation, AS4 exchange, and reporting.

🔐 Test Credentials

No shared credentials are published

An authorized administrator creates a tenant-isolated SolaBill test account and sends access through the approved secure channel. Orchida issues separate scoped sandbox credentials; they are encrypted, write-only, and never copied into this page, tickets, source control, screenshots, or queue payloads.

💡

Regulated production accounts are not currently available. Sandbox access does not prove production readiness and requires authorized SolaBill access plus separately approved Orchida company-scoped credentials.

⚡ Quick Start

Get up and running in three steps:

Step 1 — Authenticate

BASHcurl -X POST https://www.solabill.com/api/v1/client/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "YOUR_ASSIGNED_TEST_EMAIL",
    "password": "YOUR_ASSIGNED_TEST_PASSWORD"
  }'

# Response:
# {
#   "data": {
#     "token": "1|abc123...",
#     "user": { "name": "Assigned Test User", "email": "YOUR_ASSIGNED_TEST_EMAIL" },
#     "account": { "company_name": "Sandbox Corp", "status": "active" }
#   }
# }

Step 2 — Create an Invoice Draft

BASHcurl -X POST https://www.solabill.com/api/v1/client/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-SANDBOX-001",
    "recipient_name": "Sandbox Buyer LLC",
    "recipient_peppol_id": "100820361200003",
    "buyer_endpoint_scheme": "0235",
    "buyer_street": "Airport Road",
    "buyer_city": "Abu Dhabi",
    "buyer_subdivision": "AUH",
    "buyer_country": "AE",
    "total_amount": 105.00,
    "currency": "AED",
    "issue_date": "2026-02-12",
    "issue_time": "09:30",
    "due_date": "2026-03-12",
    "payment_means_code": "48",
    "items": [{"item_code":"SVC-1","name":"Service","description":"Sandbox service","unit_code":"C62","quantity":1,"base_quantity":1,"net_unit_price":100,"gross_unit_price":100,"discount_amount":0,"vat_category":"S","vat_rate":5}]
  }'

# Response includes an invoice ID and submitted=false

# Submit only after an active Orchida sandbox connection is provisioned
curl -X POST https://www.solabill.com/api/v1/client/invoices/INVOICE_ID/submit-orchida \
  -H "Authorization: Bearer YOUR_TOKEN"

Step 3 — Check Orchida Status

BASHcurl https://www.solabill.com/api/v1/client/invoices/INVOICE_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

# Returns provider validation, Orchida invoice, tax-authority and receiver states separately

🧪 Test Scenarios

Cover these scenarios before going to production:

Scenario	How to Test	Expected Result	Status Code
Successful login	POST valid credentials	Token in `data.token`	200
Invalid credentials	POST wrong password	Error with `invalid_credentials`	401
Suspended account	Login with suspended account	Error with `account_suspended`	403
Expired / revoked token	Use an old or revoked bearer token	Error with `unauthenticated`	401
Validation errors	Submit invoice missing required fields	Field-level error details	422
Create invoice	POST valid invoice payload	Invoice draft created; no delivery claimed	201
Submit to Orchida	POST a complete draft using an active scoped sandbox connection	Exact Orchida provider status recorded	200
Create credit note	POST valid credit note payload	Internal draft created; Orchida submission remains disabled pending confirmed contract and sandbox mapping	201
Change password	POST current + new password	Password updated confirmation	200
Paginated listing	GET invoices with `?page=2&per_page=5`	Response with `pagination` object	200
Rate limiting	Exceed request limit on login	`Retry-After` header set	429
Webhook delivery	Create invoice with webhook subscription active	Signed SolaBill customer event derived from retained Orchida workflow evidence	N/A

⚖️ Sandbox vs Production

Feature	Sandbox	Production
Regulated transport	Orchida adapter with fake HTTP or approved sandbox credentials	Available only after the eligible Orchida entity, contract, customer appointment, sandbox/pilot acceptance and production launch are approved; SolaBill does not operate AS4 transport
Certificate Validation	Owned by Orchida; SolaBill retains only the sandbox outcome supplied under the approved test contract	Owned and evidenced by Orchida under the executed agreement; SolaBill separately checks API reachability and company scope
Receiver discovery	Provider response is simulated or returned by Orchida sandbox	Owned by Orchida within regulated exchange
Rate Limits	SolaBill application limits apply; Orchida sandbox limits require written confirmation	SolaBill and Orchida limits must match the approved contracts and deployment configuration
Webhook Delivery	SolaBill callbacks remain signed and retryable; Orchida webhook behavior is unconfirmed	SolaBill callbacks use the approved signing/retry policy; Orchida webhook behavior must match the signed provider contract
Data Persistence	Controlled synthetic-data lifecycle; confirm the deployment-specific reset policy	Approved retention, legal-hold, backup, recovery and deletion policy; “permanent” is not claimed
Tax-authority reporting	Only the exact Orchida sandbox state is shown	Performed by Orchida; SolaBill displays and retains the returned outcome
API Response Format	Current SolaBill sandbox envelope; compatibility changes are published in the changelog	Must match the separately approved production contract and release

⚠️

Important: Never use sandbox credentials in production. Customer SolaBill API tokens and Orchida provider credentials are separate secrets. Production access remains unavailable until every legal, provider, security, sandbox, pilot, deployment and go-live gate passes.

📦 Sample Data

The sandbox comes pre-loaded with the following test data after each reset:

🧾

25 Invoices

Synthetic invoice drafts for creation, validation, submission, and status testing through the approved Orchida sandbox workflow.

📄

10 Credit Notes

Internal drafts linked to existing invoices for partial and full credit scenarios; no regulated submission.

📥

5 Incoming eInvoices

Synthetic Orchida purchase-sync results with retained revision and evidence metadata.

🔔

2 Webhook Subscriptions

Pre-configured webhook URLs with delivery history logs.

🔬 Interactive API Explorer

Try API calls directly from this page only after an administrator securely assigns your tenant-isolated SolaBill test account. No shared credentials are embedded here.

🔑

How to authenticate in the explorer:

First, use the POST /client/auth/login endpoint below to get a token
Click the green Authorize 🔒 button at the top of the explorer
Enter: Bearer YOUR_TOKEN (include the word Bearer)
Click Authorize then Close
All subsequent requests will include your token automatically

1. Login → Get Token

→

2. Click Authorize 🔒

→

3. Paste Bearer Token

→

4. Expand Endpoint

→

5. Try It Out

→

6. Execute ▶

✅ Pre-Production Checklist

Before switching from sandbox to production, verify all of the following:

☐
Authentication flow — Login, token storage, refresh/re-login on 401, logout
☐
Invoice creation — Valid payloads accepted (201), invalid payloads rejected (422)
☐
Credit-note boundary — Drafts link correctly; regulated submission remains blocked until the confirmed Orchida contract and sandbox mapping exist
☐
Buyer and onboarding data — Verify buyer profiles supply ordinary endpoint data and regulated onboarding remains Orchida-owned
☐
Orchida status tracking — Reconcile provider-validation, top-level invoice, tax-authority and receiver states separately without inferring exchange success
☐
Pagination — Handle has_more, current_page, last_page correctly
☐
Error handling — Parse error envelope (error.code, error.message, error.details)
☐
Rate limit handling — Respect 429 responses and Retry-After header
☐
Webhook verification — Validate HMAC signature, reject stale/duplicate events
☐
Invoice idempotency — No duplicate Orchida invoice submission on safe retries; never imply credit-note submission is enabled
☐
Request tracing — Log X-Request-Id header from responses for support tickets
☐
Production promotion — Provision a separately approved production connection; never turn sandbox into production by changing only a URL

🚀

Checklist completion is not production authorization. Preserve the sandbox acceptance evidence, then follow the controlled customer onboarding, deployment, and seven-control partnership go-live process. Only Orchida issues/revokes provider credentials through its approved secure channel.