> ## Documentation Index
> Fetch the complete documentation index at: https://invoiceapi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve a ticket invoice

> Fetch one ticket invoice by id, including its current lifecycle status.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/ticket_invoices/{id}
openapi: 3.1.0
info:
  title: Invoice API
  description: >-
    Mexican CFDI 4.0 invoicing API. Versioned via the Invoice-Version header;
    current: 2026-07-15. See GET /v1/versions.
  version: 0.1.0
servers:
  - url: https://api.newinvoice.dev
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: api_keys
    description: Platform API-key lifecycle (create, list, revoke)
  - name: accounts
    description: 'Connect: platform-owned connected accounts (multi-tenant)'
  - name: fiscal_profiles
    description: Emitter RFC + CSD/FIEL registration
  - name: invoices
    description: Create, stamp, cancel CFDI 4.0 invoices
  - name: validations
    description: Validate arbitrary CFDI XML
  - name: ticket_invoices
    description: Self-invoice merchant tickets from a photo (autofacturación)
  - name: downloads
    description: SAT descarga masiva jobs
  - name: webhook_endpoints
    description: HMAC-signed event delivery
  - name: events
    description: Event log
  - name: balance
    description: Remaining stamp credits
  - name: usage
    description: Metered usage records (stamps consumed)
  - name: catalogs
    description: SAT reference catalogs (uso CFDI, payment forms/methods, tax regimes, …)
  - name: docs
    description: Served documentation (error catalog + guides)
paths:
  /v1/ticket_invoices/{id}:
    get:
      tags:
        - ticket_invoices
      summary: Retrieve a ticket invoice
      description: Fetch one ticket invoice by id, including its current lifecycle status.
      parameters:
        - schema:
            type: string
          in: path
          name: id
          required: true
          description: Ticket-invoice id, e.g. "tkt_...".
        - $ref: '#/components/parameters/InvoiceVersion'
        - $ref: '#/components/parameters/InvoiceAccount'
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    description: Always "ticket_invoice".
                    enum:
                      - ticket_invoice
                  id:
                    type: string
                    description: Ticket-invoice id.
                  status:
                    type: string
                    enum:
                      - extracting
                      - processing
                      - needs_review
                      - completed
                      - failed
                    description: >-
                      Lifecycle: extracting → processing → completed |
                      needs_review | failed. Poll or watch ticket_invoice.*
                      webhooks.
                  fiscal_profile_id:
                    type: string
                    description: The Receptor fiscal profile.
                  uso_cfdi:
                    type: string
                    description: c_UsoCFDI requested for the emitted CFDI.
                  merchant:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Merchant name read off the ticket (the CFDI Emisor).
                  merchant_rfc:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Merchant RFC, when printed on the ticket.
                  portal_url:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: The merchant self-invoice portal used.
                  portal_domain:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Bare host of the portal (recipe key).
                  folio:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Ticket folio / web id used to look it up.
                  sucursal:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Branch / station identifier, when needed.
                  currency:
                    type: string
                    description: ISO-4217 currency, default MXN.
                  subtotal:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Ticket subtotal as a decimal string.
                  total:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Ticket total as a decimal string.
                  ticket_date:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Ticket date as printed, yyyy-mm-dd.
                  confidence:
                    anyOf:
                      - type: number
                      - type: 'null'
                    description: >-
                      Extraction confidence 0..1 (below the auto-submit
                      threshold → needs_review).
                  uuid:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      SAT folio fiscal (UUID) of the emitted CFDI, when
                      completed.
                  portal_reference:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Portal-side acuse/reference id, when shown.
                  recipe_id:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: The learned portal recipe used/produced for this run.
                  error:
                    anyOf:
                      - type: object
                        properties:
                          code:
                            type: string
                            description: >-
                              Stable machine code, e.g.
                              "autofactura.portal_unknown".
                          message:
                            type: string
                            description: Human-readable failure description.
                          remediation:
                            type: string
                            description: Actionable fix for a human or agent.
                        required:
                          - code
                          - message
                          - remediation
                        additionalProperties: false
                      - type: 'null'
                    description: >-
                      Failure detail when status is failed/needs_review, else
                      null.
                  metadata:
                    anyOf:
                      - type: object
                        propertyNames:
                          type: string
                        additionalProperties:
                          type: string
                      - type: 'null'
                    description: Echoed integrator metadata.
                  livemode:
                    type: boolean
                    description: True if created with a live-mode key.
                  created_at:
                    type: string
                    description: Creation timestamp, ISO-8601 UTC.
                  updated_at:
                    type: string
                    description: Last update timestamp, ISO-8601 UTC.
                required:
                  - object
                  - id
                  - status
                  - fiscal_profile_id
                  - uso_cfdi
                  - merchant
                  - merchant_rfc
                  - portal_url
                  - portal_domain
                  - folio
                  - sucursal
                  - currency
                  - subtotal
                  - total
                  - ticket_date
                  - confidence
                  - uuid
                  - portal_reference
                  - recipe_id
                  - error
                  - metadata
                  - livemode
                  - created_at
                  - updated_at
                additionalProperties: false
              example:
                object: ticket_invoice
                id: obj_2P9K3sample
                status: extracting
                fiscal_profile_id: fp_2P9K3sample
                uso_cfdi: string
                merchant: string
                merchant_rfc: string
                portal_url: https://example.com/webhooks/invoice
                portal_domain: string
                folio: string
                sucursal: string
                currency: MXN
                subtotal: '116.00'
                total: '116.00'
                ticket_date: string
                confidence: 1
                uuid: 5FB2822E-396D-4725-8521-CDC4BDD20CCF
                portal_reference: string
                recipe_id: obj_2P9K3sample
                error:
                  code: string
                  message: string
                  remediation: string
                metadata: {}
                livemode: false
                created_at: '2026-07-10T18:25:43Z'
                updated_at: '2026-07-10T18:25:43Z'
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '401':
          description: Missing or invalid API key.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/auth_unauthorized
                title: Authentication required
                status: 401
                code: auth.unauthorized
                detail: Missing or invalid API key.
                remediation: >-
                  Send `Authorization: Bearer sk_test_...` (or sk_live_...) with
                  a valid API key.
                doc_url: /docs/errors#auth-unauthorized
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
        '404':
          description: Resource not found in this org + mode.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/resource_not_found
                title: Resource not found
                status: 404
                code: resource.not_found
                detail: No such id in this org + mode.
                remediation: >-
                  Verify the id and that the key mode (test/live) matches the
                  id.
                doc_url: /docs/errors#resource-not_found
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
        '422':
          description: Request validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/request_validation_failed
                title: Request validation failed
                status: 422
                code: request.validation_failed
                detail: One or more fields did not satisfy the schema.
                remediation: Fix the fields listed in `errors` and resubmit.
                doc_url: /docs/errors#request-validation_failed
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
        '429':
          description: Rate limit exceeded — back off per the Retry-After header.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/rate_limit_exceeded
                title: Rate limit exceeded
                status: 429
                code: rate_limit.exceeded
                detail: >-
                  Too many requests for this key + request class (reads and
                  writes are limited separately).
                remediation: >-
                  Back off and retry after the number of seconds in the
                  Retry-After header; batch work or lower your request rate.
                doc_url: /docs/errors#rate_limit-exceeded
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/internal_error
                title: Internal server error
                status: 500
                code: internal.error
                detail: An unexpected error occurred.
                remediation: >-
                  Retry later; contact support with the request_id if it
                  persists.
                doc_url: /docs/errors#internal-error
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
components:
  parameters:
    InvoiceVersion:
      name: Invoice-Version
      in: header
      required: false
      description: >-
        Pin a dated API release (Stripe-style). Omit to use the current version.
        An unknown value returns 400 `request.invalid_version`. Echoed back on
        every response.
      schema:
        type: string
        example: '2026-07-10'
    InvoiceAccount:
      name: Invoice-Account
      in: header
      required: false
      description: >-
        Connect: act on behalf of one of your connected accounts (its
        `acct_…`/`org_…` id). Omit to act as your own organization. Not honored
        on /v1/api_keys.
      schema:
        type: string
        example: org_2P9connectedacct
  headers:
    RequestId:
      description: >-
        Unique id for this request. Also the `request_id` in every error body —
        log it and quote it to support; idempotency keys off it too.
      schema:
        type: string
        example: req_2P9K3sample
    InvoiceVersionResponse:
      description: >-
        The dated API version resolved for this request (request header → key
        pin → current). Echoed on every response.
      schema:
        type: string
        example: '2026-07-15'
    Traceparent:
      description: >-
        W3C Trace Context. When you send a valid `traceparent`, the response
        continues the trace (same trace-id, a fresh span-id, sampled flag).
      schema:
        type: string
        example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
    RateLimitLimit:
      description: >-
        IETF draft rate-limit: the ceiling of the token bucket consulted for
        this request class (reads and writes have independent buckets).
      schema:
        type: integer
        example: 100
    RateLimitRemaining:
      description: 'IETF draft rate-limit: tokens left in the bucket after this request.'
      schema:
        type: integer
        example: 99
    RateLimitReset:
      description: 'IETF draft rate-limit: seconds until the bucket refills to its ceiling.'
      schema:
        type: integer
        example: 1
    RetryAfter:
      description: >-
        Seconds to wait before retrying (RFC 9110). Present on 429 and on
        retryable upstream failures.
      schema:
        type: integer
        example: 1
  schemas:
    Problem:
      type: object
      description: RFC 9457 problem+json error with agent-first extensions.
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          description: Stable dotted machine code to switch on.
        detail:
          type: string
        remediation:
          type: string
          description: Actionable next step for a human or agent.
        request_id:
          type: string
        pac:
          type: object
          properties:
            provider:
              type: string
            codigo:
              type: string
            mensaje:
              type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
      required:
        - type
        - title
        - status
        - code
        - request_id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key: `Authorization: Bearer sk_test_...` or `sk_live_...`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.