Frihet Quotes API

openapi: 3.2.0
info:
  title: Frihet Quotes 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: Quotes
  description: Create and manage quotes with PDF generation and email delivery. Convert accepted quotes to invoices.
paths:
  /v1/quotes:
    get:
      operationId: listQuotes
      summary: List quotes
      description: Retrieve a paginated list of quotes with optional filters for status, date range, and search.
      tags:
      - Quotes
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Cursor'
      - name: status
        in: query
        description: Filter by quote status
        schema:
          $ref: '#/components/schemas/QuoteStatus'
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/Search'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/FilterClientId'
      - $ref: '#/components/parameters/FilterSeriesId'
      responses:
        '200':
          description: A paginated list of quotes
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Quote'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createQuote
      summary: Create a quote
      description: Create a new quote. The quote is created in `draft` status by default.
      tags:
      - Quotes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteCreate'
      responses:
        '201':
          description: Quote created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeForbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/quotes/{quoteId}:
    get:
      operationId: getQuote
      summary: Get a quote
      description: Retrieve a single quote by ID.
      tags:
      - Quotes
      parameters:
      - $ref: '#/components/parameters/QuoteId'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Quote details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateQuote
      summary: Full update a quote
      description: Replace all fields on an existing quote.
      tags:
      - Quotes
      parameters:
      - $ref: '#/components/parameters/QuoteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteCreate'
      responses:
        '200':
          description: Quote updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      operationId: patchQuote
      summary: Partial update a quote
      description: Update only the provided fields on an existing quote.
      tags:
      - Quotes
      parameters:
      - $ref: '#/components/parameters/QuoteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteCreate'
      responses:
        '200':
          description: Quote updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteQuote
      summary: Delete a quote
      description: 'Delete a quote. Draft quotes are permanently deleted (204).

        Non-draft quotes are soft-deleted (cancelled) to preserve VeriFactu

        hash chain integrity, returning 200 with the cancelled document body.'
      tags:
      - Quotes
      parameters:
      - $ref: '#/components/parameters/QuoteId'
      responses:
        '200':
          description: Quote soft-deleted (cancelled). Returned for non-draft quotes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      status:
                        type: string
                        example: cancelled
                      cancelledVia:
                        type: string
                        example: api
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
        '204':
          description: Quote permanently deleted (draft quotes only)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/quotes/{quoteId}/pdf:
    get:
      operationId: getQuotePdf
      summary: Download quote PDF
      description: Generate and download the quote as a PDF document.
      tags:
      - Quotes
      parameters:
      - $ref: '#/components/parameters/QuoteId'
      responses:
        '200':
          description: PDF document
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/quotes/{quoteId}/send:
    post:
      operationId: sendQuote
      summary: Send quote by email
      description: Send the quote to a recipient via email. If the quote is in `draft` status, it will be automatically changed to `sent`.
      tags:
      - Quotes
      parameters:
      - $ref: '#/components/parameters/QuoteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
      responses:
        '200':
          description: Quote sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  messageId:
                    type: string
                    description: Email provider message ID
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Fiscal profile not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    Search:
      name: q
      in: query
      description: 'Full-text search query. Searches across relevant fields per resource type

        (e.g., clientName, documentNumber for invoices; name, email for clients).

        Case-insensitive.

        '
      schema:
        type: string
        example: acme
    Offset:
      name: offset
      in: query
      description: Number of items to skip for pagination (max 10000)
      schema:
        type: integer
        minimum: 0
        maximum: 10000
        default: 0
    FilterClientId:
      name: clientId
      in: query
      description: Filter invoices or quotes by client ID
      schema:
        type: string
    To:
      name: to
      in: query
      description: End date filter in ISO format (YYYY-MM-DD)
      schema:
        type: string
        format: date
        example: '2026-12-31'
    From:
      name: from
      in: query
      description: Start date filter in ISO format (YYYY-MM-DD)
      schema:
        type: string
        format: date
        example: '2026-01-01'
    Limit:
      name: limit
      in: query
      description: Number of items to return (default 50, max 100)
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    QuoteId:
      name: quoteId
      in: path
      required: true
      description: Quote unique identifier
      schema:
        type: string
    FilterSeriesId:
      name: seriesId
      in: query
      description: Filter invoices or quotes by invoice series ID
      schema:
        type: string
    Cursor:
      name: cursor
      in: query
      description: 'Cursor for cursor-based pagination. Use the `nextCursor` value from

        a previous response to fetch the next page. When provided, `offset`

        is ignored. The cursor is a base64url-encoded JSON string.

        '
      schema:
        type: string
        example: eyJpc3N1ZURhdGUiOiIyMDI2LTAzLTIwIiwiX19pZCI6ImFiYzEyMyJ9
    Fields:
      name: fields
      in: query
      description: 'Comma-separated list of fields to include in the response.

        The `id` field is always included. Example: `fields=id,name,total`

        '
      schema:
        type: string
        example: id,name,total
  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
    QuoteCreate:
      type: object
      required:
      - clientName
      - items
      properties:
        clientName:
          type: string
          description: Client name
          example: Acme Corp
        items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
          minItems: 1
        validUntil:
          type: string
          format: date
          description: Quote expiration date
          example: '2026-04-09'
        status:
          $ref: '#/components/schemas/QuoteStatus'
        notes:
          type: string
          description: Additional notes
          example: Valid for 30 days
    QuoteStatus:
      type: string
      enum:
      - draft
      - sent
      - accepted
      - rejected
      - expired
    SendEmailRequest:
      type: object
      required:
      - recipientEmail
      properties:
        recipientEmail:
          type: string
          format: email
          description: Recipient email address
          example: client@example.com
        recipientName:
          type: string
          description: Recipient name
          example: John Doe
        customMessage:
          type: string
          description: Optional custom message to include in the email
          example: Please find attached your invoice.
        locale:
          type: string
          enum:
          - es
          - en
          default: es
          description: Email language
    PaginatedResponse:
      type: object
      properties:
        data:
          type: array
          items: {}
        total:
          type: integer
          description: Total number of items matching the query
        limit:
          type: integer
          description: Number of items per page
        offset:
          type: integer
          description: Current offset
        nextCursor:
          type: string
          description: 'Cursor for fetching the next page of results. Only present when there

            are more results available. Pass this value as the `cursor` query parameter

            in the next request. Base64url-encoded.

            '
          example: eyJpc3N1ZURhdGUiOiIyMDI2LTAzLTIwIiwiX19pZCI6ImFiYzEyMyJ9
        truncated:
          type: boolean
          description: 'Only present (and `true`) when the underlying search query

            saturated the internal 500-document cap. `total` therefore reports

            the size of the first 500 matches, not the full match count.

            Narrow the search query (taxId / fiscal id, exact email) to ensure

            you see every result.

            '
          example: true
    Quote:
      allOf:
      - type: object
        properties:
          id:
            type: string
            description: Unique identifier
          createdAt:
            type: string
            format: date-time
          updatedAt:
            type: string
            format: date-time
      - $ref: '#/components/schemas/QuoteCreate'
      - type: object
        properties:
          documentNumber:
            type: string
            description: Auto-generated quote number
            example: PRE-2026-0015
          subtotal:
            type: number
            description: Subtotal before tax
          tax:
            type: number
            description: Tax amount
          total:
            type: number
            description: Total amount including tax
    LineItem:
      type: object
      required:
      - description
      - quantity
      - unitPrice
      properties:
        description:
          type: string
          description: Item description
          example: Web development services
        quantity:
          type: number
          description: Quantity
          example: 10
        unitPrice:
          type: number
          description: Price per unit
          example: 85
  responses:
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal server error
            meta:
              requestId: 550e8400-e29b-41d4-a716-446655440000
    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
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Resource not found
            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
    RateLimited:
      description: Rate limit exceeded (100 requests per minute)
      headers:
        Retry-After:
          description: Integer seconds until the current rate-limit window resets
          schema:
            type: integer
            minimum: 1
          example: 60
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Rate limit exceeded
              message:
                type: string
                example: Maximum 100 requests per minute
              retryAfter:
                type: integer
                description: Seconds until rate limit resets
                example: 60
              meta:
                type: object
                properties:
                  requestId:
                    type: string
    WriteScopeForbidden:
      description: Write scope required to mutate, send or submit. The API key must include the `write` scope (or `einvoice:write` for e-invoice sends) or be unrestricted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Forbidden
            detail: This API key does not have the write scope required to create, update, delete, send or submit. E-invoice sends also accept einvoice:write. Use an API key with write access.
            meta:
              requestId: 550e8400-e29b-41d4-a716-446655440000
  headers:
    X-RateLimit-Reset:
      description: Unix timestamp (seconds) when the rate limit window resets
      schema:
        type: integer
        example: 1742310060
  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.

        '