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

# Connect with the SAT password (CIEC)

> Connect Descarga Masiva SAT with the team's SAT password (CIEC) instead of the e.firma (FIEL). The RFC is always the team's own.

gigstack logs into the SAT once to verify the password. Only a verified password is stored (encrypted); a rejected one leaves nothing behind. The password is never returned.

- `200` with `status: verified`: the SAT accepted the password and the first batch of invoices starts.
- `202` with `status: verifying`: the SAT is slow to answer. Poll `GET /invoices/download/ciec` until the status changes.

Every XML downloaded through the CIEC is billed like any Descarga Masiva download. Requires live mode and Descarga Masiva activated (`POST /invoices/download/activate`). A team may start up to 5 connection attempts per day.




## OpenAPI

````yaml openapi.json POST /invoices/download/ciec
openapi: 3.0.3
info:
  title: gigstack API v2
  description: >
    # gigstack API v2


    Build customer, invoice and payment integrations. Start with the
    [quickstart](https://docs.gigstack.io/quickstart), then select the [issuing
    country](https://docs.gigstack.io/concepts/shared-fields).


    ## Authentication and environments


    Use Authorization: Bearer YOUR_API_KEY. Standard live and test keys use
    https://api.gigstack.io/v2. Internal staging uses
    https://gigstack-staging-9z9nnaat.uc.gateway.dev/v2 and separate keys. Test
    mode is a data mode within an environment; a body field does not switch a
    key's mode.


    See [authentication](https://docs.gigstack.io/authentication) for key
    handling, OAuth team scope and gigstack Connect. Internal partner
    provisioning is outside this public contract; health probes have their own
    security declarations. Operations marked unavailable have no configured
    public gateway route.


    ## Read the operation contract


    Response envelopes, pagination and retry rules differ by endpoint. HTTP
    success alone does not prove external fiscal completion or movement of
    money. Reconcile ambiguous writes before retrying. Use [responses and
    recovery](https://docs.gigstack.io/responses) and the operation's error
    codes; document credits and daily limits are not generic retryable rate
    limits.


    The issuing team's configuration selects Mexico or Colombia; customer
    country and currency do not. Read
    [Mexico](https://docs.gigstack.io/countries/mexico) or
    [Colombia](https://docs.gigstack.io/countries/colombia) before choosing
    fiscal fields. Accepted public input differs from a provider's direct
    payload.


    Examples and schema checks do not imply every operation has been executed
    live. [Verification coverage](https://docs.gigstack.io/verification)
    distinguishes source review, offline checks and observed staging behavior.
    Documentation describes operations and does not authorize execution.
  version: 2.0.0
  contact:
    name: Gigstack API Support
    url: https://gigstack.io
    email: support@gigstack.io
  license:
    name: Proprietary
    url: https://gigstack.io/terms
  termsOfService: https://gigstack.io/terms
servers:
  - url: https://api.gigstack.io/v2
    description: >
      Public API for standard live and test-mode keys. Test data is isolated by
      the key mode

      (`livemode: false`). Internal staging is a separate deployment and key
      store; see

      https://docs.gigstack.io/authentication#environments for its base URL.
security:
  - bearerAuth: []
externalDocs:
  description: Complete API Documentation & Guides
  url: https://docs.gigstack.io
paths:
  /invoices/download/ciec:
    post:
      tags:
        - Descarga Masiva SAT
      summary: Connect with the SAT password (CIEC)
      description: >
        Connect Descarga Masiva SAT with the team's SAT password (CIEC) instead
        of the e.firma (FIEL). The RFC is always the team's own.


        gigstack logs into the SAT once to verify the password. Only a verified
        password is stored (encrypted); a rejected one leaves nothing behind.
        The password is never returned.


        - `200` with `status: verified`: the SAT accepted the password and the
        first batch of invoices starts.

        - `202` with `status: verifying`: the SAT is slow to answer. Poll `GET
        /invoices/download/ciec` until the status changes.


        Every XML downloaded through the CIEC is billed like any Descarga Masiva
        download. Requires live mode and Descarga Masiva activated (`POST
        /invoices/download/activate`). A team may start up to 5 connection
        attempts per day.
      operationId: createInvoicesDownloadCiec
      parameters:
        - $ref: '#/components/parameters/TeamParameter'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - password
              properties:
                password:
                  type: string
                  maxLength: 256
                  description: SAT password (CIEC), the one used to log into the SAT portal
                sync_period:
                  type: string
                  enum:
                    - year
                    - max
                  description: >-
                    Where the first sync starts: year (January 1 of this year)
                    or max (65 months back, the default)
                  example: max
      responses:
        '200':
          description: The SAT accepted the password
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiecConnectResponse'
              example:
                success: true
                message: >-
                  Listo: el SAT aceptó tu contraseña. Empezamos a traer tus
                  facturas.
                data:
                  status: verified
                  rfc: XAXX010101000
                  verified_at: 1763164800000
                  rejected_at: null
        '202':
          description: Verification still running; poll GET /invoices/download/ciec
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiecConnectResponse'
              example:
                success: true
                message: >-
                  Estamos verificando tu contraseña con el SAT. Esto puede
                  tardar unos minutos.
                data:
                  status: verifying
                  rfc: XAXX010101000
                  verified_at: null
                  rejected_at: null
        '400':
          description: >-
            Rejected password, invalid input or test mode (`ciec_rejected`,
            `password_required`, `rfc_invalid`, `livemode_required`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiecErrorResponse'
              example:
                success: false
                message: >-
                  El SAT no aceptó tu contraseña. Revisa que sea la misma con la
                  que entras al portal del SAT.
                error: ciec_rejected
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Descarga Masiva not activated (`billing_not_activated`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiecErrorResponse'
        '409':
          description: A verification is already running (`ciec_verification_in_progress`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiecErrorResponse'
        '429':
          description: Too many connection attempts today (`too_many_attempts`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiecErrorResponse'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          description: >-
            The SAT could not confirm the password right now
            (`ciec_inconclusive`, `sat_service_unavailable`); retry later
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiecErrorResponse'
      security:
        - bearerAuth: []
components:
  parameters:
    TeamParameter:
      name: team
      in: query
      required: false
      schema:
        type: string
      description: >
        **gigstack Connect:** Target team ID for multi-team access.


        Requires gigstack Connect enabled on your team and shared billing
        account.


        Also requires the `multipleIssuerAccounts` feature on your plan.
        Requests targeting a

        team other than the one your API key belongs to return `403` without it.


        Only API keys can use it: an OAuth access token sent with another team's
        id is rejected with

        `403 Team mismatch with OAuth token`.


        **Optional — omit it entirely** unless you are acting on another team.
        It deliberately

        carries no example value so generated snippets do not emit
        `?team=undefined`; when the

        parameter is absent, the team is derived from your API key.


        **Example:** `?team=team_xyz789`
  schemas:
    CiecConnectResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          $ref: '#/components/schemas/CiecConnection'
    CiecErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        error:
          type: string
          enum:
            - ciec_rejected
            - ciec_inconclusive
            - sat_service_unavailable
            - livemode_required
            - billing_not_activated
            - rfc_invalid
            - password_required
            - password_too_long
            - ciec_verification_in_progress
            - too_many_attempts
        retryable:
          type: boolean
    CiecConnection:
      type: object
      properties:
        status:
          type: string
          enum:
            - none
            - verifying
            - verified
            - rejected
        rfc:
          type: string
          nullable: true
        verified_at:
          type: number
          nullable: true
          description: Epoch milliseconds
        rejected_at:
          type: number
          nullable: true
          description: Epoch milliseconds
    AuthMiddlewareError:
      type: object
      description: >
        Raw error body produced by the authentication layer (before any endpoint
        runs). It is not

        the standardized envelope: there is no `success` and no `timestamp`.
      required:
        - message
      properties:
        message:
          type: string
          description: >-
            Human-readable reason. Some messages are in Spanish; branch on the
            HTTP status, not on this text.
          example: Unauthorized
        error:
          type: string
          description: >-
            OAuth error code. Present only when an OAuth access token was
            presented.
          enum:
            - invalid_token
            - token_expired
            - token_revoked
            - server_error
          example: token_expired
        error_description:
          type: string
          description: Same text as `message`. Present only alongside `error`.
          example: Access token has expired. Please refresh your token.
        details:
          description: >-
            Extra detail, e.g. `Invalid API Key` when a revoked key is rejected
            with `403`.
          oneOf:
            - type: string
            - type: object
          example: Invalid API Key
    UnauthorizedError:
      allOf:
        - $ref: '#/components/schemas/StandardErrorResponse'
      example:
        success: false
        error:
          code: unauthorized
          message: Unauthorized access
        timestamp: 1767225600000
    StandardErrorResponse:
      type: object
      description: >
        Standardized error envelope emitted by `sendErrorResponse` and its
        helpers

        (`sendValidationError`, `sendNotFoundError`, `sendUnauthorizedError`,

        `sendForbiddenError`, `sendConflictError`, `sendBadRequestError`,

        `sendInternalServerError`).
      required:
        - success
        - error
        - timestamp
      properties:
        success:
          type: boolean
          enum:
            - false
          example: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: >
                Stable machine-readable code. Values emitted by the shared
                helpers:

                `unauthorized`, `forbidden`, `invalid_token`,
                `validation_failed`,

                `invalid_request_body`, `missing_required_field`,
                `invalid_field_value`,

                `resource_not_found`, `resource_already_exists`,
                `resource_conflict`,

                `business_rule_violation`, `operation_not_allowed`,

                `insufficient_permissions`, `external_service_error`,

                `payment_processor_error`, `cfdi_service_error`,

                `internal_server_error`, `service_unavailable`,
                `rate_limit_exceeded`,

                `database_error`, `data_integrity_error`, `file_not_found`,

                `file_upload_error`, `invalid_file_format`. Individual handlers
                may

                emit additional endpoint-specific codes, documented per
                operation.
              example: validation_failed
            message:
              type: string
              example: Request validation failed
            details:
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
                - type: object
              description: >
                Present only when the handler supplies detail. Validation
                failures

                emit an array of `"<field path>: <message>"` strings. An object
                only

                where an operation documents its keys: account billing answers
                `409`

                `billing_operation_pending` with `{ "operation_id": "<id>" }`,
                the

                operation holding the account lock, to reconcile

                (`POST /teams/{id}/billing/operations/{operationId}/reconcile`).
              example:
                - 'currency: Field is required'
        timestamp:
          type: integer
          format: int64
          description: Server time in epoch milliseconds.
          example: 1767225600000
  responses:
    Unauthorized:
      description: >
        Authentication failed. Two different bodies can come back with a `401`:


        1. **From the authentication layer**, before the endpoint runs: a raw
        object with
           `message` and — for OAuth access tokens only — `error` / `error_description`. It does
           **not** use the standardized envelope (`success` and `timestamp` are absent). Messages:
           `Unauthorized` (missing header, missing `Bearer ` prefix, unparseable token),
           `Unauthorized, missing team in token`, `Unauthorized, not a master team` and
           `Unauthorized, no matched teams` (gigstack Connect), `Invalid access token`,
           `Access token has expired. Please refresh your token.`, `Access token has been revoked`.
        2. **From the endpoint itself**: the standardized envelope with
        `error.code: unauthorized`.


        Branch on the HTTP status, not on the body shape.
      content:
        application/json:
          schema:
            anyOf:
              - $ref: '#/components/schemas/AuthMiddlewareError'
              - $ref: '#/components/schemas/UnauthorizedError'
          examples:
            missing_or_invalid_key:
              summary: Authentication layer — missing or unparseable API key
              value:
                message: Unauthorized
            oauth_token_expired:
              summary: Authentication layer — expired OAuth access token
              value:
                message: Access token has expired. Please refresh your token.
                error: token_expired
                error_description: Access token has expired. Please refresh your token.
            connect_not_master_team:
              summary: >-
                Authentication layer — `team` sent by a team without gigstack
                Connect
              value:
                message: Unauthorized, not a master team
            endpoint_envelope:
              summary: Endpoint — standardized envelope
              value:
                success: false
                error:
                  code: unauthorized
                  message: Unauthorized access
                timestamp: 1767225600000
    ServerError:
      description: >-
        Unexpected server error (`error.code: internal_server_error`). The
        failure is logged on gigstack's side.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StandardErrorResponse'
          example:
            success: false
            error:
              code: internal_server_error
              message: An internal server error occurred
            timestamp: 1767225600000
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        **Authentication Method:** HTTP Bearer token.


        The runtime requires the literal `Bearer ` prefix — a bare token in the

        `Authorization` header is rejected with `401 unauthorized`.


        **Header Format:** `Authorization: Bearer YOUR_API_KEY`


        Your API key is a JWT. Live keys operate on live data (`livemode:
        true`);

        test keys operate on isolated test data (`livemode: false`).


        **Get your key at:**
        [app.gigstack.pro/settings?tab=api](https://app.gigstack.pro/settings?tab=api)


        **Errors:** credential failures are answered by the authentication layer
        with a raw

        `{ "message": … }` body, not the standardized envelope — `401` for a
        missing, malformed or

        expired token, `403` for a revoked key or a plan without API access. See
        the `Unauthorized`

        and `AuthForbidden` responses.

````

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