Invoices API Guide

Create, manage, and cancel CFDI 4.0 compliant invoices with full SAT integration. The Invoices API handles the complete invoice lifecycle including creation, stamping, cancellation, and payment complements.

📋 Overview

The Invoices API provides comprehensive invoicing capabilities with Mexican tax compliance. Create PUE (single payment) or PPD (partial payments) invoices, manage payment complements, and handle cancellations with SAT.

🔑 Key Features

CFDI 4.0 Compliance - Full SAT specification support

Automatic Stamping - Real-time SAT integration

Payment Complements - PPD invoice management

Cancellation Support - SAT-compliant cancellation process

Global Invoices - Monthly global invoice generation

File Generation - Automatic PDF and XML creation

Automation Options - Flexible workflow automation

📚 Endpoints

List Income Invoices

Retrieve a paginated list of income invoices.

Query Parameters:

limit (integer, 1-100) - Number of results per page (default: 10)

next (string) - Pagination cursor for next page

team (string) - gigstack Connect: Target team ID

Example Request:

Example Response:

{
    "message": "Invoices retrieved successfully",
    "data": [
        {
            "uuid": "invoice_1234567890",
            "client": {
                "id": "client_1234567890",
                "name": "Juan Pérez García",
                "tax_id": "PEGJ800101ABC"
            },
            "folio_number": 123,
            "series": "A",
            "invoice_type": "I",
            "total": 1160.0,
            "subtotal": 1000.0,
            "taxes": 160.0,
            "currency": "MXN",
            "payment_method": "PUE",
            "status": "valid",
            "created_at": 1677651234,
            "stamp": {
                "stamp_at": 1677651234,
                "sello": "ABC123..."
            }
        }
    ],
    "has_more": false,
    "total_results": 1
}

Create Income Invoice

Create a new income invoice with optional automation.

Automation Types:

payment - Create PUE invoice immediately

payment_and_complement - Create PPD invoice and payment complement

none - No automation, create invoice only

Request Body:

{
    "automation_type": "payment",
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "items": [
        {
            "description": "Consulting services",
            "quantity": 2,
            "unit_price": 1000.0,
            "product_key": "80141503",
            "unit_key": "E48",
            "unit_name": "Servicio",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "factor": "Tasa",
                    "withholding": false
                }
            ]
        }
    ],
    "use": "P01",
    "payment_form": "03",
    "payment_method": "PUE",
    "series": "A",
    "folio_number": 123,
    "send_email": true,
    "emails": ["client@example.com"]
}

Example Request with Client Search:

Get Income Invoice

Retrieve a specific income invoice by ID.

Example Request:

Get Invoice Files

Get XML and PDF files for an invoice.

Query Parameters:

file_type (string) - Type of file: "pdf", "xml" (optional, returns both if not specified)

team (string) - gigstack Connect: Target team ID

Example Request:

Example Response:

{
    "message": "Invoice files retrieved successfully",
    "data": {
        "pdf": "https://storage.gigstack.io/invoices/invoice_1234567890.pdf",
        "xml": "https://storage.gigstack.io/invoices/invoice_1234567890.xml"
    }
}

Cancel Invoice

Cancel an invoice with SAT.

Request Body:

{
    "motive": "02",
    "substitution_uuid": "12345678-1234-1234-1234-123456789012"
}

Cancellation Motives:

01 - Comprobante emitido con errores con relación (requires substitution_uuid)

02 - Comprobante emitido con errores sin relación

03 - No se llevó a cabo la operación

04 - Operación nominativa relacionada en una factura global

Example Request:

🏗️ Invoice Structure

Invoice Types

I - Ingreso (Income)

E - Egreso (Expense)

P - Pago (Payment complement)

N - Nómina (Payroll)

Payment Methods

PUE - Pago en Una sola Exhibición (Single payment)

PPD - Pago en Parcialidades o Diferido (Partial or deferred payment)

Payment Forms (Formas de Pago)

Code	Description
01	Efectivo
02	Cheque nominativo
03	Transferencia electrónica de fondos
04	Tarjeta de crédito
28	Tarjeta de débito
99	Por definir

📊 Complex Invoice Examples

Invoice with Multiple Items and Taxes

{
    "automation_type": "payment",
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "items": [
        {
            "description": "Consulting services - Phase 1",
            "quantity": 10,
            "unit_price": 1000.0,
            "product_key": "80141503",
            "unit_key": "HUR",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "withholding": false
                }
            ]
        },
        {
            "description": "Software license",
            "quantity": 1,
            "unit_price": 5000.0,
            "product_key": "81111500",
            "unit_key": "H87",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "withholding": false
                }
            ]
        }
    ],
    "use": "G03",
    "payment_form": "03",
    "payment_method": "PUE"
}

Invoice with Withholding Taxes

{
    "automation_type": "payment",
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "items": [
        {
            "description": "Professional services",
            "quantity": 1,
            "unit_price": 10000.0,
            "product_key": "80141503",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "withholding": false
                },
                {
                    "type": "ISR",
                    "rate": 0.1,
                    "withholding": true
                },
                {
                    "type": "IVA",
                    "rate": 0.106667,
                    "withholding": true
                }
            ]
        }
    ],
    "use": "G03",
    "payment_form": "03",
    "payment_method": "PUE"
}

PPD Invoice (Partial Payments)

{
    "automation_type": "none",
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "items": [
        {
            "description": "Large project - Total amount",
            "quantity": 1,
            "unit_price": 100000.0,
            "product_key": "80141503",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        }
    ],
    "use": "G03",
    "payment_form": "99",
    "payment_method": "PPD"
}

Global Invoice

{
    "automation_type": "none",
    "client": {
        "id": "client_publico_general"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "global": {
        "periodicity": "04",
        "months": "01",
        "year": 2024
    },
    "items": [
        {
            "description": "Ventas del periodo",
            "quantity": 1,
            "unit_price": 50000.0,
            "product_key": "01010101",
            "unit_key": "ACT",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        }
    ],
    "use": "P01",
    "payment_form": "03",
    "payment_method": "PUE"
}

{
    "related_documents": [
        {
            "relationship": "04",
            "documents": ["12345678-1234-1234-1234-123456789012"]
        }
    ]
}

Relationship Types:

01 - Nota de crédito de los documentos relacionados

02 - Nota de débito de los documentos relacionados

03 - Devolución de mercancía sobre facturas o traslados previos

04 - Sustitución de los CFDI previos

07 - CFDI por aplicación de anticipo

🎯 Common Scenarios

1. Simple Sale Invoice

2. Service Invoice with Email

3. USD Invoice with Exchange Rate

💡 Best Practices

Use idempotency keys - Prevent duplicate invoices

Validate clients first - Ensure fiscal data is correct

Configure email settings - Set up BCC for accounting

Use correct payment methods - PUE for immediate, PPD for partial

Include all required taxes - IVA, ISR, IEPS as applicable

Set proper CFDI use - Match client's tax requirements

Keep series organized - Use different series for different invoice types

Clients API - Manage invoice recipients

Services API - Configure invoice items

Payments API - Process invoice payments

Teams API - Configure invoice settings

🚨 Error Handling

Missing Required Fields

{
    "message": "Invalid request body",
    "error": "client is required"
}

Invalid Tax Configuration

{
    "message": "Tax validation failed",
    "error": "IVA rate must be 0.16 for standard rate"
}

Stamping Error

{
    "message": "Failed to stamp invoice",
    "error": "Stamping service unavailable"
}

Cancellation Error

{
    "message": "Cannot cancel invoice",
    "error": "Invoice has dependent payment complements"
}

Need help with invoice management? Check our support documentation or contact support@gigstack.io

📋 Overview#

🔑 Key Features#

📚 Endpoints#

List Income Invoices#

Create Income Invoice#

Get Income Invoice#

Get Invoice Files#

Cancel Invoice#

🏗️ Invoice Structure#

Invoice Types#

Payment Methods#

Payment Forms (Formas de Pago)#

📊 Complex Invoice Examples#

Invoice with Multiple Items and Taxes#

Invoice with Withholding Taxes#

PPD Invoice (Partial Payments)#

Global Invoice#

🔄 Related Documents#

Creating Related Invoices#

🎯 Common Scenarios#

1. Simple Sale Invoice#

2. Service Invoice with Email#

3. USD Invoice with Exchange Rate#

💡 Best Practices#

🔗 Related Resources#

🚨 Error Handling#

Missing Required Fields#

Invalid Tax Configuration#

Stamping Error#

Cancellation Error#

📋 Overview

🔑 Key Features

📚 Endpoints

List Income Invoices

Create Income Invoice

Get Income Invoice

Get Invoice Files

Cancel Invoice

🏗️ Invoice Structure

Invoice Types

Payment Methods

Payment Forms (Formas de Pago)

📊 Complex Invoice Examples

Invoice with Multiple Items and Taxes

Invoice with Withholding Taxes

PPD Invoice (Partial Payments)

Global Invoice

🔄 Related Documents

Creating Related Invoices

🎯 Common Scenarios

1. Simple Sale Invoice

2. Service Invoice with Email

3. USD Invoice with Exchange Rate

💡 Best Practices

🔗 Related Resources

🚨 Error Handling

Missing Required Fields

Invalid Tax Configuration

Stamping Error

Cancellation Error