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

# Create egress invoice

> [Small working example](/recipes/credit-note)

**Integration note:** A credit note adjusts the fiscal document. It does not refund money through a payment processor. Verified staging issuance returned HTTP 200 and data.uuid. Read [shared fields](/concepts/shared-fields) and the [Mexico](/countries/mexico) or [Colombia](/countries/colombia) guide for country-specific meaning. The linked fiscal recipes and staging issuance results use a Mexican issuer.

Create a new egress invoice (expense/credit note) with CFDI 4.0 compliance.

**gigstack Connect:** Create invoices for other teams using the `team` parameter.




## OpenAPI

````yaml openapi.json POST /invoices/egress
openapi: 3.0.3
info:
  title: gigstack API v2
  description: >
    # gigstack API v2


    Build customer, invoice and payment integrations. Start with the
    [quickstart](https://docs.gigstack.io/quickstart), then select the [issuing
    country](https://docs.gigstack.io/concepts/shared-fields).


    ## Authentication and environments


    Use Authorization: Bearer YOUR_API_KEY. Standard live and test keys use
    https://api.gigstack.io/v2. Internal staging uses
    https://gigstack-staging-9z9nnaat.uc.gateway.dev/v2 and separate keys. Test
    mode is a data mode within an environment; a body field does not switch a
    key's mode.


    See [authentication](https://docs.gigstack.io/authentication) for key
    handling, OAuth team scope and gigstack Connect. Signup requires its
    separately documented internal credential; health probes have their own
    security declarations. Operations marked unavailable have no configured
    public gateway route.


    ## Read the operation contract


    Response envelopes, pagination and retry rules differ by endpoint. HTTP
    success alone does not prove external fiscal completion or movement of
    money. Reconcile ambiguous writes before retrying. Use [responses and
    recovery](https://docs.gigstack.io/responses) and the operation's error
    codes; document credits and daily limits are not generic retryable rate
    limits.


    The issuing team's configuration selects Mexico or Colombia; customer
    country and currency do not. Read
    [Mexico](https://docs.gigstack.io/countries/mexico) or
    [Colombia](https://docs.gigstack.io/countries/colombia) before choosing
    fiscal fields. Accepted public input differs from a provider's direct
    payload.


    Examples and schema checks do not imply every operation has been executed
    live. [Verification coverage](https://docs.gigstack.io/verification)
    distinguishes source review, offline checks and observed staging behavior.
    Documentation describes operations and does not authorize execution.
  version: 2.0.0
  contact:
    name: Gigstack API Support
    url: https://gigstack.io
    email: support@gigstack.io
  license:
    name: Proprietary
    url: https://gigstack.io/terms
  termsOfService: https://gigstack.io/terms
servers:
  - url: https://api.gigstack.io/v2
    description: >
      Public API for standard live and test-mode keys. Test data is isolated by
      the key mode

      (`livemode: false`). Internal staging is a separate deployment and key
      store; see

      https://docs.gigstack.io/authentication#environments for its base URL.
security:
  - bearerAuth: []
tags:
  - name: gigstack Connect
    description: >
      **Multi-Team Resource Access**


      gigstack Connect lets a master team act on other teams that share its
      billing account.


      ## 🔗 How It Works


      Add the `team` query parameter to a request made with an **API key**:


      ```bash

      # Access team_xyz789's clients

      GET /clients?team=team_xyz789


      # Create an income invoice for team_abc123

      POST /invoices/income?team=team_abc123


      # Update service in team_def456

      PUT /services/service_456?team=team_def456

      ```


      ## ✅ Requirements


      - The API key's team must be a master team (gigstack Connect enabled)

      - The target team must exist and share the master team's billing account

      - The plan must include the `multipleIssuerAccounts` feature

      - OAuth access tokens cannot act on another team


      ## ⚠️ Error Responses


      Raw `{ "message": … }` bodies from the authentication layer:


      - `401 Unauthorized, not a master team` - gigstack Connect not enabled on
      your key's team

      - `404 Team not found` - Target team doesn't exist

      - `401 Unauthorized, no matched teams` - Target team could not be resolved
      within your billing account

      - `403 Tu plan no incluye múltiples cuentas emisoras. …` - Plan lacks
      `multipleIssuerAccounts`

      - `403 Team mismatch with OAuth token` - OAuth access token used with
      another team's id


      ## 🌐 Availability


      The `team` parameter is read by the authentication layer, so it is
      accepted on every authenticated

      endpoint, including ones whose parameter list does not show it.
  - name: Clients
    description: Client management operations with Mexican tax compliance
  - name: Services
    description: Service and product catalog management with SAT product keys
  - name: Invoices
    description: Invoice management with CFDI 4.0 compliance and SAT integration
  - name: Draft Invoices (Pre-Facturas)
    description: >
      **Create, edit, preview and stamp draft invoices (pre-facturas)**


      Draft invoices let you build CFDI invoices incrementally before stamping
      them with SAT. Use them as **pre-facturas** — generate a preview PDF with
      a "Sin Validez Fiscal" watermark to share with your client for approval,
      then stamp the draft to create a valid CFDI when ready.


      ## Typical Workflow


      1. `POST /invoices/draft` — Create a draft with minimal data

      2. `PUT /invoices/draft/{id}` — Update as more data becomes available

      3. `POST /invoices/draft/{id}/preview` — Generate a preview PDF
      (pre-factura)

      4. `POST /invoices/draft/{id}/stamp` — Finalize into a valid CFDI invoice
  - name: Descarga Masiva SAT
    description: >
      **SAT bulk invoice download via FIEL authentication**


      Download all your issued and received CFDI invoices directly from the SAT
      (Servicio de Administración Tributaria) using your FIEL (Firma Electrónica
      Avanzada).


      ## Setup flow

      1. `GET /invoices/download/activate/status` — Check if activated and
      what's needed

      2. `POST /invoices/download/activate` — Activate billing (adds Stripe
      meter/add-on)

      3. `POST /invoices/download/fiel` — Upload `.cer` + `.key` files
      (auto-registers with SAT)

      4. `PUT /invoices/download/schedule` — Configure daily auto-sync

      5. `POST /invoices/download/request` — Submit manual download requests


      ## Pricing

      - Included in Pro/Business plans: only the download meter ($0.20 MXN/XML)

      - Other paid plans: the same $0.20 MXN/XML download meter, no monthly base
      fee
  - name: Payments
    description: Payment processing, tracking, and refund management
  - name: Receipts
    description: Receipt creation and management with CFDI stamping capabilities
  - name: Retentions
    description: >-
      Tax retention documents (CFDI Retenciones 2.0) — creation, stamping,
      cancellation, and file retrieval
  - name: Platform Payouts
    description: >
      **Plan and stamp a marketplace's provider payouts from two files.**


      For marketplaces and digital platforms that pay providers under the SAT
      digital-platforms scheme

      (Plataformas Tecnológicas, RESICO 625, retention key 26): ride-hailing
      drivers, delivery couriers,

      lodging hosts, sellers of goods. Available to marketplace **master teams**
      whose billing account has

      platform payouts enabled. Upload a movements file and a commissions file.
      gigstack matches each row

      to a provider's team in your billing account and plans three kinds of
      CFDI: the provider's income

      invoice to you, your retention certificate (key 26) to the provider, and
      your monthly commission

      invoice to the provider.


      **Not for your own sales.** This is for a platform invoicing on behalf of
      its providers. A company

      invoicing its own sales, one CFDI per sale, should use `POST
      /invoices/income`.


      **Tax policy per account.** Which documents are issued, and with which SAT
      keys and rates, is set

      per master account at onboarding: allowed tax regimes, CSD requirement,
      service type (`tipoDeServ` /

      `subTipServ`), ISR and IVA withholding rates, product keys and concept
      descriptions. The defaults are

      for ground passenger transport (service type `01`, 2.1% ISR withholding).
      Contact support to

      configure your account's policy; it can't be changed through the API.


      1. `POST /platform-payouts` with an `Idempotency-Key` - upload and plan
      (synchronous)

      2. `GET /platform-payouts/{id}` and `GET /platform-payouts/{id}/movements`
      - review the plan

      3. `POST /platform-payouts/{id}/confirm` - irreversible hand-off to the
      stamping worker

      4. `GET /platform-payouts/{id}` - poll until `completed` or `failed`, then
      read `result`
         (`completed`, `partially_completed` or `failed`)

      Error messages and exclusion reasons are Spanish sentences for end users;
      branch on `error.code`,

      `reason_code` and `exclusion_codes`.
  - name: Documents
    description: >
      SAT supporting documentation (contracts, delivery/payment proofs,
      communications) — upload

      metadata, compliance review, AI extraction, and linking to invoices,
      payments, receipts and clients.
  - name: Teams
    description: Team management, settings, and member administration
  - name: Users
    description: User account management and password operations
  - name: Auth
    description: >
      **API-only signup for AI agents and partner integrations.**


      A single `POST /v2/auth/signup` call provisions a Firebase Auth user,
      billing

      account, team, plan subscription, and returns API keys — no UI, no FIEL
      upload,

      no human onboarding required.


      Designed for the AI-agents-as-customers use case. RFC defaults to genérico

      (`XAXX010101000`) so agents can transact under público en general
      until/unless

      their customer uploads their own RFC.


      Authenticated with `X-Internal-API-Key` (partner-issued) — Bearer tokens
      are

      team-scoped and a brand-new caller doesn't have one yet.


      See `AGENTS.md` in the gigstack-cli repo for end-to-end integration guide.
  - name: Webhooks
    description: Webhook management for real-time event notifications
  - name: Catalogs
    description: >
      **Read-only search over the SAT catalogs**


      Look up the SAT codes required on CFDI line items without hardcoding them:


      - `GET /catalogs/product-keys` — `c_ClaveProdServ`, the item `product_key`

      - `GET /catalogs/unit-keys` — `c_ClaveUnidad`, the item `unit_key` /
      `unit_name`


      Both are typo-tolerant full-text searches ranked by relevance. The
      catalogs are

      published by the SAT and identical for every team, so results carry no
      team data

      and ignore `livemode` — but a valid API key is still required.
  - name: SAT Lists
    description: >
      Read-only access to the RFC lists the SAT publishes under Artículo 69,
      69-B and 69-B Bis.


      gigstack re-syncs all 22 lists from the SAT's published CSVs every Sunday,
      so you can screen a counterparty's

      RFC before invoicing it without scraping the SAT yourself.
externalDocs:
  description: Complete API Documentation & Guides
  url: https://docs.gigstack.io
paths:
  /invoices/egress:
    post:
      tags:
        - Invoices
      summary: Create egress invoice
      description: >
        [Small working example](/recipes/credit-note)


        **Integration note:** A credit note adjusts the fiscal document. It does
        not refund money through a payment processor. Verified staging issuance
        returned HTTP 200 and data.uuid. Read [shared
        fields](/concepts/shared-fields) and the [Mexico](/countries/mexico) or
        [Colombia](/countries/colombia) guide for country-specific meaning. The
        linked fiscal recipes and staging issuance results use a Mexican issuer.


        Create a new egress invoice (expense/credit note) with CFDI 4.0
        compliance.


        **gigstack Connect:** Create invoices for other teams using the `team`
        parameter.
      operationId: createInvoicesEgress
      parameters:
        - $ref: '#/components/parameters/TeamParameter'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceEgressInput'
            example:
              automation_type: none
              currency: MXN
              use: G03
              payment_form: '03'
              client:
                id: client_1234567890
              items:
                - quantity: 1
                  description: Purchased materials
                  sku: MAT-001
                  product_key: '80141503'
                  unit_key: E48
                  unit_name: Unidad
                  unit_price: 500
                  taxability: '02'
                  taxes:
                    - type: IVA
                      rate: 0.16
                      factor: Tasa
                      withholding: false
                      inclusive: false
              send_email: true
              emails:
                - proveedor@empresa.com
              metadata:
                purchase_order: PO-2024-001
                department: procurement
      responses:
        '200':
          description: Invoice created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invoice created successfully
                  data:
                    $ref: '#/components/schemas/ApiPublicIncomeInvoice'
              example:
                message: Invoice created successfully
                data:
                  uuid: B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB
                  client:
                    id: client_1234567890
                    name: Proveedor ABC SA
                    email: proveedor@empresa.com
                    tax_id: PABC800101ABC
                    from: api
                    livemode: true
                    owner: user_1234567890
                    team: team_1234567890
                    created_at: 1767225600000
                  status: valid
                  currency: MXN
                  exchange_rate: 1
                  total: 580
                  subtotal: 500
                  taxes: 80
                  discount: 0
                  series: E
                  folio_number: 123
                  invoice_type: E
                  items:
                    - id: item_1234567890
                      description: Purchased materials
                      quantity: 1
                      unit_price: 500
                      product_key: '80141503'
                      unit_key: E48
                  created_at: 1677651234
                  livemode: true
                  owner: user_1234567890
        '400':
          description: >
            Bad Request. All bodies here are **raw**, not the standardized
            envelope.

            - Body validation: `{ "message": "Invalid body", "errors": [ {
            "path": …, "code": …, "message": … } ] }`.
              Unknown keys are rejected — there is no `client_id` field; use `client: { "id": … }`.
            - `{ "message": "Billing account not found", "error": "Billing
            account is required" }`

            - `{ "message": "Invalid currency", "error": … }`

            - `{ "message": "Exchange rate not found" }`

            - `{ "message": "Resource resolution failed", "error": … }` when the
            client/service
              reference is ambiguous (both `id` and `search`, or `safety_check` matched several).
            - Generic CFDI/PAC stamping failure, nested one level under
            `message`:
              `{ "message": { "error": …, "code": …, "providerMessage": …, "retryable": false } }`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LegacyErrorResponse'
                  - type: object
                    properties:
                      message:
                        $ref: '#/components/schemas/CfdiErrorResponse'
        '401':
          description: Unauthorized. Raw shape with only a `message` key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
        '403':
          description: >
            The referenced client or service belongs to another team, or its
            `livemode` does

            not match the API key. Raw shape `{ "message": "Resource resolution
            failed", "error": … }`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
        '404':
          description: The referenced client or service id was not found. Raw shape.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
        '409':
          description: >
            A concurrent create holds the lock for the same client or service.
            Retry the

            request. Raw shape.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
        '412':
          description: >
            **SAT not connected.** The team has no valid CSD, or the certificate
            failed

            validation. Returned in the CFDI error shape nested under `message`,
            with

            `retryable: false`. Upload a CSD via `POST
            /v2/teams/{id}/sat-connection`

            before retrying — retrying as-is will fail identically.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    $ref: '#/components/schemas/CfdiErrorResponse'
              example:
                message:
                  error: >-
                    El certificado de sello digital (CSD) no está configurado o
                    no es válido.
                  code: csd_validation_error
                  retryable: false
        '500':
          description: >
            Internal Server Error. Raw shape — either

            `{ "message": "Failed to save invoice", "error": { "code":
            "invoice_save_error", … } }`

            or `{ "message": "An error occurred while creating invoice",
            "error": { "code": …, "message": … } }`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyErrorResponse'
        '503':
          description: >
            **PAC unavailable.** The stamping provider could not be reached.
            Returned in the

            CFDI error shape nested under `message`, with `retryable: true` —
            this is the only

            CFDI failure that is safe to retry unchanged. Wait a few minutes and
            retry with

            the same `idempotency_key`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    $ref: '#/components/schemas/CfdiErrorResponse'
              example:
                message:
                  error: >-
                    El servicio de timbrado no está disponible en este momento.
                    Vuelve a intentarlo en unos minutos.
                  code: pac_unavailable
                  retryable: true
      security:
        - bearerAuth: []
components:
  parameters:
    TeamParameter:
      name: team
      in: query
      required: false
      schema:
        type: string
      description: >
        **gigstack Connect:** Target team ID for multi-team access.


        Requires gigstack Connect enabled on your team and shared billing
        account.


        Also requires the `multipleIssuerAccounts` feature on your plan.
        Requests targeting a

        team other than the one your API key belongs to return `403` without it.


        Only API keys can use it: an OAuth access token sent with another team's
        id is rejected with

        `403 Team mismatch with OAuth token`.


        **Optional — omit it entirely** unless you are acting on another team.
        It deliberately

        carries no example value so generated snippets do not emit
        `?team=undefined`; when the

        parameter is absent, the team is derived from your API key.


        **Example:** `?team=team_xyz789`
  schemas:
    InvoiceEgressInput:
      description: >
        Unknown top-level keys are rejected (`400 validation_failed` /
        `unexpected_key`) — body

        validation runs in strict allowlist mode, so a field the schema does not
        declare

        produces that error. In particular there is no `client_id` field:
        reference an

        existing client with `client: { "id": "client_…" }`, or look one up with

        `client: { "search": { "on_key": "tax_id", "on_value": "…" } }`.
        Supplying both `id`

        and `search` on the same object is a `400`.


        `team`, `livemode` and `owner` are reserved and injected by the auth
        middleware.
      type: object
      additionalProperties: false
      required:
        - client
        - currency
        - use
        - items
        - payment_form
      properties:
        date:
          description: Unix timestamp for invoice date
          example: 1640995200
          type: number
        client:
          $ref: '#/components/schemas/EmbeddedClientInput'
        return_files:
          description: Return base64 encoded PDF and XML files in response
          example: true
          type: boolean
        currency:
          type: string
          example: MXN
        exchange_rate:
          description: >-
            Exchange rate for currency conversion. If not provided, the latest
            rate from our rates collection will be used automatically.
          example: 1
          type: number
        folio_number:
          example: 123
          type: number
        series:
          description: Optional. Defaults to the team's credit-note serie, then 'E'.
          example: A
          type: string
        idempotency_key:
          description: Optional idempotency key to prevent duplicate invoices
          example: unique_key_123
          type: string
          nullable: true
        use:
          type: string
          example: G03
        exports:
          example: '01'
          type: string
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - null
          nullable: true
        complements:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - type
              - data
            properties:
              type:
                example: custom
                type: string
              data:
                example: <xml>...</xml>
                type: string
          nullable: true
        related_documents:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - relationship
              - documents
            properties:
              relationship:
                example: '04'
                type: string
              documents:
                type: array
                items:
                  example: 12345678-1234-1234-1234-123456789012
                  type: string
          nullable: true
        invoice_pdf_notes:
          example: Additional notes for PDF
          type: string
        addenda:
          example: <addenda>...</addenda>
          type: string
          nullable: true
        send_email:
          description: >-
            Whether to send the document via email to the client. Defaults to
            `true`.
          example: true
          type: boolean
        ignore_emails:
          description: >
            Suppress all notification emails for this document. Takes precedence
            over

            `send_email` — when `true`, no mail is sent even if `send_email` is
            `true`.
          example: false
          type: boolean
          nullable: true
        emails:
          example:
            - client@example.com
          type: array
          items:
            type: string
            format: email
        metadata:
          type: object
          additionalProperties: true
          properties: {}
        automation_type:
          description: |
            Payment automation type:
            - `none`: No automation, create invoice only
          example: none
          type: string
          enum:
            - none
        items:
          description: >-
            Line items. Only `quantity` is required on each item; everything
            else is optional or resolved from the referenced service.
          type: array
          items:
            $ref: '#/components/schemas/ItemSchema'
        payment_form:
          type: string
          example: '03'
        payment_method:
          description: >
            CFDI `MetodoPago`. Optional — defaults to `PUE` when omitted, which
            is how every

            egress invoice was stamped before this field existed.


            With `PPD`, SAT requires `payment_form` to be `99` ("Por definir");
            any other

            value you send is overridden to `99` rather than rejected.
          example: PUE
          default: PUE
          type: string
          enum:
            - PPD
            - PUE
    ApiPublicIncomeInvoice:
      type: object
      properties:
        uuid:
          type: string
          example: B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB
          description: SAT UUID (folio fiscal)
        client:
          $ref: '#/components/schemas/ApiPublicClient'
        created_at:
          type: number
          example: 1677651234
          description: Invoice creation timestamp
        currency:
          type: string
          example: MXN
          description: Invoice currency
        exchange_rate:
          type: number
          example: 1
          description: Exchange rate used
        total:
          type: number
          example: 1160
          description: Total invoice amount
        subtotal:
          type: number
          example: 1000
          description: Subtotal before taxes
        taxes:
          type: number
          example: 160
          description: Total tax amount
        discount:
          type: number
          example: 0
          description: Total discount amount
        withholding_taxes:
          type: number
          example: 0
          description: Total withholding tax amount
        series:
          description: Invoice series
          example: A
          type: string
        folio_number:
          type: number
          example: 123
          description: Invoice folio number
        invoice_type:
          type: string
          enum:
            - I
            - E
            - P
            - 'N'
          example: I
          description: Invoice type (I=Income, E=Egress, P=Payment, N=Nomina)
        use:
          type: string
          example: G03
          description: Mexican SAT usage code
        payment_form:
          type: string
          example: '03'
          description: Mexican SAT payment form code
        payment_method:
          type: string
          example: PUE
          description: Payment method (PUE/PPD)
        status:
          type: string
          enum:
            - draft
            - pending
            - valid
            - canceled
            - cancelled
          example: valid
          description: >
            Invoice status as stored. A stamped invoice is `valid`; a cancelled
            one is

            `canceled`. `cancelled` (double L) appears only on older records —
            new writes

            always use `canceled`. `draft` is a pre-factura that has not been
            stamped.
        livemode:
          type: boolean
          example: true
          description: Whether this is a live invoice
        owner:
          type: string
          example: user_1234567890
          description: User who created the invoice
        from:
          type: string
          example: api
          description: >-
            Source of invoice creation. Documents created through the public API
            are stored with `api`; requests carrying the `X-Gigstack-Client:
            mcp` header (the gigstack MCP server) are stored with `mcp` and
            behave identically.
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: item_1234567890
              description:
                type: string
                example: Professional consulting services
              product_key:
                type: string
                example: '80141503'
              quantity:
                type: number
                example: 1
              unit_price:
                type: number
                example: 1000
              unit_key:
                type: string
                example: E48
              unit_name:
                type: string
                example: Servicio
              sku:
                type: string
                example: CONS-001
              taxability:
                type: string
                enum:
                  - '01'
                  - '02'
                example: '01'
              taxes:
                type: array
                items:
                  $ref: '#/components/schemas/TaxSchema'
        payments:
          type: array
          items:
            type: string
          example:
            - payment_1234567890
          description: Associated payment IDs
        invoices:
          type: array
          items:
            type: string
          example: []
          description: Related invoice IDs
        stamp:
          type: object
          nullable: true
          properties:
            sello:
              type: string
              example: ABC123...
            stamp_at:
              type: number
              example: 1677651234
        cancellation:
          type: object
          nullable: true
          properties:
            cancellation_status:
              type: string
              example: cancelled
            cancelled_at:
              type: number
              example: 1677651234
            motive:
              type: string
              example: '02'
            code:
              type: string
              example: '201'
        verification_url:
          type: string
          example: https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx
          description: SAT verification URL
        exports:
          type: string
          example: '01'
          description: Export indicator
        addenda:
          type: string
          example: ''
          description: Additional XML addenda
        invoice_pdf_notes:
          type: string
          example: Additional notes for PDF
          description: Custom notes for PDF generation
        files:
          type: object
          nullable: true
          description: Base64 encoded files (only returned when return_files=true)
          properties:
            pdf:
              type: string
              example: JVBERi0xLjQKJeLjz9MKMSAwIG9ia...
              description: Base64 encoded PDF file
            xml:
              type: string
              example: PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4...
              description: Base64 encoded XML file
        idempotency_key:
          type: string
          nullable: true
        team:
          type: string
          example: team_1234567890
        billing_account:
          type: string
          nullable: true
        date:
          type: integer
          format: int64
          nullable: true
          description: Comprobante date, epoch ms.
        payment_conditions:
          type: string
          nullable: true
        global:
          type: object
          nullable: true
          description: Global-invoice period (see the Global Invoices guide).
          properties:
            periodicity:
              type: string
            months:
              type: string
            year:
              type: integer
        related_documents:
          type: array
          nullable: true
          items:
            type: object
            properties:
              relationship:
                type: string
              documents:
                type: array
                items:
                  type: string
        complements:
          type: array
          nullable: true
          items:
            type: object
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        emails:
          type: array
          nullable: true
          items:
            type: string
        issuer_info:
          type: object
          nullable: true
          properties:
            legal_name:
              type: string
            tax_id:
              type: string
            tax_system:
              type: string
            zip:
              type: string
        namespaces:
          type: array
          nullable: true
          items:
            type: object
            properties:
              prefix:
                type: string
              uri:
                type: string
              schema_location:
                type: string
    LegacyErrorResponse:
      type: object
      description: >
        Raw error body returned by handlers that do not use the standardized
        helpers.

        Note the absence of `success` and `timestamp`.
      required:
        - message
      properties:
        message:
          type: string
          example: Invalid body
        error:
          oneOf:
            - type: string
            - type: object
          description: Present on most, but not all, legacy error paths.
        errors:
          type: array
          description: >-
            Field-level validation errors, when the failure came from body
            validation.
          items:
            type: object
            properties:
              path:
                type: string
                example: client_id
              code:
                type: string
                example: unexpected_key
              message:
                type: string
                example: Unexpected field
    CfdiErrorResponse:
      type: object
      description: >
        Raw CFDI/PAC error body produced by `handleCFDIError`. **Not** the
        standardized

        envelope. On `POST /v2/invoices/income`, `/egress` and
        `/invoices/draft/{id}/stamp`

        this object is nested one level deeper, under a `message` key

        (`{ "message": { "error": …, "code": …, "retryable": … } }`); on

        `DELETE /v2/invoices/{id}` it is returned at the top level.
      required:
        - error
        - code
        - retryable
      properties:
        error:
          type: string
          description: Human-readable Spanish error message shown to the end user.
          example: 'Error al timbrar la factura: El CSD del emisor no es válido.'
        code:
          type: string
          description: >
            CFDI/PAC error code: a SAT/PAC code (e.g. `CFDI40147`) or one of
            gigstack's own

            (`SAT_NOT_CONNECTED`, `CSD_VALIDATION_ERROR`, `PAC_UNAVAILABLE`,
            `PAC_OUTCOME_UNKNOWN`,

            `STAMP_NEEDS_REVIEW`, `INVALID_INVOICE`, `STAMPING_ERROR`, …).
          example: CSD_VALIDATION_ERROR
        providerMessage:
          type: string
          description: >-
            Raw message returned by the PAC. Only present on generic (400)
            stamping failures.
          example: CFDI40147 - El campo UsoCFDI no es válido
        retryable:
          type: boolean
          description: >
            Whether sending the **same** request again is safe and can succeed.
            `true` for `503`

            `PAC_UNAVAILABLE`, and for `503` `PAC_OUTCOME_UNKNOWN` only when the
            request carried an

            `idempotency_key`. Every `400`, `409` and `412` is `false`.
          example: false
        duplicate:
          type: boolean
          description: >
            Present and `true` only on the `400` answered for an
            `idempotency_key` whose invoice already

            exists. Nothing was stamped or charged by this request; `uuid` names
            the existing invoice.
          example: true
        uuid:
          type: string
          description: >-
            With `duplicate`, the folio fiscal (UUID) of the invoice already
            issued under this `idempotency_key`.
          example: 0f8fad5b-d9cb-469f-a165-70867728950e
    EmbeddedClientInput:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          nullable: true
        search:
          type: object
          additionalProperties: false
          required:
            - on_key
            - on_value
          properties:
            on_key:
              type: string
            on_value:
              type: string
            auto_create:
              type: boolean
              nullable: true
            safety_check:
              type: boolean
              nullable: true
            update:
              type: boolean
              nullable: true
          nullable: true
        address:
          type: object
          additionalProperties: false
          properties:
            country:
              type: string
              nullable: true
              maxLength: 3
            street:
              type: string
              nullable: true
            zip:
              type: string
              nullable: true
            city:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
            exterior:
              type: string
              nullable: true
            interior:
              type: string
              nullable: true
            municipality:
              type: string
              nullable: true
            neighborhood:
              type: string
              nullable: true
          nullable: true
        name:
          type: string
          nullable: true
        company:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        bcc:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
          properties: {}
        legal_name:
          type: string
          nullable: true
        tax_id:
          type: string
          nullable: true
        use:
          type: string
          nullable: true
        tax_system:
          type: string
          nullable: true
        document_type:
          description: DIAN identification document code
          type: string
          enum:
            - ''
            - '11'
            - '12'
            - '13'
            - '21'
            - '22'
            - '31'
            - '41'
            - '42'
            - '47'
            - '48'
            - '50'
            - '91'
            - null
          nullable: true
        organization_type:
          description: 1 = persona jurídica, 2 = persona natural
          oneOf:
            - type: string
              enum:
                - ''
                - '1'
                - '2'
                - null
              nullable: true
            - type: number
              enum:
                - 1
                - 2
        tribute_code:
          description: '''01'' = responsable de IVA, ''ZZ'' = no aplica'
          type: string
          enum:
            - ''
            - '01'
            - ZZ
            - null
          nullable: true
        fiscal_responsibilities:
          description: >-
            DIAN responsabilidades fiscales (lista 53). Omitted means 'R-99-PN'
            (no responsable)
          type: array
          items:
            type: string
            enum:
              - O-13
              - O-15
              - O-23
              - O-47
              - R-99-PN
          nullable: true
        dv:
          description: NIT verification digit
          type: string
          nullable: true
          pattern: ^[0-9]?$
        municipality_code:
          description: DANE municipality code, only for clients domiciled in Colombia
          type: string
          nullable: true
          pattern: ^([0-9]{5})?$
    ItemSchema:
      description: >
        A line item on an invoice, receipt or payment. Only `quantity` is
        required; everything

        else is optional, or resolved from the referenced service when
        `id`/`search` is used.

        `id` and `search` are mutually exclusive — supplying both is a `400`.


        Unknown keys are rejected. Note there is no per-item `metadata` field.
      type: object
      additionalProperties: false
      required:
        - quantity
      properties:
        id:
          description: Service/product ID reference
          example: service_1234567890
          type: string
          nullable: true
        search:
          type: object
          additionalProperties: false
          required:
            - on_key
            - on_value
          properties:
            on_key:
              description: Field to search on (sku, name, etc.)
              example: sku
              type: string
            on_value:
              description: Value to search for
              example: CONS-001
              type: string
            auto_create:
              description: Create service if not found
              example: true
              type: boolean
              nullable: true
            safety_check:
              description: >-
                When true, prevents using multiple matching results (returns
                error). When false, uses the first result found. Default: false
              example: false
              type: boolean
              nullable: true
            update:
              type: boolean
              nullable: true
          nullable: true
        quantity:
          description: Item quantity
          example: 1
          type: number
        description:
          description: Item description
          example: Consulting services
          type: string
          nullable: true
        sku:
          description: Stock keeping unit
          example: CONS-001
          type: string
          nullable: true
        product_key:
          description: SAT product key (c_ClaveProdServ)
          example: '80141503'
          type: string
          nullable: true
        unit_key:
          description: SAT unit key (c_ClaveUnidad)
          example: E48
          type: string
          nullable: true
        unit_name:
          description: Unit name
          example: Servicio
          type: string
          nullable: true
        unit_price:
          description: Unit price
          example: 1000
          type: number
          nullable: true
        discount:
          description: >-
            Discount amount (absolute value in the item currency, not a
            percentage)
          example: 0
          type: number
          nullable: true
        taxability:
          description: SAT `c_ObjetoImp` — whether the item is subject to tax.
          example: '02'
          type: string
          enum:
            - '01'
            - '02'
            - '03'
            - '04'
            - '05'
            - '06'
            - '07'
            - '08'
            - null
          nullable: true
        taxes:
          description: Tax elements applied to this item
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              base:
                description: >-
                  Taxable base amount. Accepts number or numeric string. If
                  null, calculated automatically from item price.
                example: 100
                oneOf:
                  - type: number
                    nullable: true
                  - type: string
                    description: Numeric string accepted by the request validator.
              factor:
                type: string
                nullable: true
                example: Tasa
                description: SAT tax factor (Tasa, Cuota, Exento)
              inclusive:
                type: boolean
                nullable: true
                example: false
                description: Whether the tax is included in the unit price
              rate:
                description: Tax rate (e.g., 0.16 for 16% IVA)
                example: 0.16
                type: number
                nullable: true
              type:
                description: Type of tax
                example: IVA
                type: string
                enum:
                  - IVA
                  - ISR
                  - IEPS
                  - null
                nullable: true
              withholding:
                type: boolean
                nullable: true
                example: false
                description: Whether this is a withholding tax
            nullable: true
        third_party:
          description: Third party information for items provided by external parties
          type: object
          additionalProperties: false
          properties:
            legal_name:
              description: Third party legal name
              example: Third Party SA
              type: string
              nullable: true
            tax_id:
              description: Third party RFC (tax ID)
              example: TPR800101ABC
              type: string
              nullable: true
            tax_system:
              description: Third party tax system
              example: '601'
              type: string
              nullable: true
            zip:
              description: Third party ZIP code
              example: '03100'
              type: string
              nullable: true
          nullable: true
        item_complement:
          description: CFDI item-level complement.
          type: object
          additionalProperties: false
          properties:
            hydrocarbons:
              description: >-
                Complemento de hidrocarburos. All four fields are required when
                this object is present.
              type: object
              additionalProperties: false
              required:
                - permit_type
                - permit_number
                - fuel_code
                - fuel_sub_product
              properties:
                permit_type:
                  example: PL/12345/EXP/ES/2020
                  type: string
                permit_number:
                  example: '12345'
                  type: string
                fuel_code:
                  example: PR03
                  type: string
                fuel_sub_product:
                  example: '10'
                  type: string
              nullable: true
          nullable: true
    ApiPublicClient:
      type: object
      required:
        - id
        - email
        - from
        - livemode
        - owner
        - team
        - created_at
      properties:
        id:
          type: string
          example: client_1234567890
          description: Unique client identifier
        address:
          $ref: '#/components/schemas/ClientAddress'
        name:
          type: string
          nullable: true
          example: Juan Pérez García
          description: Client name
        company:
          type: string
          nullable: true
          example: Empresa SA de CV
          description: Client company name
        phone:
          type: string
          nullable: true
          example: +52 55 1234 5678
          description: Client phone number
        email:
          type: string
          format: email
          nullable: true
          example: juan.perez@ejemplo.com
          description: Client email address
        bcc:
          type: array
          items:
            type: string
            format: email
          nullable: true
          example:
            - admin@empresa.com
          description: BCC email addresses for client communications
        metadata:
          type: object
          additionalProperties: true
          nullable: true
          example:
            custom_field: value
          description: Additional metadata for the client
        is_valid:
          type: boolean
          nullable: true
          example: true
          description: Whether the client data is valid
        from:
          type: string
          example: api
          description: >-
            Source of client creation. Documents created through the public API
            are stored with `api`; requests carrying the `X-Gigstack-Client:
            mcp` header (the gigstack MCP server) are stored with `mcp` and
            behave identically.
        legal_name:
          type: string
          nullable: true
          example: Juan Pérez García
          description: Legal name for tax purposes
        livemode:
          type: boolean
          example: true
          description: Whether this client is in live mode
        owner:
          type: string
          example: user_1234567890
          description: User ID who owns this client
        tax_id:
          type: string
          nullable: true
          example: PEGJ800101ABC
          description: RFC (Tax ID) for Mexican tax compliance
        use:
          type: string
          nullable: true
          example: G03
          description: CFDI use code
        tax_system:
          type: string
          nullable: true
          example: '601'
          description: SAT tax system code
        team:
          type: string
          example: team_1234567890
          description: Team ID this client belongs to
        created_at:
          type: number
          example: 1677651234
          description: Unix timestamp of client creation
        efos:
          type: object
          nullable: true
          properties:
            is_valid:
              type: boolean
              nullable: true
              example: true
              description: >-
                true = RFC is NOT on the EFOS (Art. 69-B) blacklist (safe).
                false = RFC appears on the blacklist.
          description: >-
            EFOS (Art. 69-B CFF) blacklist check. Independent from
            `fiscal_validation` — an RFC can fail one and pass the other.
        fiscal_validation:
          type: object
          nullable: true
          description: >-
            Result of attempting to stamp a test CFDI against the PAC. Only
            returned on create/update/validate; not persisted on the client doc.
          properties:
            status:
              type: string
              enum:
                - valid
                - not_valid
                - skipped
              example: not_valid
              description: >-
                `valid` = PAC accepted; `not_valid` = PAC rejected
                (RFC/legal_name/CP do not match SAT registry); `skipped` =
                required fields missing.
            message:
              type: string
              nullable: true
              example: >-
                Fiscal info validation failed. El campo DomicilioFiscalReceptor
                del receptor, debe pertenecer al nombre asociado al RFC
                registrado en el campo Rfc del Receptor.
              description: Human-readable reason when status is not_valid or skipped.
        sat_status:
          type: object
          nullable: true
          description: >
            Unified SAT risk signal combining the EFOS check with 20 SAT Datos
            Abiertos lists (Art. 69, 69-B, 69-B Bis)

            synced weekly into Firestore. A hit on any "risky" list (Cancelados,
            No localizados, CSD sin efectos, Definitivos 69-B,

            Presuntos 69-B, etc.) or a failed EFOS check sets `is_risky: true`.
          properties:
            is_risky:
              type: boolean
              example: true
              description: true if any risky list hit OR `efos.is_valid === false`.
            efos:
              type: object
              nullable: true
              properties:
                is_valid:
                  type: boolean
                  nullable: true
                  example: false
              description: EFOS check result (duplicated here for convenience).
            hits:
              type: array
              description: >-
                Every SAT list the RFC appears on, with the full row from the
                source CSV.
              items:
                type: object
                properties:
                  list:
                    type: string
                    example: art_69b_definitivos
                    description: >-
                      List key (matches the source filename). See
                      /sat_rfc_list_entries for all.
                  label:
                    type: string
                    example: Definitivos 69-B
                  source:
                    type: string
                    enum:
                      - art_69
                      - art_69b
                      - art_69b_bis
                    example: art_69b
                  is_risky:
                    type: boolean
                    example: true
                    description: Whether a hit on this specific list marks the RFC unsafe.
                  detail:
                    type: object
                    additionalProperties: true
                    description: >-
                      Full SAT record (razón social, situación, dates, oficios
                      DOF, etc.). Shape varies per list.
            checked_at:
              type: number
              example: 1776887458784
              description: Unix timestamp (ms) of when this check was run.
        defaults:
          type: object
          nullable: true
          properties:
            keep_full_legal_name:
              type: boolean
              nullable: true
              example: false
              description: Keep full legal name in documents
            issue_automatic_invoices:
              type: boolean
              nullable: true
              example: false
              description: Issue automatic invoices
            issue_invoiceable_receipts:
              type: boolean
              nullable: true
              example: true
              description: Issue invoiceable receipts
          description: Client default settings
        document_type:
          type: string
          nullable: true
          description: >-
            Colombia (DIAN) only: identification document code (`11`, `12`,
            `13`, `21`, `22`, `31`, `41`, `42`, `47`, `48`, `50`, `91`).
        organization_type:
          anyOf:
            - description: 'Colombia (DIAN) only: `1` legal entity, `2` natural person.'
              oneOf:
                - type: integer
                - type: string
            - type: object
              nullable: true
              enum:
                - null
        tribute_code:
          type: string
          nullable: true
          description: 'Colombia (DIAN) only: `01` IVA responsible, `ZZ` not applicable.'
        fiscal_responsibilities:
          type: array
          nullable: true
          items:
            type: string
          description: >-
            Colombia (DIAN) only: fiscal responsibilities (list 53), e.g.
            `O-13`, `R-99-PN`.
        dv:
          type: string
          nullable: true
          description: 'Colombia (DIAN) only: NIT verification digit (informational).'
        municipality_code:
          type: string
          nullable: true
          description: 'Colombia (DIAN) only: 5-digit DANE municipality code.'
    TaxSchema:
      type: object
      additionalProperties: false
      properties:
        base:
          description: >-
            Taxable base amount. Accepts number or numeric string. If null,
            calculated automatically from item price.
          example: 100
          oneOf:
            - type: number
              nullable: true
            - type: string
              description: Numeric string accepted by the request validator.
        factor:
          example: Tasa
          type: string
          nullable: true
        inclusive:
          type: boolean
          nullable: true
          example: false
        rate:
          example: 0.16
          type: number
          nullable: true
        type:
          example: IVA
          type: string
          enum:
            - IVA
            - ISR
            - IEPS
            - null
          nullable: true
        withholding:
          type: boolean
          nullable: true
          example: false
    ClientAddress:
      type: object
      additionalProperties: false
      properties:
        country:
          example: MEX
          type: string
          nullable: true
          maxLength: 3
        street:
          example: Av. Insurgentes Sur
          type: string
          nullable: true
        zip:
          example: '03100'
          type: string
          nullable: true
        city:
          example: Ciudad de México
          type: string
          nullable: true
        state:
          example: CDMX
          type: string
          nullable: true
        exterior:
          example: '123'
          type: string
          nullable: true
        interior:
          example: 4B
          type: string
          nullable: true
        municipality:
          example: Benito Juárez
          type: string
          nullable: true
        neighborhood:
          example: Del Valle
          type: string
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        **Authentication Method:** HTTP Bearer token.


        The runtime requires the literal `Bearer ` prefix — a bare token in the

        `Authorization` header is rejected with `401 unauthorized`.


        **Header Format:** `Authorization: Bearer YOUR_API_KEY`


        Your API key is a JWT. Live keys operate on live data (`livemode:
        true`);

        test keys operate on isolated test data (`livemode: false`).


        **Get your key at:**
        [app.gigstack.pro/settings?tab=api](https://app.gigstack.pro/settings?tab=api)


        **Errors:** credential failures are answered by the authentication layer
        with a raw

        `{ "message": … }` body, not the standardized envelope — `401` for a
        missing, malformed or

        expired token, `403` for a revoked key or a plan without API access. See
        the `Unauthorized`

        and `AuthForbidden` responses.

````

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