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

# Secure fiscal uploads

> Integration guide for 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.

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

```bash theme={null}
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](/reference/createFiscalUploadSession) and [reconciliation reference](/reference/reconcileFiscalUploadSession) for exact contracts.


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