# Edara API v3: Tax Invoices

Read the [guide](../guide.md) first: authentication, paging, errors, rate limits and the shared `PagedResult`, `BatchResult` and `*Reference` shapes.

- `GET /v3/tax-invoices/nr-report`: Gets the notes receivable report.
- `GET /v3/tax-invoices/np-report`: Gets the notes payable report.
- `POST /v3/tax-invoices/taxable-sales-invoices`: Creates a taxable sales invoice.

## Endpoints

### `GET /v3/tax-invoices/nr-report`: Gets the notes receivable report.

Operation `GetNrReport` · permission `read:tax-invoice-report`

**Responses**: OK `TaxInvoiceReportResponse`: Notes receivable report. · NotFound `ProblemDetails`: No report rows were found.

**Notes**

- The report takes no parameters. It always returns the notes that are not yet collected, with no date limit.
- The response is a generic table. `columns` lists each column's name and data type, and `rows` holds one object per row. Empty values are null.
- When there is no data, the endpoint returns `404` instead of an empty table, so handle `404` as an empty report.

---

### `GET /v3/tax-invoices/np-report`: Gets the notes payable report.

Operation `GetNpReport` · permission `read:tax-invoice-report`

**Responses**: OK `TaxInvoiceReportResponse`: Notes payable report. · NotFound `ProblemDetails`: No report rows were found.

**Notes**

- The report takes no parameters. It always returns the notes that are not yet collected.
- The response has the same generic `columns` and `rows` shape as the notes receivable report.
- When there is no data, the endpoint returns `404` instead of an empty table, so handle `404` as an empty report.

---

### `POST /v3/tax-invoices/taxable-sales-invoices`: Creates a taxable sales invoice.

Operation `CreateTaxableSalesInvoice` · permission `create:taxable-sales-invoice`

**Body**: `CreateTaxableSalesInvoiceRequest`

| field | type | default | validation | description |
|---|---|---|---|---|
| `salesOrderCode` | `string` |  | NotEmpty() | The source sales order code. |
| `invoiceNumber` | `int` |  | NotEmpty() .GreaterThan(0) | The taxable invoice number to assign. |
| `date` | `DateTime?` |  | NotNull() | The taxable invoice date. |

**Responses**: Created `TaxableSalesInvoiceResponse`: Taxable sales invoice created. · NotFound `ProblemDetails`: The related SI/IO/SO chain could not be resolved.

**Business errors** (HTTP 409, match on `errorCode`):

- `CannotSaveWithZeroQuantityOrPrice`: At least one invoice line has zero quantity or zero price.
- `DupplicatedDate`: Another invoice already uses the same date or numbering combination.
- `DupplicatedInvoiceNumber`: Another invoice already uses the same invoice number.
- `IO_SO_AlreadyHasRelatedInvoice`: The source IO or SO already has a taxable invoice, so it cannot be created again.
- `RelatedSalesOrderDeleted`: The linked sales order record was deleted, so the taxable sales invoice cannot reference it.
- `RelatedWorkorderDeleted`: The linked work order record was deleted, so the taxable sales invoice cannot be built from it.

**Notes**

- The sales order must have exactly one related document whose code starts with SI. If it has none or more than one, the request returns `400`, not `404`.
- If that document has a related issue offering (IO) document, the invoice is built from the issue offering. Otherwise it is built from the sales order. If any of these documents is missing, the request returns `404`.
- If the source issue offering or sales order already has a tax invoice, the request returns `409` `IO_SO_AlreadyHasRelatedInvoice`.
- A customer with an empty name returns `409` `SecondPartyMandatoryError`, even though this error is not listed for the endpoint.
- `CannotSaveWithZeroQuantityOrPrice` is returned only when a quantity is zero or less. A zero price does not trigger it.
- The invoice code is SlsInv-{year}-{invoiceNumber}, using your `invoiceNumber`. The year comes from the date of the source issue offering or sales order, not from `date`. `date` is stored as the invoice date.
- An `invoiceNumber` already used in the same year for another document of the same type returns `409` `DupplicatedInvoiceNumber`. You can also get `409` `DupplicatedDate`, and `RelatedWorkorderDeleted` or `RelatedSalesOrderDeleted` when the source document no longer exists.
- Creating the invoice does not create an accounting journal entry.

## Types

### `TaxInvoiceReportColumnResponse`

Response describing a tax invoice report column.

| field | type | description |
|---|---|---|
| `name` | `string` | The column name. |
| `type` | `string` | The CLR type name for column values. |

### `TaxInvoiceReportResponse`

Response describing a tax invoice report.

| field | type | description |
|---|---|---|
| `columns` | `IReadOnlyCollection<TaxInvoiceReportColumnResponse>` | The ordered column definitions. |
| `rows` | `IReadOnlyCollection<TaxInvoiceReportRowResponse>` | The ordered report rows. |

### `TaxInvoiceReportRowResponse`

Response describing a tax invoice report row.

| field | type | description |
|---|---|---|
| `values` | `IDictionary<string,object>` | The row values keyed by column name. |

### `TaxableSalesInvoiceResponse`

Response describing a created taxable sales invoice.

| field | type | description |
|---|---|---|
| `invoiceCode` | `string` | The created invoice code. |