Frihet Gestoria API
The Gestoria API from Frihet — 1 operation(s) for gestoria.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/frihet-io:frihet-io-gestoria-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Frihet Gestoria API
version: '2026-03-18'
description: 'The Frihet REST API provides programmatic access to your business data
in Frihet, the AI-native business management platform for modern businesses. ## Authentication
All API requests require an API key passed via the `X-API-Key` header. Generate keys from **Settings > API Keys** in the Frihet app. ```
X-API-Key: fri_your_api_key_here
```
### API-key scopes
A key without scopes (no list, or an empty one) is unrestricted. A key with a
non-empty scope list gets only what the list grants. On such a key, every
request other than `GET` and `HEAD` needs the `write` scope (or `*`), except
the read-only `POST /v1/gestoria/aging` and the POS and purchase-order routes,
which check their own `pos:` and `purchase-orders:` scopes. E-invoicing endpoints need an `einvoice:` scope,
and the sends (`einvoice/export`, `face/submit`, `ticketbai/submit`) also need
`write` or `einvoice:write`. A request without the scope it needs gets
`403 Forbidden` with a `detail` naming that scope. The refusal happens before
the idempotency gate, so it does not reserve the `Idempotency-Key`. `GET /v1/permissions/me` reports `denied.write`, `denied.einvoice` and
`denied.einvoiceSend` for the calling key. Inventory (`/v1/inventory/*`) and purchase-order (`/v1/purchase-orders/*`) routes are
not released yet: after the scope checks they answer `503` with code
`INVENTORY_AUTHORITY_NOT_RELEASED`, before the idempotency gate. ## Rate Limiting
The API enforces a rate limit of **100 requests per minute** per API key. When exceeded, the API returns `429 Too Many Requests` with an integer
delta-seconds `Retry-After` header and matching `retryAfter` JSON field. Every authenticated response includes rate limit headers:
| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests per window (100) |
| `X-RateLimit-Remaining` | Remaining requests in current window |
| `X-RateLimit-Reset` | Unix timestamp (seconds) when the window resets |
| `Retry-After` | Integer seconds until the window resets (429 responses) |
## Idempotency
Most POST requests accept an `Idempotency-Key` header to prevent duplicate
resource creation from network retries. For protected routes, the key is
reserved against the operation *before* the request is executed, and it stays
reserved for 24 hours unless released by an explicit pre-write refusal. ```
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```
Keys must be at most 64 characters. We recommend UUID v4. A retry of the same operation gets one of three answers:
| Situation | Response |
|---|---|
| The first request finished | The **original status and body**, verbatim, with `X-Idempotent-Replayed: true` |
| The first request is still running, or its outcome could not be recorded | `409 IDEMPOTENCY_REQUEST_IN_PROGRESS` |
| The key is live but was used for a **different** operation | `409 IDEMPOTENCY_KEY_REUSED` — the second operation is not executed |
The replayed status is the **stored** one. A `201` replays as `201`, not `200`. This includes stored error responses: a request that answered `4xx` or `5xx`
replays that same status and body, it does not re-execute — except explicit
pre-mutation refusals on `POST /v1/pos/cash-sessions/{id}/close` (`503` when
the workspace POS money-authority grant is not enabled and `403 POS_INACTIVE`
before the POS app is activated), which release the reservation instead of
caching the refusal for 24 hours. ### When a retry is refused
A `409 IDEMPOTENCY_REQUEST_IN_PROGRESS` after the first request already
returned means the outcome could not be recorded — the response was too large
or unserializable, or the bookkeeping write failed. The API refuses rather than
execute a second time, because for a fiscal document a duplicate is not
recoverable. **Reconcile; do not simply retry with a fresh key.** Read the resource back
(`GET` the collection, or look for the document the operation would have
created) and decide from its actual state.'
contact:
name: Frihet API Support
url: https://docs.frihet.io/desarrolladores/api-rest
email: api@frihet.io
license:
name: MIT
url: https://opensource.org/licenses/MIT
x-logo:
url: https://frihet.io/logos/frihet-logo.svg
servers:
- url: https://api.frihet.io
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Gestoria
paths:
/v1/gestoria/aging:
post:
operationId: gestoriaAgingConsolidated
summary: Consolidated AR aging across client workspaces
description: 'For an accountant/gestor, returns accounts-receivable aging consolidated across the given client workspaces. Each workspaceId is authorised per-workspace: the caller must be an active accountant or owner member of that workspace, otherwise it is silently rejected and listed in rejectedWorkspaceIds (no data returned for it). This current-state report deliberately ignores Idempotency-Key and re-checks membership on every request; an old completed marker is never replayed. Amounts are never summed across currencies: `currencySummaries` (per workspace and consolidated) carries one entry per invoice currency with an open balance and is authoritative. The single-number fields (`buckets`, `grandTotal`, `totalOverdue`, `topDebtors`, `currency`, and the `consolidated*` totals) are filled only when exactly one currency is present, and are null when open balances span more than one currency. With no open balance they are zero/empty and `currency` is null. A non-empty `failedWorkspaceIds` means the report is partial: those workspaces could not be checked or computed (e.g. a transient error), no data is returned for them and every total excludes them.'
tags:
- Gestoria
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- workspaceIds
properties:
workspaceIds:
type: array
items:
type: string
minItems: 1
maxItems: 200
description: Client workspace UIDs the caller manages.
asOf:
type: string
format: date
description: Reference date (YYYY-MM-DD). Defaults to today.
bustCache:
type: boolean
description: Honoured only by the callable CF; REST always computes fresh.
responses:
'200':
description: Consolidated aging report
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
workspaces:
type: array
items:
type: object
properties:
workspaceId:
type: string
ownerName:
type: string
currencySummaries:
type: array
description: One entry per currency with an open balance, sorted by currency code.
items:
type: object
properties:
currency:
type: string
buckets:
type: object
properties:
current:
type: number
days1_30:
type: number
days31_60:
type: number
days61_90:
type: number
days90plus:
type: number
grandTotal:
type: number
totalOverdue:
type: number
topDebtors:
type: array
description: Top debtors ranked within this currency only.
items:
type: object
properties:
clientId:
type: string
clientName:
type: string
currency:
type: string
totalOutstanding:
type: number
daysOldestInvoice:
type: number
invoiceCount:
type: number
buckets:
type:
- object
- 'null'
description: Null when open balances span more than one currency.
properties:
current:
type: number
days1_30:
type: number
days31_60:
type: number
days61_90:
type: number
days90plus:
type: number
grandTotal:
type:
- number
- 'null'
description: Null when open balances span more than one currency.
totalOverdue:
type:
- number
- 'null'
description: Null when open balances span more than one currency.
asOf:
type: string
currency:
type:
- string
- 'null'
description: The single currency of the open balances; null when there are none or several.
topDebtors:
type:
- array
- 'null'
description: Null when open balances span more than one currency.
items:
type: object
properties:
clientId:
type: string
clientName:
type: string
currency:
type: string
totalOutstanding:
type: number
daysOldestInvoice:
type: number
invoiceCount:
type: number
rejectedWorkspaceIds:
type: array
items:
type: string
description: Workspaces the caller is not an authorised member of.
failedWorkspaceIds:
type: array
items:
type: string
description: 'Requested workspaces whose membership check or aging computation failed in this request. No data is returned for them and all totals exclude them; a non-empty list means the report is partial.
'
currencySummaries:
type: array
description: Per-currency totals across authorised workspaces, sorted by currency code.
items:
type: object
properties:
currency:
type: string
buckets:
type: object
properties:
current:
type: number
days1_30:
type: number
days31_60:
type: number
days61_90:
type: number
days90plus:
type: number
grandTotal:
type: number
totalOverdue:
type: number
consolidatedBuckets:
type:
- object
- 'null'
description: Null when the authorised workspaces span more than one currency.
properties:
current:
type: number
days1_30:
type: number
days31_60:
type: number
days61_90:
type: number
days90plus:
type: number
consolidatedTotal:
type:
- number
- 'null'
description: Null when the authorised workspaces span more than one currency.
consolidatedOverdue:
type:
- number
- 'null'
description: Null when the authorised workspaces span more than one currency.
asOf:
type: string
generatedAt:
type: string
format: date-time
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
components:
responses:
BadRequest:
description: Bad request - invalid parameters or request body
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Validation error
details:
- code: invalid_type
message: Required
path:
- clientName
meta:
requestId: 550e8400-e29b-41d4-a716-446655440000
Unauthorized:
description: Authentication required or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Invalid or expired API key
meta:
requestId: 550e8400-e29b-41d4-a716-446655440000
schemas:
Error:
type: object
required:
- error
properties:
error:
type: string
description: Human-readable error message
code:
type: string
description: Optional machine-readable code, including MISSING_FISCAL_INFO, AEAT_QR_UNAVAILABLE (422) and AEAT_RECORD_IRREPRODUCIBLE (409) on invoice PDF.
message:
type: string
description: Optional explanatory message accompanying the error code.
details:
type: array
description: Validation error details (Zod issues). Only present on 400 validation errors.
items:
type: object
properties:
code:
type: string
message:
type: string
path:
type: array
items:
type: string
meta:
type: object
properties:
requestId:
type: string
description: Unique request identifier for tracing
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: 'API key for authentication. Keys start with `fri_` prefix.
Generate keys from Settings > API Keys in the Frihet app.
'