> ## 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.

# Teams API Guide

> Integration guide for Teams

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 with initial member setup
* **Member Administration** - Add/remove team members, bulk import from master team
* **Settings Configuration** - Invoice, tax, and email settings
* **SAT Connection** - Upload CSD certificates for CFDI invoicing
* **Series Management** - Configure invoice series and folios
* **Integration Support** - Connect with external services
* **gigstack Connect** - Enable multi-team access

## Endpoints

### List Teams

```http theme={null}
GET /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:**

```bash theme={null}
curl -X GET "https://api.gigstack.io/v2/teams?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example Response:**

```json theme={null}
{
    "success": true,
    "message": "Clients retrieved successfully",
    "timestamp": 1768240724433,
    "data": [
        {
            "id": "team_1234567890",
            "legal_name": "Empresa de Tecnología S.A. de C.V.",
            "address": {
                "country": "MEX",
                "street": "Av. Insurgentes Sur 456",
                "zip": "03100",
                "city": "Ciudad de México",
                "state": "CDMX",
                "exterior": "96",
                "interior": "10",
                "neighborhood": "Polanco"
            },
            "brand": {
                "alias": "Mi Empresa",
                "primary_color": "#007bff",
                "secondary_color": "#6c757d",
                "logo": "https://example.com/logo.png"
            },
            "settings": {
                "avoid_automations_on_currencies": ["USD", "EUR"],
                "default_description": "Default invoice description",
                "taxes": [],
                "taxes_usd": [],
                "emails": {
                    "invoices_bcc": ["accounting@example.com"],
                    "avoid_invoice_emails": false,
                    "avoid_test_invoice_emails": true,
                    "avoid_receipts_emails": false
                },
                "override_item_description": "Custom item description",
                "global_invoice_disabled": false,
                "complements": [],
                "uses_on_self_invoice_portal": ["G03", "S01"],
                "invoice_pdf_notes": "Additional notes for PDF",
                "product_key": "81112209",
                "unit_key": "E48",
                "use": "G03",
                "automate_complement_for_ppd_invoices": true,
                "withholding_taxes": [],
                "customer_portal_id": "portal_1234567890",
                "periodicity": {
                    "label": "Mes",
                    "value": "month"
                },
                "default_series": {
                    "income": {
                        "serie": "A"
                    },
                    "complements": {
                        "serie": "P"
                    },
                    "credit_note": {
                        "serie": "NC"
                    }
                }
            },
            "tax_id": "EMP800101ABC",
            "tax_system": "601",
            "support_email": "support@empresa.com",
            "support_phone": "+52 55 1234 5678",
            "owner": "user_1234567890",
            "created_at": 1677651234,
            "credit_limit": 1000,
            "used_credits": 250,
            "credit_period_start": 1677651234000,
            "sat": {
                "completed": true,
                "connected_at": 1677651234,
                "csd_expires_at": 1924991999
            },
            "members": [
                {
                    "id": "user_1234567890",
                    "email": "member@empresa.com",
                    "role": "admin"
                }
            ],
            "integrations": {
                "stripe": {
                    "completed": false,
                    "category": "payments"
                },
                "mercadopago": {
                    "completed": false,
                    "category": "payments"
                },
                "clip": {
                    "completed": false,
                    "category": "payments"
                },
                "whmcs": {
                    "completed": false,
                    "category": "payments"
                },
                "paypal": {
                    "completed": false,
                    "category": "payments"
                },
                "openpay": {
                    "completed": false,
                    "category": "payments"
                },
                "conekta": {
                    "completed": false,
                    "category": "payments"
                },
                "bank": {
                    "completed": false,
                    "category": "payments"
                },
                "shopify": {
                    "completed": false,
                    "category": "payments"
                },
                "zapier": {
                    "completed": false,
                    "category": "payments"
                },
                "airtable": {
                    "completed": false,
                    "category": "payments"
                },
                "google_sheets": {
                    "completed": false,
                    "category": "payments"
                },
                "hilos": {
                    "completed": false,
                    "category": "messaging"
                }
            },
            "metadata": {
                "custom_field": "value"
            }
        }
    ],
    "next": "team_dmU311Ajzj",
    "total_results": 105,
    "has_more": true
}
```

### Create Team

```http theme={null}
POST /teams
```

Create a new team with initial configuration. This operation requires a live key;
it rejects test keys. Creating an issuing team does not configure its certificates
or establish that it can issue fiscal documents.

> Requires the `multipleIssuerAccounts` feature on your plan. Without it this endpoint returns `403`, as does `DELETE /teams/{id}`.

**Request Body:**

```json theme={null}
{
    "legal_name": "Empresa de Tecnología S.A. de C.V.",
    "tax_id": "EMP800101ABC",
    "tax_system": "601",
    "brand": {
        "alias": "My Company",
        "primary_color": "#FF0000",
        "secondary_color": "#00FF00",
        "logo": "https://example.com/logo.png"
    },
    "support_email": "support@company.com",
    "support_phone": "+52 55 1234 5678",
    "generate_onboarding_url": true,
    "address": {
        "country": "MEX",
        "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": {
        "external_id": "erp-1234",
        "segment": "enterprise"
    },
    "add_members": [
        {
            "id": "user123abc",
            "role": "editor"
        },
        {
            "id": "user456def",
            "role": "viewer"
        }
    ],
    "add_master_team_members": false
}
```

**Body Parameters:**

* `legal_name` (string, optional) - Legal name of the team/company
* `tax_id` (string, optional) - Tax identification number (RFC)
* `tax_system` (string, optional) - SAT tax system code (regimen fiscal)
* `brand` (object, optional) - Branding configuration
  * `alias` (string, required within object) - Team display name
  * `primary_color` (string, optional) - Primary brand color
  * `secondary_color` (string, optional) - Secondary brand color
  * `logo` (string, optional) - Logo URL
* `support_email` (string, optional) - Support contact email
* `support_phone` (string, optional) - Support contact phone
* `generate_onboarding_url` (boolean, optional) - When true, includes a secure onboarding URL in the response
* `address` (object, optional) - Team address information
  * `country` (string, required within object) - Country code (e.g., "MEX")
  * `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
* `metadata` (object, optional) - Arbitrary key-value pairs to store with the team
* `add_members` (array, optional) - Array of members to add to the team on creation
  * `id` (string, required) - User ID to add as a team member
  * `role` (string, optional, defaults to "viewer") - Member role. Options: "admin", "editor", "viewer"
* `add_master_team_members` (boolean, optional) - When true, copies all members from the master team to the newly created team with their existing permissions. Only applicable for gigstack Connect accounts

**Example Request (basic team creation):**

```bash theme={null}
curl -X POST https://api.gigstack.io/v2/teams \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Tech Solutions S.A. de C.V.",
    "brand": {
      "alias": "Tech Solutions SA"
    },
    "tax_id": "TSO123456789",
    "tax_system": "601"
  }'
```

**Example Request (with members):**

```bash theme={null}
curl -X POST https://api.gigstack.io/v2/teams \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Tech Solutions S.A. de C.V.",
    "brand": {
      "alias": "Tech Solutions SA"
    },
    "tax_id": "TSO123456789",
    "tax_system": "601",
    "add_members": [
      {
        "id": "user123abc",
        "role": "editor"
      },
      {
        "id": "user456def",
        "role": "viewer"
      }
    ]
  }'
```

**Example Request (with master team members):**

```bash theme={null}
curl -X POST https://api.gigstack.io/v2/teams \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Tech Solutions S.A. de C.V.",
    "brand": {
      "alias": "Tech Solutions SA"
    },
    "tax_id": "TSO123456789",
    "tax_system": "601",
    "add_master_team_members": true
  }'
```

**Example Response (201 Created):**

```json theme={null}
{
    "success": true,
    "message": "Team created successfully",
    "timestamp": 1768240724433,
    "data": {
        "id": "team_1234567890",
        "legal_name": "Tech Solutions S.A. de C.V.",
        "tax_id": "TSO123456789",
        "tax_system": "601",
        "brand": {
            "alias": "Tech Solutions SA",
            "primary_color": null,
            "secondary_color": null,
            "logo": null
        },
        "address": {
            "country": "MEX",
            "street": null,
            "zip": null,
            "city": null,
            "state": null,
            "exterior": null,
            "interior": null,
            "neighborhood": null
        },
        "support_email": null,
        "support_phone": null,
        "owner": "user_owner123",
        "members": [
            {
                "id": "user_owner123",
                "email": "owner@techsolutions.com",
                "role": "admin"
            }
        ],
        "settings": {},
        "sat": {
            "completed": false,
            "connected_at": null,
            "csd_expires_at": null
        },
        "integrations": {
            "stripe": { "completed": false, "category": "payments" },
            "mercadopago": { "completed": false, "category": "payments" }
        },
        "metadata": null,
        "created_at": 1768240724433,
        "onboarding_url": ""
    }
}
```

Note: `onboarding_url` is only populated when `generate_onboarding_url: true` is sent in the request. Otherwise it is an empty string.

### Get Team

```http theme={null}
GET /teams/{id}
```

Retrieve a specific team by ID.

**Example Request:**

```bash theme={null}
curl -X GET https://api.gigstack.io/v2/teams/team_1234567890 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example Response:**

```json theme={null}
{
    "success": true,
    "message": "Team retrieved successfully",
    "timestamp": "2026-01-12T18:00:01.845Z",
    "data": {
        "id": "team_1234567890",
        "legal_name": "Empresa de Tecnología S.A. de C.V.",
        "address": {
            "country": "MEX",
            "street": "Av. Insurgentes Sur 456",
            "zip": "03100",
            "city": "Ciudad de México",
            "state": "CDMX",
            "exterior": "96",
            "interior": "10",
            "neighborhood": "Polanco"
        },
        "brand": {
            "alias": "Mi Empresa",
            "primary_color": "#007bff",
            "secondary_color": "#6c757d",
            "logo": "https://example.com/logo.png"
        },
        "settings": {
            "avoid_automations_on_currencies": ["USD", "EUR"],
            "default_description": "Default invoice description",
            "taxes": [],
            "taxes_usd": [],
            "emails": {
                "invoices_bcc": ["accounting@example.com"],
                "avoid_invoice_emails": false,
                "avoid_test_invoice_emails": true,
                "avoid_receipts_emails": false
            },
            "override_item_description": "Custom item description",
            "global_invoice_disabled": false,
            "complements": [],
            "uses_on_self_invoice_portal": ["G03", "S01"],
            "invoice_pdf_notes": "Additional notes for PDF",
            "product_key": "81112209",
            "unit_key": "E48",
            "use": "G03",
            "automate_complement_for_ppd_invoices": true,
            "withholding_taxes": [],
            "customer_portal_id": "portal_1234567890",
            "periodicity": {
                "label": "Mes",
                "value": "month"
            },
            "default_series": {
                "income": {
                    "serie": "A"
                },
                "complements": {
                    "serie": "P"
                },
                "credit_note": {
                    "serie": "NC"
                }
            }
        },
        "tax_id": "EMP800101ABC",
        "tax_system": "601",
        "support_email": "support@empresa.com",
        "support_phone": "+52 55 1234 5678",
        "owner": "user_1234567890",
        "created_at": 1677651234,
        "sat": {
            "completed": true,
            "connected_at": 1677651234,
            "csd_expires_at": 1924991999
        },
        "members": [
            {
                "id": "user_1234567890",
                "email": "member@empresa.com",
                "role": "admin"
            }
        ],
        "integrations": {
            "stripe": {
                "completed": false,
                "category": "payments"
            },
            "mercadopago": {
                "completed": false,
                "category": "payments"
            },
            "clip": {
                "completed": false,
                "category": "payments"
            },
            "whmcs": {
                "completed": false,
                "category": "payments"
            },
            "paypal": {
                "completed": false,
                "category": "payments"
            },
            "openpay": {
                "completed": false,
                "category": "payments"
            },
            "conekta": {
                "completed": false,
                "category": "payments"
            },
            "bank": {
                "completed": false,
                "category": "payments"
            },
            "shopify": {
                "completed": false,
                "category": "payments"
            },
            "zapier": {
                "completed": false,
                "category": "payments"
            },
            "airtable": {
                "completed": false,
                "category": "payments"
            },
            "google_sheets": {
                "completed": false,
                "category": "payments"
            },
            "hilos": {
                "completed": false,
                "category": "messaging"
            }
        },
        "metadata": {
            "custom_field": "value"
        }
    }
}
```

## Team Response Structure

### Core Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique team identifier |
| `legal_name` | string | Official registered legal name of the company/team |
| `tax_id` | string | Tax identification number (RFC) |
| `tax_system` | string | SAT tax system code |
| `support_email` | string | Team support contact email |
| `support_phone` | string | Team support contact phone |
| `owner` | string | User ID of the team owner |
| `created_at` | number | Unix timestamp of team creation |
| `credit_limit` | number \| null | Maximum documents (credits) the team can create per billing period. Null means no per-team limit. |
| `used_credits` | number | Number of credits used by this team in the current billing period |
| `credit_period_start` | number \| null | Unix timestamp (ms) when the current credit period started |
| `metadata` | object | Custom metadata key-value pairs |

### Address Object

| Field | Type | Description |
| - | - | - |
| `country` | string | Country code (e.g., "MEX") |
| `street` | string | Street address |
| `zip` | string | Postal code |
| `city` | string | City name |
| `state` | string | State or province |
| `exterior` | string | Exterior number |
| `interior` | string | Interior number/apartment |
| `neighborhood` | string | Neighborhood or colony |

### Brand Object

| Field | Type | Description |
| - | - | - |
| `alias` | string | Team display name |
| `primary_color` | string | Primary brand color (hex) |
| `secondary_color` | string | Secondary brand color (hex) |
| `logo` | string | URL to brand logo image |

### Settings Object

The settings object contains comprehensive configuration for team operations:

| Field | Type | Description |
| - | - | - |
| `avoid_automations_on_currencies` | array | List of currency codes to skip automation |
| `default_description` | string | Default invoice item description |
| `taxes` | array | Default tax configuration for MXN |
| `taxes_usd` | array/boolean | Tax configuration for USD transactions |
| `emails` | object | Email notification settings |
| `override_item_description` | string | Override for all item descriptions |
| `global_invoice_disabled` | boolean | Whether global invoicing is disabled |
| `complements` | array | CFDI complements configuration |
| `uses_on_self_invoice_portal` | array | Allowed CFDI uses on self-invoice portal |
| `invoice_pdf_notes` | string | Additional notes for PDF invoices |
| `product_key` | string | Default SAT product key |
| `unit_key` | string | Default SAT unit key |
| `use` | string | Default CFDI use code |
| `automate_complement_for_ppd_invoices` | boolean | Auto-create payment complements for PPD invoices |
| `withholding_taxes` | array | Withholding tax configuration |
| `customer_portal_id` | string | Associated customer portal ID |
| `periodicity` | object | Default billing periodicity |
| `default_series` | object | Default invoice series configuration |

#### Email Settings

| Field | Type | Description |
| - | - | - |
| `invoices_bcc` | array | BCC email addresses for invoices |
| `avoid_invoice_emails` | boolean | Skip invoice email notifications |
| `avoid_test_invoice_emails` | boolean | Skip test invoice emails |
| `avoid_receipts_emails` | boolean | Skip receipt email notifications |

#### Periodicity Object

| Field | Type | Description |
| - | - | - |
| `label` | string | Display label (e.g., "Mes") |
| `value` | string | Value code (e.g., "month") |

#### Default Series Object

| Field | Type | Description |
| - | - | - |
| `income` | object | Income invoice series configuration |
| `complements` | object | Complement invoice series configuration |
| `credit_note` | object | Credit note series configuration |

Each series object contains:

* `serie` (string): Series identifier

### SAT Object

| Field | Type | Description |
| - | - | - |
| `completed` | boolean | Whether SAT configuration is complete |
| `connected_at` | number | Unix timestamp of SAT connection |
| `csd_expires_at` | number | Unix timestamp when CSD certificate expires |

### Members Array

Each member object contains:

| Field | Type | Description |
| - | - | - |
| `id` | string | User ID |
| `email` | string | User email address |
| `role` | string | Member role (admin, editor, viewer) |

### Integrations Object

The integrations object contains status for all available integrations. Each integration has:

| Field | Type | Description |
| - | - | - |
| `completed` | boolean | Whether integration is configured |
| `category` | string | Integration category (payments, messaging) |

**Available Integrations:**

* Payment providers: `stripe`, `mercadopago`, `clip`, `whmcs`, `paypal`, `openpay`, `conekta`, `bank`, `shopify`
* Data integrations: `zapier`, `airtable`, `google_sheets`
* Messaging: `hilos`

### Update Team

```http theme={null}
PUT /teams/{id}
```

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):**

```json theme={null}
{
    "brand": {
        "alias": "Tech Solutions International"
    },
    "support_email": "help@techsolutions.com",
    "tax_system": "601"
}
```

**Example Request:**

```bash theme={null}
curl -X PUT https://api.gigstack.io/v2/teams/team_1234567890 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": {
      "alias": "Tech Solutions International"
    },
    "support_email": "help@techsolutions.com"
  }'
```

### Update Team Settings

```http theme={null}
PUT /teams/{id}/settings
```

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

> ### ⚠️ Here `periodicity` is `two_months` — plural
>
> `PUT /teams/{id}/settings` accepts exactly:
>
> ```
> day | week | two_weeks | month | two_months
> ```
>
> sent as a **plain string**, not an object. Anything else fails validation with `400`.
>
> **The receipts endpoints use `two_month` — singular** (`POST /v2/receipts`, field `periodicity`). The two endpoints genuinely disagree and neither accepts the other's spelling. This is the current state of the API, deliberately left alone because normalizing it would break live integrations. Never copy a periodicity value between the two — look it up. See [Receipts → Periodicity Options](/guides/receipts#periodicity-options).
>
> Note the asymmetry between write and read: you **send** `periodicity` as a string here, but `GET /teams/{id}` returns whatever is stored under the team's `defaults.periodicity`, which for teams configured through the dashboard is a `{ label, value }` object. Read `periodicity.value` defensively.

**Request Body:**

```json theme={null}
{
    "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",
    "periodicity": "month",
    "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:**

```bash theme={null}
curl -X PUT https://api.gigstack.io/v2/teams/team_1234567890/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_description": "Consulting services",
    "product_key": "80141503",
    "unit_key": "E48",
    "taxes": [
      {
        "type": "IVA",
        "rate": 0.16
      }
    ],
    "emails": {
      "invoices_bcc": ["finance@company.com"],
      "avoid_test_invoice_emails": true
    }
  }'
```

### Get Team Integrations

```http theme={null}
GET /teams/integrations
```

> **🚧 Not yet available.** The route is registered and reachable, but the handler is still a stub. Every call returns:
>
> ```http theme={null}
> HTTP/1.1 501 Not Implemented
> ```
>
> ```json theme={null}
> { "message": "Not implemented" }
> ```
>
> Do not build against it. **Use `GET /teams/{id}` instead** — the team response already carries the [Integrations Object](#integrations-object) with a `completed` flag per provider, which is the information this endpoint is eventually meant to serve.
>
> (Historical note: this path used to be unreachable altogether — it was registered after `GET /teams/{id}`, so Express matched `integrations` as a team id and you got a 404 for a team that does not exist. The ordering is fixed; only the handler remains.)

### Add Team Member

```http theme={null}
POST /teams/{id}/add-member
```

Add a member to a team with a specified role.

**Request Body:**

```json theme={null}
{
    "id": "user_9876543210",
    "role": "editor"
}
```

**Body Parameters:**

* `id` (string, required) - User ID of the member to add
* `role` (string, optional) - Member role. If not specified, defaults to "viewer"
  * Options: `"admin"`, `"editor"`, `"viewer"`
  * Default: `"viewer"`

The user must belong to the caller's billing account. For user-scoped credentials,
the caller cannot grant a role above their own. An API key or OAuth token represents
the team; the endpoint still checks team and billing-account access. Use `id`, not
`user_id`, in this body.

**Example Request (with specified role):**

```bash theme={null}
curl -X POST https://api.gigstack.io/v2/teams/team_1234567890/add-member \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user_9876543210",
    "role": "editor"
  }'
```

**Example Request (default role - viewer):**

```bash theme={null}
curl -X POST https://api.gigstack.io/v2/teams/team_1234567890/add-member \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user_9876543210"
  }'
```

### Remove Team Member

```http theme={null}
POST /teams/{id}/remove-member
```

Remove a member from a team.

**Request Body:**

```json theme={null}
{
    "id": "user_9876543210"
}
```

**Body Parameters:**

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

The user must belong to the caller's billing account. For user-scoped credentials,
the caller cannot grant a role above their own. An API key or OAuth token represents
the team; the endpoint still checks team and billing-account access. Use `id`, not
`user_id`, in this body.

**Example Request:**

```bash theme={null}
curl -X POST https://api.gigstack.io/v2/teams/team_1234567890/remove-member \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user_9876543210"
  }'
```

### Get Team Series

```http theme={null}
GET /teams/{id}/series
```

Get invoice series configuration for a team.

**Example Request:**

```bash theme={null}
curl -X GET https://api.gigstack.io/v2/teams/team_1234567890/series \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Create Team Series

```http theme={null}
POST /teams/{id}/series
```

Create a new invoice series for a team.

**Request Body:**

```json theme={null}
{
    "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:**

```bash theme={null}
curl -X POST https://api.gigstack.io/v2/teams/team_1234567890/series \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "series": "B",
    "live": 1000,
    "test": 1
  }'
```

### Update Team Series

```http theme={null}
PUT /teams/{id}/series/{seriesId}
```

Update an existing team series.

**Request Body:**

```json theme={null}
{
    "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:**

```bash theme={null}
curl -X PUT https://api.gigstack.io/v2/teams/team_1234567890/series/B \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "live": 2000
  }'
```

### Get Team Onboarding URL

```http theme={null}
GET /teams/{id}/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:**

```bash theme={null}
curl -X GET https://api.gigstack.io/v2/teams/team_1234567890/onboarding-url \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example Response:**

```json theme={null}
{
    "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.

### Upload SAT CSD Certificates

```http theme={null}
POST /teams/{id}/sat-connection
```

Upload SAT CSD (Certificado de Sello Digital) certificates to establish SAT connection for CFDI invoicing. This endpoint accepts multipart form data with the certificate files and password.

**Required Files:**

* **cert**: Certificate file (.cer) - The public certificate
* **key**: Private key file (.key) - The encrypted private key
* **keyPass**: Password for the private key

**First-Time Connection:**
When this is the first SAT connection for a team (no previous SAT setup), the system will automatically initialize default invoice series (G, NC, P, T).

**gigstack Connect:** Upload SAT certificates for other teams using the `team` query parameter.

**Parameters:**

* `id` (path, required) - Team ID to upload SAT certificates for
* `team` (query, optional) - Target team ID for gigstack Connect

**Request Body (multipart/form-data):**

* `cert` (binary, required) - Certificate file (.cer)
* `key` (binary, required) - Private key file (.key)
* `keyPass` (string, required) - Password for the private key

**Example Request:**

```bash theme={null}
curl -X POST https://api.gigstack.io/v2/teams/team_1234567890/sat-connection \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "cert=@certificate.cer" \
  -F "key=@private_key.key" \
  -F "keyPass=your_certificate_password"
```

**Example Response:**

```json theme={null}
{
    "message": "SAT connection established successfully",
    "data": {
        "isValid": true,
        "details": {
            "serialNumber": "30001000000500003416",
            "validTo": 1735689600000
        }
    }
}
```

**Response Fields:**

* `isValid` (boolean) - Whether the certificate is valid
* `details.serialNumber` (string) - Certificate serial number
* `details.validTo` (number) - Unix timestamp in milliseconds when certificate expires

**Error Responses:**

**400 - Bad Request:**

```json theme={null}
{
    "message": "Invalid certificate",
    "error": "Missing required files or invalid certificate format"
}
```

**401 - Unauthorized:**

```json theme={null}
{
    "message": "Unauthorized",
    "error": "Invalid or missing authentication token"
}
```

**403 - Forbidden:**

```json theme={null}
{
    "message": "Access denied",
    "error": "Team not in same billing account"
}
```

### Sign Manifest Document

```http theme={null}
POST /teams/{id}/manifest/sign
```

Sign a manifest document (Carta Manifiesto) using the FIEL (Firma Electronica Avanzada) for SAT compliance. This endpoint is used to sign the authorization manifest that authorizes the PAC (Proveedor Autorizado de Certificacion) to issue CFDI invoices on behalf of your team's RFC.

The manifest must be signed to grant the PAC permission to stamp and process invoices under your team's tax identification. Once signed, the manifest is stored in your team's SAT configuration and includes both XML and PDF files.

**Important Requirements:**

* Your SAT configuration must be completed before signing the manifest
* The FIEL certificate must be valid and issued by SAT
* The certificate must match your team's RFC
* The team ID is specified in the URL path parameter

**Supported Formats:**

This endpoint accepts two content types:

1. **JSON format (application/json):** Send Base64 encoded certificate files
2. **Form Data format (multipart/form-data):** Upload certificate files directly

**Parameters:**

* `id` (path, required) - Team ID to sign manifest for

**Request Body (JSON):**

```json theme={null}
{
    "key": "MIIFDjBABgkqhkiG9w0BBQ0wMz...",
    "cert": "MIIFuzCCA6OgAwIBAgIUMzAwMD...",
    "password": "my_secure_password"
}
```

**Request Body (Form Data):**

* `key` (file) - FIEL .key file upload
* `cert` (file) - FIEL .cer file upload
* `password` (string) - FIEL password (private key password)

**Example Request (JSON):**

```bash theme={null}
curl -X POST https://api.gigstack.io/v2/teams/team_1234567890/manifest/sign \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "MIIFDjBABgkqhkiG9w0BBQ0wMz...",
    "cert": "MIIFuzCCA6OgAwIBAgIUMzAwMD...",
    "password": "my_secure_password"
  }'
```

**Example Request (Form Data):**

```bash theme={null}
curl -X POST https://api.gigstack.io/v2/teams/team_1234567890/manifest/sign \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "key=@/path/to/fiel.key" \
  -F "cert=@/path/to/fiel.cer" \
  -F "password=my_secure_password"
```

**Example Response:**

```json theme={null}
{
    "message": "Manifest signed successfully",
    "data": {
        "xmlBase64": "PD94bWwgdmVyc2lvbj0iMS4wIi...",
        "pdfBase64": "JVBERi0xLjQKJeLjz9MKMyAwIG...",
        "fechaFirma": "2024-01-08T15:30:00.000Z",
        "mensajeResultado": "Firma exitosa"
    }
}
```

**Response Fields:**

* `xmlBase64` (string) - Base64 encoded signed manifest XML
* `pdfBase64` (string) - Base64 encoded manifest PDF
* `fechaFirma` (string) - Signature date and time in ISO 8601 format
* `mensajeResultado` (string) - Result message from signing service

**Error Responses:**

| Status | Error | Description |
| - | - | - |
| 400 | key (Base64 encoded .key file) is required | Missing required key field |
| 400 | cert (Base64 encoded .cert file) is required | Missing required cert field |
| 400 | password is required | Missing required password field |
| 400 | Certificado FIEL invalido | Invalid FIEL certificate |
| 400 | El RFC del certificado no coincide con el RFC del equipo | Certificate RFC does not match team RFC |
| 400 | SAT configuration is incomplete | SAT setup must be completed before signing manifests |
| 400 | Manifest signing failed: \[error message] | Signing service rejected the request |
| 401 | Unauthorized | Invalid or missing authentication token |
| 404 | Team not found | Team does not exist |

## 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 |
| `periodicity` | object | Default billing/invoicing period with label and value |
| `invoice_pdf_notes` | string | Notes added to PDF invoices |
| `override_item_description` | string | Override all item descriptions |
| `avoid_automations_on_currencies` | array | List of currency codes to skip automation |
| `global_invoice_disabled` | boolean | Whether global invoicing is disabled |
| `automate_complement_for_ppd_invoices` | boolean | Auto-create payment complements for PPD invoices |
| `customer_portal_id` | string | Associated customer portal ID |
| `uses_on_self_invoice_portal` | array | Allowed CFDI uses on self-invoice portal |
| `complements` | array | CFDI complements configuration |
| `default_series` | object | Default invoice series for income, complements, and credit notes |

### Tax Configuration

```json theme={null}
{
    "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

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

### Series Configuration

```json theme={null}
{
    "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

```bash theme={null}
curl -X PUT https://api.gigstack.io/v2/teams/team_1234567890/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_key": "80141503",
    "unit_key": "E48",
    "use": "P01",
    "taxes": [
      {
        "type": "IVA",
        "rate": 0.16
      }
    ]
  }'
```

### Professional Services Configuration

```bash theme={null}
curl -X PUT https://api.gigstack.io/v2/teams/team_1234567890/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_description": "Professional consulting services",
    "product_key": "80141503",
    "unit_key": "HUR",
    "taxes": [
      {
        "type": "IVA",
        "rate": 0.16,
        "withholding": false
      },
      {
        "type": "ISR",
        "rate": 0.10,
        "withholding": true
      },
      {
        "type": "IVA",
        "rate": 0.106667,
        "withholding": true
      }
    ],
    "automate_complement_for_ppd_invoices": true
  }'
```

### E-commerce Configuration

```bash theme={null}
curl -X PUT https://api.gigstack.io/v2/teams/team_1234567890/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_description": "Online purchase",
    "product_key": "01010101",
    "unit_key": "H87",
    "taxes": [
      {
        "type": "IVA",
        "rate": 0.16
      }
    ],
    "uses_on_self_invoice_portal": ["G01", "G03"],
    "emails": {
      "invoices_bcc": ["ventas@tienda.com"],
      "avoid_test_invoice_emails": true
    }
  }'
```

### International Business Configuration

```bash theme={null}
curl -X PUT https://api.gigstack.io/v2/teams/team_1234567890/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "taxes": [
      {
        "type": "IVA",
        "rate": 0.16
      }
    ],
    "taxes_usd": [
      {
        "type": "IVA",
        "rate": 0.00,
        "factor": "Exento"
      }
    ],
    "complements": [
      {
        "type": "export",
        "enabled": true
      }
    ]
  }'
```

## Best Practices

1. **Configure defaults early** - Set up team settings before creating invoices
2. **Use appropriate tax settings** - Configure taxes based on business type
3. **Set up email BCCs** - Ensure accounting gets copies
4. **Manage series carefully** - Don't duplicate series across invoice types
5. **Test in staging** - Verify settings with test folios first
6. **Enable automations wisely** - Understand impact on workflows
7. **Keep member roles updated** - Regular access reviews

## Member Roles

| Role | Permissions |
| - | - |
| **admin** | Full access |
| **editor** | Create/edit resources |
| **viewer** | Read-only access |

## Team Workflows

### Initial Setup

```mermaid theme={null}
graph LR
    A[Create Team] --> B[Configure Settings]
    B --> C[Add Members]
    C --> D[Set Up Series]
    D --> E[Configure Integrations]
```

### Member Management

```mermaid theme={null}
graph LR
    A[Invite User] --> B[Assign Role]
    B --> C[User Accepts]
    C --> D[Access Granted]
```

## Related Resources

* [Users API](/guides/users) - Manage team members
* [gigstack Connect](/guides/gigstack-connect) - Multi-team access
* [Invoices API](/guides/invoices) - Uses team settings
* [Payments API](/guides/payments) - Uses team configuration

## Error Handling

### Team Not Found

```json theme={null}
{
    "message": "Team not found",
    "error": "The specified team does not exist"
}
```

### Invalid Tax Configuration

```json theme={null}
{
    "message": "Invalid tax settings",
    "error": "Tax rate must be between 0 and 1"
}
```

### Member Already Exists

```json theme={null}
{
    "message": "Member already in team",
    "error": "User is already a member of this team"
}
```

### Invalid Series

```json theme={null}
{
    "message": "Series conflict",
    "error": "Series 'A' already exists for income invoices"
}
```

### Permission Denied

```json theme={null}
{
    "message": "Insufficient permissions",
    "error": "Admin role required for this action"
}
```

***

For additional assistance, contact [support@gigstack.io](mailto:support@gigstack.io)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.