> ## 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 income invoice
> [Small working example](/recipes/paid-later)
**Integration note:** This endpoint stamps immediately. For a reviewable document, create a draft first. Successful issuance returns HTTP 200 and data.uuid. Fiscal validity does not establish that payment has been received. 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 income invoice with CFDI 4.0 compliance.
**Safe retries with `idempotency_key`.** Send your own identifier for the invoice (for example your
order id) in `idempotency_key`. gigstack claims the key before charging a credit or stamping, so
repeating the request cannot issue a second CFDI or charge twice:
- The invoice already exists: `400` with `message.duplicate: true` and `message.uuid`.
- Another request with the key is still being processed: `409` `idempotency_in_progress`. Retry later.
- The PAC's answer was lost: `503` `PAC_OUTCOME_UNKNOWN` with `retryable: true`. Retry with the same
key: the same XML and folio are sent again, so the PAC stamps it once or returns the stamp it already made.
- The PAC can't confirm an earlier attempt: `409` `STAMP_NEEDS_REVIEW`. Don't retry; contact support.
- The SAT or PAC rejected the data: `400`, and the key is free again for a corrected request.
Without an `idempotency_key` none of this applies, and after a `503` `PAC_OUTCOME_UNKNOWN`
(`retryable: false`) you can't tell whether the invoice exists: look it up before sending it again.
To issue many invoices at once, use `POST /invoices/income/batch`.
**gigstack Connect:** Create invoices for other teams using the `team` parameter.
## OpenAPI
````yaml openapi.json POST /invoices/income
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/income:
post:
tags:
- Invoices
summary: Create income invoice
description: >
[Small working example](/recipes/paid-later)
**Integration note:** This endpoint stamps immediately. For a reviewable
document, create a draft first. Successful issuance returns HTTP 200 and
data.uuid. Fiscal validity does not establish that payment has been
received. 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 income invoice with CFDI 4.0 compliance.
**Safe retries with `idempotency_key`.** Send your own identifier for
the invoice (for example your
order id) in `idempotency_key`. gigstack claims the key before charging
a credit or stamping, so
repeating the request cannot issue a second CFDI or charge twice:
- The invoice already exists: `400` with `message.duplicate: true` and
`message.uuid`.
- Another request with the key is still being processed: `409`
`idempotency_in_progress`. Retry later.
- The PAC's answer was lost: `503` `PAC_OUTCOME_UNKNOWN` with
`retryable: true`. Retry with the same
key: the same XML and folio are sent again, so the PAC stamps it once or returns the stamp it already made.
- The PAC can't confirm an earlier attempt: `409` `STAMP_NEEDS_REVIEW`.
Don't retry; contact support.
- The SAT or PAC rejected the data: `400`, and the key is free again for
a corrected request.
Without an `idempotency_key` none of this applies, and after a `503`
`PAC_OUTCOME_UNKNOWN`
(`retryable: false`) you can't tell whether the invoice exists: look it
up before sending it again.
To issue many invoices at once, use `POST /invoices/income/batch`.
**gigstack Connect:** Create invoices for other teams using the `team`
parameter.
operationId: createInvoicesIncome
parameters:
- $ref: '#/components/parameters/TeamParameter'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceIncomeInput'
example:
automation_type: payment
currency: MXN
use: G03
payment_form: '03'
payment_method: PUE
client:
id: client_1234567890
items:
- description: Professional consulting services
sku: CONS-001
product_key: '80141503'
unit_key: ACT
unit_name: Actividad
unit_price: 1500
taxability: '02'
taxes:
- type: IVA
rate: 0.16
factor: Tasa
withholding: false
inclusive: false
quantity: 1
send_email: true
emails:
- cliente@empresa.com
metadata:
project_id: PROJ-2024-001
department: consulting
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: Juan Pérez García
email: juan.perez@ejemplo.com
tax_id: PEGJ800101ABC
from: api
livemode: true
owner: user_1234567890
team: team_1234567890
created_at: 1767225600000
status: valid
currency: MXN
exchange_rate: 1
total: 1160
subtotal: 1000
taxes: 160
discount: 0
series: A
folio_number: 123
invoice_type: I
payment_method: PUE
items:
- id: item_1234567890
description: Professional consulting services
quantity: 1
unit_price: 1000
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 } }`.
A rejection frees the `idempotency_key`: a corrected request may reuse it.
- **Duplicate `idempotency_key`.** An invoice already exists under
the key. Same CFDI shape,
`code: INVALID_INVOICE`, plus `duplicate: true` and the existing invoice's `uuid`. Nothing was
stamped or charged. Treat it as success and read the invoice with `GET /invoices/income/{id}`.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/LegacyErrorResponse'
- type: object
properties:
message:
$ref: '#/components/schemas/CfdiErrorResponse'
examples:
invalid_body:
summary: Body validation
value:
message: Invalid body
errors:
- path: client_id
code: unexpected_key
message: Unexpected field
sat_rejection:
summary: The SAT rejected the document's data
value:
message:
error: >-
Error al timbrar la factura: CFDI40147 - El campo
UsoCFDI no es válido [pcs_8f2a1c]
code: CFDI40147
providerMessage: CFDI40147 - El campo UsoCFDI no es válido
retryable: false
duplicate_idempotency_key:
summary: An invoice already exists under this idempotency_key
value:
message:
error: >-
Error al timbrar la factura: Ya existe un comprobante
con la misma idempotencia (uuid:
0f8fad5b-d9cb-469f-a165-70867728950e)
code: INVALID_INVOICE
providerMessage: >-
Ya existe un comprobante con la misma idempotencia
(uuid: 0f8fad5b-d9cb-469f-a165-70867728950e)
retryable: false
duplicate: true
uuid: 0f8fad5b-d9cb-469f-a165-70867728950e
'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: >
Three cases, all raw bodies:
- **Client or service lock.** A concurrent create holds the lock for
the same client or service
(`search` + `auto_create`). `{ "message": "Resource resolution failed", "error": … }`. Retry
after about a second.
- **`idempotency_in_progress`.** Another request with the same
`idempotency_key` is being
processed (`IdempotencyInProgressResponse`, `retryable: true`). Retry later with the same key;
you get the invoice's outcome (a `400` duplicate once it exists). A request that died mid-way
holds the key for up to 10 minutes.
- **`STAMP_NEEDS_REVIEW`.** An earlier attempt with this
`idempotency_key` reached the PAC, and
the PAC could not confirm whether it stamped (no UUID returned, or the SAT's 72-hour window
has passed), or it stamped and the invoice could not be saved. CFDI shape under `message`,
`retryable: false`. Retrying could issue a second CFDI, so every retry gets this answer.
Contact support with the key.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/LegacyErrorResponse'
- $ref: '#/components/schemas/IdempotencyInProgressResponse'
- type: object
required:
- message
properties:
message:
$ref: '#/components/schemas/CfdiErrorResponse'
examples:
client_lock:
summary: Concurrent create of the same client
value:
message: Resource resolution failed
error: >-
Client creation in progress for tax_id=EKU9003173C9.
Please retry.
idempotency_in_progress:
summary: Same idempotency_key, still being processed
value:
message: >-
An invoice with this idempotency_key is already being
created
error:
code: idempotency_in_progress
message: >-
An invoice with this idempotency_key is already being
created; retry later
retryable: true
stamp_needs_review:
summary: The PAC could not confirm an earlier attempt
value:
message:
error: >-
El PAC indica que el comprobante A-1284 ya fue timbrado
pero no devolvió su UUID: Comprobante timbrado
previamente [pcs_3b7e9d]
code: STAMP_NEEDS_REVIEW
retryable: false
'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
'429':
description: >
**Team credit limit reached.** Raw shape carrying the limit and
current usage.
No document is created.
content:
application/json:
schema:
$ref: '#/components/schemas/CreditLimitResponse'
example:
message: Team credit limit reached
error: Credit limit of 100 documents reached for this billing period
credit_limit: 100
used_credits: 100
'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": … } }`.
A `Failed to save invoice` after a stamp means the CFDI exists: with
an `idempotency_key`, a retry
answers `409` `STAMP_NEEDS_REVIEW` instead of stamping again.
content:
application/json:
schema:
$ref: '#/components/schemas/LegacyErrorResponse'
'503':
description: >
The stamp did not complete. CFDI error shape nested under `message`.
Read `code`:
- **`PAC_UNAVAILABLE`** (`retryable: true`). The PAC could not be
reached, or refused the request
before stamping (HTTP 4xx such as 429, maintenance). The document never reached the SAT and no
CFDI exists. Wait a few minutes and retry.
- **`PAC_OUTCOME_UNKNOWN`**. The request reached the PAC and its
answer was lost (timeout, reset,
HTTP 5xx, unreadable body), so the CFDI **may exist**. Its folio is never reused.
- With an `idempotency_key`, `retryable: true`: retry with the **same** key. The same XML and
folio are sent again, so the PAC either stamps it now or returns the stamp it already made; it
cannot stamp twice, and the retry is not charged again. Any other failure after the XML was
sent is also answered this way.
- Without one, `retryable: false`: a new request would take a new folio and could issue a second
CFDI. Check whether the invoice exists before sending it again.
Timeouts and HTTP 5xx from the PAC used to be answered as
`PAC_UNAVAILABLE`; they are now
`PAC_OUTCOME_UNKNOWN`.
content:
application/json:
schema:
type: object
properties:
message:
$ref: '#/components/schemas/CfdiErrorResponse'
examples:
pac_unavailable:
summary: PAC unreachable; nothing was stamped
value:
message:
error: >-
El servicio de timbrado no está disponible en este
momento. Vuelve a intentarlo en unos minutos. No se pudo
contactar al PAC (Prodigia): connect ECONNREFUSED
[pcs_1a2b3c]
code: PAC_UNAVAILABLE
retryable: true
pac_outcome_unknown:
summary: PAC answer lost; retry with the same idempotency_key
value:
message:
error: >-
No se recibió la respuesta del servicio de timbrado; el
comprobante podría estar timbrado. Se perdió la
respuesta del PAC (Prodigia): The operation was aborted
due to timeout [pcs_4d5e6f]
code: PAC_OUTCOME_UNKNOWN
retryable: true
pac_outcome_unknown_no_key:
summary: PAC answer lost on a request without idempotency_key
value:
message:
error: >-
No se recibió la respuesta del servicio de timbrado; el
comprobante podría estar timbrado. El PAC (Prodigia)
respondió 504 Gateway Timeout [pcs_7a8b9c]
code: PAC_OUTCOME_UNKNOWN
retryable: false
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:
InvoiceIncomeInput:
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
- payment_method
properties:
date:
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:
type: string
example: A
idempotency_key:
description: >
Your identifier for this invoice, for example your order id. With
it, sending the same request
again cannot issue a second CFDI or charge a second credit:
- Once the invoice exists, the same key answers `400` with
`duplicate: true` and the existing `uuid`.
- While another request with the key is being processed, it answers
`409` `idempotency_in_progress`.
- After a `503` `PAC_OUTCOME_UNKNOWN`, a retry with the key resends
the exact same XML and folio, so
the PAC either stamps it once or reports the stamp it already made.
- A definitive rejection (for example the SAT refusing the data)
frees the key, so you can fix the
body and send it again under the same key.
Scoped to your team and the credential's mode. Required on every
item of `POST /invoices/income/batch`.
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: ...
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: ...
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: |
Optional. Invoice automation type:
- `payment`: Create invoice with payment automation
- `none`: No automation, create invoice only
example: payment
type: string
enum:
- payment
- none
global:
type: object
additionalProperties: false
required:
- periodicity
- months
- year
properties:
periodicity:
example: '04'
type: string
months:
example: '01'
type: string
year:
example: 2024
type: integer
nullable: true
items:
type: array
items:
$ref: '#/components/schemas/ItemSchema'
payment_form:
example: '03'
type: string
enum:
- '01'
- '02'
- '03'
- '04'
- '05'
- '06'
- '08'
- '12'
- '13'
- '14'
- '15'
- '17'
- '23'
- '24'
- '25'
- '26'
- '27'
- '28'
- '29'
- '30'
- '31'
- '99'
payment_method:
example: 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
IdempotencyInProgressResponse:
type: object
description: >
Raw `409` body of `POST /invoices/income` when another request with the
same `idempotency_key` is being
processed. Not the standardized envelope. Retry later with the same key.
required:
- message
- error
- retryable
properties:
message:
type: string
example: An invoice with this idempotency_key is already being created
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- idempotency_in_progress
example: idempotency_in_progress
message:
type: string
example: >-
An invoice with this idempotency_key is already being created;
retry later
retryable:
type: boolean
enum:
- true
example: true
CreditLimitResponse:
type: object
description: >
Raw credit-limit body (HTTP 429) returned by invoice income creation and
draft
stamping. Not the standardized envelope.
required:
- message
- error
properties:
message:
type: string
example: Team credit limit reached
error:
type: string
description: Reason reported by the credit checker.
example: Credit limit of 100 documents reached for this billing period
credit_limit:
type: number
example: 100
used_credits:
type: number
example: 100
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.