# Generate the detailed VAT return (PCN874)

`POST /businesses/{bid}/exports/pcn874`

Requires the `export` scope.

The file a dealer uploads to the Tax Authority for the period's VAT return (דיווח מפורט, mandatory from ₪500,000 of yearly turnover since 2026): header entry, one entry per invoice and credit note (identified customers each, unidentified ones summed per month), one per supplier invoice carrying VAT (suppliers with no id summed as petty cash), closing entry. Built from the ledger alone; the summary carries the four figures of the return and the warnings to fix before uploading. Download the file through `GET /files/{id}`.

## Path parameters

| Name | Type | | Description |
|---|---|---|---|
| `bid` | string | **required** | Business id, from `POST /businesses`. |

## Body

| Field | Type | | Description |
|---|---|---|---|
| `period` | string | **required** | YYYY-MM: the reporting month. For a bi-monthly filer, the LAST month of the period. |
| `months` | integer |  | 1 (monthly) or 2 (bi-monthly). One of: `1`, `2`. Default `1`. |

## Response

`201`: `{ "ok": true, … }`

| Field | Type | | Description |
|---|---|---|---|
| `ok` | boolean | **required** |  |
| `exportRun` | ExportRun | **required** | One OPENFRMT (מבנה אחיד) generation, with its verification summary. |
| `file` | FileMeta |  |  |
| `totals` | VatTotals |  | The periodic VAT return in whole shekels, signed (a period of credit notes can go negative). |
| `warnings` | array of VatWarning |  |  |

Errors: `400`, `401`, `403`, `404`, `429`. Every failure answers `{ "error", "reason", "hint", "param", "doc_url", "retryable", "request_id" }`: branch on `reason`, and read `hint` for what to change (https://docs.billos.co.il/errors.md).

## Examples

### cURL

```bash
curl -X POST "$BASE/businesses/$BID/exports/pcn874" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "period": "string"
  }'
```
### Node

```node
const res = await fetch(`${BASE}/businesses/${BID}/exports/pcn874`, {
  method: 'POST',
  headers: {
    'X-Api-Key': KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "period": "string"
  }),
})
const data = await res.json()
if (!data.ok) throw new Error(data.reason)
```
### Python

```python
import requests
res = requests.post(
    f"{BASE}/businesses/{BID}/exports/pcn874",
    headers={"X-Api-Key": KEY},
    json={
      "period": "string"
    },
)
data = res.json()
```