Skip to content

Following an invoice to its outcome

Waiting on the invoice or on the event stream (no public URL needed) and reading its files and emails.

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.
held_closed_by_staff The provider kept giving an answer the service could not interpret, so the invoice was held, and a person of the staff of the service closed it as failed after asking the provider for it. Nothing was sent to close it. Its number stays used. Issue the sale again as a new invoice (POST /v1/invoices). The event invoice.failed carries, in close, the reason the staff wrote. GET /v1/invoices/{id}/correction also works: it asks the provider again first.

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 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.

Type to search…

↑↓ navigate↵ selectEsc close