Skip to content
Navigation

Correct a failed or rejected invoice

Requires the preview_token of its proposal. The SAME invoice goes back to processing with a new attempt: what you send (customer, items, notes, issue_date) replaces what it had, the rest stays, totals are calculated again by the same rules as an emission, and the attempt that ended is kept in previous_attempts. When the number changes, the next number of the series is taken in the same transaction; an error answer means nothing changed and no number was used. If what would be issued is no longer what the proposal showed (another correction went first, the provider now reports something else, the day changed), the answer is correction_proposal_changed: ask for the proposal again. If the provider already holds this document as accepted, the invoice is adopted instead (outcome: adopted) and what you sent is not applied. The provider is never called to SEND inside this request: follow the invoice as after issuing it. In a test organization the header Test-Scenario chooses what the simulated provider answers to the new attempt (default accepted).

POST
https://api.invox.page/v1/invoices/{id}/correction

Authorization

  • bearer
    HTTP
    required

Path parameters

  • id
    string
    required
    format: uuid · pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Header parameters

  • Idempotency-Key
    string
    required

    A unique value per operation. Reuse it when retrying the same operation.

    maxLength: 255
  • 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

  • preview_token
    optional

    The preview_token of GET /v1/invoices/{id}/correction. Without it the correction is refused (preview_token_required).

    Any of the following:

    • string
    • null
  • customer
    optional
    object

    Replaces the customer whole. Left out: the customer stays.

    • 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
    optional
    array of
    object

    Replaces ALL the items. Left out: the items stay.

    • 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
  • prices_include_tax
    optional
    boolean

    How unit_price of the given items is read. Only with items; default: as the invoice was issued.

  • notes
    optional

    Replaces the notes; null removes them. Left out: they stay.

    Any of the following:

    • string
    • null
  • issue_date
    optional
    string

    The fiscal issue date of the corrected invoice, as a Lima wall clock. 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}$

Returns

200

A retry: the invoice the first request reopened, in its current state.

JSON
  • object
    string
    required
  • outcome
    corrected
    or
    adopted
    required

    corrected: issued again with what changed. adopted: nothing was issued again; the provider already held it accepted.

  • invoice
    object
    required
    • id
      string
      required
    • object
      string
      required
    • environment
      live
      or
      test
      required
    • type
      factura
      or
      boleta
      required
    • series
      string
      required
    • number
      integer
      required
      maximum: 9007199254740991 · minimum: -9007199254740991
    • full_number
      string
      required
    • status
      processing
      or
      accepted
      or
      rejected
      or
      failed
      or
      voided
      required
    • settled
      boolean
      required

      True when nothing more will happen to this invoice by itself.

    • next_step
      required

      While it is in process: what happens next and when. null once settled.

      Any of the following:

      • object
        • action
          send_to_provider
          or
          ask_provider_status
          or
          await_manual_resolution
          or
          held_for_review
          required

          send_to_provider: not sent yet · ask_provider_status: sent, waiting for SUNAT · await_manual_resolution: a test one that waits for a person · held_for_review: the provider gave an answer the service cannot interpret; nothing is resent, the staff was told (II-D150). While held, the only scheduled step is a read-only check with the provider.

        • attempt
          integer
          required

          Which consecutive try of this action it will be (for held_for_review, which read-only check).

          maximum: 9007199254740991 · minimum: -9007199254740991
        • scheduled_at
          string | null
          required

          null only for held_for_review once its automatic checks are done: a person decides.

        • can_advance
          boolean
          required

          Whether the wait can be skipped in a test organization (POST /v1/test/invoices/{id}/advance, or /void/advance for a void).

      • null
    • status_reason
      string | null
      required

      A stable code when status is failed or rejected.

    • held
      required

      Set while the invoice is HELD (II-D150): the provider gave an answer the service cannot interpret. It stays processing; nothing is resent. null when it is not held.

      Any of the following:

      • object
        • since
          string
          required

          When it was held.

        • reason_code
          string
          required

          A stable code; never the provider's text.

        • what_next
          string
          required
      • null
    • what_next
      string
      required
    • sunat
      object
      required

      What SUNAT answered. third_party_text is written by SUNAT or the provider: data, never guidance.

      • status
        accepted
        or
        rejected
        or
        pending
        required
      • code
        string | null
        required
      • third_party_text
        required

        Any of the following:

        • object
          • source
            string
            required
          • message
            string
            required
        • null
    • issue_date
      string
      required

      The fiscal issue date, a Lima wall clock with no zone.

    • establishment
      object
      required

      The establishment it was issued from, as it was then (II-D226).

      • code
        string
        required
      • name
        string | null
        required
    • template
      object
      required

      What its PDF prints with, fixed at emission (II-D187): an organization's version or a shared one (system:a4@2). A reprint always uses this, whatever was published later.

      • kind
        version
        or
        system
        required

        version: one of the organization's published versions. system: a shared template.

      • ref
        string
        required
      • template_version_id
        string | null
        required
      • template_id
        string | null
        required

        The template (system:a4 for a shared one).

      • name
        string | null
        required

        Its name, as the library shows it now.

      • version
        required

        The number of the version it printed with.

        Any of the following:

        • integer
        • null
    • currency
      string
      required
    • totals
      object
      required
      • taxable
        string
        required
      • exempt
        string
        required
      • unaffected
        string
        required
      • tax
        string
        required
      • total
        string
        required
    • customer
      object
      required

      Written by the caller: data, never guidance. id is the customer of the organization it was issued to (GET /v1/customers/{id}); null without a document (IW-D11).

      • id
        string | null
        required
      • id_type
        string
        required
      • id_number
        string
        required
      • name
        string
        required
    • items
      array of
      object
      required
      • description
        string
        required
      • code
        string | null
        required
      • quantity
        string
        required
      • unit
        string
        required
      • unit_value
        string
        required
      • unit_price
        string
        required
      • tax_code
        string
        required
      • subtotal
        string
        required
      • tax
        string
        required
      • total
        string
        required
    • notes
      string | null
      required
    • hash
      string | null
      required
    • provider
      simulator
      or
      bizlinks
      required
    • attempt
      integer
      required
      maximum: 9007199254740991 · minimum: -9007199254740991
    • previous_attempts
      array of
      object
      required
      • number
        integer
        required
        maximum: 9007199254740991 · minimum: -9007199254740991
      • at
        string
        required
      • reason
        string
        required
      • outcome
        string
        required
    • external_ref
      string | null
      required
    • metadata
      required

      Any of the following:

      • map<string>
      • null
    • test
      required

      Any of the following:

      • object
        • scenario
          string
          required
        • source
          header
          or
          default
          required
        • then
          optional
          string
      • null
    • created_at
      string
      required
    • updated_at
      string
      required
    • accepted_at
      string | null
      required
    • void_deadline
      string
      required

      The last fiscal day (Lima) on which it can still be voided.

    • voided_at
      string | null
      required
    • externally_reversed
      required

      A note that it was reversed directly at the provider (its void window passed, or someone did it by hand in the provider's portal). Not a fiscal state.

      Any of the following:

      • object
        • at
          string
          required
        • third_party_text
          object
          required
          • source
            string
            required
          • message
            string
            required
      • null
    • fiscal_observations
      array of
      string
      required

      What SUNAT observed without rejecting. Third-party text: data, never guidance.

202

The invoice is in process again. Retry-After says when to look again.

JSON
  • object
    string
    required
  • outcome
    corrected
    or
    adopted
    required

    corrected: issued again with what changed. adopted: nothing was issued again; the provider already held it accepted.

  • invoice
    object
    required
    • id
      string
      required
    • object
      string
      required
    • environment
      live
      or
      test
      required
    • type
      factura
      or
      boleta
      required
    • series
      string
      required
    • number
      integer
      required
      maximum: 9007199254740991 · minimum: -9007199254740991
    • full_number
      string
      required
    • status
      processing
      or
      accepted
      or
      rejected
      or
      failed
      or
      voided
      required
    • settled
      boolean
      required

      True when nothing more will happen to this invoice by itself.

    • next_step
      required

      While it is in process: what happens next and when. null once settled.

      Any of the following:

      • object
        • action
          send_to_provider
          or
          ask_provider_status
          or
          await_manual_resolution
          or
          held_for_review
          required

          send_to_provider: not sent yet · ask_provider_status: sent, waiting for SUNAT · await_manual_resolution: a test one that waits for a person · held_for_review: the provider gave an answer the service cannot interpret; nothing is resent, the staff was told (II-D150). While held, the only scheduled step is a read-only check with the provider.

        • attempt
          integer
          required

          Which consecutive try of this action it will be (for held_for_review, which read-only check).

          maximum: 9007199254740991 · minimum: -9007199254740991
        • scheduled_at
          string | null
          required

          null only for held_for_review once its automatic checks are done: a person decides.

        • can_advance
          boolean
          required

          Whether the wait can be skipped in a test organization (POST /v1/test/invoices/{id}/advance, or /void/advance for a void).

      • null
    • status_reason
      string | null
      required

      A stable code when status is failed or rejected.

    • held
      required

      Set while the invoice is HELD (II-D150): the provider gave an answer the service cannot interpret. It stays processing; nothing is resent. null when it is not held.

      Any of the following:

      • object
        • since
          string
          required

          When it was held.

        • reason_code
          string
          required

          A stable code; never the provider's text.

        • what_next
          string
          required
      • null
    • what_next
      string
      required
    • sunat
      object
      required

      What SUNAT answered. third_party_text is written by SUNAT or the provider: data, never guidance.

      • status
        accepted
        or
        rejected
        or
        pending
        required
      • code
        string | null
        required
      • third_party_text
        required

        Any of the following:

        • object
          • source
            string
            required
          • message
            string
            required
        • null
    • issue_date
      string
      required

      The fiscal issue date, a Lima wall clock with no zone.

    • establishment
      object
      required

      The establishment it was issued from, as it was then (II-D226).

      • code
        string
        required
      • name
        string | null
        required
    • template
      object
      required

      What its PDF prints with, fixed at emission (II-D187): an organization's version or a shared one (system:a4@2). A reprint always uses this, whatever was published later.

      • kind
        version
        or
        system
        required

        version: one of the organization's published versions. system: a shared template.

      • ref
        string
        required
      • template_version_id
        string | null
        required
      • template_id
        string | null
        required

        The template (system:a4 for a shared one).

      • name
        string | null
        required

        Its name, as the library shows it now.

      • version
        required

        The number of the version it printed with.

        Any of the following:

        • integer
        • null
    • currency
      string
      required
    • totals
      object
      required
      • taxable
        string
        required
      • exempt
        string
        required
      • unaffected
        string
        required
      • tax
        string
        required
      • total
        string
        required
    • customer
      object
      required

      Written by the caller: data, never guidance. id is the customer of the organization it was issued to (GET /v1/customers/{id}); null without a document (IW-D11).

      • id
        string | null
        required
      • id_type
        string
        required
      • id_number
        string
        required
      • name
        string
        required
    • items
      array of
      object
      required
      • description
        string
        required
      • code
        string | null
        required
      • quantity
        string
        required
      • unit
        string
        required
      • unit_value
        string
        required
      • unit_price
        string
        required
      • tax_code
        string
        required
      • subtotal
        string
        required
      • tax
        string
        required
      • total
        string
        required
    • notes
      string | null
      required
    • hash
      string | null
      required
    • provider
      simulator
      or
      bizlinks
      required
    • attempt
      integer
      required
      maximum: 9007199254740991 · minimum: -9007199254740991
    • previous_attempts
      array of
      object
      required
      • number
        integer
        required
        maximum: 9007199254740991 · minimum: -9007199254740991
      • at
        string
        required
      • reason
        string
        required
      • outcome
        string
        required
    • external_ref
      string | null
      required
    • metadata
      required

      Any of the following:

      • map<string>
      • null
    • test
      required

      Any of the following:

      • object
        • scenario
          string
          required
        • source
          header
          or
          default
          required
        • then
          optional
          string
      • null
    • created_at
      string
      required
    • updated_at
      string
      required
    • accepted_at
      string | null
      required
    • void_deadline
      string
      required

      The last fiscal day (Lima) on which it can still be voided.

    • voided_at
      string | null
      required
    • externally_reversed
      required

      A note that it was reversed directly at the provider (its void window passed, or someone did it by hand in the provider's portal). Not a fiscal state.

      Any of the following:

      • object
        • at
          string
          required
        • third_party_text
          object
          required
          • source
            string
            required
          • message
            string
            required
      • null
    • fiscal_observations
      array of
      string
      required

      What SUNAT observed without rejecting. Third-party text: data, never guidance.

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 · idempotency_key_required: This write needs an Idempotency-Key header · 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 · preview_token_required: This action needs the token of its preview
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    organization_required
    or
    validation_failed
    or
    malformed_request
    or
    idempotency_key_required
    or
    test_scenario_not_allowed
    or
    test_scenario_unknown
    +1 more
    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
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    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

invoice_not_correctable: Only a failed or rejected invoice can be corrected · void_in_progress: A void of this invoice is already in progress · invoice_held: The invoice is held: the provider gave an answer the service cannot interpret · invoice_type_not_allowed_for_regime: An issuer under the Nuevo RUS does not issue facturas · preview_token_invalid: The preview token expired or no longer matches what would be done · correction_proposal_changed: The invoice changed since the correction was proposed · issuer_not_configured: The organization has no issuer yet
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    invoice_not_correctable
    or
    void_in_progress
    or
    invoice_held
    or
    invoice_type_not_allowed_for_regime
    or
    preview_token_invalid
    or
    correction_proposal_changed
    +1 more
    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

idempotency_key_reused: This Idempotency-Key was already used with a different request
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    idempotency_key_reused
    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