Factuarea API

openapi: 3.1.0
info:
  title: Factuarea API
  version: '2026-11-07'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-07: 8 operation(s) read from 8 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Factuarea has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 8
    documentation: 0
    pages-with-code: 8
    pages-read: 8
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-07'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.factuarea.com/api-reference/packs/public-api.v1.packs.list
  - https://docs.factuarea.com/api-reference/packs/public-api.v1.packs.show
  - https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.list
  - https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.show
  - https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.stats
  - https://docs.factuarea.com/api-reference/events/public-api.v1.events.list
  - https://docs.factuarea.com/api-reference/events/public-api.v1.events.show
  - https://docs.factuarea.com/api-reference/packs/public-api.v1.packs.create
servers:
- url: https://api.factuarea.com
paths:
  /v1/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/packs:
    post:
      operationId: post_v1_companies_01931b3e_7c4a_7f2e_9a8b_3c5d6e7f8a01_packs
      tags:
      - Companies
      summary: POST /v1/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/packs
      x-source: https://docs.factuarea.com/api-reference/packs/public-api.v1.packs.create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1Companies01931B3E7C4A7F2E9A8B3C5D6E7F8A01PacksRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1Companies01931B3E7C4A7F2E9A8B3C5D6E7F8A01PacksResponse'
      x-evidence:
        kind: code-example
        language: javascript
        snippet: 'fetch("https://api.factuarea.com/v1/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/packs", { method: "POST", headers: { Authorization:
          `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-packs-create"}
          }, body: JSON.stringify({ "name": "Pack Huerto urbano", "sku": "PACK-HUERTO", "slug": "pack-huerto-urbano", "summary": "To'
  /v1/companies/{company}/events:
    get:
      operationId: get_v1_companies_company_events
      tags:
      - Companies
      summary: List all events
      description: List events in your event log with cursor‑based pagination. Supports filtering by type and creation date.
      x-source: https://docs.factuarea.com/api-reference/events/public-api.v1.events.list
      parameters:
      - name: company
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Number of objects to return, between 1 and 100 (default 25).
      - name: starting_after
        in: query
        required: false
        schema:
          type: string
        description: 'Cursor for forward pagination: pass the id of the last object on the previous page.'
      - name: ending_before
        in: query
        required: false
        schema:
          type: string
        description: 'Cursor for backward pagination: pass the id of the first object on the current page.'
      - name: type
        in: query
        required: false
        schema:
          type: string
        description: Event type (e.g. invoice.created). Exact match on type.
      - name: type[in]
        in: query
        required: false
        schema:
          type: string
        description: Comma‑separated list of event types; any of the values matches.
      - name: created[gte]
        in: query
        required: false
        schema:
          type: string
        description: Creation date (ISO 8601) greater than or equal to the given value.
      - name: created[lte]
        in: query
        required: false
        schema:
          type: string
        description: Creation date (ISO 8601) less than or equal to the given value.
      - name: created[gt]
        in: query
        required: false
        schema:
          type: string
        description: Creation date (ISO 8601) strictly greater than the given value.
      - name: created[lt]
        in: query
        required: false
        schema:
          type: string
        description: Creation date (ISO 8601) strictly less than the given value.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1CompaniesCompanyEventsResponse'
      x-evidence:
        kind: documentation
  /v1/companies/{company}/events/{event}:
    get:
      operationId: get_v1_companies_company_events_event
      tags:
      - Companies
      summary: Retrieve an event
      x-source: https://docs.factuarea.com/api-reference/events/public-api.v1.events.show
      parameters:
      - name: company
        in: path
        required: true
        schema:
          type: string
      - name: event
        in: path
        required: true
        schema:
          type: string
      - name: Factuarea-Version
        in: header
        required: false
        schema:
          type: string
        description: Pin the API version (YYYY-MM-DD, Stripe‑style date versioning) for this request.
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer token API key.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1CompaniesCompanyEventsEventResponse'
      x-evidence:
        kind: documentation
  /v1/companies/{company}/packs:
    get:
      operationId: get_v1_companies_company_packs
      tags:
      - Companies
      summary: List all packs
      x-source: https://docs.factuarea.com/api-reference/packs/public-api.v1.packs.list
      parameters:
      - name: company
        in: path
        required: true
        schema:
          type: string
      - name: date
        in: query
        required: false
        schema:
          type: string
        description: Day (YYYY-MM-DD, company time zone) the promotion is resolved for; default today.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Number of objects to return, between 1 and 100 (default 25).
      - name: starting_after
        in: query
        required: false
        schema:
          type: string
        description: 'Cursor for forward pagination: pass the id of the last object on the previous page.'
      - name: ending_before
        in: query
        required: false
        schema:
          type: string
        description: 'Cursor for backward pagination: pass the id of the first object on the current page.'
      - name: slug
        in: query
        required: false
        schema:
          type: string
        description: Pack slug. Exact match on slug.
      - name: sku
        in: query
        required: false
        schema:
          type: string
        description: Pack SKU. Exact match on sku.
      - name: tag
        in: query
        required: false
        schema:
          type: string
        description: Classification tag. Exact match on tag.
      - name: channel
        in: query
        required: false
        schema:
          type: string
        description: 'Sales channel the pack is enabled for: documents or web.'
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: 'Pack status: active, inactive or archived.'
      - name: availability
        in: query
        required: false
        schema:
          type: string
        description: 'Availability: in_stock, low, out_of_stock or untracked.'
      - name: availability[in]
        in: query
        required: false
        schema:
          type: string
        description: Comma‑separated list of availability values.
      - name: updated[gte]
        in: query
        required: false
        schema:
          type: string
        description: Last update date (ISO 8601) greater than or equal to the given value.
      - name: sort
        in: query
        required: false
        schema:
          type: string
        description: 'Sort order: created, name, price (prefix - for descending).'
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Free‑text search (max 80 chars).
      - name: view
        in: query
        required: false
        schema:
          type: string
        description: 'Shape of the pack: all (default) or storefront.'
      - name: If-None-Match
        in: header
        required: false
        schema:
          type: string
        description: 'Conditional request: send the ETag to get 304 if unchanged.'
      - name: Factuarea-Version
        in: header
        required: false
        schema:
          type: string
        description: Pin the API version (YYYY‑MM‑DD).
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1CompaniesCompanyPacksResponse'
      x-evidence:
        kind: documentation
  /v1/companies/{company}/packs/{pack}:
    get:
      operationId: get_v1_companies_company_packs_pack
      tags:
      - Companies
      summary: Retrieve a pack
      x-source: https://docs.factuarea.com/api-reference/packs/public-api.v1.packs.show
      parameters:
      - name: company
        in: path
        required: true
        schema:
          type: string
      - name: pack
        in: path
        required: true
        schema:
          type: string
      - name: date
        in: query
        required: false
        schema:
          type: string
        description: Day (YYYY‑MM‑DD, company time zone) the promotion is resolved for; default today.
      - name: view
        in: query
        required: false
        schema:
          type: string
        description: 'Shape of the pack: all (default) returns the full pack, storefront only what a web shop may show.'
      - name: If-None-Match
        in: header
        required: false
        schema:
          type: string
        description: 'Conditional request: send the ETag to get 304 Not Modified.'
      - name: Factuarea-Version
        in: header
        required: false
        schema:
          type: string
        description: Pin the API version (YYYY‑MM‑DD).
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1CompaniesCompanyPacksPackResponse'
      x-evidence:
        kind: documentation
  /v1/companies/{company}/taxes:
    get:
      operationId: get_v1_companies_company_taxes
      tags:
      - Companies
      summary: List all taxes
      description: 'List the taxes visible to your company: the global platform catalog plus the taxes your company created.'
      x-source: https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.list
      parameters:
      - name: company
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Number of objects to return, between 1 and 100 (default 25).
      - name: starting_after
        in: query
        required: false
        schema:
          type: string
        description: 'Cursor for forward pagination: pass the id of the last object on the previous page.'
      - name: ending_before
        in: query
        required: false
        schema:
          type: string
        description: 'Cursor for backward pagination: pass the id of the first object on the current page.'
      - name: type
        in: query
        required: false
        schema:
          type: string
        description: 'Tax type: vat, retention, surcharge, other. Exact match.'
      - name: type[in]
        in: query
        required: false
        schema:
          type: string
        description: Comma‑separated list of tax types; any match.
      - name: is_active
        in: query
        required: false
        schema:
          type: boolean
        description: Filter active / inactive taxes.
      - name: is_default
        in: query
        required: false
        schema:
          type: boolean
        description: Filter taxes that are your company's effective default.
      - name: applies_to
        in: query
        required: false
        schema:
          type: string
        description: 'Scope: sales, purchases, both. Exact match.'
      - name: applies_to[in]
        in: query
        required: false
        schema:
          type: string
        description: Comma‑separated list of scopes; any match.
      - name: country
        in: query
        required: false
        schema:
          type: string
        description: ISO 3166‑1 alpha‑2 country code.
      - name: code
        in: query
        required: false
        schema:
          type: string
        description: Short tax code (exact match).
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Escaped LIKE search over name and code (limit 80 chars).
      - name: external_reference
        in: query
        required: false
        schema:
          type: string
        description: 'Exact AEAT key: S1..S3, E1..E6, N1..N2.'
      - name: external_reference[in]
        in: query
        required: false
        schema:
          type: string
        description: Comma‑separated list of AEAT keys; any match.
      - name: is_system
        in: query
        required: false
        schema:
          type: boolean
        description: Filter the protected canonical taxes of the Factuarea catalog.
      - name: ownership
        in: query
        required: false
        schema:
          type: string
        description: 'Whose taxes to list: global or company.'
      - name: country_aeat_zone
        in: query
        required: false
        schema:
          type: string
        description: 'AEAT fiscal zone: peninsula, canarias, ceuta, melilla.'
      - name: indirect_tax_regime
        in: query
        required: false
        schema:
          type: string
        description: 'Indirect tax regime derived from the AEAT zone: iva, igic, ipsi.'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1CompaniesCompanyTaxesResponse'
      x-evidence:
        kind: documentation
  /v1/companies/{company}/taxes/{tax}:
    get:
      operationId: get_v1_companies_company_taxes_tax
      tags:
      - Companies
      summary: Retrieve a tax
      x-source: https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.show
      parameters:
      - name: company
        in: path
        required: true
        schema:
          type: string
      - name: tax
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer token, e.g., fact_live_… or fact_test_…
      - name: Factuarea-Version
        in: header
        required: false
        schema:
          type: string
        description: Pin the API version (YYYY‑MM‑DD).
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1CompaniesCompanyTaxesTaxResponse'
      x-evidence:
        kind: documentation
  /v1/me:
    get:
      operationId: get_v1_me
      tags:
      - Me
      summary: List all taxes
      description: The page does not document this endpoint; it is only mentioned as a way to obtain a company ID.
      x-source: https://docs.factuarea.com/api-reference/taxes/public-api.v1.taxes.list
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostV1Companies01931B3E7C4A7F2E9A8B3C5D6E7F8A01PacksRequest:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        slug:
          type: string
        summary:
          type: string
        tags:
          type: array
          items:
            type: string
        channels:
          type: object
          properties:
            documents:
              type: boolean
            web:
              type: boolean
        available_from:
          type: string
          format: date
        available_until:
          type: string
          format: date
        pricing:
          type: object
          properties:
            mode:
              type: string
            value:
              type: string
            basis:
              type: string
        components:
          type: array
          items:
            type: object
            properties:
              product_id:
                type: string
              quantity:
                type: string
        metadata:
          type: object
          properties:
            erp_ref:
              type: string
    PostV1Companies01931B3E7C4A7F2E9A8B3C5D6E7F8A01PacksResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        name:
          type: string
        slug:
          type: string
        previous_slugs:
          type: array
          items:
            type: string
        sku:
          type: string
        summary:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        seo:
          type: object
          properties:
            title:
              type: string
            description:
              type: string
        currency:
          type: string
        price:
          type: object
          properties:
            net:
              type: string
            tax:
              type: string
            gross:
              type: string
        tax_breakdown:
          type: array
          items:
            type: object
            properties:
              rate:
                type: integer
              base:
                type: string
              tax:
                type: string
        separately:
          type: object
          properties:
            net:
              type: string
            gross:
              type: string
        savings:
          type: object
          properties:
            gross:
              type: string
            percent:
              type: number
        promotion:
          type:
          - string
          - 'null'
        available_from:
          type: string
          format: date
        available_until:
          type: string
          format: date
        cover:
          type: object
          properties:
            url:
              type: string
            thumb_url:
              type: string
            alt:
              type: string
            source:
              type: string
        gallery:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              url:
                type: string
              thumb_url:
                type: string
              alt:
                type: string
              width:
                type: integer
              height:
                type: integer
              position:
                type: integer
              content_type:
                type: string
        components:
          type: array
          items:
            type: object
            properties:
              product_id:
                type: string
              variant_id:
                type:
                - string
                - 'null'
              presentation_id:
                type:
                - string
                - 'null'
              configuration_id:
                type:
                - string
                - 'null'
              name:
                type: string
              slug:
                type: string
              quantity:
                type: string
              unit:
                type: object
                properties:
                  code:
                    type: string
                  label:
                    type: string
              image:
                type: object
                properties:
                  url:
                    type: string
                  alt:
                    type: string
              variant_name:
                type:
                - string
                - 'null'
              presentation_name:
                type:
                - string
                - 'null'
              sku:
                type: string
              configuration_signature:
                type:
                - string
                - 'null'
              options:
                type: array
                items: {}
              position:
                type: integer
        status:
          type: string
        channels:
          type: object
          properties:
            documents:
              type: boolean
            web:
              type: boolean
        pricing:
          type: object
          properties:
            mode:
              type: string
            value:
              type: string
            basis:
              type: string
        sellable:
          type: object
          properties:
            documents:
              type: boolean
            web:
              type: boolean
            reason:
              type:
              - string
              - 'null'
            code:
              type:
              - string
              - 'null'
        availability:
          type: object
          properties:
            status:
              type: string
            quantity:
              type: string
            limited_by:
              type: object
              properties:
                product_id:
                  type: string
                variant_id:
                  type:
                  - string
                  - 'null'
        attention:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              product_id:
                type:
                - string
                - 'null'
        metadata:
          type: object
          properties:
            erp_ref:
              type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    GetV1CompaniesCompanyEventsResponse:
      type: object
      properties:
        data:
          type: array
          description: Array of event objects.
        has_more:
          type: boolean
          description: Indicates if more pages are available.
        next_cursor:
          type: string
          description: Cursor for the next page, if any.
    GetV1CompaniesCompanyEventsEventResponse:
      type: object
      properties:
        data:
          type: object
          description: Event object
    GetV1CompaniesCompanyPacksResponse:
      type: object
      properties:
        data:
          type: array
          description: List of pack objects.
        has_more:
          type: boolean
          description: Whether more pages are available.
        next_cursor:
          type: string
          description: Cursor for the next page.
    GetV1CompaniesCompanyPacksPackResponse:
      type: object
      properties:
        data:
          type: object
          description: Pack object with its attributes (id, name, price, components, etc.).
    GetV1CompaniesCompanyTaxesResponse:
      type: object
      properties:
        data:
          type: array
          description: List of tax objects.
        has_more:
          type: boolean
          description: Indicates if more pages are available.
        next_cursor:
          type: string
          description: Cursor for the next page.
    GetV1CompaniesCompanyTaxesTaxResponse:
      type: object
      properties:
        data:
          type: object
          description: Tax object
tags:
- name: Companies
- name: Me