Skip to content
Navigation

Close held invoices and voids as failed, with the token of their preview (staff only)

Irreversible. Requires the preview_token of POST /v1/staff/held/close/preview (without it, or with one that expired or is not yours, nothing happens), a reason that is kept in the events, and accept_risk: true when the preview marked a document unanswered or unrecognized (without it, held_close_risk_not_accepted and nothing happens). The provider is NOT asked again and nothing is sent to it. Each document still held exactly as the preview saw it is closed in one transaction: an invoice becomes failed with status_reason: held_closed_by_staff (its number stays used; the sale is issued again as a new invoice), a void becomes failed with the same reason and its invoice stays accepted. A document released, resolved or held again since the preview is not closed (skipped). Each closed document gets its event (invoice.failed, invoice.void_failed) with close: who closed it, the reason, what the provider answered, whether the risk was accepted and the version of the code; its organization receives the alert of a failure, and it leaves the staff's list and its reminders. A retry with the same Idempotency-Key answers what the first call closed while the token lives, and never closes twice. Reserved to the staff of the service; anyone else gets staff_required, and a service-account key gets person_credential_required.

POST
https://api.invox.page/v1/staff/held/close

Authorization

  • bearer
    HTTP
    required

Header parameters

  • Idempotency-Key
    string
    required

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

    maxLength: 255

Request body JSON required

  • reason
    string
    required

    Why these documents are closed as failed. It is kept in the event of each one, which its organization receives.

    maxLength: 1000 · minLength: 3
  • preview_token
    optional

    The preview_token of POST /v1/staff/held/close/preview. Without it the close is refused (preview_token_required).

    Any of the following:

    • string
    • null
  • accept_risk
    optional
    boolean

    Required as true when the preview marked a document unanswered or unrecognized: the provider may hold it, even accepted by SUNAT.

Returns

200

What was closed and what was skipped, with the id of the close.

JSON
  • object
    string
    required
  • close_id
    string
    required

    Derived from the person and the Idempotency-Key; every event of this close carries it.

  • count
    integer
    required
    maximum: 9007199254740991 · minimum: -9007199254740991
  • invoices
    array of
    object
    required

    Invoices now failed with status_reason: held_closed_by_staff.

    • id
      string
      required
    • organization_id
      string
      required
    • full_number
      string
      required
    • signature
      string
      required

      The signature it was held with.

    • check
      not_found
      or
      unanswered
      or
      unrecognized
      required

      What the provider answered in the preview.

  • voids
    array of
    object
    required

    Voids now failed with status_reason: held_closed_by_staff; their invoices stay accepted.

    • id
      string
      required
    • organization_id
      string
      required
    • full_number
      string
      required
    • signature
      string
      required

      The signature it was held with.

    • check
      not_found
      or
      unanswered
      or
      unrecognized
      required

      What the provider answered in the preview.

    • invoice_id
      string
      required
  • skipped
    array of
    object
    required

    Documents of the preview that were NOT closed: released, resolved or held again since the preview.

    • object
      invoice
      or
      invoice_void
      required
    • id
      string
      required
    • organization_id
      string
      required
    • why
      string
      required
  • reason
    string
    required
  • accept_risk
    boolean
    required
  • closed_by
    string
    required
  • code_version
    string | null
    required

    The version of the code that closed them (null where it is not stamped, as on a workstation).

  • what_next
    string
    required

400

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 · preview_token_required: This action needs the token of its preview
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    validation_failed
    or
    malformed_request
    or
    idempotency_key_required
    or
    preview_token_required
    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

person_credential_required: This route is for a person, not for a service account · staff_required: This operation is reserved to the staff of the service
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    person_credential_required
    or
    staff_required
    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

nothing_held: Nothing is held under that signature or those ids
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    nothing_held
    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

preview_token_invalid: The preview token expired or no longer matches what would be done
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    preview_token_invalid
    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 · held_close_risk_not_accepted: Closing these held documents needs accept_risk: true
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    idempotency_key_reused
    or
    held_close_risk_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