Build on SolaBill API
Integrate ordinary invoice inputs, internal credit-note drafts, exact Orchida outcomes, incoming evidence, and ERP workflow through tenant-scoped client APIs. Regulated production access is not yet available.
Documentation Map
Getting Started
Step-by-step onboarding from authentication to draft creation and approved Orchida sandbox submission.
API Reference
Endpoint catalog, schemas, request/response examples, and status codes.
Webhooks
Event payloads, signature verification, retry model, and consumer guidance.
Sandbox
Integration-safe environment for testing happy and failure paths before go-live.
SDKs
Language clients and quick-start snippets for PHP, Node.js, and Python.
Changelog
Release notes, versioning changes, and compatibility guidance.
Integration Flow
| Step | Action | Output |
|---|---|---|
| 1 | Login via POST /api/v1/client/auth/login | Bearer access token |
| 2 | Create an invoice or credit-note draft | Internal customer-scoped draft; no regulated delivery claimed |
| 3 | Explicitly submit an invoice through an approved scoped Orchida sandbox connection | Exact provider result retained; credit-note submission remains blocked |
| 4 | Read separate provider-validation, Orchida invoice, authority and receiver states | Current Orchida-returned evidence without an invented exchange-success claim |
| 5 | Handle SolaBill webhooks and reconcile ambiguous outcomes before retry | Auditable application workflow without blind duplicate submission |
Customer API and Orchida Boundary
| Layer | Used by | Responsibility |
|---|---|---|
| SolaBill Client API | Customer ERP and approved client applications | Ordinary invoice inputs, drafts, workflow, customer-visible status and evidence access. |
| Internal Orchida Adapter | SolaBill server only | Maps approved requests to Orchida's contracted API and preserves exact provider responses. Orchida credentials are never exposed to customers. |
| Orchida Regulated Service | Appointed provider service | PINT-AE document generation, regulated validation, exchange and authority reporting, subject to contract, sandbox approval and production authorization. |
Important: an accepted SolaBill API request is not presented as final delivery. Consumers must read the separate provider, exchange, authority and receiver outcomes returned through the integration.
Auth Basics
Every request must include an active client token and stay within authorized tenant/client boundaries. Unauthorized or cross-tenant access attempts are denied.
| Area | Rule | Priority |
|---|---|---|
| Token Usage | Include Authorization: Bearer <token> in each protected endpoint call. | Critical |
| Scope Control | Never reuse tokens across client accounts or tenants. | Critical |
| Rotation | Rotate credentials periodically and revoke compromised tokens immediately. | High |
Integration Best Practices
- Use idempotent keys or unique business document identifiers when implementing retries.
- Validate payloads client-side before submission to reduce 422 response loops.
- Implement exponential backoff on transient errors like 429, 500, and 503.
- Persist webhook events and handle duplicates safely.
- Run regression tests in sandbox before promoting integration changes.