Skip to content

The first invoice, in test mode

Issue a test invoice end to end: series, preview, the call, and what the answer means.

Use the id of the TEST organization (or an sk_test_… key). Nothing here reaches SUNAT.

  1. GET /v1/series (permission series:read): the test twin already has one series for facturas and one for boletas.

  2. POST /v1/invoices/preview (permission invoices:emit): optional: the totals and the number it would take, without issuing.

  3. POST /v1/invoices (permission invoices:emit; Idempotency-Key required): one call per invoice. Send a new Idempotency-Key per invoice and REUSE it when you retry: the same key with the same body returns the same invoice, never a second one.

{
  "type": "factura",
  "customer": {
    "id_type": "ruc",
    "id_number": "20601188750",
    "name": "CLIENTE S.A.C.",
    "email": "pagos@cliente.example"
  },
  "prices_include_tax": false,
  "items": [
    {
      "description": "Plan Pro (noviembre)",
      "quantity": "1",
      "unit": "ZZ",
      "unit_price": "100.00"
    }
  ],
  "external_ref": "charge_8f3a"
}

The answer is 202: the invoice has its number and is on its way. status is processing until SUNAT answers; what_next says what to do, in words. Amounts are decimal strings; issue_date is a Lima wall clock without a zone.

issue_date is optional (default: now in Lima). Never in the future, and at most 3 days in the past for a factura and 7 for a boleta (the legal window to send it to SUNAT). An older one is refused with issue_date_too_old before any number is taken.

Errors of this call: issuer_not_configured, invoice_type_not_allowed_for_regime, provider_not_connected, series_not_found, test_scenario_not_allowed, test_scenario_unknown, establishment_required, establishment_not_found, establishment_series_mismatch, establishment_inactive, template_not_found, template_archived, template_not_published, template_version_not_promoted, template_document_type_not_accepted, external_ref_already_used. A request that fails validation (validation_failed) lists EVERY problem in errors and does not consume the key.

To choose what the simulated provider answers, send the header Test-Scenario: <name> (see test mode).

Next: follow it to its outcome.

Type to search…

↑↓ navigate↵ selectEsc close