Frihet E Invoicing API

openapi: 3.2.0
info:
  title: Frihet E Invoicing 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: E-Invoicing
  description: 'EN16931-compliant e-invoicing export and B2G submission endpoints.

    Supports 9 formats (Facturae, XRechnung-CII/UBL, Factur-X, FatturaPA, PEPPOL-BIS-3, FA-2-KSeF, UBL, CII).

    FACe (Spain B2G portal) submission and TicketBAI XML/sandbox preview pipelines (live submission to Basque Haciendas Forales is not enabled).

    Trust Area: COMPLIANCE. Requires owner role or API key with `einvoice:*` scope.

    Export and submit also require `write` or `einvoice:write`.'
paths:
  /v1/invoices/{invoiceId}/einvoice/export:
    post:
      operationId: exportEInvoice
      summary: Export e-invoice XML
      description: 'Generate and return an e-invoice XML document for the invoice in one of 9 supported formats.

        Optionally sign with XAdES-EPES (Facturae only). Conforms to EN16931 semantic model.


        Supported formats: Facturae 3.2.2, XRechnung-CII, XRechnung-UBL, Factur-X (EN16931),

        FatturaPA 1.2.2, PEPPOL-BIS-3, FA-2-KSeF (Polish KSeF FA(3)), UBL 2.1, CII D16B.


        **Trust Area: COMPLIANCE** — Requires owner role, or an API key with `einvoice:*` scope plus `write` or `einvoice:write`.'
      tags:
      - E-Invoicing
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - format
              additionalProperties: false
              properties:
                format:
                  type: string
                  enum:
                  - Facturae
                  - XRechnung-CII
                  - XRechnung-UBL
                  - Factur-X
                  - FatturaPA
                  - PEPPOL-BIS-3
                  - FA-2-KSeF
                  - UBL
                  - CII
                  description: 'Target e-invoice format.

                    - Facturae: Spanish B2G (Agencia Tributaria, FACe)

                    - XRechnung-CII/UBL: German B2G (PEPPOL/ZRE/OZG-RE)

                    - Factur-X: French standard (PDF/A-3 XML component)

                    - FatturaPA: Italian SDI clearance

                    - PEPPOL-BIS-3: Pan-European PEPPOL network

                    - FA-2-KSeF: Polish KSeF FA(3) XML

                    - UBL/CII: Generic cross-border EU

                    '
                  example: Facturae
                signed:
                  type: boolean
                  default: false
                  description: 'Sign the XML with XAdES-EPES. Only supported for `format: Facturae`.

                    Requires a valid PKCS#12 certificate uploaded in Settings > Compliance.

                    '
      responses:
        '200':
          description: E-invoice XML generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      xml:
                        type: string
                        description: E-invoice XML content (UTF-8)
                      contentType:
                        type: string
                        example: application/xml
                      filename:
                        type: string
                        example: F2026-001_Facturae.xml
                      signed:
                        type: boolean
                        description: Whether the XML was signed with XAdES-EPES
                      format:
                        type: string
                        example: Facturae
                      warnings:
                        type: array
                        description: 'EN 16931 validation findings with severity `warning`. They do not block

                          generation, but a receiving validator may reject the document for them.

                          Empty when there are none.

                          '
                        items:
                          $ref: '#/components/schemas/EInvoiceValidationIssue'
        '400':
          description: Invalid format, signing not supported for this format, or body validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: XML generation failed or certificate not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/invoices/{invoiceId}/face/submit:
    post:
      operationId: submitFaceInvoice
      summary: Submit invoice to FACe B2G portal
      description: 'Submit a signed Facturae XML to Spain''s FACe B2G portal (face.gob.es).


        Pipeline: load invoice → generate Facturae XML → sign with XAdES-EPES → submit to FACe.

        Result is persisted to `invoices/{id}/face/submission` subdoc.


        **Idempotent**: if the invoice was already accepted (registered), returns the prior result

        with `idempotent: true` — does not resubmit.


        **Trust Area: COMPLIANCE** — Requires owner role, or an API key with `einvoice:*` scope plus `write` or `einvoice:write`.

        Requires a PKCS#12 certificate for sandbox/production modes.'
      tags:
      - E-Invoicing
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                mode:
                  type: string
                  enum:
                  - mock
                  - sandbox
                  - production
                  description: FACe submission mode. Defaults to `ES_FACE_MODE` env var (default `mock`).
                correo:
                  type: string
                  format: email
                  description: Recipient notification email (required by FACe protocol). Defaults to fiscal billing email.
      responses:
        '200':
          description: Invoice submitted to FACe
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        example: submitted
                      numeroRegistro:
                        type: string
                        description: FACe registration number (never fabricated)
                        example: REG/2026/000042
                      codigo:
                        type: string
                        description: FACe result code
                        example: '0'
                      descripcion:
                        type: string
                        description: FACe result description
                        example: Registrada
                      idempotent:
                        type: boolean
                        description: Present and true when returning a prior accepted submission
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: FACe rejection, certificate missing, or XML generation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        codigo:
                          type: string
                        descripcion:
                          type: string
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/invoices/{invoiceId}/face/status:
    get:
      operationId: getFaceInvoiceStatus
      summary: Get FACe submission status
      description: 'Query the current tramitación status of a previously submitted FACe invoice.

        Reads the saved `numeroRegistro` from Firestore and calls FACe `consultarFactura`.


        **Trust Area: COMPLIANCE** — Requires owner role or API key with `einvoice:*` scope.'
      tags:
      - E-Invoicing
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      responses:
        '200':
          description: FACe tramitación status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      numeroRegistro:
                        type: string
                        description: FACe registration number (read from Firestore, never fabricated)
                      estadoTramitacion:
                        type: string
                        nullable: true
                        description: FACe tramitación code (e.g. '1200' = Registrada, '1300' = En tramitación)
                      codigo:
                        type: string
                        nullable: true
                      descripcion:
                        type: string
                        nullable: true
                      motivo:
                        type: string
                        nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No FACe submission found for this invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Certificate required or FACe transport error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/invoices/{invoiceId}/ticketbai/submit:
    post:
      operationId: submitTicketBaiInvoice
      summary: Submit invoice to TicketBAI sandbox/preview (live foral submission not enabled)
      description: 'Build and sign a TicketBAI XML and run the sandbox/preview pipeline (live submission to Basque Haciendas Forales / BATUZ is not enabled in the product).


        Pipeline: fetch BYOC cert → compute hash chain → build TicketBAI XML →

        sign with XAdES-BES → sandbox/preview dispatch → generate QR code.

        Result persisted to `invoices/{id}/tbai/submission` subdoc.


        **Idempotent**: if the invoice was already accepted, returns the prior result

        with `idempotent: true` — does not resubmit.


        **Trust Area: COMPLIANCE** — Requires owner role, or an API key with `einvoice:*` scope plus `write` or `einvoice:write`.

        Requires a TicketBAI BYOC certificate uploaded in Settings > Integrations > TicketBAI.'
      tags:
      - E-Invoicing
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                sandbox:
                  type: boolean
                  description: Override to sandbox mode (default from user integration config).
      responses:
        '200':
          description: TicketBAI submission accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      accepted:
                        type: boolean
                        example: true
                      csv:
                        type: string
                        description: CSV de verificación (never fabricated)
                        example: TBAI-48-120226-000001-2H
                      tbaiIdentifier:
                        type: string
                        description: TicketBAI identifier string
                        example: TBAI-B-000001
                      qrUrl:
                        type: string
                        description: QR code URL for invoice printing
                      idempotent:
                        type: boolean
                        description: Present and true when returning a prior accepted submission
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: TicketBAI rejection, certificate missing, or chain broken
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/invoices/{invoiceId}/ticketbai/status:
    get:
      operationId: getTicketBaiInvoiceStatus
      summary: Get TicketBAI sandbox/preview status
      description: 'Read the TicketBAI sandbox/preview record for a previously processed invoice (live submission to Basque Haciendas Forales is not enabled).

        Returns accepted/rejected status, CSV, identifier, and QR URL from Firestore.


        **Trust Area: COMPLIANCE** — Requires owner role or API key with `einvoice:*` scope.'
      tags:
      - E-Invoicing
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      responses:
        '200':
          description: TicketBAI submission status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      accepted:
                        type: boolean
                      csv:
                        type: string
                        description: CSV de verificación (read from Firestore, never fabricated)
                      tbaiIdentifier:
                        type: string
                      estado:
                        type: string
                        description: accepted | rejected
                      qrUrl:
                        type: string
                        nullable: true
                      submittedAt:
                        type: string
                        format: date-time
                        nullable: true
                      errors:
                        type: array
                        nullable: true
                        items:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No TicketBAI submission found for this invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    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
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Insufficient permissions
            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
    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
  schemas:
    EInvoiceValidationIssue:
      type: object
      required:
      - severity
      - ruleId
      - message
      properties:
        severity:
          type: string
          enum:
          - error
          - warning
          - info
        ruleId:
          type: string
          description: EN 16931 or format rule identifier
          example: BR-E-10
        message:
          type: string
          description: Rule message in English
        i18nKey:
          type: string
          description: Translation key for the message in the Frihet app, when one exists
    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
  parameters:
    InvoiceId:
      name: invoiceId
      in: path
      required: true
      description: Invoice unique identifier
      schema:
        type: string
  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.

        '