Teams API Guide - gigstack

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

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:

curl -X GET "https://api.gigstack.io/v2/teams?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response:

{
    "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

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:

{
    "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):

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

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

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

{
    "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

GET /teams/{id}

Retrieve a specific team by ID. Example Request:

curl -X GET https://api.gigstack.io/v2/teams/team_1234567890 \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response:

{
    "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

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

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

Example Request:

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

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

{
    "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:

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

GET /teams/integrations

🚧 Not yet available. The route is registered and reachable, but the handler is still a stub. Every call returns:
HTTP/1.1 501 Not Implemented
&#123; "message": "Not implemented" &#125;
Do not build against it. Use GET /teams/{id} instead — the team response already carries the 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

POST /teams/{id}/add-member

Add a member to a team with a specified role. Request Body:

{
    "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):

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

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

POST /teams/{id}/remove-member

Remove a member from a team. Request Body:

{
    "id": "user_9876543210"
}

Body Parameters:

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

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

GET /teams/{id}/series

Get invoice series configuration for a team. Example Request:

curl -X GET https://api.gigstack.io/v2/teams/team_1234567890/series \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Team Series

POST /teams/{id}/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:

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

PUT /teams/{id}/series/{seriesId}

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:

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

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:

curl -X GET https://api.gigstack.io/v2/teams/team_1234567890/onboarding-url \
  -H "Authorization: Bearer YOUR_TOKEN"

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.

Upload SAT CSD Certificates

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:

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:

{
    "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:

{
    "message": "Invalid certificate",
    "error": "Missing required files or invalid certificate format"
}

401 - Unauthorized:

{
    "message": "Unauthorized",
    "error": "Invalid or missing authentication token"
}

403 - Forbidden:

{
    "message": "Access denied",
    "error": "Team not in same billing account"
}

Sign Manifest Document

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:

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

Parameters:

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

Request Body (JSON):

{
    "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):

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

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:

{
    "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

{
    "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

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

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

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

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

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
editor	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"
}

For additional assistance, contact support@gigstack.io

​Overview

​Key Features

​Endpoints

​List Teams

​Create Team

​Get Team

​Team Response Structure

​Core Fields

​Address Object

​Brand Object

​Settings Object

​Email Settings

​Periodicity Object

​Default Series Object

​SAT Object

​Members Array

​Integrations Object

​Update Team

​Update Team Settings

​⚠️ Here periodicity is two_months — plural

​Get Team Integrations

​Add Team Member

​Remove Team Member

​Get Team Series

​Create Team Series

​Update Team Series

​Get Team Onboarding URL

​Upload SAT CSD Certificates

​Sign Manifest Document

​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

Team Response Structure

Core Fields

Address Object

Brand Object

Settings Object

Email Settings

Periodicity Object

Default Series Object

SAT Object

Members Array

Integrations Object

Update Team

Update Team Settings

⚠️ Here `periodicity` is `two_months` — plural

Get Team Integrations

Add Team Member

Remove Team Member

Get Team Series

Create Team Series

Update Team Series

Get Team Onboarding URL

Upload SAT CSD Certificates

Sign Manifest Document

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