Facturación electrónica que opera tu agente.

GET /v1

{
"name": "Invoicing",
"description": "Electronic invoicing for Peru (SUNAT), built to be operated by agents.",
"links": {  ← el mapa
"openapi": "https://api.invox.page/v1/openapi.json",
"docs": "https://api.invox.page/v1/docs",
"errors": "https://api.invox.page/v1/errors",
"event_types": "https://api.invox.page/v1/event_types"
},
"authentication": {
"header": "Authorization: Bearer <credential>",  ← cómo autenticarse
"credentials": {
"person_access_token": {
"what": "A person signs in once in a browser and the client receives a short-lived access token and a refresh token."
},
"service_account_key": {
"what": "A key of a service account of one organization (`sk_test_…` or `sk_live_…`). It acts only on that organization, with the scopes of its service account."
}
}
}
}

GET /v1

1. POST `device_authorization_endpoint` with `client_id` (form-encoded).
2. Show `verification_uri_complete` to the person and wait for them to confirm.
3. Poll `token_endpoint` with `grant_type=device_grant_type`, `device_code` and `client_id` every `interval` seconds.
4. Use `access_token` as the Bearer credential; when it expires, exchange `refresh_token` at `token_endpoint` with `grant_type=refresh_grant_type`.
5. Never print the tokens; keep them in the operating system's credential store.

POST /v1/invoices?wait=10
Authorization: Bearer sk_test_…
Idempotency-Key: venta-0001
Test-Scenario: accepted

{
  "type": "factura",
  "prices_include_tax": false,
  "customer": {
    "id_type": "ruc",
    "id_number": "20601188750",
    "name": "CLIENTE S.A.C."
  },
  "items": [
    {
      "description": "Soporte técnico mensual",
      "quantity": "1",
      "unit": "ZZ",
      "unit_price": "100.00"
    }
  ]
}

{
"id": "00000000-0000-4000-8000-00000000e0e0",
"object": "invoice",
"environment": "test",
"type": "factura",
"series": "F001",
"number": 123,
"full_number": "F001-00000123",  ← numerado por el servicio
"status": "accepted",  ← aceptado por SUNAT
"settled": true,
"status_reason": null,
"currency": "PEN",
"totals": {
"taxable": "100.00",
"exempt": "0.00",
"unaffected": "0.00",
"tax": "18.00",  ← IGV calculado
"total": "118.00"
},
"customer": {
"id_type": "ruc",
"id_number": "20601188750",
"name": "CLIENTE S.A.C."
},
"external_ref": null,
"created_at": "2026-01-15T15:04:05.000Z"
}

POST /v1/invoices/{id}/correction
Idempotency-Key: correccion-0001

{
  "preview_token": "pv_…"
}

{
"code": "provider_account_suspended",
"status": 503,
"title": "The account with the invoicing provider is suspended",  ← qué pasó
"retryable": "same_request",  ← ¿reintentar?
"effect": "Nothing was created or changed, and no invoice number was used. No invoice is marked failed or rejected because of the account: what is in process stays in process.",  ← qué NO pasó
"next_steps": [  ← qué hacer
"Nothing in the request is wrong. Send the same request again after `Retry-After`.",
"GET /v1/provider shows the state of the account and since when it is blocked.",
"Invoices can still be issued: they are taken (202) and sent by themselves when the account recovers."
]
}

POST /v1/invoices
Test-Scenario: <escenario>

Test-Scenario: acceptedThe invoice becomes `accepted`.Test-Scenario: rejectedThe invoice becomes `rejected`. Its number was not used before SUNAT.Test-Scenario: pendingThe invoice stays `processing` — nothing resolves it by itself, however long you wait — until POST /v1/test/invoices/{id}/resolve decides.Test-Scenario: already_existsThe service looks the number up, sees the document is its own, and the invoice becomes `accepted`. Exercises recovery without a duplicate.Test-Scenario: sunat_1033Its number is NEVER changed automatically. The invoice stays `processing` while SUNAT is asked again (three times, ten minutes apart: skip each wait with POST /v1/test/invoices/{id}/advance); then it ends `failed` with `status_reason: number_already_registered`. That reason says how it is corrected to the next number.

POST /v1/invoices/{id}/void
Idempotency-Key: anulacion-0001

{
  "reason": "Error en el monto"
}

{
"code": "preview_token_required",
"status": 400,
"title": "This action needs the token of its preview",
"retryable": "after_fixing_request",
"effect": "The action was not performed. Nothing was created, sent or changed.",  ← qué NO pasó
"next_steps": [  ← qué hacer
"Ask for the preview of the action first (POST /v1/invoices/{id}/void/preview, GET /v1/invoices/{id}/correction): its answer carries `preview_token`.",
"Show the preview to the person who approves, then send the action with that `preview_token`."
]
}

GET /v1/events?types=invoice.accepted,invoice.rejected&wait=20

invoice.acceptedSUNAT accepted the invoice.invoice.rejectedSUNAT rejected the invoice. Its number was not used.invoice.voidedSUNAT accepted the void. The invoice is voided.invoice.files_storedThe files of the invoice (XML, CDR, PDF) are stored and can be downloaded.invoice.email_sentAn email about the invoice was sent.

GET /v1/readiness

What is still missing to issue for real, and who must do each thing

Answerable with a credential of either half of a pair (live or test), and always about the pair. `requirements` lists what production needs, each with its `owner` — `agent` (doable through this API), `person` or `provider` — whether it is `blocking`, and `how`. `integration_evidence` is what the API has seen the integration exercise in the TEST organization (a rejection, a blocked provider account, a webhook acknowledged); events fabricated with the test tools do not count. It advises: nothing is allowed or refused because of this answer.