Secure fiscal uploads

An agent can create a session and inspect its outcome. The account owner supplies certificates, private keys and passwords directly in the authenticated browser page.

curl --fail-with-body -X POST \
  "$GIGSTACK_API_URL/teams/$TEAM_ID/fiscal-upload-sessions" \
  -H "Authorization: Bearer $GIGSTACK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"purpose":"csd"}'

Use a personal MCP token or Firebase user credential belonging to the current team owner. Team API keys cannot create this session. Expect HTTP 201, data.status: "pending", and an upload_url. Open that URL and sign in as the same owner. The URL identifies the session; it does not grant access. The browser displays the team, fiscal identity, purpose, expiry, and provider environment. It requires explicit consent before submission. Keep files and passwords in that page; do not paste them into agent messages or tool arguments.

Choose the purpose

Purpose	What the owner supplies	Effect
`csd`	CSD certificate, private key and password	Replaces the team’s certificate configuration used for invoicing.
`fiel`	FIEL certificate, private key and password; optional phone	Stores bulk-download credentials. Providing a phone requests provider registration.
`pfx`	PFX/P12 file and password; phone if the team has no valid support phone	Stores bulk-download credentials and requests registration.
`manifest`	FIEL certificate, private key and password	Signs the exact consent text shown in the session; does not enroll bulk download.

Fiscal configuration is shared across live and test credentials. Read effect_scope: "team_shared" and provider_environment. FIEL/PFX calls currently reach the production provider even in staging. Creating a session is not an upload, registration or signature. A test credential alone does not make those later effects sandbox operations. Manifest consent is frozen at creation, with a content hash. The browser displays that text and submits its version. If the fiscal identity changes, create a new session with the current identity.

Inspect the result

curl --fail-with-body \
  "$GIGSTACK_API_URL/teams/$TEAM_ID/fiscal-upload-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $GIGSTACK_TOKEN"

Read data.status, data.result and data.error. An HTTP 200 alone does not establish completion.

Status	Next step
`pending`	Owner can submit before the fifteen-minute expiry, or cancel.
`processing`	Wait and read again. Never automatically upload the files again.
`completed`	Inspect the safe fiscal result for the requested purpose.
`failed`	Upload was rejected before fiscal processing; review the files and consent before creating a new session.
`outcome_unknown`	The operation may have had effects. Reconcile before considering another upload.
`cancelled` / `expired`	The session cannot be submitted. Existing fiscal configuration is unchanged by cancellation or expiry.

GET /teams/{id}/fiscal-status returns safe stored certificate, registration and manifest metadata. Credentials stored with sat_download.registered: false are not fully registered for downloads. This read does not contact a provider or finalize a manifest.

Recover from a lost response

Use POST /teams/{id}/fiscal-upload-sessions/{sessionId}/reconcile with {}. It checks locally persisted evidence tied to the exact session and upload attempt. It does not replay files or make a provider call. Missing evidence leaves the outcome unknown. After ten minutes, an uncertain upload can be reviewed in the browser by the current owner. Explicit acknowledgment releases its team lock for a separate, reviewed upload. The original outcome stays unknown and retains a resolution record. Releasing the lock does not undo, retry, or declare success. A new owner can discover blocking_session_id through fiscal status and recover a previous owner’s session. Only the original creator, while still the current owner, can submit that session. After ownership transfer, use a new session for a new upload. DELETE /teams/{id}/fiscal-upload-sessions/{sessionId} cancels a pending session. Once processing starts, cancellation returns 409 operation_started; it cannot promise rollback. See the session reference and reconciliation reference for exact contracts.

Start here

Fields by country

Shared examples

Mexico · CFDI examples

Build and troubleshoot

Invoicing

Customers and payments

Mexico · SAT

Accounts

Mexico · SAT catalogs

Secure fiscal uploads

Choose the purpose

Inspect the result

Recover from a lost response

​Choose the purpose

​Inspect the result

​Recover from a lost response

Choose the purpose

Inspect the result

Recover from a lost response