# Core concepts

The Lazy Embedded API is built around four levels. Your platform owns businesses, one per customer.
Each business has transactions, and each transaction groups one or more documents.

```mermaid
flowchart TD
    Platform["Your platform"]
    Platform --> B1["Business (tenant): customer-1042"]
    Platform --> B2["Business (tenant): customer-1043"]
    B1 --> T1["Transaction: one payment"]
    B1 --> T2["Transaction: another payment"]
    T1 --> D1["Document: tax invoice"]
    T1 --> D2["Document: receipt"]
    T2 --> D3["Document: utility bill"]
```

## Platform

Your platform is your company's account with Lazy. It holds your [API keys](https://developers.lazyinvoice.co.il/embedded/authentication/)
and your contract with Lazy. The contract sets each business's limits and prices. Lazy bills your
platform once a month for all its businesses and for the extras bought for them.

## Business

A business is a tenant: one of your customers inside Lazy. Each business's documents,
transactions, settings and usage are isolated from every other business, including the other
businesses of your platform. Create one business per customer, and never share a business between
customers.

A business has two IDs:

| ID            | Who chooses it | Used for                                                                         |
| ------------- | -------------- | -------------------------------------------------------------------------------- |
| `biz_id`      | Lazy           | The path of every request about the business, such as `/v1/businesses/{biz_id}`. |
| `external_id` | Your platform  | Linking the business to your own customer record, and finding it again.          |

The `external_id` is unique within your platform. Creating a second business with the same
`external_id` fails with `409 business_exists`, and the error names the existing business's
`biz_id`. You can change a business's `external_id` later with
[Update a business](https://developers.lazyinvoice.co.il/embedded/api/businesses/update/).

A business also has tax info: its tax profile, such as its business type and whether it is
registered for VAT. See the
[tax info object](https://developers.lazyinvoice.co.il/embedded/objects/tax-info/).

Deleting a business is permanent: there is no way to restore it.

## Usage and limits

Each business has a monthly document allowance and a limit on how far back Lazy scans its email.
The [usage object](https://developers.lazyinvoice.co.il/embedded/objects/usage/) shows both, along with how many documents the business
used in the current period. You can raise either limit for one business:

- [Top up documents](https://developers.lazyinvoice.co.il/embedded/api/usage/top-up/) adds documents to the current month.
- [Extend the scan period](https://developers.lazyinvoice.co.il/embedded/api/usage/scan-period/) makes Lazy scan further back,
  permanently.

Both purchases are billed to your platform in its next monthly bill.

## Documents and transactions

A document is one financial document of the business. Lazy reads these types:

- tax invoice
- tax invoice-receipt
- receipt
- proforma invoice
- credit note
- utility bill
- fine
- order confirmation

Documents reach Lazy in three ways:

- **Email sync:** Lazy scans the business's connected mailbox.
- **WhatsApp:** the business sends documents to Lazy on WhatsApp.
- **Manual upload:** the business uploads a file.

A transaction is one payment, either revenue or expense, with the other side of the payment as its
party: a supplier for an expense, a customer for revenue. Lazy groups the documents of one payment
into its transaction. For example, the tax invoice and the receipt for the same purchase belong to
one transaction. Every document belongs to exactly one transaction.

The API does not expose documents and transactions yet. The [changelog](https://developers.lazyinvoice.co.il/embedded/changelog/)
announces them when it does.