One Stop Invoice - HTTP API (v1)

JSON API under /v1/… on the same host as the web app (or on a subdomain whose document root is this project). Implementation entrypoint: `api/v1/index.php`.

The API hub and reference show the public base `https://api.onestopinvoice.com/v1` even on localhost, so copy-paste targets production. To override (e.g. staging), set `ONESTOP_API_V1_BASE`.

Authentication

1. Open Dashboard → API Key (requires api permission) and copy your key.
2. Every request must include the key in one of:

- Header Authorization: Bearer <your_api_key>

- Header X-API-Key: <your_api_key>

- Query ?api_key= (discouraged; logs and referrer leakage)

The key is stored on accounts.api_key. Invalid or missing key → 401 with error.code = unauthorized.

Account gates

Same rules as the logged-in app:

• Suspended account → 403 (account_suspended)
• Subscription expired → 403 (subscription_expired)

Response shape

Success:

{ "ok": true, "data": { } }

Error:

{
  "ok": false,
  "error": {
    "code": "validation_error",
    "message": "…",
    "details": { }
  }
}

CORS

If Origin is sent, the API reflects it and allows GET, POST, PATCH, DELETE, OPTIONS with Authorization, Content-Type, and X-API-Key. Preflight OPTIONS returns 204.

Pagination

List endpoints accept limit (default 50, max 200) and offset (default 0).

Document list filters

Invoice, quotation, debit note, credit note, and proforma invoice lists accept the same filter query params (combine as needed):

| Param | Applies to | Values / format |

|-------|------------|-----------------|

| fy_start_year | All document lists | Integer FY start year (Apr–Mar), e.g. 2025 for FY 2025–26 |

| date_from, date_to | All | Y-m-d document date range (ignored when fy_start_year is set) |

| client_id | All | Positive integer |

| search | All | Matches invoice/quotation number or client name |

| status | Invoices, debit/credit notes | draft, issued, cancelled, archived |

| payment_status | Invoices | pending, paid, partial, overdue |

| due_from, due_to | Invoices | Due date range (Y-m-d) |

| payment_date_from, payment_date_to | Invoices | Payment date range |

| approval_status | Quotations, proforma | pending, approved, rejected |

| document_kind | Quotations only | quotation or proforma (legacy rows on quotations table) |

Example — invoices for FY 2025–26, paid only:

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.onestopinvoice.com/v1/invoices?fy_start_year=2025&payment_status=paid&limit=50"

Client deduplication

POST /v1/clients checks existing rows in your account. If any of the following match a non-empty value you send, the API returns 200 with data.skipped: true and the existing data.client (no new row):

• Phone (normalized to 10 digits, compared to stored digits)
• Email (case-insensitive)
• GSTIN (exact)

Delete client

DELETE /v1/clients/{id} without related documents succeeds directly. If related invoices, quotations, proforma invoices, debit notes, or credit notes exist, you get 409 unless you call DELETE /v1/clients/{id}?cascade=1, which removes related document rows, nulls expense.client_id for that client, then deletes the client.

Bulk operations

Bulk delete — POST /v1/{resource}/bulk-delete with JSON body {"ids": [1, 2, 3]}. Supported resources: clients, invoices, quotations, debit-notes, credit-notes, proforma-invoices, inventory, expenses. Returns counts of deleted and skipped ids.

Bulk invoice PDF — POST /v1/invoices/bulk-pdf with {"ids": [101, 102]}. Returns a ZIP file of PDFs (binary response, not JSON).

Recent payments — GET /v1/invoices/recent-payments?since=2026-03-01%2000:00:00 returns invoices marked paid since the timestamp (useful for integrations polling payment status).

Binary responses

Some endpoints return files instead of the JSON envelope:

| Endpoint | Content-Type |

|----------|----------------|

| GET /v1/documents/{type}/{id}/pdf | application/pdf |

| POST /v1/invoices/bulk-pdf | application/zip |

Send Accept: application/json on JSON endpoints. For PDF/ZIP, save the raw response body.

Apache / subdomain

Same document root as the main site (recommended): `.htaccess` maps /v1/... to api/v1/index.php.

Subdomain `api.example.com` with document root = project root: no extra rules; use https://api.example.com/v1/me.

Subdomain with document root = `/api` folder only: ship the repo’s `../.htaccess` in that folder. It maps /v1/… to v1/index.php and rewrites extensionless paths (e.g. /docs/cursor-skill-download) to *.php so public links match api_docs_url(). Older /docs/guide and /docs/reference URLs redirect to the unified docs hub.

OpenAPI

Machine-readable contract: `openapi.yaml`. Human-friendly reference (examples + Try console) lives on the unified docs hub at `../index.php` (#ref-meta and section anchors).

Cursor / AI coding assistants

Download the maintained Agent Skill for this API (implementation notes, auth, endpoints, error codes):

• !MD0! save as .cursor/skills/onestop-api/SKILL.md (or your tool’s equivalent skill folder).
• !MD0! extra file map and error-code table (optional; link from the skill).

If these links 404, the server checkout is missing .cursor/skills/onestop-api/ (deploy with that directory or copy the files from the repo).

Integration cookbook (step-by-step)

Replace YOUR_API_KEY and the base URL with yours. Production base is typically https://api.onestopinvoice.com/v1 (or your own host + /v1).

1) Verify the key

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.onestopinvoice.com/v1/me"

You should see {"ok":true,"data":{...}} with account_id, currency, etc. If you see 401 / unauthorized, the key is wrong or missing.

2) Create a client (or reuse an existing one)

Minimum JSON: name, phone, email are required. address and gstin are optional. Use gstin only when you have a valid 15-character GSTIN; otherwise send "" or omit.

curl -sS -X POST "https://api.onestopinvoice.com/v1/clients" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Retail Pvt Ltd",
    "phone": "9876543210",
    "email": "billing@acme.example",
    "address": "Shop 12, MG Road, Bengaluru 560001",
    "gstin": ""
  }'

Response patterns:

• New client: data.skipped is false, and data.client.client_id is the id you need for invoices and quotations.
• Duplicate: if phone (10 digits), email, or GSTIN matches an existing client in your account, you get 200 with data.skipped: true and data.client set to the existing row. Always read client_id from this response before creating documents.

List or find clients:

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.onestopinvoice.com/v1/clients?limit=50&offset=0"

Each client object includes additive platform fields:

• uses_onestopinvoice — true when the client matches another One Stop Invoice account

(GSTIN first when present; if that fails or GSTIN is empty, business email)

• onestopinvoice_logo_url — that account's business logo URL when available; null if unused

or the matched account has no public logo URL (never a data: URI)

3) Invoice and quotation line items (same shape)

Both invoices and quotations accept an items array. Each element is one line. The server ignores any array entry where item_description is missing or empty after trim—so an “empty” {} or { "quantity": 1 } does nothing. Always set item_description.

| Field | Meaning |

|--------|---------|

| item_description | Required for the line to be saved (human-readable line text). |

| hsn_code | HSN/SAC string (can be ""). |

| quantity | Number (decimals allowed). |

| rate | Unit rate before tax (as you use in the app). |

| tax_rate | Percentage (e.g. 18 for 18%). |

| cgst_amount, sgst_amount, igst_amount | Tax amounts your integration calculated (intra-state often CGST+SGST; inter-state often IGST). |

| total_amount | Line total including tax (must match how your app/PDF logic works; the API stores what you send). |

| discount_type, discount_value | Optional; only if your database has discount columns (same as dashboard). discount_type: percentage or fixed. |

Inter-state example (IGST only, CGST/SGST zero): set igst_amount to your computed IGST and keep cgst_amount / sgst_amount at 0.

4) Create an invoice with lines

Required top-level fields: client_id, invoice_date, payment_due_date (dates as Y-m-d).

Optional: payment_status, status, currency, invoice_type, lut_number, declaration_text, items.

curl -sS -X POST "https://api.onestopinvoice.com/v1/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 10,
    "invoice_date": "2026-03-21",
    "payment_due_date": "2026-04-05",
    "payment_status": "pending",
    "status": "draft",
    "currency": "INR",
    "invoice_type": "local_sale",
    "items": [
      {
        "item_description": "Professional services March",
        "hsn_code": "998314",
        "quantity": 1,
        "rate": 10000,
        "tax_rate": 18,
        "cgst_amount": 900,
        "sgst_amount": 900,
        "igst_amount": 0,
        "total_amount": 11800
      }
    ]
  }'

Then fetch the full document with lines:

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.onestopinvoice.com/v1/invoices/101"

GET /v1/invoices returns list rows only (no items). Use GET /v1/invoices/{id} for items[].

5) Create a quotation with lines

Required: client_id, quotation_date.

If you omit validity_date, the API defaults it to quotation_date.

items uses the same keys as invoice lines (see table above).

curl -sS -X POST "https://api.onestopinvoice.com/v1/quotations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 10,
    "quotation_date": "2026-03-21",
    "validity_date": "2026-04-21",
    "approval_status": "pending",
    "currency": "INR",
    "quotation_type": "bill_of_supply",
    "items": [
      {
        "item_description": "Annual maintenance (quoted)",
        "hsn_code": "9987",
        "quantity": 1,
        "rate": 50000,
        "tax_rate": 18,
        "cgst_amount": 4500,
        "sgst_amount": 4500,
        "igst_amount": 0,
        "total_amount": 59000
      }
    ]
  }'

Why it looked like “empty parentheses” before: sample docs used "items": []. That creates a valid quotation/invoice with no saved lines, because there are no rows with a non-empty item_description. Populate items as in the example above.

6) Debit note lines (different shape)

Debit notes use different item fields: description, expense_date, amount (not item_description / HSN).

"items": [
  { "description": "Rate difference adjustment", "expense_date": "2026-03-21", "amount": 500 }
]

7) Credit note lines (same shape as debit notes)

Credit notes use description, expense_date, and amount per line (not invoice line fields). Optional source_invoice_id on create pre-fills from an existing invoice.

"items": [
  { "description": "Return adjustment", "expense_date": "2026-03-22", "amount": 500 }
]

8) Proforma invoices

Proforma invoices live on the dedicated proforma_invoices table (not the legacy document_kind: proforma path on quotations). Required: client_id, proforma_date, items[] with the same line shape as invoices.

curl -sS -X POST "https://api.onestopinvoice.com/v1/proforma-invoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 10,
    "proforma_date": "2026-03-22",
    "validity_date": "2026-04-22",
    "approval_status": "pending",
    "items": [
      {
        "item_description": "Advance order",
        "quantity": 1,
        "rate": 25000,
        "tax_rate": 18,
        "cgst_amount": 2250,
        "sgst_amount": 2250,
        "igst_amount": 0,
        "total_amount": 29500
      }
    ]
  }'

Convert to invoice: POST /v1/proforma-invoices/{id}/convert-to-invoice or POST /v1/quotations/{id}/convert-to-invoice.

9) Document utilities

| Action | Endpoint |

|--------|----------|

| Download PDF | GET /v1/documents/{type}/{id}/pdf — type is invoice, quotation, proforma-invoice, debit-note, or credit-note |

| Public share link | GET or POST /v1/documents/{type}/{id}/share |

| Revoke share | DELETE /v1/documents/{type}/{id}/share |

10) Sendouts and email

Send PDF: POST /v1/sendouts with client_id, document_type, document_id, subject, message.

Supported `document_type`: invoice, quotation, proforma-invoice, debit-note, credit-note.

History: GET /v1/sendouts?limit=20

Email template: GET /v1/sendouts/templates?document_type=invoice&client_id=10&document_id=101

Remove queue row: DELETE /v1/sendouts/{queue_id}

11) Mobile app notifications

Activity alerts and login notifications for the Flutter app — no SMTP cost. Authenticate with mobile Bearer token (POST /v1/auth/login).

| Action | Endpoint |

|--------|----------|

| Sign in | POST /v1/auth/login — { username, password } → access_token, refresh_token |

| Refresh token | POST /v1/auth/refresh |

| Current user | GET /v1/auth/me — Bearer access_token |

| List feed | GET /v1/notifications?limit=50&offset=0 — optional unread_only=1 |

| Unread badge | GET /v1/notifications/unread-count |

| Mark read | PATCH /v1/notifications/{id}/read |

| Mark all read | POST /v1/notifications/read-all |

| Push prefs | GET / PATCH /v1/notifications/prefs |

| Register FCM | POST /v1/devices — { fcm_token, platform: android\|ios } |

| Unregister FCM | DELETE /v1/devices — { fcm_token } |

Each notification includes deep_link for navigation (invoice_detail, client_detail, etc.). Login alerts are hidden for the user who signed in (actor_user_id filter).

Note: Client invoice PDF delivery still uses POST /v1/sendouts (email). Push is for your account team only.

12) Analytics

Summary: GET /v1/analytics/summary — dashboard aggregates. Optional ?fy_start_year=2025 scopes to a fiscal year; omit for all-time.

Full insights: GET /v1/analytics/full — extended metrics (expenses, inventory, TDS, credit notes, proforma, GST breakdown). Same optional fy_start_year.

13) TDS, settings, and integrations

| Group | Key endpoints |

|-------|----------------|

| TDS | GET/POST /v1/tds/sections, GET /v1/tds/deductions, PATCH /v1/tds/deductions/{id}/deposit, POST /v1/tds/certificates, GET /v1/tds/reports, POST /v1/tds/calculate |

| Settings | GET/PATCH /v1/settings/business, GET/POST/PATCH/DELETE /v1/settings/users/{id}, GET/PATCH /v1/settings/templates, GET/PATCH /v1/settings/ca-sync, POST /v1/settings/ca-sync/test-send, GET /v1/settings/api-key (masked, read-only) |

| Shopify | GET/POST/DELETE /v1/integrations/shopify, POST .../backfill, POST .../webhooks, GET .../logs |

Invoice create/update accepts optional TDS fields (tds_section_id, tds_rate, tds_amount) when your account uses TDS — same as the dashboard.

14) Typical automation flow

1. GET /v1/me confirm key and currency.
2. POST /v1/clients upsert client; read client_id (handle skipped).
3. POST /v1/quotations, POST /v1/proforma-invoices, or POST /v1/invoices with full items arrays.
4. GET /v1/.../{id} verify stored lines and totals.
5. GET /v1/documents/invoice/{id}/pdf download PDF, or POST /v1/sendouts email it.
6. GET /v1/analytics/full?fy_start_year=2025 pull FY metrics for reporting.

15) Debugging bad requests

• `validation_error` often invalid client_id, missing required dates, or wrong field names (e.g. debit note lines vs invoice lines).
• `401` key missing/invalid.
• `403` account_suspended or subscription_expired.
• `404` wrong id or resource not in your account.

Full error table: reference appendix.