Frihet Inventory API

openapi: 3.2.0
info:
  title: Frihet Inventory 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: Inventory
paths:
  /v1/inventory/balances:
    get:
      operationId: listInventoryBalances
      summary: List inventory balances (on-hand, valuation, currency, coverage)
      description: 'Returns one row per `physical`/`trackStock` product of the workspace.

        Each row carries the legacy `stockQuantity`, the ledger atoms at the

        receiving location (`warehouse/main/stock/sellable`), and the moving-

        average valuation snapshot when one exists. Items without a valuation

        document are returned with `valuation: null`; an opening-run applies

        the moving-average write to those items.


        A restricted API key needs `inventory:read` or `inventory:*`; a key

        with no scope list is unrestricted by the legacy-key convention.'
      tags:
      - Inventory
      security:
      - ApiKeyAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: Balances for the workspace.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InventoryBalance'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/InventoryAuthorityNotReleased'
  /v1/inventory/conservation-report:
    get:
      operationId: getInventoryConservationReport
      summary: Conservation report (Σ = 0, valuation drift, uncovered outbound)
      description: 'Read-only report over `users/{uid}/inventoryBalances` and

        `users/{uid}/inventoryValuation`. ADR 0027 D1.3 / D4 / S4a-2:

        Σ over every bucket of an item is 0; an item''s on-hand equals the

        valuation''s `valuedAtoms + unvaluedAtoms`; the valuation document

        passes the strict reader; and uncovered outbounds are reported.


        The runner is the only writer of the underlying reports

        (conservation reports are read-only at the kernel level); this

        endpoint exposes the same view the conservation runner would issue.'
      tags:
      - Inventory
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Conservation report findings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      workspaceUid:
                        type: string
                      itemCount:
                        type: integer
                      findings:
                        type: array
                        items:
                          $ref: '#/components/schemas/InventoryConservationFinding'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/InventoryAuthorityNotReleased'
  /v1/inventory/opening-run:
    post:
      operationId: runInventoryOpeningRun
      summary: Apply the opening run on the workspace (ADR 0027 D5 / S4a-2)
      description: 'Walks every `physical`/`trackStock` product of the workspace, reads

        the receiving-bucket balance, and posts the per-item valuation

        delta (`stockQuantity − ledgerAtomsAtReceiving`) as a priced,

        unpriced, shortfall, or no-op outcome. Opening NEVER invents a

        price: items without a usable `costPrice` book as UNVALUED atoms.


        The run is owner-only on the callable transport (`enforceAppCheck`

        + workspace-owner-or-admin predicate inside the transaction). On

        the API transport, restricted keys need `inventory:write` or

        `inventory:*`. A legacy unrestricted key can call it.


        The audit document is written at

        `users/{uid}/inventoryOpeningRuns/{runId}` (deny-all on the

        client path) with the run''s priced/unpriced/shortfall/no-op

        counts and the total opening value in minor units.'
      tags:
      - Inventory
      security:
      - ApiKeyAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                workspaceUid:
                  type: string
                  description: Optional. The run always targets the workspace the API key belongs to; if present, the value must equal that workspace, otherwise the request is refused with 403 FORBIDDEN.
      responses:
        '200':
          description: Opening-run outcome.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/InventoryOpeningRunOutcome'
                  auditCollection:
                    type: string
                    description: Firestore collection where the audit document is written.
                    example: inventoryOpeningRuns
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: A pre-existing valued item uses a different currency; the run refuses to overwrite it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/InventoryAuthorityNotReleased'
components:
  schemas:
    InventoryOpeningRunOutcome:
      type: object
      description: 'The opening-run outcome. `runId` is content-addressed over

        `(workspaceUid, sorted items, sorted ledger receipts)` so two runs on

        the same workspace and same data hash to the same id (the second is a

        no-op).

        '
      properties:
        runId:
          type: string
        currency:
          type: string
          nullable: true
        pricedItemCount:
          type: integer
        unpricedItemCount:
          type: integer
        shortfallItemCount:
          type: integer
        noOpItemCount:
          type: integer
        totalOpeningValueMinor:
          type: string
        pricedItemIds:
          type: array
          items:
            type: string
        unpricedItemIds:
          type: array
          items:
            type: string
        shortfallItemIds:
          type: array
          items:
            type: string
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        actorUid:
          type: string
    InventoryBalance:
      type: object
      description: 'One balance row from `GET /v1/inventory/balances`. The legacy

        `stockQuantity` is the user-supplied product stock; `ledgerAtoms`

        is the projection at the receiving location; `valuation` is the

        moving-average snapshot (null until an opening run writes it).

        '
      properties:
        itemId:
          type: string
        locationId:
          type: string
          example: warehouse/main/stock/sellable
        legacyStockQuantity:
          type: integer
          description: Stored on `products.stockQuantity`, NOT scaled.
        ledgerAtoms:
          type: string
          description: Hex-fixed-point integer at scale 6 (read with BigInt).
        valuation:
          nullable: true
          type: object
          properties:
            currency:
              type: string
              nullable: true
            valueMinor:
              type: string
            valuedAtoms:
              type: string
            unvaluedAtoms:
              type: string
            uncoveredAtoms:
              type: string
    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
    InventoryConservationFinding:
      type: object
      description: 'One finding from `GET /v1/inventory/conservation-report`. The

        `kind` discriminator narrows the payload (see ADR 0027 D1.3 / D4).

        '
      properties:
        kind:
          type: string
          enum:
          - BALANCE_INVALID
          - CONSERVATION_BROKEN
          - VALUATION_INVALID
          - VALUATION_ATOMS_DRIFT
          - VALUATION_UNCOVERED_OUTBOUND
  responses:
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Insufficient permissions
            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
    InventoryAuthorityNotReleased:
      description: The inventory authority is not released yet. Every `/v1/inventory/*` and `/v1/purchase-orders/*` route answers 503 with code `INVENTORY_AUTHORITY_NOT_RELEASED` to a key that passed its scope checks. No inventory or purchase-order data is read or written, and the `Idempotency-Key` is not reserved.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Service Unavailable
            code: INVENTORY_AUTHORITY_NOT_RELEASED
            message: Inventory and purchase-order routes are not released yet. No inventory or purchase-order data was read or changed. Retry after the inventory authority is released.
            meta:
              requestId: 550e8400-e29b-41d4-a716-446655440000
  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.

        '