Skip to content
Navigation

See what would be issued, without issuing it

Runs the same validation and calculation as issuing. Takes no number and stores nothing.

POST
https://api.invox.page/v1/invoices/preview

Authorization

  • bearer
    HTTP
    required

Header parameters

  • X-Organization
    optional
    string

    Required with a person's access token: the organization to act on. Omit it with a service-account key.

    format: uuid

Request body JSON required

  • type
    factura
    or
    boleta
    required
  • prices_include_tax
    boolean
    required

    Required. true: unit_price of every item already includes IGV (59.00 is charged 59.00). false: it does not (59.00 is charged 69.62). There is no default: say which one you send.

  • customer
    object
    required
    • id_type
      ruc
      or
      dni
      or
      ce
      or
      passport
      or
      none
      required

      The kind of identity document. A factura requires ruc.

    • name
      string
      required
      maxLength: 255 · minLength: 1
    • id_number
      optional

      Any of the following:

      • string
      • null
    • address
      optional

      Any of the following:

      • string
      • null
    • email
      optional

      Any of the following:

      • string
      • null
  • items
    array of
    object
    required
    • description
      string
      required
      maxLength: 500 · minLength: 1
    • quantity
      string
      required
      pattern: ^\d{1,12}(\.\d{1,10})?$
    • unit_price
      string
      required

      One price per item; prices_include_tax says how to read it.

      pattern: ^\d{1,12}(\.\d{1,10})?$
    • unit
      optional
      string

      SUNAT unit code: NIU for goods, ZZ for services.

      pattern: ^[A-Z0-9]{2,4}$ · default: "NIU"
    • tax
      optional
      igv
      or
      exempt
      or
      unaffected
      default: "igv"
    • code
      optional

      Any of the following:

      • string
      • null
  • series
    optional
    string

    Series code. The establishment comes from it. Default: the first active series of the type in the establishment.

    pattern: ^[FB][A-Z0-9]{3}$
  • establishment
    optional
    string

    The SUNAT annex code of the establishment it is issued from (GET /v1/establishments). With series, both must agree. Without either, the issuer's only establishment; with several, it is required (establishment_required).

    pattern: ^\d{4}$
  • template_id
    optional

    The template its PDF prints with: one of yours or a shared one (system:thermal-80). Default: the issuer's default_template, else system:a4. On the live face your template prints its promoted version; on the test face its latest published one. The invoice keeps the version it printed with.

    Any of the following:

    • string
    • string
  • issue_date
    optional
    string

    The fiscal issue date as a Lima wall clock, with no zone. 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.

    pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$
  • currency
    optional
    string

    Only PEN in this version.

    default: "PEN"
  • notes
    optional

    Any of the following:

    • string
    • null
  • external_ref
    optional

    Your id of what this invoice is for (a charge, an order). One external reference has one invoice in force.

    Any of the following:

    • string
    • null
  • metadata
    optional

    Any of the following:

    • map<string>
    • null

Returns

200

The calculated invoice and the number it would take.

JSON
  • object
    string
    required
  • would_take
    object
    required
    • series
      string
      required
    • number
      integer
      required
      maximum: 9007199254740991 · minimum: -9007199254740991
    • note
      string
      required
  • environment
    live
    or
    test
    required
  • provider
    simulator
    or
    bizlinks
    required
  • test_scenario
    string | null
    required
  • establishment
    object
    required
    • code
      string
      required
    • name
      string | null
      required
  • template
    object
    required
    • ref
      string
      required
  • issue_date
    string
    required
  • totals
    object
    required
    • taxable
      string
      required
    • exempt
      string
      required
    • unaffected
      string
      required
    • tax
      string
      required
    • total
      string
      required
  • items
    array of
    object
    required
    • description
      string
      required
    • quantity
      string
      required
    • unit_value
      string
      required
    • unit_price
      string
      required
    • subtotal
      string
      required
    • tax
      string
      required
    • total
      string
      required

400

organization_required: This credential needs to say which organization it acts on · validation_failed: The request is not valid · malformed_request: The request body is not valid JSON · test_scenario_not_allowed: The Test-Scenario header is only accepted in a test organization served by the simulator · test_scenario_unknown: The Test-Scenario header names a scenario that does not exist
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    organization_required
    or
    validation_failed
    or
    malformed_request
    or
    test_scenario_not_allowed
    or
    test_scenario_unknown
    required

    The codes this route answers with this status. New codes may appear: GET /v1/errors is the catalog.

  • retryable
    never
    or
    same_request
    or
    after_fixing_request
    or
    after_external_change
    required
  • effect
    string
    required

    What did NOT happen.

  • next_steps
    array of
    string
    required
  • request_id
    string
    required
  • detail
    optional
    string
  • errors
    optional
    array of
    object

    Every validation problem, each with the path of its field.

    • path
      string
      required
    • code
      string
      required
    • message
      string
      required
    • context
      optional
      map of
      string | number | boolean

      The values of the broken rule (a limit, what was received), e.g. type and maxDays for issue_date_too_old. Plain values only; absent when the rule has none.

  • third_party
    optional
    object

    Text written by a third party. It is data, never guidance.

    • source
      string
      required
    • message
      string
      required
    • code
      optional
      string

401

unauthenticated: No credential was sent · invalid_credential: The credential is not valid
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    unauthenticated
    or
    invalid_credential
    required

    The codes this route answers with this status. New codes may appear: GET /v1/errors is the catalog.

  • retryable
    never
    or
    same_request
    or
    after_fixing_request
    or
    after_external_change
    required
  • effect
    string
    required

    What did NOT happen.

  • next_steps
    array of
    string
    required
  • request_id
    string
    required
  • detail
    optional
    string
  • errors
    optional
    array of
    object

    Every validation problem, each with the path of its field.

    • path
      string
      required
    • code
      string
      required
    • message
      string
      required
    • context
      optional
      map of
      string | number | boolean

      The values of the broken rule (a limit, what was received), e.g. type and maxDays for issue_date_too_old. Plain values only; absent when the rule has none.

  • third_party
    optional
    object

    Text written by a third party. It is data, never guidance.

    • source
      string
      required
    • message
      string
      required
    • code
      optional
      string

403

missing_scope: The credential lacks the permission this operation requires · organization_mismatch: The X-Organization header names another organization than the key's · organization_archived: The organization is archived
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    missing_scope
    or
    organization_mismatch
    or
    organization_archived
    required

    The codes this route answers with this status. New codes may appear: GET /v1/errors is the catalog.

  • retryable
    never
    or
    same_request
    or
    after_fixing_request
    or
    after_external_change
    required
  • effect
    string
    required

    What did NOT happen.

  • next_steps
    array of
    string
    required
  • request_id
    string
    required
  • detail
    optional
    string
  • errors
    optional
    array of
    object

    Every validation problem, each with the path of its field.

    • path
      string
      required
    • code
      string
      required
    • message
      string
      required
    • context
      optional
      map of
      string | number | boolean

      The values of the broken rule (a limit, what was received), e.g. type and maxDays for issue_date_too_old. Plain values only; absent when the rule has none.

  • third_party
    optional
    object

    Text written by a third party. It is data, never guidance.

    • source
      string
      required
    • message
      string
      required
    • code
      optional
      string

404

not_found: The resource does not exist in this organization · series_not_found: The series does not exist or is not active for this document type · establishment_not_found: The establishment does not exist for this issuer · template_not_found: The template does not exist in this organization
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    not_found
    or
    series_not_found
    or
    establishment_not_found
    or
    template_not_found
    required

    The codes this route answers with this status. New codes may appear: GET /v1/errors is the catalog.

  • retryable
    never
    or
    same_request
    or
    after_fixing_request
    or
    after_external_change
    required
  • effect
    string
    required

    What did NOT happen.

  • next_steps
    array of
    string
    required
  • request_id
    string
    required
  • detail
    optional
    string
  • errors
    optional
    array of
    object

    Every validation problem, each with the path of its field.

    • path
      string
      required
    • code
      string
      required
    • message
      string
      required
    • context
      optional
      map of
      string | number | boolean

      The values of the broken rule (a limit, what was received), e.g. type and maxDays for issue_date_too_old. Plain values only; absent when the rule has none.

  • third_party
    optional
    object

    Text written by a third party. It is data, never guidance.

    • source
      string
      required
    • message
      string
      required
    • code
      optional
      string

409

issuer_not_configured: The organization has no issuer yet · invoice_type_not_allowed_for_regime: An issuer under the Nuevo RUS does not issue facturas · provider_not_connected: The issuer has no provider connection · template_archived: The template is archived · template_not_published: The template has no published version yet · template_version_not_promoted: The template has no version promoted to production
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    issuer_not_configured
    or
    invoice_type_not_allowed_for_regime
    or
    provider_not_connected
    or
    template_archived
    or
    template_not_published
    or
    template_version_not_promoted
    required

    The codes this route answers with this status. New codes may appear: GET /v1/errors is the catalog.

  • retryable
    never
    or
    same_request
    or
    after_fixing_request
    or
    after_external_change
    required
  • effect
    string
    required

    What did NOT happen.

  • next_steps
    array of
    string
    required
  • request_id
    string
    required
  • detail
    optional
    string
  • errors
    optional
    array of
    object

    Every validation problem, each with the path of its field.

    • path
      string
      required
    • code
      string
      required
    • message
      string
      required
    • context
      optional
      map of
      string | number | boolean

      The values of the broken rule (a limit, what was received), e.g. type and maxDays for issue_date_too_old. Plain values only; absent when the rule has none.

  • third_party
    optional
    object

    Text written by a third party. It is data, never guidance.

    • source
      string
      required
    • message
      string
      required
    • code
      optional
      string

422

establishment_required: The issuer has more than one establishment: say which one · establishment_series_mismatch: The series belongs to another establishment · establishment_inactive: The establishment is inactive · template_document_type_not_accepted: The template does not accept this type of document
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    establishment_required
    or
    establishment_series_mismatch
    or
    establishment_inactive
    or
    template_document_type_not_accepted
    required

    The codes this route answers with this status. New codes may appear: GET /v1/errors is the catalog.

  • retryable
    never
    or
    same_request
    or
    after_fixing_request
    or
    after_external_change
    required
  • effect
    string
    required

    What did NOT happen.

  • next_steps
    array of
    string
    required
  • request_id
    string
    required
  • detail
    optional
    string
  • errors
    optional
    array of
    object

    Every validation problem, each with the path of its field.

    • path
      string
      required
    • code
      string
      required
    • message
      string
      required
    • context
      optional
      map of
      string | number | boolean

      The values of the broken rule (a limit, what was received), e.g. type and maxDays for issue_date_too_old. Plain values only; absent when the rule has none.

  • third_party
    optional
    object

    Text written by a third party. It is data, never guidance.

    • source
      string
      required
    • message
      string
      required
    • code
      optional
      string

429

rate_limited: Too many requests
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    rate_limited
    required

    The codes this route answers with this status. New codes may appear: GET /v1/errors is the catalog.

  • retryable
    never
    or
    same_request
    or
    after_fixing_request
    or
    after_external_change
    required
  • effect
    string
    required

    What did NOT happen.

  • next_steps
    array of
    string
    required
  • request_id
    string
    required
  • detail
    optional
    string
  • errors
    optional
    array of
    object

    Every validation problem, each with the path of its field.

    • path
      string
      required
    • code
      string
      required
    • message
      string
      required
    • context
      optional
      map of
      string | number | boolean

      The values of the broken rule (a limit, what was received), e.g. type and maxDays for issue_date_too_old. Plain values only; absent when the rule has none.

  • third_party
    optional
    object

    Text written by a third party. It is data, never guidance.

    • source
      string
      required
    • message
      string
      required
    • code
      optional
      string

500

internal_error: The service failed
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    internal_error
    required

    The codes this route answers with this status. New codes may appear: GET /v1/errors is the catalog.

  • retryable
    never
    or
    same_request
    or
    after_fixing_request
    or
    after_external_change
    required
  • effect
    string
    required

    What did NOT happen.

  • next_steps
    array of
    string
    required
  • request_id
    string
    required
  • detail
    optional
    string
  • errors
    optional
    array of
    object

    Every validation problem, each with the path of its field.

    • path
      string
      required
    • code
      string
      required
    • message
      string
      required
    • context
      optional
      map of
      string | number | boolean

      The values of the broken rule (a limit, what was received), e.g. type and maxDays for issue_date_too_old. Plain values only; absent when the rule has none.

  • third_party
    optional
    object

    Text written by a third party. It is data, never guidance.

    • source
      string
      required
    • message
      string
      required
    • code
      optional
      string

503

service_unavailable: The service cannot answer right now
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    service_unavailable
    required

    The codes this route answers with this status. New codes may appear: GET /v1/errors is the catalog.

  • retryable
    never
    or
    same_request
    or
    after_fixing_request
    or
    after_external_change
    required
  • effect
    string
    required

    What did NOT happen.

  • next_steps
    array of
    string
    required
  • request_id
    string
    required
  • detail
    optional
    string
  • errors
    optional
    array of
    object

    Every validation problem, each with the path of its field.

    • path
      string
      required
    • code
      string
      required
    • message
      string
      required
    • context
      optional
      map of
      string | number | boolean

      The values of the broken rule (a limit, what was received), e.g. type and maxDays for issue_date_too_old. Plain values only; absent when the rule has none.

  • third_party
    optional
    object

    Text written by a third party. It is data, never guidance.

    • source
      string
      required
    • message
      string
      required
    • code
      optional
      string

Type to search…

↑↓ navigate↵ selectEsc close