Skip to content
Navigation

See what closing held invoices and voids as failed would do, after asking their provider (staff only)

The way out for a held document whose provider never again answers something the service understands. Irreversible, so it starts here. Send { "signature": "…" } or { "invoice_ids": […], "void_ids": […] }, as for a release. Each document (at most 20 per call; more: true says there are more) is FIRST asked about at its provider, because an answer nobody understands may hide a success: an invoice by a lookup of its number, a void by a query of its status. What the provider holds as ours (or, for a void, a verdict of SUNAT) is ADOPTED right here, exactly as the read-only recheck adopts it, and is never closed (check: adopted). What the provider does not hold can be closed (not_found). What it did not answer, or answered without settling anything (unanswered, unrecognized), can be closed only with accept_risk: true: closing it may mark here as failed a document SUNAT accepted, and its sale may be invoiced twice. Nothing is sent to the provider and nothing is closed by this call. The answer lists each document with what the provider answered, a warning to show the person who decides, and a preview_token valid for 10 minutes, bound to this person and to exactly the closable documents and their holds. 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/preview

Authorization

  • bearer
    HTTP
    required

Request body JSON required

  • signature
    optional
    string

    The signature of a hold: <provider>:<operation>:<provider code or unparsed>, as GET /v1/staff/held shows it.

    maxLength: 120 · minLength: 3
  • invoice_ids
    optional
    array of
    string

    Ids of held invoices, of any organization. At most 100.

    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)$
  • void_ids
    optional
    array of
    string

    Ids of held voids, of any organization. At most 100.

    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)$

Returns

200

Each document with what its provider answered, the warning and the token of the close.

JSON
  • object
    string
    required
  • count
    integer
    required

    Documents examined (each one was asked about at its provider).

    maximum: 9007199254740991 · minimum: -9007199254740991
  • documents
    array of
    object
    required
    • object
      invoice
      or
      invoice_void
      required
    • id
      string
      required

      The id of the invoice, or of the void.

    • invoice_id
      string
      required
    • organization_id
      string
      required
    • full_number
      string
      required

      The number of the invoice (of the voided invoice, for a void).

    • signature
      string
      required

      The signature it was held with.

    • held_at
      string
      required
    • check
      adopted
      or
      not_found
      or
      unanswered
      or
      unrecognized
      required

      adopted: the provider holds it as ours (or gave the verdict of the void); it was taken as a recheck takes it and is NOT closed. not_found: ours is not at the provider; it can be closed. unanswered, unrecognized: the provider did not answer, or answered without settling anything; it can be closed only with accept_risk: true.

    • provider_answer
      ours
      or
      absent
      or
      another_document
      or
      incomparable
      or
      no_answer
      or
      void_accepted
      +3 more
      required

      What the provider answered. Invoices (a lookup of the number): ours, absent, another_document (another document holds the number, so ours never reached it), incomparable (it has a document there but what it shows cannot be compared), no_answer. Voids (a status query): void_accepted, void_rejected, absent, pending (does not prove the provider holds the summary), not_understood, no_answer.

    • closable
      boolean
      required
    • needs_accept_risk
      boolean
      required
  • adopted
    integer
    required

    Documents the provider holds as ours: adopted now, never closed.

    maximum: 9007199254740991 · minimum: -9007199254740991
  • closable
    integer
    required

    Documents the token allows to close.

    maximum: 9007199254740991 · minimum: -9007199254740991
  • needs_accept_risk
    boolean
    required

    True when some closable document needs accept_risk: true in the close.

  • warning
    string
    required
  • would
    object
    required
    • invoice_status
      string
      required
    • void_status
      string
      required
    • status_reason
      string
      required
    • effect
      string
      required
    • reversible
      boolean
      required
  • preview_token
    string | null
    required

    Required by POST /v1/staff/held/close. null when nothing can be closed.

  • preview_expires_at
    string | null
    required
  • more
    boolean
    required

    True when more documents are held under this request than one preview examines: close these, then preview again.

  • what_next
    string
    required

400

validation_failed: The request is not valid · malformed_request: The request body is not valid JSON
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    validation_failed
    or
    malformed_request
    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

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