Skip to content

Reference: routes, permissions and limits

Every route with the permission it needs and how a retry is made safe; the scopes; the limits.

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.

Type to search…

↑↓ navigate↵ selectEsc close