> ## 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.
# Preview a range of SAT history before paying for it
> **Availability:** This operation has no configured public API gateway route and is not available through the documented base URL.
Queues a metadata pull for a date range and reports how many CFDIs exist and what downloading them would cost.
Reading header data from the SAT costs nothing; only fetching an XML is billed. This endpoint uses that gap: it stores what it finds as browsable rows in the `metadata` stage, which you can list with `GET /invoices/sat?sync_state=metadata` and then selectively import.
Answers **202**, not 200. One month is roughly a twelve second round trip to the SAT and a full history is dozens of them, well past any HTTP timeout. Poll `GET /invoices/download/jobs/{id}` for progress.
Only one job may run per team at a time.
This operation exists in Discovery, but a matching public API gateway route is not configured. It is not currently available through the documented base URL.
## OpenAPI
````yaml openapi.json POST /invoices/download/preview
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/download/preview:
post:
tags:
- Descarga Masiva SAT
summary: Preview a range of SAT history before paying for it
description: >
**Availability:** This operation has no configured public API gateway
route and is not available through the documented base URL.
Queues a metadata pull for a date range and reports how many CFDIs exist
and what downloading them would cost.
Reading header data from the SAT costs nothing; only fetching an XML is
billed. This endpoint uses that gap: it stores what it finds as
browsable rows in the `metadata` stage, which you can list with `GET
/invoices/sat?sync_state=metadata` and then selectively import.
Answers **202**, not 200. One month is roughly a twelve second round
trip to the SAT and a full history is dozens of them, well past any HTTP
timeout. Poll `GET /invoices/download/jobs/{id}` for progress.
Only one job may run per team at a time.
operationId: createInvoicesDownloadPreview
parameters:
- $ref: '#/components/parameters/TeamParameter'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- start_date
- end_date
properties:
start_date:
type: string
format: date
example: '2026-01-01'
end_date:
type: string
format: date
example: '2026-08-31'
directions:
type: array
description: Defaults to received only
items:
type: string
enum:
- issued
- received
responses:
'202':
description: Job queued
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
id:
type: string
example: satjob_a1b2c3d4e5
status:
type: string
enum:
- queued
total_windows:
type: integer
example:
success: true
message: Sincronización encolada
data:
id: satjob_a1b2c3d4e5
status: queued
total_windows: 8
'400':
description: Invalid date range or directions
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Descarga Masiva not activated
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'409':
description: A job is already running for this team
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'500':
$ref: '#/components/responses/ServerError'
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:
ValidationErrorResponse:
allOf:
- $ref: '#/components/schemas/StandardErrorResponse'
description: >
Body validation failure. Unknown top-level keys are rejected — the
validator runs in
strict allowlist mode (`allowUnknown: false`), so a field not declared
in the request
schema produces an `unexpected_key` detail rather than being ignored.
example:
success: false
error:
code: validation_failed
message: Request validation failed
details:
- 'currency: Field is required'
- 'client_id: Unexpected field'
timestamp: 1767225600000
StandardErrorResponse:
type: object
description: >
Standardized error envelope emitted by `sendErrorResponse` and its
helpers
(`sendValidationError`, `sendNotFoundError`, `sendUnauthorizedError`,
`sendForbiddenError`, `sendConflictError`, `sendBadRequestError`,
`sendInternalServerError`).
required:
- success
- error
- timestamp
properties:
success:
type: boolean
enum:
- false
example: false
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: >
Stable machine-readable code. Values emitted by the shared
helpers:
`unauthorized`, `forbidden`, `invalid_token`,
`validation_failed`,
`invalid_request_body`, `missing_required_field`,
`invalid_field_value`,
`resource_not_found`, `resource_already_exists`,
`resource_conflict`,
`business_rule_violation`, `operation_not_allowed`,
`insufficient_permissions`, `external_service_error`,
`payment_processor_error`, `cfdi_service_error`,
`internal_server_error`, `service_unavailable`,
`rate_limit_exceeded`,
`database_error`, `data_integrity_error`, `file_not_found`,
`file_upload_error`, `invalid_file_format`. Individual handlers
may
emit additional endpoint-specific codes, documented per
operation.
example: validation_failed
message:
type: string
example: Request validation failed
details:
oneOf:
- type: string
- type: array
items:
type: string
description: >
Present only when the handler supplies detail. Validation
failures
emit an array of `": "` strings.
example:
- 'currency: Field is required'
timestamp:
type: integer
format: int64
description: Server time in epoch milliseconds.
example: 1767225600000
AuthMiddlewareError:
type: object
description: >
Raw error body produced by the authentication layer (before any endpoint
runs). It is not
the standardized envelope: there is no `success` and no `timestamp`.
required:
- message
properties:
message:
type: string
description: >-
Human-readable reason. Some messages are in Spanish; branch on the
HTTP status, not on this text.
example: Unauthorized
error:
type: string
description: >-
OAuth error code. Present only when an OAuth access token was
presented.
enum:
- invalid_token
- token_expired
- token_revoked
- server_error
example: token_expired
error_description:
type: string
description: Same text as `message`. Present only alongside `error`.
example: Access token has expired. Please refresh your token.
details:
description: >-
Extra detail, e.g. `Invalid API Key` when a revoked key is rejected
with `403`.
oneOf:
- type: string
- type: object
example: Invalid API Key
UnauthorizedError:
allOf:
- $ref: '#/components/schemas/StandardErrorResponse'
example:
success: false
error:
code: unauthorized
message: Unauthorized access
timestamp: 1767225600000
responses:
Unauthorized:
description: >
Authentication failed. Two different bodies can come back with a `401`:
1. **From the authentication layer**, before the endpoint runs: a raw
object with
`message` and — for OAuth access tokens only — `error` / `error_description`. It does
**not** use the standardized envelope (`success` and `timestamp` are absent). Messages:
`Unauthorized` (missing header, missing `Bearer ` prefix, unparseable token),
`Unauthorized, missing team in token`, `Unauthorized, not a master team` and
`Unauthorized, no matched teams` (gigstack Connect), `Invalid access token`,
`Access token has expired. Please refresh your token.`, `Access token has been revoked`.
2. **From the endpoint itself**: the standardized envelope with
`error.code: unauthorized`.
Branch on the HTTP status, not on the body shape.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AuthMiddlewareError'
- $ref: '#/components/schemas/UnauthorizedError'
examples:
missing_or_invalid_key:
summary: Authentication layer — missing or unparseable API key
value:
message: Unauthorized
oauth_token_expired:
summary: Authentication layer — expired OAuth access token
value:
message: Access token has expired. Please refresh your token.
error: token_expired
error_description: Access token has expired. Please refresh your token.
connect_not_master_team:
summary: >-
Authentication layer — `team` sent by a team without gigstack
Connect
value:
message: Unauthorized, not a master team
endpoint_envelope:
summary: Endpoint — standardized envelope
value:
success: false
error:
code: unauthorized
message: Unauthorized access
timestamp: 1767225600000
ServerError:
description: >-
Unexpected server error (`error.code: internal_server_error`). The
failure is logged on gigstack's side.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
example:
success: false
error:
code: internal_server_error
message: An internal server error occurred
timestamp: 1767225600000
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.