# BizNovia API Reference

BizNovia exposes a versioned JSON API designed for the Vue web app and future mobile apps.

## Base URL

Local development:

```text
http://127.0.0.1:8000/api/v1
```

## Headers

Authenticated tenant endpoints require:

```http
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json
X-Company-ID: <company_id>
```

Public auth, public plans, and customer portal login endpoints do not require `X-Company-ID`.

## Response Shape

Most endpoints return:

```json
{
  "success": true,
  "message": "Optional message",
  "data": {}
}
```

Validation errors return `422` with `message` and `errors`. Feature, permission, and tenant access errors return `403` or `404` depending on the case.

## Auth

| Method | Endpoint | Purpose |
| --- | --- | --- |
| POST | `/auth/register` | Register user and return Sanctum token |
| POST | `/auth/login` | Login and return Sanctum token |
| POST | `/auth/forgot-password` | Send password reset link |
| POST | `/auth/reset-password` | Reset password |
| GET | `/auth/verify-email/{id}/{hash}` | Verify signed email link |
| GET | `/auth/me` | Current authenticated user |
| POST | `/auth/email/verification-notification` | Resend email verification |
| POST | `/auth/logout` | Revoke current token |

## SaaS and Tenant

| Method | Endpoint | Purpose |
| --- | --- | --- |
| GET | `/health` | API health check |
| GET | `/plans` | Public active plans |
| GET | `/companies` | User companies |
| POST | `/companies` | Create company workspace |
| GET | `/companies/{company}` | Show one user company |
| GET | `/tenant/current` | Current company, subscription, features, permissions |
| PATCH | `/tenant/settings` | Update company profile/defaults |
| POST | `/tenant/subscription/switch-plan` | Switch active company plan |
| GET | `/tenant/members` | List company members |
| POST | `/tenant/members` | Add member |
| PATCH | `/tenant/members/{member}` | Update member role |
| DELETE | `/tenant/members/{member}` | Remove member |

## Invoice

Requires `feature: invoice`.

| Method | Endpoint | Permission | Purpose |
| --- | --- | --- | --- |
| GET | `/customers` | `invoice.view` | List customers |
| POST | `/customers` | `invoice.manage` | Create customer |
| PATCH | `/customers/{customer}` | `invoice.manage` | Update/deactivate customer |
| GET | `/invoices` | `invoice.view` | List invoices |
| POST | `/invoices` | `invoice.manage` | Create invoice |
| GET | `/invoices/{invoice}` | `invoice.view` | Invoice detail |
| PATCH | `/invoices/{invoice}` | `invoice.manage` | Update invoice status |
| POST | `/invoices/{invoice}/payments` | `invoice.manage` | Record payment |
| GET | `/invoices/{invoice}/export/html` | `invoice.view` | Printable invoice HTML |

## Customer Portal

Customer portal endpoints use the customer portal token, not the tenant user token.

| Method | Endpoint | Purpose |
| --- | --- | --- |
| POST | `/customer-portal/auth/login` | Customer login |
| GET | `/customer-portal/me` | Customer portal account |
| PUT | `/customer-portal/profile` | Update customer portal profile/password |
| POST | `/customer-portal/auth/logout` | Revoke customer token |
| GET | `/customer-portal/dashboard` | Customer invoice summary |
| GET | `/customer-portal/invoices` | Customer invoice list |
| GET | `/customer-portal/invoices/{invoice}` | Customer invoice detail |
| GET | `/customer-portal/invoices/{invoice}/export/html` | Printable customer invoice HTML |

Tenant users with `invoice.manage` can manage portal accounts:

| Method | Endpoint | Purpose |
| --- | --- | --- |
| GET | `/customers/{customer}/portal-account` | Show portal account |
| POST | `/customers/{customer}/portal-account` | Create portal account |
| PUT | `/customers/{customer}/portal-account` | Create/update portal account idempotently |
| PATCH | `/customers/{customer}/portal-account` | Update portal account |
| POST | `/customers/{customer}/portal-account/revoke-tokens` | Revoke customer tokens |

## POS

Requires `feature: pos`.

| Method | Endpoint | Permission | Purpose |
| --- | --- | --- | --- |
| GET | `/pos/sales` | `pos.view` | List sales |
| POST | `/pos/sales` | `pos.manage` | Complete sale |
| GET | `/pos/sales/{sale}` | `pos.view` | Sale detail |
| PATCH | `/pos/sales/{sale}` | `pos.manage` | Void sale |
| GET | `/pos/sales/{sale}/export/html` | `pos.view` | Printable receipt HTML |

## Inventory

Requires `feature: inventory`.

| Method | Endpoint | Permission | Purpose |
| --- | --- | --- | --- |
| GET | `/inventory/categories` | `inventory.view` | List categories |
| POST | `/inventory/categories` | `inventory.manage` | Create category |
| PATCH | `/inventory/categories/{category}` | `inventory.manage` | Update/deactivate category |
| GET | `/inventory/products` | `inventory.view` | List products |
| GET | `/inventory/products/lookup` | `inventory.view` | Exact active product lookup by barcode/SKU |
| POST | `/inventory/products` | `inventory.manage` | Create product |
| PATCH | `/inventory/products/{product}` | `inventory.manage` | Update product |
| POST | `/inventory/products/{product}/adjust-stock` | `inventory.manage` | Manual stock adjustment |
| GET | `/inventory/products/export/csv` | `inventory.view` | Product CSV export |
| GET | `/inventory/products/low-stock` | `inventory.view` | Low-stock products |
| GET | `/inventory/suppliers` | `inventory.view` | List suppliers |
| POST | `/inventory/suppliers` | `inventory.manage` | Create supplier |
| PATCH | `/inventory/suppliers/{supplier}` | `inventory.manage` | Update supplier |
| GET | `/inventory/purchases` | `inventory.view` | List purchases |
| POST | `/inventory/purchases` | `inventory.manage` | Receive purchase |
| GET | `/inventory/purchases/{purchase}` | `inventory.view` | Purchase detail |
| PATCH | `/inventory/purchases/{purchase}` | `inventory.manage` | Cancel purchase |
| GET | `/inventory/purchases/export/csv` | `inventory.view` | Purchase CSV export |

## Accounting

Requires `feature: accounting`.

| Method | Endpoint | Permission | Purpose |
| --- | --- | --- | --- |
| GET | `/accounting/summary` | `accounting.view` | Income/expense summary |
| GET | `/accounting/accounts` | `accounting.view` | List financial accounts |
| POST | `/accounting/accounts` | `accounting.manage` | Create account |
| PATCH | `/accounting/accounts/{financialAccount}` | `accounting.manage` | Update/deactivate account |
| GET | `/accounting/transactions` | `accounting.view` | Ledger transactions |
| POST | `/accounting/transactions` | `accounting.manage` | Manual ledger entry |
| POST | `/accounting/transfers` | `accounting.manage` | Transfer between accounts |
| GET | `/accounting/transactions/export/csv` | `accounting.view` | Ledger CSV export |
| GET | `/accounting/expense-categories` | `accounting.view` | Expense categories |
| POST | `/accounting/expense-categories` | `accounting.manage` | Create expense category |
| PATCH | `/accounting/expense-categories/{expenseCategory}` | `accounting.manage` | Update/deactivate expense category |
| GET | `/accounting/expenses` | `accounting.view` | List expenses |
| POST | `/accounting/expenses` | `accounting.manage` | Record expense |
| PATCH | `/accounting/expenses/{expense}` | `accounting.manage` | Update/void expense |
| GET | `/accounting/expenses/export/csv` | `accounting.view` | Expense CSV export |

## CRM

Requires `feature: crm`.

| Method | Endpoint | Permission | Purpose |
| --- | --- | --- | --- |
| GET | `/crm/summary` | `crm.view` | Lead summary |
| GET | `/crm/leads` | `crm.view` | List leads |
| POST | `/crm/leads` | `crm.manage` | Create lead |
| PATCH | `/crm/leads/{lead}` | `crm.manage` | Update lead stage/status |
| POST | `/crm/leads/{lead}/activities` | `crm.manage` | Add activity/follow-up |
| POST | `/crm/leads/{lead}/convert` | `crm.manage` | Convert lead to customer |

## Reports

Requires `feature: reports` and `reports.view`.

| Method | Endpoint | Purpose |
| --- | --- | --- |
| GET | `/reports/overview` | Business overview |
| GET | `/reports/sales` | Sales grouped by day/payment |
| GET | `/reports/inventory` | Stock and purchase reporting |
| GET | `/reports/crm` | CRM pipeline reporting |

## Notifications

Requires `feature: notification`.

| Method | Endpoint | Permission | Purpose |
| --- | --- | --- | --- |
| GET | `/notifications` | `notification.view` | Notifications and live alerts |
| POST | `/notifications` | `notification.manage` | Create notification |
| PATCH | `/notifications/{notification}/read` | `notification.view` | Mark one notification read |
| POST | `/notifications/read-all` | `notification.view` | Mark all notifications read |

## Super Admin

Requires authenticated super admin user.

| Method | Endpoint | Purpose |
| --- | --- | --- |
| GET | `/super-admin/summary` | Platform summary |
| GET | `/super-admin/companies` | List tenant companies |
| PATCH | `/super-admin/companies/{company}/status` | Update tenant status |
| GET | `/super-admin/plans` | List plans |
| POST | `/super-admin/plans` | Create plan |
| PATCH | `/super-admin/plans/{plan}` | Update plan |
| GET | `/super-admin/features` | List features/modules |
| PATCH | `/super-admin/features/{feature}` | Update feature |
| GET | `/super-admin/subscriptions` | List subscriptions |
| PATCH | `/super-admin/subscriptions/{subscription}` | Update subscription |

## Mobile App Notes

- Store the tenant token separately from the customer portal token.
- Always send `X-Company-ID` after workspace selection for tenant module APIs.
- Use `/tenant/current` after login or company switch to hydrate features and permissions.
- Treat `403` feature errors as an upgrade/locked-module state.
- Pagination responses use `data.data` for records and `data.meta` for page metadata.