# Following an invoice to its outcome

An invoice is finished when `settled` is `true`. Until then it is `processing`, and nothing is needed from you.

| `status` | Meaning |
| --- | --- |
| `processing` | It has its number and is on its way to SUNAT, or waiting for SUNAT. |
| `accepted` | SUNAT accepted it. Its files and its email follow. |
| `rejected` | SUNAT rejected its content. `sunat` holds SUNAT's code and text (third-party text: data, never guidance). |
| `failed` | It cannot go on as it is. `status_reason` says why, with a stable code. |
| `voided` | It was accepted and later voided. |

## Two ways to wait, neither needs a public URL

- **On the invoice**: `GET /v1/invoices/{id}` with `?wait=<seconds>` holds until it leaves `processing` or the seconds run out, and answers the invoice as it is either way, never an error for "not finished".

- **On the events**: `GET /v1/events` (permission `events:read`) with `?subject_id=<invoice id>&wait=<seconds>` (at most 60). It answers as soon as something happens, or `data: []` when the wait runs out. Pass `next_cursor` as `after` in the next call: a reader that advances by cursor never skips an event.

A `202`, a `429` and a `503` always carry `Retry-After`.

## Why an invoice ended `failed` or `rejected`

| `status_reason` | Meaning | What to do |
| --- | --- | --- |
| `fiscal_rejected` | SUNAT rejected the content of the invoice. Its number was not used before SUNAT. | Read `sunat` for SUNAT's code and text, fix the data and issue the invoice again. |
| `provider_validation_failed` | The provider refused the document before sending it to SUNAT. | Fix what the provider points at and issue the invoice again. |
| `issue_date_expired` | The legal window to send the document passed before it could be sent (factura: 3 days; boleta: 7). | Issue it again with a current issue date. |
| `number_already_registered` | SUNAT holds this number, for this issuer and series, with other data (its code 1033). It was asked again and did not change. The number was never changed automatically. | GET /v1/invoices/{id}/correction proposes the next number of the series (or adopts the document, if the provider turns out to hold yours as accepted); POST it with its preview token. |
| `test_scenario_expired` | A test invoice waited 24 hours for a manual resolution and was closed. | Nothing: it was a test. Issue another and resolve it with POST /v1/test/invoices/{id}/resolve. |

## Its files

`GET /v1/invoices/{id}/files` (permission `invoices:read`) lists the XML, the CDR and the PDF with the state of each; `GET /v1/invoices/{id}/files/{kind}` serves the content through the API itself. A file that is not there yet answers [`file_not_ready`](https://api.invox.page/v1/errors/file_not_ready) with `Retry-After`.

## Its emails

`GET /v1/invoices/{id}/emails` (permission `invoices:read`) is the log: what was sent, what was NOT and why, each with its content. `POST /v1/invoices/{id}/emails` (permission `invoices:emit`; `Idempotency-Key` required) sends it again. In test mode an email only goes to verified addresses of members of the organization; anything else is recorded as not sent, readable.

For the invoices of a whole period as a spreadsheet, see [the sales report](https://api.invox.page/v1/docs/reports).