Clients API Guide

Manage clients with fiscal information for Mexican tax compliance. The Clients API handles customer data, RFC validation, EFOS checking, and SAT compliance requirements.

📋 Overview

Clients are the foundation of your invoicing system. Each client contains fiscal information required for Mexican tax compliance, including RFC (tax ID), tax system, and address information.

🔑 Key Features

RFC Validation - Automatic tax ID validation against SAT

EFOS Checking - Blacklist validation for compliance

Address Management - Mexican address structure support

Metadata Support - Custom fields for additional data

Auto-creation - Create clients during invoice/payment flow

📚 Endpoints

List Clients

Retrieve a paginated list of clients with filtering and search capabilities.

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": "Clients retrieved successfully",
    "data": [
        {
            "id": "client_1234567890",
            "name": "Juan Pérez García",
            "company": "Empresa SA de CV",
            "email": "juan.perez@ejemplo.com",
            "tax_id": "PEGJ800101ABC",
            "tax_system": "601",
            "livemode": true,
            "created_at": 1677651234,
            "efos": {
                "is_valid": true
            }
        }
    ],
    "has_more": false,
    "total_results": 1
}

Create Client

Create a new client with fiscal information.

Request Body:

{
    "name": "Juan Pérez García",
    "company": "Empresa SA de CV",
    "email": "juan.perez@ejemplo.com",
    "phone": "+52 55 1234 5678",
    "tax_id": "PEGJ800101ABC",
    "tax_system": "601",
    "use": "P01",
    "legal_name": "Juan Pérez García",
    "address": {
        "country": "Mexico",
        "street": "Av. Insurgentes Sur",
        "exterior": "123",
        "interior": "4B",
        "neighborhood": "Del Valle",
        "municipality": "Benito Juárez",
        "city": "Ciudad de México",
        "state": "CDMX",
        "zip": "03100"
    },
    "metadata": {
        "custom_field": "value"
    }
}

Example Request:

Get Client

Retrieve a specific client by ID.

Example Request:

Update Client

Update an existing client's information.

Example Request:

Delete Client

Delete a specific client.

Example Request:

Validate Client

Validate client's fiscal information against SAT.

Example Request:

Stamp Pending Receipts

Stamp all pending receipts for a client.

Example Request:

Customer Portal Access

Get access token for client customer portal.

🏗️ Client Structure

Required Fields

None - All fields are optional for maximum flexibility

Important Fields

tax_id (string) - RFC for Mexican tax compliance

tax_system (string) - SAT tax system code (e.g., "601", "612")

use (string) - Default CFDI use code (e.g., "P01", "G03")

email (string) - Email for invoice delivery

Tax System Codes

Common SAT tax system codes:

601 - General de Ley Personas Morales

612 - Persona Física con Actividades Empresariales

621 - Incorporación Fiscal

622 - Actividades Agrícolas, Ganaderas, Silvícolas y Pesqueras

623 - Opcional para Grupos de Sociedades

624 - Coordinados

625 - Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas

626 - Régimen Simplificado de Confianza

CFDI Use Codes

Common CFDI use codes:

P01 - Por definir

G01 - Adquisición de mercancías

G02 - Devoluciones, descuentos o bonificaciones

G03 - Gastos en general

I01 - Construcciones

I02 - Mobiliario y equipo de oficina por inversiones

I03 - Equipo de transporte

I04 - Equipo de computo y accesorios

I05 - Dados, troqueles, moldes, matrices y herramental

I06 - Comunicaciones telefónicas

I07 - Comunicaciones satelitales

I08 - Otra maquinaria y equipo

🔍 Search and Auto-Creation

When creating invoices or payments, you can search for existing clients or auto-create them:

{
    "client": {
        "search": {
            "on_key": "tax_id",
            "on_value": "PEGJ800101ABC",
            "auto_create": true
        },
        "name": "Juan Pérez García",
        "email": "juan.perez@ejemplo.com",
        "tax_id": "PEGJ800101ABC",
        "tax_system": "601"
    }
}

🛡️ Validation and Compliance

RFC Validation

Automatic format validation

SAT registry verification

EFOS Checking

Blacklist validation against SAT's EFOS list

Automatic status updates

Compliance reporting

Address Validation

Mexican postal code verification

Address completeness checking

💡 Best Practices

Always include tax_id for Mexican clients

Set appropriate tax_system based on client type

Use metadata for custom business logic

Validate clients before important transactions

Keep addresses updated for compliance

Use search functionality to avoid duplicates

Invoices API - Create invoices for clients

Payments API - Process payments from clients

Teams API - Manage team settings that affect clients

🚨 Error Handling

Common error scenarios:

Invalid RFC Format

{
    "message": "Invalid tax_id format",
    "error": "RFC must be 12 or 13 characters"
}

Client Not Found

{
    "message": "Client not found",
    "error": "The specified client does not exist"
}

EFOS Validation Failed

{
    "message": "Client failed EFOS validation",
    "error": "Client is on SAT blacklist"
}

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

Clients API Guide

Clients API Guide#

📋 Overview#

🔑 Key Features#

📚 Endpoints#

List Clients#

Create Client#

Get Client#

Update Client#

Delete Client#

Validate Client#

Stamp Pending Receipts#

Customer Portal Access#

🏗️ Client Structure#

Required Fields#

Important Fields#

Tax System Codes#

CFDI Use Codes#

🔍 Search and Auto-Creation#

🛡️ Validation and Compliance#

RFC Validation#

EFOS Checking#

Address Validation#

💡 Best Practices#

🔗 Related Resources#

🚨 Error Handling#

Invalid RFC Format#

Client Not Found#

EFOS Validation Failed#

Clients API Guide

📋 Overview

🔑 Key Features

📚 Endpoints

List Clients

Create Client

Get Client

Update Client

Delete Client

Validate Client

Stamp Pending Receipts

Customer Portal Access

🏗️ Client Structure

Required Fields

Important Fields

Tax System Codes

CFDI Use Codes

🔍 Search and Auto-Creation

🛡️ Validation and Compliance

RFC Validation

EFOS Checking

Address Validation

💡 Best Practices

🔗 Related Resources

🚨 Error Handling

Invalid RFC Format

Client Not Found

EFOS Validation Failed