Teams API Guide

Manage teams, configure settings, and control member access. The Teams API handles team creation, configuration, member management, and system-wide settings for invoicing and payments.

📋 Overview

Teams are organizational units that contain settings, members, and resources. Each team has its own configuration for invoicing, taxes, series, and automation preferences.

🔑 Key Features

Team Management - Create and configure teams

Member Administration - Add/remove team members

Settings Configuration - Invoice, tax, and email settings

Series Management - Configure invoice series and folios

Integration Support - Connect with external services

gigstack Connect - Enable multi-team access

📚 Endpoints

List Teams

Retrieve a paginated list of teams.

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": "Teams retrieved successfully",
    "data": [
        {
            "id": "team_1234567890",
            "name": "My Company",
            "settings": {
                "product_key": "80141503",
                "unit_key": "E48",
                "use": "P01",
                "taxes": [
                    {
                        "type": "IVA",
                        "rate": 0.16
                    }
                ]
            },
            "created_at": 1677651234
        }
    ],
    "has_more": false,
    "total_results": 1
}

Create Team

Create a new team with initial configuration.

Request Body:

{
    "brand": {
        "alias": "My Company",
        "primary_color": "#FF0000",
        "secondary_color": "#00FF00",
        "logo": "https://example.com/logo.png"
    },
    "tax_id": "ABC123456789",
    "tax_system": "601",
    "support_email": "support@company.com",
    "support_phone": "+52 55 1234 5678",
    "generate_onboarding_url": true,
    "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"
    }
}

Body Parameters:

brand (object, optional) - Branding configuration

alias (string, required) - Team display name

primary_color (string, optional) - Primary brand color

secondary_color (string, optional) - Secondary brand color

logo (string, optional) - Logo URL

tax_id (string, optional) - Tax identification number

tax_system (string, optional) - SAT tax system code

support_email (string, optional) - Support contact email

support_phone (string, optional) - Support contact phone

generate_onboarding_url (boolean, optional) - Generate onboarding URL in response

address (object, optional) - Team address information

country (string, required) - Country name

street (string, optional) - Street address

exterior (string, optional) - Exterior number

interior (string, optional) - Interior number

neighborhood (string, optional) - Neighborhood/colony

municipality (string, optional) - Municipality

city (string, optional) - City

state (string, optional) - State/province

zip (string, optional) - Postal code

Example Request:

Get Team

Retrieve a specific team by ID.

Example Request:

Update Team

Update team information. Uses the same schema as Create Team but all fields are optional for updates.

Request Body (same as Create Team, all fields optional):

{
    "brand": {
        "alias": "Tech Solutions International"
    },
    "support_email": "help@techsolutions.com",
    "tax_system": "601"
}

Example Request:

Update Team Settings

Update comprehensive team settings including defaults, taxes, and automation.

Request Body:

{
    "avoid_legal_name_replacer": false,
    "default_description": "Professional services",
    "invoice_pdf_notes": "Thank you for your business",
    "product_key": "80141503",
    "unit_key": "E48",
    "use": "P01",
    "taxes": [
        {
            "type": "IVA",
            "rate": 0.16,
            "factor": "Tasa",
            "withholding": false
        }
    ],
    "taxes_usd": [
        {
            "type": "IVA",
            "rate": 0.0,
            "factor": "Exento"
        }
    ],
    "emails": {
        "invoices_bcc": ["accounting@company.com"],
        "avoid_invoice_emails": false,
        "avoid_test_invoice_emails": true,
        "avoid_receipts_emails": false
    },
    "default_series": {
        "income": {
            "serie": "A",
            "folio_number_live": 1001,
            "folio_number_test": 1
        },
        "complements": {
            "serie": "C",
            "folio_number_live": 1001,
            "folio_number_test": 1
        },
        "credit_note": {
            "serie": "N",
            "folio_number_live": 1001,
            "folio_number_test": 1
        }
    },
    "automate_complement_for_ppd_invoices": true,
    "global_invoice_disabled": false,
    "uses_on_self_invoice_portal": ["P01", "G03", "G01"]
}

Example Request:

Get Team Integrations

Get available integrations for teams.

Example Request:

Add Team Member

Add a member to a team.

Request Body:

{
    "id": "user_9876543210",
    "role": "admin"
}

Body Parameters:

id (string, required) - User ID of the member to add

role (string, optional) - Member role (default: "viewer"). Options: "admin", "member", "viewer"

Note: Body parameters are validated in the handler using withBaseSchema() with inline validation.

Example Request:

Remove Team Member

Remove a member from a team.

Request Body:

{
    "id": "user_9876543210"
}

Body Parameters:

id (string, required) - User ID of the member to remove

Note: Body parameters are validated in the handler using withBaseSchema() with inline validation.

Example Request:

Get Team Series

Get invoice series configuration for a team.

Example Request:

Create Team Series

Create a new invoice series for a team.

Request Body:

{
    "series": "B",
    "live": 1000,
    "test": 1
}

Body Parameters:

series (string, required) - Series identifier (alphanumeric, max 10 characters)

live (number, optional) - Initial folio number for live mode (default: 0)

test (number, optional) - Initial folio number for test mode (default: 0)

Example Request:

Update Team Series

Update an existing team series.

Request Body:

{
    "live": 2000,
    "test": 50
}

Body Parameters:

live (number, optional) - Update folio number for live mode

test (number, optional) - Update folio number for test mode

Note: At least one of live or test must be provided.

Example Request:

Get Team Onboarding URL

Generate a secure onboarding URL for team setup and configuration. This endpoint is only available for gigstack Connect accounts (master teams).

Important: This endpoint is only available for gigstack Connect accounts.

Use Cases:

Generate onboarding links for new teams

Allow secure team configuration setup

Enable embedded team management flows

Parameters:

id (path, required) - Team ID to generate onboarding URL for

Example Request:

Example Response:

{
    "data": "https://embeded.gigstack.pro/?sessionId=otpOnboarding_abc123&c=secure_token",
    "message": "Onboarding URL generated successfully"
}

Error Responses:

401 Unauthorized - Only available for master teams

404 Not Found - Team not found

The generated URL provides secure access to the team onboarding interface with a temporary session and secure code.

🏗️ Team Settings Structure

Core Settings

Setting	Type	Description
`default_description`	string	Default item description
`product_key`	string	Default SAT product key
`unit_key`	string	Default SAT unit key
`use`	string	Default CFDI use code
`invoice_pdf_notes`	string	Notes added to PDF invoices
`override_item_description`	string	Override all item descriptions

Tax Configuration

{
    "taxes": [
        {
            "type": "IVA",
            "rate": 0.16,
            "factor": "Tasa",
            "withholding": false
        }
    ],
    "taxes_usd": [
        {
            "type": "IVA",
            "rate": 0.0,
            "factor": "Exento"
        }
    ],
    "withholding_taxes": [
        {
            "type": "ISR",
            "rate": 0.1,
            "withholding": true
        }
    ]
}

Email Settings

{
    "emails": {
        "invoices_bcc": ["accounting@company.com", "admin@company.com"],
        "avoid_invoice_emails": false,
        "avoid_test_invoice_emails": true,
        "avoid_receipts_emails": false
    }
}

Series Configuration

{
    "default_series": {
        "income": {
            "serie": "A",
            "folio_number_live": 1001,
            "folio_number_test": 1
        },
        "complements": {
            "serie": "C",
            "folio_number_live": 1001,
            "folio_number_test": 1
        },
        "credit_note": {
            "serie": "N",
            "folio_number_live": 1001,
            "folio_number_test": 1
        }
    }
}

🎯 Configuration Examples

Basic Team Setup

Professional Services Configuration

E-commerce Configuration

International Business Configuration

💡 Best Practices

Configure defaults early - Set up team settings before creating invoices

Use appropriate tax settings - Configure taxes based on business type

Set up email BCCs - Ensure accounting gets copies

Manage series carefully - Don't duplicate series across invoice types

Test in staging - Verify settings with test folios first

Enable automations wisely - Understand impact on workflows

Keep member roles updated - Regular access reviews

🔐 Member Roles

Role	Permissions
admin	Full access
member	Create/edit resources
viewer	Read-only access

🔄 Team Workflows

Initial Setup

Member Management

Users API - Manage team members

gigstack Connect - Multi-team access

Invoices API - Uses team settings

Payments API - Uses team configuration

🚨 Error Handling

Team Not Found

{
    "message": "Team not found",
    "error": "The specified team does not exist"
}

Invalid Tax Configuration

{
    "message": "Invalid tax settings",
    "error": "Tax rate must be between 0 and 1"
}

Member Already Exists

{
    "message": "Member already in team",
    "error": "User is already a member of this team"
}

Invalid Series

{
    "message": "Series conflict",
    "error": "Series 'A' already exists for income invoices"
}

Permission Denied

{
    "message": "Insufficient permissions",
    "error": "Admin role required for this action"
}

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

📋 Overview#

🔑 Key Features#

📚 Endpoints#

List Teams#

Create Team#

Get Team#

Update Team#

Update Team Settings#

Get Team Integrations#

Add Team Member#

Remove Team Member#

Get Team Series#

Create Team Series#

Update Team Series#

Get Team Onboarding URL#

🏗️ Team Settings Structure#

Core Settings#

Tax Configuration#

Email Settings#

Series Configuration#

🎯 Configuration Examples#

Basic Team Setup#

Professional Services Configuration#

E-commerce Configuration#

International Business Configuration#

💡 Best Practices#

🔐 Member Roles#

🔄 Team Workflows#

Initial Setup#

Member Management#

🔗 Related Resources#

🚨 Error Handling#

Team Not Found#

Invalid Tax Configuration#

Member Already Exists#

Invalid Series#

Permission Denied#

📋 Overview

🔑 Key Features

📚 Endpoints

List Teams

Create Team

Get Team

Update Team

Update Team Settings

Get Team Integrations

Add Team Member

Remove Team Member

Get Team Series

Create Team Series

Update Team Series

Get Team Onboarding URL

🏗️ Team Settings Structure

Core Settings

Tax Configuration

Email Settings

Series Configuration

🎯 Configuration Examples

Basic Team Setup

Professional Services Configuration

E-commerce Configuration

International Business Configuration

💡 Best Practices

🔐 Member Roles

🔄 Team Workflows

Initial Setup

Member Management

🔗 Related Resources

🚨 Error Handling

Team Not Found

Invalid Tax Configuration

Member Already Exists

Invalid Series

Permission Denied