Skip to content
Navigation

One invoice, optionally waiting for its outcome

status is processing until SUNAT answers; settled says whether anything more will happen by itself, and what_next what to do. With wait, the call holds until the invoice leaves processing or the seconds run out, and answers the invoice as it is either way. template says which template and version its PDF prints with (kind, ref, template_id, name, version), fixed at emission. customer carries, besides id, id_type, id_number and name, its email (where the invoice is sent) and address (what it prints) as the invoice froze them when it was issued, not the customer as it is now; each null when it was issued without it. Only this read carries them: the rows of GET /v1/invoices, the answer of POST /v1/invoices, the events and the webhooks carry no address of the customer.

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

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

Query parameters

  • wait
    optional
    integer

    Seconds to wait for the outcome before answering.

    maximum: 20 · minimum: 0 · default: 0

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

Returns

200

The invoice.

JSON
  • 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

    The customer plus how to reach them, as the invoice FROZE them when it was issued (not the customer as it is now): email, where it is sent, and address, what it prints; each null when it was issued without it. Only here: the light row of the listing, the events and the webhooks carry no address of the customer.

    • id
      string | null
      required
    • id_type
      string
      required
    • id_number
      string
      required
    • name
      string
      required
    • email
      string | null
      required
    • address
      string | null
      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.

  • delivery
    object
    required

    Files and email. final is true when nothing of the delivery is still on its way. files.downloads has, per stored file, a signed link that opens without a credential and lives an hour (II-D201): every read gives a fresh one.

    • final
      boolean
      required

      True when nothing of the delivery is still on its way: every file is stored or failed, no email is queued.

    • files
      object
      required
      • complete
        boolean
        required
      • xml
        pending
        or
        stored
        or
        failed
        or
        none
        required
      • cdr
        pending
        or
        stored
        or
        failed
        or
        none
        required
      • pdf
        pending
        or
        stored
        or
        failed
        or
        none
        required
      • url
        string
        required
      • downloads
        object
        required
        • xml
          required

          Any of the following:

          • object
            • url
              string
              required

              Opens without a credential until expires_at.

            • expires_at
              string
              required
          • null
        • cdr
          required

          Any of the following:

          • object
            • url
              string
              required

              Opens without a credential until expires_at.

            • expires_at
              string
              required
          • null
        • pdf
          required

          Any of the following:

          • object
            • url
              string
              required

              Opens without a credential until expires_at.

            • expires_at
              string
              required
          • null
    • email
      object
      required

      The email of emission (the automatic one), or the first one asked for. none: there is none.

      • status
        queued
        or
        sent
        or
        not_sent
        or
        failed
        or
        none
        required
      • reason
        string | null
        required
      • url
        string
        required
    • delivered_at
      string | null
      required

      When the first email to the customer really went out.

    • what_next
      string | null
      required

      What only you can do now, in words; null when nothing is needed from you: the rest happens by itself.

  • void
    required

    The latest void asked for this invoice, or null when none ever was.

    Any of the following:

    • object
      • id
        string
        required
      • object
        string
        required
      • invoice_id
        string
        required
      • invoice_full_number
        string
        required
      • invoice_status
        voided
        or
        accepted
        required

        The invoice is accepted while its void is in process, rejected or failed; voided only when the void is accepted.

      • kind
        RA
        or
        RC
        required

        RA: summary of voided invoices (a factura). RC: daily summary (a boleta).

      • status
        processing
        or
        accepted
        or
        rejected
        or
        failed
        required
      • settled
        boolean
        required

        True when nothing more will happen to this void 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 void is HELD (II-D150): an answer the service cannot interpret; nothing is resent. null otherwise.

        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
      • reason
        string
        required

        Written by the caller: data, never guidance.

      • summary
        required

        The summary sent to SUNAT: its number is taken when it is sent, with that day's date in Lima. null until then.

        Any of the following:

        • object
          • code
            string
            required
          • day
            string | null
            required
          • number
            required

            Any of the following:

            • integer
            • null
        • null
      • void_deadline
        string
        required

        The last day (Lima) on which the invoice can be voided: 7 days from its issue date.

      • sunat
        object
        required

        What SUNAT answered about the void. 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
      • test
        required

        Any of the following:

        • object
          • scenario
            string
            required
          • source
            header
            or
            default
            required
          • polls
            optional
            integer
            maximum: 9007199254740991 · minimum: -9007199254740991
          • then
            optional
            string
        • null
      • requested_by
        string | null
        required
      • created_at
        string
        required
      • updated_at
        string
        required
      • sent_at
        string | null
        required
      • settled_at
        string | null
        required
    • null

400

organization_required: This credential needs to say which organization it acts on · validation_failed: The request is not valid
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    organization_required
    or
    validation_failed
    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
JSON
  • type
    string
    required
    format: uri
  • title
    string
    required
  • status
    integer
    required
  • code
    missing_scope
    or
    organization_mismatch
    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

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