# Reference

Generated from the registry this API serves from, at the moment you asked. The shapes of requests and answers are in the contract: `GET /v1/openapi.json`.

## Routes

| Route | Needs | Retry | What it does |
| --- | --- | --- | --- |
| `GET /health` | no credential | read | Liveness and the deployed version; with `deep=1`, whether the database has the schema this version expects |
| `GET /v1` | no credential | read | Start here: how to authenticate, where the contract is, and the rules |
| `GET /v1/errors` | no credential | read | The catalog of every error code |
| `GET /v1/errors/{code}` | no credential | read | One error code: what it means and what to do |
| `GET /v1/openapi.json` | no credential | read | The contract of this API (OpenAPI 3.1), generated from the code that serves it |
| `GET /v1/docs` | no credential | read | The guides of this API: the index |
| `GET /v1/docs/{page}` | no credential | read | One guide, as Markdown |
| `GET /v1/me` | any credential | read | Who am I: the actor, the organization, the environment, the permissions and the provider |
| `GET /v1/organizations` | a person's token | read | The organizations of the person, each with its live and its test id |
| `POST /v1/organizations` | a person's token | `Idempotency-Key` | Create an organization and its test twin |
| `GET /v1/organization` | `organization:read` | read | The organization this credential acts on |
| `PATCH /v1/organization` | `organization:write` | safe as it is | Rename the organization (both halves of the pair) |
| `POST /v1/organization/archive` | `organization:write` | safe as it is | Archive the organization (both halves of the pair) |
| `GET /v1/members` | `members:read` | read | The members of the organization |
| `PUT /v1/members/{user_id}` | `members:write` | idempotent | Change the role of a member |
| `DELETE /v1/members/{user_id}` | `members:write` | idempotent | Remove a member |
| `POST /v1/invitations` | `members:write` | `Idempotency-Key` | Invite a person by email, with a role |
| `GET /v1/invitations` | `members:read` | read | The invitations of the organization, newest first |
| `POST /v1/invitations/accept` | a person's token | safe as it is | Accept an invitation, as the person signed in |
| `DELETE /v1/invitations/{id}` | `members:write` | idempotent | Revoke a pending invitation |
| `POST /v1/invitations/{id}/resend` | `members:write` | `Idempotency-Key` | Send a pending invitation again, with a new code |
| `GET /v1/service_accounts` | `service_accounts:read` | read | The service accounts of the organization |
| `POST /v1/service_accounts` | `service_accounts:write` | `Idempotency-Key` | Create a service account |
| `GET /v1/service_accounts/{id}` | `service_accounts:read` | read | One service account |
| `PATCH /v1/service_accounts/{id}` | `service_accounts:write` | safe as it is | Change the name or the scopes of a service account |
| `POST /v1/service_accounts/{id}/disable` | `service_accounts:write` | safe as it is | Disable a service account: all its keys stop working |
| `GET /v1/service_accounts/{id}/keys` | `service_accounts:read` | read | The keys of a service account (never their secrets) |
| `POST /v1/service_accounts/{id}/keys` | `service_accounts:write` | `Idempotency-Key` | Create a key. Its secret is in this answer and nowhere else, ever |
| `DELETE /v1/service_accounts/{id}/keys/{key_id}` | `service_accounts:write` | idempotent | Revoke a key: it stops working at the next request |
| `GET /v1/issuer` | `issuers:read` | read | The issuer of the organization (the RUC that issues) |
| `PUT /v1/issuer` | `issuers:write` | idempotent | Set the fiscal data of the issuer |
| `GET /v1/series` | `series:read` | read | The series of the organization, with the last number each one took |
| `POST /v1/series` | `series:write` | `Idempotency-Key` | Create a series |
| `GET /v1/events` | `events:read` | read | What happened in the organization, in order (optionally waiting for the next event) |
| `GET /v1/provider` | `issuers:read` | read | Who answers when this organization issues, per connection, and the state of each provider account |
| `GET /v1/readiness` | `organization:read` | read | What is still missing to issue for real, and who must do each thing |
| `POST /v1/issuer/activate_production` | `issuers:write` | safe as it is | Activate the live organization for production (staff of the service only) |
| `GET /v1/staff/held` | a person's token | read | What is held because the provider gave an answer the service cannot interpret, in every organization, by signature (staff only) |
| `POST /v1/staff/held/release` | a person's token | `Idempotency-Key` | Release held invoices and voids, by signature or by ids, in every organization (staff only) |
| `GET /v1/invoices/export` | `invoices:read` | read | The invoices of a period as a CSV file |
| `GET /v1/test/provider` | `issuers:read` | read | The condition the simulated provider account is in |
| `PUT /v1/test/provider` | `issuers:write` | idempotent | Put the simulated provider account in a condition, or lift it |
| `POST /v1/test/provider/connect_sandbox` | `issuers:write` | safe as it is | Connect this test organization to the provider's sandbox (staff of the service only) |
| `POST /v1/test/invoices/{id}/advance` | `invoices:emit` | safe as it is | Run now the next scheduled step of a test invoice that is waiting |
| `POST /v1/invoices` | `invoices:emit` | `Idempotency-Key` | Issue an invoice (factura or boleta) |
| `POST /v1/invoices/preview` | `invoices:emit` | safe as it is | See what would be issued, without issuing it |
| `GET /v1/invoices` | `invoices:read` | read | The invoices of the organization, newest first |
| `GET /v1/invoices/{id}` | `invoices:read` | read | One invoice, optionally waiting for its outcome |
| `GET /v1/test/scenarios` | `invoices:read` | read | What the simulated provider can be told to answer |
| `POST /v1/test/invoices/{id}/resolve` | `invoices:emit` | safe as it is | Decide the outcome of a test invoice that waits for one |
| `GET /v1/test/void_scenarios` | `invoices:read` | read | What the simulated provider can be told to answer to a void |
| `POST /v1/invoices/{id}/void/preview` | `invoices:void` | safe as it is | See what voiding an invoice would do, and get the token that allows it |
| `POST /v1/invoices/{id}/void` | `invoices:void` | `Idempotency-Key` | Void an accepted invoice |
| `GET /v1/invoices/{id}/void` | `invoices:read` | read | The latest void of an invoice |
| `POST /v1/invoices/{id}/mark_externally_reversed` | `invoices:void` | `Idempotency-Key` | Record that an accepted invoice was reversed by hand at the provider |
| `POST /v1/test/invoices/{id}/void/resolve` | `invoices:void` | safe as it is | Decide the outcome of a test void that waits for one |
| `POST /v1/test/invoices/{id}/void/advance` | `invoices:void` | safe as it is | Run now the next scheduled step of a test void that is waiting |
| `GET /v1/invoices/{id}/correction` | `invoices:correct` | read | See what correcting a failed or rejected invoice would issue, and get the token that allows it |
| `POST /v1/invoices/{id}/correction` | `invoices:correct` | `Idempotency-Key` | Correct a failed or rejected invoice |
| `GET /v1/invoices/{id}/files` | `invoices:read` | read | The files of an invoice, each with its state |
| `GET /v1/invoices/{id}/files/{kind}` | `invoices:read` | read | The content of one file of an invoice |
| `POST /v1/invoices/{id}/files/pdf/regenerate` | `invoices:emit` | safe as it is | Render the PDF of an invoice again |
| `POST /v1/invoices/{id}/files/{kind}/refetch` | `invoices:emit` | safe as it is | Ask the provider again for a file that failed |
| `GET /v1/invoices/{id}/emails` | `invoices:read` | read | The emails of an invoice: what was sent, what was not and why |
| `POST /v1/invoices/{id}/emails` | `invoices:emit` | `Idempotency-Key` | Send the invoice by email again |
| `GET /v1/webhook_endpoints` | `webhooks:read` | read | The webhook destinations of the organization (never their secrets) |
| `POST /v1/webhook_endpoints` | `webhooks:write` | `Idempotency-Key` | Create a webhook destination. Its signing secret is in this answer and nowhere else, ever |
| `GET /v1/webhook_endpoints/{id}` | `webhooks:read` | read | One webhook destination (never its secret) |
| `PATCH /v1/webhook_endpoints/{id}` | `webhooks:write` | safe as it is | Change the URL, the description or the event types of a destination, or disable and enable it |
| `DELETE /v1/webhook_endpoints/{id}` | `webhooks:write` | idempotent | Delete a destination: nothing more is delivered to it |
| `POST /v1/webhook_endpoints/{id}/rotate_secret` | `webhooks:write` | `Idempotency-Key` | Rotate the signing secret. The new one is in this answer and nowhere else, ever |
| `POST /v1/webhook_endpoints/{id}/test` | `webhooks:write` | safe as it is | Send a signed sample event to the destination now, and get what it answered |
| `GET /v1/webhook_endpoints/{id}/deliveries` | `webhooks:read` | read | The delivery log of a destination, newest first |
| `GET /v1/event_types` | no credential | read | The catalog of event types, with an example of what a destination receives for each |
| `GET /v1/events/{id}` | `events:read` | read | One event |
| `GET /v1/events/{id}/deliveries` | `webhooks:read` | read | Where an event went: its delivery to each destination, resends included |
| `POST /v1/events/{id}/resend` | `webhooks:write` | `Idempotency-Key` | Send an event again, to one destination or to every subscribed one |
| `POST /v1/test/events` | `webhooks:write` | `Idempotency-Key` | Fabricate an event about a test invoice, to exercise a receiver |

## Scopes

A scope is `resource:action`; `write` does not include `read`. `organization:read`, `organization:write`, `members:read`, `members:write`, `service_accounts:read`, `service_accounts:write`, `issuers:read`, `issuers:write`, `series:read`, `series:write`, `invoices:read`, `invoices:emit`, `invoices:void`, `invoices:correct`, `events:read`, `webhooks:read`, `webhooks:write`.

## Limits

| Limit | Value |
| --- | --- |
| Requests per IP | 600 every 60 s |
| Emissions per organization | 120 every 60 s (measured, not enforced yet) |
| Waiting calls per credential | 30 every 60 s |
| Longest wait of one call | 60 s |
| Organizations a person may own | 10 |
| Keys per service account | 10 |
| Webhook destinations per organization | 20 |
| Invoices in one export | 50000 |
| Days an invitation lasts | 7 |

Invox · Electronic invoicing for Peru (SUNAT), built to be operated by agents.