Skip to content

Activating production

The whole path in order: the access list, the activation request with its SUNAT screenshots, the staff's review and the activation.

In the beta, production is by invitation and every step is a call of this API, on the LIVE organization (the test twin answers validation_failed). Each step of the staff arrives as an event (production_access.*, production_activation.*) with its webhook, and by email to the contact_email you give.

  1. The issuer. The RUC is the one the organization was created with and is verified against SUNAT data by the service itself. Declare the tax_regime with PUT /v1/issuer (permission issuers:write).
  2. The access list. Ask with POST /v1/production_access (permission production:request; Idempotency-Key required): what production is for (reason) and who answers (contact_email). The staff accepts or rejects it; GET /v1/production_access shows the state and, if rejected, why.
  3. The activation request. Once accepted, send POST /v1/production_activation (permission production:request; Idempotency-Key required) with two screenshots of SUNAT Operaciones en Línea where the provider shows as enabled: sunat_pse and sunat_ose (PNG, JPEG, WebP or PDF, read from the bytes, up to 5 MB each, in base64). The RUC is looked up again at that moment: it must be ACTIVO and HABIDO. From the command line: invoicing call POST /v1/production_activation --attach sunat_pse=./pse.png --attach sunat_ose=./ose.png.
  4. The review. The staff marks each screenshot valid or invalid and approves, asks for changes or rejects. GET /v1/production_activation shows the state, the note and the review of each file. When changes are asked: replace with PUT /v1/production_activation/files/{kind} (same files shape, one file) and send it again with POST /v1/production_activation/resubmit.
  5. The enrolment and the activation. approved means the staff is enrolling the RUC with the provider. When it confirms, the staff activates production (POST /v1/issuer/activate_production, theirs only): the request becomes activated and the RUC is locked to this issuer.
  6. Live. Create the live series and a live key (sk_live_…), and switch the integration to them. GET /v1/readiness lists anything still missing, step by step and who must act.

What can refuse a request

Sending it: evidence_missing, evidence_too_large, evidence_type_not_allowed, production_access_required, issuer_not_configured, tax_regime_required, ruc_not_verified, activation_request_open, ruc_not_active, ruc_not_habido, ruc_check_unavailable, internal_error, service_unavailable, rate_limited, unauthenticated, invalid_credential, missing_scope, organization_required, organization_mismatch, not_found, organization_archived, malformed_request, idempotency_key_required, idempotency_key_reused. A retry with the same Idempotency-Key answers the same request; ruc_check_unavailable is the only one to retry as it is.

Changing it while the staff decides: every transition is a compare-and-set, so a step that lost the race answers activation_request_wrong_state (or production_access_wrong_state) with current_status; read the request and go on from there. POST /v1/production_access/withdraw and POST /v1/production_activation/withdraw take a request back. Archiving the organization withdraws both; a revoked access withdraws the activation request but never a production already active.

The routes

Route Needs Retry What it does
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

Type to search…

↑↓ navigate↵ selectEsc close