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, with the RUC of the company |
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, or leave the organization |
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 |
POST /v1/invitations/inspect |
a person’s token | safe as it is | See an invitation before accepting it, 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 |
PATCH /v1/issuer |
issuers:write |
safe as it is | Change some fields of the issuer, without overwriting what someone else saved |
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 |
PATCH /v1/series/{id} |
series:write |
safe as it is | Deactivate, reactivate or move the next number of a series forward |
GET /v1/events |
events:read |
read | What happened in the organization, in order (optionally waiting for the next event) |
GET /v1/customers |
customers:read |
read | The customers of the organization, most recently invoiced first, by cursor |
GET /v1/customers/{id} |
customers:read |
read | One customer |
GET /v1/establishments |
issuers:read |
read | The establishments of the issuer, with their SUNAT annex codes |
POST /v1/establishments |
issuers:write |
Idempotency-Key |
Register an establishment of the issuer |
PATCH /v1/establishments/{code} |
issuers:write |
safe as it is | Change an establishment |
GET /v1/brand |
templates:read |
read | The brand of the organization |
PUT /v1/brand |
templates:write |
idempotent | Replace the brand of the organization |
PATCH /v1/brand |
templates:write |
safe as it is | Change some entries of the brand, without overwriting what someone else saved |
GET /v1/assets |
templates:read |
read | The image library of the organization |
PUT /v1/assets/{name} |
templates:write |
idempotent | Upload an image to the library, under a name |
DELETE /v1/assets/{name} |
templates:write |
idempotent | Remove an image from the library |
GET /v1/fonts |
no credential | read | The fonts a template or the brand may use |
GET /v1/print_data/schema |
no credential | read | The JSON Schema of the print data and of a template’s manifest, and the template functions |
GET /v1/print_data/samples |
no credential | read | The official samples every template is validated with |
GET /v1/templates |
templates:read |
read | The templates of the organization and the shared ones |
POST /v1/templates |
templates:write |
Idempotency-Key |
Create a template |
GET /v1/templates/{id} |
templates:read |
read | One template, with its draft and its versions |
PUT /v1/templates/{id}/draft |
templates:write |
idempotent | Save the draft of a template |
POST /v1/templates/{id}/archive |
templates:write |
safe as it is | Archive a template |
POST /v1/templates/{id}/promote |
templates:promote |
safe as it is | Choose the version LIVE documents print with |
POST /v1/templates/{id}/preview_links |
templates:write |
Idempotency-Key |
A secret link to see (or edit) the template without a session |
GET /v1/templates/{id}/preview_links |
templates:read |
read | The preview links of a template |
DELETE /v1/templates/{id}/preview_links/{link_id} |
templates:write |
idempotent | Revoke a preview link |
POST /v1/templates/{id}/validate |
templates:write |
safe as it is | Run every check of the template on its draft (II-D197) |
POST /v1/templates/{id}/publish |
templates:write |
Idempotency-Key |
Publish the draft as a new version (TEST documents use it at once) |
POST /v1/templates/{id}/render |
templates:read |
safe as it is | Look at a template: its draft, a version or a shared one, as HTML, PNG or PDF (II-D213) |
POST /v1/templates/{id}/preview_tokens |
templates:read |
safe as it is | A short-lived token for the live preview of a template in a page (II-D221) |
POST /v1/template_gallery/preview_links |
templates:write |
Idempotency-Key |
A secret link to the gallery: your templates and the shared ones, without a session |
GET /v1/template_gallery/preview_links |
templates:read |
read | The links to the gallery |
DELETE /v1/template_gallery/preview_links/{link_id} |
templates:write |
idempotent | Revoke a link to the gallery |
GET /v1/template_previews/{secret} |
no credential | read | What a preview link opens: its template, its draft and what the link allows |
PUT /v1/template_previews/{secret}/draft |
no credential | idempotent | Save the draft through a preview link (scope edit or publish) |
POST /v1/template_previews/{secret}/validate |
no credential | safe as it is | Validate the draft through a preview link (scope edit or publish) |
POST /v1/template_previews/{secret}/publish |
no credential | Idempotency-Key |
Publish the draft through a preview link (scope publish only) |
POST /v1/template_previews/{secret}/render |
no credential | safe as it is | Render what a preview link opens (any scope): the paper of the page |
GET /v1/template_rooms/{credential} |
no credential | read | The live preview room of a template: a WebSocket told of every save |
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) |
POST /v1/staff/held/close/preview |
a person’s token | safe as it is | See what closing held invoices and voids as failed would do, after asking their provider (staff only) |
POST /v1/staff/held/close |
a person’s token | Idempotency-Key |
Close held invoices and voids as failed, with the token of their preview (staff only) |
POST /v1/production_access |
production:request |
Idempotency-Key |
Ask to enter the production access list |
GET /v1/production_access |
organization:read |
read | The latest access request of the organization and its state |
POST /v1/production_access/withdraw |
production:request |
safe as it is | Withdraw the open access request |
POST /v1/production_activation |
production:request |
Idempotency-Key |
Send the activation request with the two SUNAT screenshots |
GET /v1/production_activation |
organization:read |
read | The activation request: its state, the note of the staff and the review of each screenshot |
PUT /v1/production_activation/files/{kind} |
production:request |
idempotent | Replace one screenshot while the staff asks for changes |
POST /v1/production_activation/resubmit |
production:request |
safe as it is | Send the activation request again after the requested changes |
POST /v1/production_activation/withdraw |
production:request |
safe as it is | Withdraw the activation request in progress |
GET /v1/production_activation/files/{id}/content |
organization:read |
read | The bytes of a screenshot of this organization |
GET /v1/staff/production_access |
a person’s token | read | The open access requests of every organization (staff only) |
POST /v1/staff/production_access/{id}/accept |
a person’s token | safe as it is | Accept an organization on the production access list (staff only) |
POST /v1/staff/production_access/{id}/reject |
a person’s token | safe as it is | Reject an access request, with a note (staff only) |
POST /v1/staff/production_access/{id}/revoke |
a person’s token | safe as it is | Revoke the access of an organization, with a note (staff only) |
GET /v1/staff/production_activations |
a person’s token | read | The activation requests in progress of every organization (staff only) |
GET /v1/staff/production_activations/{id} |
a person’s token | read | An activation request with everything to review it (staff only) |
GET /v1/staff/production_activations/{id}/files/{file_id}/content |
a person’s token | read | The bytes of a screenshot of an activation request (staff only) |
POST /v1/staff/production_activations/{id}/files/{file_id}/review |
a person’s token | safe as it is | Mark a screenshot valid or invalid (staff only) |
POST /v1/staff/production_activations/{id}/request_changes |
a person’s token | safe as it is | Ask the organization to change its activation request, with a note (staff only) |
POST /v1/staff/production_activations/{id}/approve |
a person’s token | safe as it is | Approve an activation request: the enrolment with the provider starts (staff only) |
POST /v1/staff/production_activations/{id}/reject |
a person’s token | safe as it is | Reject an activation request, with a note (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 | Search the invoices of the organization, newest first, by cursor |
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 |
POST /v1/invoices/{id}/share_links |
invoices:emit |
Idempotency-Key |
A link to share one file of an invoice, revocable |
GET /v1/invoices/{id}/share_links |
invoices:read |
read | The share links of an invoice, with how many times each was opened |
DELETE /v1/invoices/{id}/share_links/{link_id} |
invoices:emit |
idempotent | Revoke a share link: it stops opening at once |
POST /v1/invoices/{id}/renders |
invoices:emit |
Idempotency-Key |
The invoice printed with another template, as PDF or PNG |
GET /v1/invoices/{id}/renders |
invoices:read |
read | The renders on request of an invoice |
GET /v1/invoices/{id}/renders/{render_id} |
invoices:read |
read | One render on request |
GET /v1/invoices/{id}/renders/{render_id}/content |
invoices:read |
read | The file of a render on request |
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 |
GET /f/{organization_id}/{invoice_id}/{file} |
no credential | read | Download a file by its signed link |
GET /s/{code} |
no credential | read | Download a file by its share link |
GET /paper/{credential} |
no credential | read | The paper of a preview: the sanitized HTML of a sample, for an iframe (II-D221) |
POST /paper/{credential} |
no credential | safe as it is | The paper of a preview with your own edits of the sample data (UX D2) |
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, customers:read, events:read, webhooks:read, webhooks:write, production:request, templates:read, templates:write, templates:promote.
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 |
| Renders and validations through a preview link, per IP and per link | 30 every 60 s |
| Papers through a preview link, per IP and per link | 120 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 |
Oldest issue_date of a factura, in days |
3 |
Oldest issue_date of a boleta, in days |
7 |
Invox · Electronic invoicing for Peru (SUNAT), built to be operated by agents.