SolaBill API Getting Started

Integrate your ERP or billing system in a few steps: authenticate, submit invoice payloads, monitor processing status, and receive events through webhooks.

API v1 Bearer Token Auth Webhook Retries Enabled

Prerequisites

Before calling production APIs, make sure your client account setup is complete.

RequirementDescriptionStatus
Client User CredentialsActive email/password for API loginRequired
Peppol Participant IDRegistered ID for outbound document exchangeRequired
Webhook EndpointPublic HTTPS endpoint to receive callbacksRecommended
Sandbox ValidationRun end-to-end test in sandbox firstRecommended

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"
  }
}

Send Invoice

Create an invoice using your bearer token. 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": "ae:TRN123456789000003",
    "issue_date": "2026-02-12",
    "due_date": "2026-03-12",
    "currency": "AED",
    "total_amount": 1500.00
  }'

Validation

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

Queue Processing

After create, message processing runs in the background queue for transport and status updates.

Idempotency Strategy

Use unique invoice identifiers on retries to avoid duplicate financial records.

Track Status

Use tracking endpoints to monitor lifecycle states from acceptance to delivery.

curl -X GET "https://solabill.com/api/v1/client/messages/{trackingId}" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
StatusMeaningAction
acceptedRequest accepted and queuedWait for next event
processingDocument under validation/transportPoll or wait for webhook
deliveredSuccessfully deliveredMark complete in ERP
failedDelivery or validation failedInspect error and retry flow

Webhook Flow

Subscribe to events to avoid frequent polling and get near-real-time updates.

  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