> ## 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.
# Get document
> **Availability:** This operation has no configured public API gateway route and is not available through the documented base URL.
Retrieve one document. Documents belonging to another team, and soft-deleted
documents, are reported as `404` rather than `403`.
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 GET /documents/{id}
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:
/documents/{id}:
get:
tags:
- Documents
summary: Get document
description: >
**Availability:** This operation has no configured public API gateway
route and is not available through the documented base URL.
Retrieve one document. Documents belonging to another team, and
soft-deleted
documents, are reported as `404` rather than `403`.
operationId: getDocument
parameters:
- $ref: '#/components/parameters/TeamParameter'
- name: id
in: path
required: true
description: Document id.
schema:
type: string
example: doc_1234567890
responses:
'200':
description: Document retrieved.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/StandardSuccessResponse'
- type: object
properties:
data:
$ref: '#/components/schemas/ApiPublicDocument'
example:
success: true
data:
id: doc_1234567890
document_type: contract
name: Contrato de servicios 2026 — Cliente ACME
description: Contrato marco de prestación de servicios
file_url: >-
https://firebasestorage.googleapis.com/v0/b/gigstackpro.appspot.com/o/teams%2Fteam_123%2Fdocuments%2Fcontrato-acme.pdf?alt=media&token=9f1c7d84-3b2e-4a56-8c0d-1e7f5b9a2c43
file_name: contrato-acme.pdf
file_size: 284913
mime_type: application/pdf
linked_entities:
- entity_type: client
entity_id: client_1234567890
linked_at: 1767225600000
compliance_status: pending_review
compliance_notes: null
valid_from: 1767225600000
valid_until: 1798761600000
ai_extraction: null
tags:
- contrato
- acme
metadata: null
created_at: 1767225600000
created_by: user_1234567890
updated_at: null
livemode: true
message: Document retrieved successfully
timestamp: 1767225600000
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/AuthForbidden'
'404':
description: >-
`Document not found` — missing, owned by another team, or
soft-deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'500':
description: '`An error occurred while retrieving document`.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
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:
StandardSuccessResponse:
type: object
description: |
Standardized success envelope emitted by `sendSuccessResponse`.
required:
- success
- data
- timestamp
properties:
success:
type: boolean
enum:
- true
example: true
data:
type: object
description: The operation payload.
message:
type: string
description: Human-readable summary. Present only when the handler supplies one.
example: Operation completed successfully
timestamp:
type: integer
format: int64
description: Server time in **epoch milliseconds** (`Luxon.now().toMillis()`).
example: 1767225600000
ApiPublicDocument:
type: object
description: A document as returned by the documents endpoints (snake_case).
properties:
id:
type: string
example: doc_1234567890
document_type:
$ref: '#/components/schemas/DocumentTypeEnum'
name:
type: string
example: Contrato de servicios 2026 — Cliente ACME
description:
type: string
nullable: true
file_url:
type: string
example: >-
https://firebasestorage.googleapis.com/v0/b/gigstackpro.appspot.com/o/teams%2Fteam_123%2Fdocuments%2Fcontrato-acme.pdf?alt=media&token=9f1c7d84-3b2e-4a56-8c0d-1e7f5b9a2c43
file_name:
type: string
example: contrato-acme.pdf
file_size:
type: number
nullable: true
example: 284913
mime_type:
type: string
nullable: true
example: application/pdf
linked_entities:
type: array
items:
type: object
properties:
entity_type:
$ref: '#/components/schemas/DocumentLinkEntityTypeEnum'
entity_id:
type: string
example: client_1234567890
linked_at:
type: integer
format: int64
example: 1767225600000
compliance_status:
$ref: '#/components/schemas/DocumentComplianceStatusEnum'
compliance_notes:
type: string
nullable: true
valid_from:
type: integer
format: int64
nullable: true
example: 1767225600000
valid_until:
type: integer
format: int64
nullable: true
example: 1798761600000
ai_extraction:
type: object
nullable: true
description: >-
Result of the last AI analysis. `null` until the document is
analyzed.
properties:
extracted_at:
type: integer
format: int64
example: 1767225600000
model:
type: string
example: gemini-2.5-flash
confidence:
type: number
example: 0.92
extracted_data:
type: object
additionalProperties: true
description: >-
Fields extracted from the document; the shape depends on
`document_type`.
tags:
type: array
items:
type: string
example:
- contrato
- acme
metadata:
type: object
nullable: true
additionalProperties: true
created_at:
type: integer
format: int64
example: 1767225600000
created_by:
type: string
example: user_1234567890
updated_at:
type: integer
format: int64
nullable: true
example: 1767225600000
livemode:
example: true
type: boolean
NotFoundError:
allOf:
- $ref: '#/components/schemas/StandardErrorResponse'
example:
success: false
error:
code: resource_not_found
message: Resource not found
timestamp: 1767225600000
InternalServerError:
allOf:
- $ref: '#/components/schemas/StandardErrorResponse'
example:
success: false
error:
code: internal_server_error
message: An internal server error occurred
timestamp: 1767225600000
DocumentTypeEnum:
type: string
enum:
- contract
- delivery_proof
- payment_proof
- communication
example: contract
description: >
Kind of supporting document. Only these four values are accepted when
creating a
document. The internal type union also contains `payment_confirmation`,
`subscription_info`, `usage_report` and `cronograma`, but those cannot
be set through
this API.
DocumentLinkEntityTypeEnum:
type: string
enum:
- invoice
- payment
- receipt
- client
example: invoice
description: Kind of gigstack entity a document can be linked to.
DocumentComplianceStatusEnum:
type: string
enum:
- pending_review
- valid
- requires_update
- expired
- rejected
example: pending_review
description: >
Compliance review state. Always `pending_review` when a document is
created; change it
with `PATCH /v2/documents/{id}`.
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
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
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
AuthForbidden:
description: >
Rejected by the authentication layer after the credential was
recognised. The body is a raw
object (`message`, sometimes `details`), **not** the standardized
envelope. Causes:
- The API key was revoked or disabled: `message: "API Key inválida."`,
`details: "Invalid API Key"`.
- The billing account's plan does not include API access. `message` is a
Spanish sentence
containing an HTML link to `https://app.gigstack.pro/memberships`. Branch on the status
code; do not display or match the text.
- gigstack Connect: the plan lacks the `multipleIssuerAccounts` feature
(Spanish message
starting `Tu plan no incluye múltiples cuentas emisoras.`), or an OAuth access token was
sent with a `team` other than its own (`Team mismatch with OAuth token`).
An endpoint may also answer `403` for its own reasons; those are
documented on the
operation when they exist.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthMiddlewareError'
examples:
revoked_api_key:
summary: API key revoked or disabled
value:
message: API Key inválida.
details: Invalid API Key
plan_without_api_access:
summary: Plan does not include API access
value:
message: >-
La API se encuentra disponible para un plan más grande, por
favor actualiza tu plan aquí o ponte
en contacto con soporte.
connect_plan_without_multiple_issuers:
summary: gigstack Connect — plan lacks multipleIssuerAccounts
value:
message: >-
Tu plan no incluye múltiples cuentas emisoras. Actualiza tu
plan en https://app.gigstack.pro/memberships o ponte en
contacto con soporte para operar sobre otros equipos.
oauth_team_mismatch:
summary: gigstack Connect — OAuth token used for another team
value:
message: Team mismatch with OAuth token
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.