SolaBill API Getting Started

Integrate ordinary ERP or billing data in a few steps: authenticate, create invoice drafts, explicitly use an approved Orchida sandbox connection, and monitor separate provider outcomes.

API v1 Bearer Token Auth Webhook Retries Enabled

Prerequisites

Regulated production access is not currently available. Before testing provider submission, complete the controlled client and Orchida sandbox onboarding gates.

RequirementDescriptionStatus
Client User CredentialsActive email/password for API loginRequired
Buyer ProfileOrdinary customer routing, address and payment inputs required by the provisional Orchida mapperRequired
Scoped Orchida Sandbox ConnectionAPI-reachable current credential with Orchida company-scope evidence; no shared provider credentialsRequired for submission
Webhook EndpointPublic HTTPS endpoint to receive callbacksRecommended
Sandbox AcceptanceRun and retain approved scenarios; SolaBill input checks are not PINT-AE validationRequired before production

Authentication

Get an access token and pass it in the Authorization: Bearer <token> header.

curl -X POST "https://solabill.com/api/v1/client/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client.user@example.com",
    "password": "password",
    "device_name": "erp-connector"
  }'
{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "1|sample-token-value",
    "token_type": "Bearer"
  }
}

Create an invoice draft, then test the approved Orchida sandbox

First create a draft with ordinary business data. Keep invoice_number unique per client account.

curl -X POST "https://solabill.com/api/v1/client/invoices" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-2026-1001",
    "recipient_name": "Acme LLC",
    "recipient_peppol_id": "123456789000003",
    "buyer_endpoint_scheme": "0235",
    "buyer_street": "Sheikh Zayed Road",
    "buyer_city": "Dubai",
    "buyer_subdivision": "DXB",
    "buyer_country": "AE",
    "issue_date": "2026-02-12",
    "issue_time": "09:30",
    "due_date": "2026-03-12",
    "currency": "AED",
    "total_amount": 105.00,
    "payment_means_code": "48",
    "items": [{
      "item_code": "SERVICE-1", "name": "Consulting", "description": "Professional consulting 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
    }]
  }'
curl -X POST "https://solabill.com/api/v1/client/invoices/{invoiceId}/submit-orchida" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

This second call is unavailable without an active, reachable, company-scope-confirmed Orchida connection in the selected sandbox environment. It must not be presented as production access.

Validation

Payload is validated before persistence. Invalid fields return HTTP 422 with field-level messages.

Responsibility

SolaBill captures and maps business inputs. Orchida creates and validates the regulated document and handles exchange and reporting.

Idempotency Strategy

Repeat the submit call with the unchanged draft safely; SolaBill uses a deterministic payload key and retains the provider result.

Track Orchida status

Read the invoice detail to see provider validation, Orchida invoice, tax-authority and receiver states separately.

curl -X GET "https://solabill.com/api/v1/client/invoices/{invoiceId}" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
StatusMeaningAction
submission_stateOrchida request validation resultFix provider errors if rejected
provider_invoice_stateCanonical view of Orchida's top-level invoice status; not independent proof of network exchangeWait while pending or submitted and inspect the exact provider_status
tax_authority_stateTax-authority outcome returned by OrchidaDo not infer from HTTP success
receiver_stateReceiver outcome returned by OrchidaReconcile separately

Webhook Flow

Subscribe to SolaBill customer webhooks for application events. Orchida provider-webhook semantics remain unconfirmed; do not assume every regulated state is event-driven or real-time.

  1. Create a webhook subscription from your client account.
  2. Verify signatures on incoming callback requests.
  3. Return HTTP 2xx quickly and process asynchronously in your system.
  4. Handle retries for duplicate deliveries safely.

Errors and Retries

HTTP CodeTypeHandling Guidance
400Bad requestFix payload structure and retry once corrected.
401UnauthorizedRefresh login token and retry.
403ForbiddenVerify account permissions and tenant scope.
422Validation errorInspect field errors and correct source mapping.
429Rate limitedApply exponential backoff and jitter.
500/503Server/transientRetry with backoff; alert if repeated.
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "invoice_number": ["The invoice number field is required."]
  }
}

Go Live Checklist

Back to Developers Home