openapi-schema.yaml

openapi: 3.0.3
info:
  title: TiBillet API v2
  version: "2.0.0"
  description: |
    Semantic, schema.org-based API.
servers:
  - url: https://{tenant}.{domain}
    variables:
      tenant:
        default: lespass
      domain:
        default: tibillet.localhost
paths:
  /api/v2/events/:
    get:
      operationId: listEvents
      summary: List all published Events
      description: >
        Lists published events. The time filters start from YESTERDAY, not from now:
        an event that began last night is still relevant. They also keep ONGOING events
        (started before the window but still running), by looking at endDate.
      tags: [Event]
      security:
        - ApiKeyAuth: []
      parameters:
        - name: only_futur
          in: query
          required: false
          description: >
            Any truthy value keeps only upcoming or ongoing events (from yesterday on).
            Ignored when `next_days` is supplied.
          schema:
            type: string
            example: "1"
        - name: next_days
          in: query
          required: false
          description: >
            Keep only the events of the next N days (from yesterday on). Takes precedence
            over `only_futur`. Must be an integer between 1 and 366; anything else
            returns 400.
          schema:
            type: integer
            minimum: 1
            maximum: 366
            example: 30
        - name: filter
          in: query
          required: false
          description: >
            Free-text search on the event name, short description and long description.
          schema:
            type: string
            example: concert
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
        "400":
          description: >
            `next_days` is not an integer, or is outside the 1..366 range.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: next_days doit être compris entre 1 et 366.
    post:
      operationId: createEvent
      summary: Create an Event (schema.org/Event)
      tags: [Event]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
            examples:
              musicCreate:
                summary: Create a music event
                value:
                  "@context": "https://schema.org"
                  "@type": "MusicEvent"
                  name: API v2 — Test create
                  startDate: "2025-12-20T19:00:00Z"
          multipart/form-data:
            schema:
              type: object
              properties:
                '@context':
                  type: string
                  example: https://schema.org
                '@type':
                  type: string
                  example: MusicEvent
                name:
                  type: string
                startDate:
                  type: string
                  format: date-time
                endDate:
                  type: string
                  format: date-time
                maximumAttendeeCapacity:
                  type: integer
                disambiguatingDescription:
                  type: string
                description:
                  type: string
                eventStatus:
                  type: string
                audience:
                  type: object
                keywords:
                  type: array
                  items:
                    type: string
                img:
                  type: string
                  format: binary
                sticker_img:
                  type: string
                  format: binary
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
  /api/v2/events/{uuid}/:
    get:
      operationId: retrieveEvent
      summary: Retrieve a single Event (by UUID or front slug)
      description: |
        Accepts either the Event UUID, or the front-end slug
        (e.g. my-event-260620-0900-7d51dee7) whose last 8 hex characters are the
        start of the UUID. Mirrors the front controller (EventMVT.retrieve):
        valid UUID -> direct lookup; otherwise uuid__startswith=<last 8 hex>, then
        a slug__startswith fallback. No `published` filter (an unpublished event is
        retrievable). Returns 404 when nothing matches.
      tags: [Event]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          description: Event UUID or front-end slug.
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        "404":
          description: Not Found — no Event matches this UUID/slug
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteEvent
      summary: Delete an Event by UUID
      tags: [Event]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Deleted
  /api/v2/events/{uuid}/link-address/:
    post:
      operationId: linkEventAddress
      summary: Link a PostalAddress to an Event (by id or schema.org payload)
      tags: [Event]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    postalAddressId:
                      type: integer
                - $ref: '#/components/schemas/PostalAddress'
      responses:
        '200':
          description: Updated Event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
  /api/v2/events/{uuid}/link-product/:
    post:
      operationId: linkEventProduct
      summary: Attach one or several EXISTING products to an Event
      description: |
        Link already-created Product(s) to this Event via the ManyToMany
        Event.products. The same product can be shared across several events.
        Unlike POST /api/v2/products/ (which creates a product and attaches it),
        this route never creates a product. All product UUIDs are validated
        before anything is attached (no partial link on a bad UUID).
      tags: [Event]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: |
                Accepts several flexible shapes. Provide at least one product
                identifier via productId, productIds, product or products.
              properties:
                productId:
                  type: string
                  format: uuid
                  description: A single product UUID
                productIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Several product UUIDs
                product:
                  oneOf:
                    - type: string
                      format: uuid
                    - type: object
                      properties:
                        '@type':
                          type: string
                          example: Product
                        identifier:
                          type: string
                          format: uuid
                products:
                  type: array
                  items:
                    oneOf:
                      - type: string
                        format: uuid
                      - type: object
                        properties:
                          identifier:
                            type: string
                            format: uuid
            examples:
              singleProduct:
                summary: Attach one existing product
                value:
                  productId: "c2a9f2a2-3e6a-4c1e-8d5c-3f8b2d6a9b01"
              severalProducts:
                summary: Attach several existing products
                value:
                  productIds:
                    - "c2a9f2a2-3e6a-4c1e-8d5c-3f8b2d6a9b01"
                    - "d3b8e3b3-4f7b-5d2f-9e6d-4a9c3e7b0c12"
      responses:
        '200':
          description: Updated Event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '400':
          description: No/invalid product identifier, or a product was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/initiatives/:
    get:
      operationId: listInitiatives
      summary: List Crowds initiatives
      tags: [Initiative]
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Initiative'
    post:
      operationId: createInitiative
      summary: Create a Crowds initiative (schema.org/Project)
      tags: [Initiative]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Initiative'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Initiative'
  /api/v2/initiatives/{uuid}/:
    get:
      operationId: retrieveInitiative
      summary: Retrieve a Crowds initiative
      tags: [Initiative]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Initiative'
    delete:
      operationId: deleteInitiative
      summary: Delete a Crowds initiative by UUID
      tags: [Initiative]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Deleted
  /api/v2/initiatives/{uuid}/budget-items/:
    get:
      operationId: listInitiativeBudgetItems
      summary: List budget items for an initiative
      tags: [Initiative]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/BudgetItem'
    post:
      operationId: createInitiativeBudgetItem
      summary: Create a budget item for an initiative
      tags: [Initiative]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetItemCreate'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetItem'
  /api/v2/initiatives/{uuid}/votes/:
    get:
      operationId: getInitiativeVotes
      summary: Retrieve vote count for an initiative
      tags: [Initiative]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoteCount'
    post:
      operationId: createInitiativeVote
      summary: Cast a vote for an initiative (idempotent)
      tags: [Initiative]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '201':
          description: Created or already existed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoteCount'
  /api/v2/initiatives/{uuid}/participations/:
    get:
      operationId: listInitiativeParticipations
      summary: List participations for an initiative
      tags: [Initiative]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Participation'
    post:
      operationId: createInitiativeParticipation
      summary: Create a participation for an initiative
      tags: [Initiative]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipationCreate'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participation'
  /api/v2/postal-addresses/:
    get:
      operationId: listPostalAddresses
      summary: List PostalAddresses
      tags: [PostalAddress]
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/PostalAddress'
    post:
      operationId: createPostalAddress
      summary: Create PostalAddress (schema.org)
      tags: [PostalAddress]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostalAddress'
          multipart/form-data:
            schema:
              type: object
              properties:
                '@type':
                  type: string
                  example: PostalAddress
                name:
                  type: string
                streetAddress:
                  type: string
                addressLocality:
                  type: string
                addressRegion:
                  type: string
                postalCode:
                  type: string
                addressCountry:
                  type: string
                geo:
                  type: object
                  properties:
                    '@type':
                      type: string
                      example: GeoCoordinates
                    latitude:
                      type: number
                      format: float
                    longitude:
                      type: number
                      format: float
                img:
                  type: string
                  format: binary
                sticker_img:
                  type: string
                  format: binary
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostalAddress'
  /api/v2/postal-addresses/{id}/:
    get:
      operationId: retrievePostalAddress
      summary: Retrieve PostalAddress by id
      tags: [PostalAddress]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostalAddress'
    delete:
      operationId: deletePostalAddress
      summary: Delete PostalAddress by id
      tags: [PostalAddress]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Deleted
  /api/v2/products/:
    get:
      operationId: listProducts
      summary: List Products
      tags: [Product]
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
    post:
      operationId: createProduct
      summary: Create Product with offers and optional form fields
      tags: [Product]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreate'
            examples:
              ticketCreate:
                summary: Create ticket product with prices and form fields
                value:
                  "@context": "https://schema.org"
                  "@type": "Product"
                  name: "Billets - Test Event"
                  category: "Ticket booking"
                  isRelatedTo:
                    "@type": "Event"
                    identifier: "c2a9f2a2-3e6a-4c1e-8d5c-3f8b2d6a9b01"
                  offers:
                    - "@type": "Offer"
                      name: "Tarif Soutien"
                      price: "10.00"
                      priceCurrency: "EUR"
                  additionalProperty:
                    - "@type": "PropertyValue"
                      name: "formFields"
                      value:
                        - label: "Nom"
                          fieldType: "shortText"
                          required: true
                        - label: "Votre motivation"
                          fieldType: "longText"
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /api/v2/products/{uuid}/:
    get:
      operationId: retrieveProduct
      summary: Retrieve Product by UUID
      tags: [Product]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /api/v2/reservations/:
    post:
      operationId: createReservation
      summary: Create Reservation (schema.org/Reservation)
      description: |
        FR: Creation d'une reservation (schema.org/Reservation) via API v2.
        Cette route requiert une cle API avec permission `reservation`.

        EN: Create a Reservation (schema.org/Reservation) using API v2.
        This route requires an API key with `reservation` permission.
      tags: [Reservation]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReservationCreate'
            examples:
              reservationCreate:
                summary: Create a free reservation (confirmed)
                value:
                  "@context": "https://schema.org"
                  "@type": "Reservation"
                  reservationFor:
                    "@type": "Event"
                    identifier: "c2a9f2a2-3e6a-4c1e-8d5c-3f8b2d6a9b01"
                  underName:
                    "@type": "Person"
                    email: "test@example.org"
                  reservedTicket:
                    - "@type": "Ticket"
                      identifier: "f66b3c1b-0b6f-4d8c-9e2c-4c9df2d2a111"
                      ticketQuantity: 1
                  additionalProperty:
                    - "@type": "PropertyValue"
                      name: "confirmed"
                      value: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
  /api/v2/reservations/{uuid}/:
    get:
      operationId: retrieveReservation
      summary: Retrieve Reservation by UUID
      tags: [Reservation]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
  /api/v2/memberships/:
    post:
      operationId: createMembership
      summary: Create Membership (schema.org/ProgramMembership)
      description: |
        FR: Creation d'une adhesion (schema.org/ProgramMembership) via API v2.
        Cette route requiert une cle API avec permission `membership`.

        EN: Create a ProgramMembership using API v2.
        This route requires an API key with `membership` permission.
      tags: [Membership]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProgramMembershipCreate'
            examples:
              membershipCreate:
                summary: Create a free membership (API)
                value:
                  "@context": "https://schema.org"
                  "@type": "ProgramMembership"
                  member:
                    "@type": "Person"
                    email: "test@example.org"
                    givenName: "Ada"
                    familyName: "Lovelace"
                  membershipPlan:
                    "@type": "Offer"
                    identifier: "b2e7b7a0-8b0b-4a1f-8c9b-9d1f0a55e001"
                  additionalProperty:
                    - "@type": "PropertyValue"
                      name: "paymentMode"
                      value: "FREE"
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgramMembership'
  /api/v2/memberships/{uuid}/:
    get:
      operationId: retrieveMembership
      summary: Retrieve Membership by UUID
      tags: [Membership]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgramMembership'
  /api/v2/sales/:
    get:
      operationId: listSales
      summary: List sales lines as schema.org Products (requires start/end, TZ-aware)
      description: |
        FR (FALC): Liste des ventes entre deux dates. Vous DEVEZ fournir
        deux paramètres: `start` et `end` au format ISO‑8601 avec fuseau horaire
        (exemple: 2025-01-31T23:59:59+01:00). La réponse est une `ItemList`
        de `Product` (schema.org), avec des propriétés additionnelles utiles
        (`sale_line_uuid`, `quantity`, `vat`, `payment_method`, `status`).

        EN: List sales in a date window. Requires `start` and `end` query
        parameters as ISO‑8601 TZ‑aware datetimes. Returns an `ItemList` of
        schema.org `Product` items, each representing the sold product.
      tags: [Sale]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: start
          required: true
          description: |
            FR: Début de période (ISO‑8601, avec fuseau horaire). Exemple: 2025-01-01T00:00:00+01:00
            EN: Period start (ISO‑8601 with timezone). Example: 2025-01-01T00:00:00+01:00
          schema:
            type: string
            format: date-time
          example: "2025-01-01T00:00:00+01:00"
        - in: query
          name: end
          required: true
          description: |
            FR: Fin de période (ISO‑8601, avec fuseau horaire). Doit être ≥ start.
            EN: Period end (ISO‑8601 with timezone). Must be ≥ start.
          schema:
            type: string
            format: date-time
          example: "2025-01-31T23:59:59+01:00"
        - in: query
          name: status
          required: false
          description: |
            FR: Filtre sur le statut métier de la ligne. Par défaut, seules les lignes `VALID` sont renvoyées.
            Utilisez `ALL` pour désactiver le filtre. Valeurs possibles: `ALL`, `CANCELED (C)`, `REFUNDED (R)`,
            `CREATED (O)`, `UNPAID (U)`, `FREERES (F)`, `PAID (P)`, `VALID (V)`, `FAILED (D)`.

            EN: Filter by line business status. Default returns only `VALID` lines. Use `ALL` to disable the filter.
            Allowed values: `ALL`, `CANCELED (C)`, `REFUNDED (R)`, `CREATED (O)`, `UNPAID (U)`, `FREERES (F)`,
            `PAID (P)`, `VALID (V)`, `FAILED (D)`.
          schema:
            type: string
            example: VALID
      responses:
        '200':
          description: OK — ItemList of Products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemList'
              examples:
                salesList:
                  summary: Sales list example
                  value:
                    "@context": "https://schema.org"
                    "@type": "ItemList"
                    startDate: "2025-01-01T00:00:00+01:00"
                    endDate: "2025-01-31T23:59:59+01:00"
                    itemListElement:
                      - "@type": "Product"
                        name: "Billet Concert — Plein tarif"
                        category: "Ticket booking"
                        image: "https://example.test/media/images/abc_med.jpg"
                        sku: "c2a9f2a2-3e6a-4c1e-8d5c-3f8b2d6a9b01"
                        identifier: "c2a9f2a2-3e6a-4c1e-8d5c-3f8b2d6a9b01"
                        offers:
                          "@type": "Offer"
                          price: "10.00"
                          priceCurrency: "EUR"
                        additionalProperty:
                          - "@type": "PropertyValue"
                            name: "sale_line_uuid"
                            value: "6a1f2e8c-9c3b-4f1a-8e2d-7b6a5c4d3e2f"
                          - "@type": "PropertyValue"
                            name: "quantity"
                            value: "1"
                          - "@type": "PropertyValue"
                            name: "vat"
                            value: "20.00"
                salesListAll:
                  summary: Sales list without status filter
                  value:
                    "@context": "https://schema.org"
                    "@type": "ItemList"
                    startDate: "2025-01-01T00:00:00+01:00"
                    endDate: "2025-01-31T23:59:59+01:00"
                    itemListElement: []
        '400':
          description: Bad Request — missing/invalid start/end
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: "Paramètres 'start' et 'end' obligatoires (ISO 8601, avec fuseau horaire)."
        '401':
          description: Unauthorized — API key missing/invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — API key lacks "sale" permission or user not tenant admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/sales/{uuid}/:
    get:
      operationId: retrieveSale
      summary: Retrieve one sale line as schema.org Product by UUID
      description: |
        FR (FALC): Donne le détail d’une ligne de vente sous forme de `Product` (schema.org).
        Les propriétés additionnelles incluent l’UUID de la ligne, la quantité et la TVA.

        EN: Returns a single sale line as a schema.org `Product` resource.
      tags: [Sale]
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK — Product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              examples:
                oneSale:
                  summary: One sale line as Product
                  value:
                    "@context": "https://schema.org"
                    "@type": "Product"
                    name: "Adhésion annuelle"
                    category: "Subscription or membership"
                    identifier: "6a1f2e8c-9c3b-4f1a-8e2d-7b6a5c4d3e2f"
                    offers:
                      "@type": "Offer"
                      price: "5.00"
                      priceCurrency: "EUR"
                    additionalProperty:
                      - "@type": "PropertyValue"
                        name: "sale_line_uuid"
                        value: "6a1f2e8c-9c3b-4f1a-8e2d-7b6a5c4d3e2f"
                      - "@type": "PropertyValue"
                        name: "quantity"
                        value: "2"
                      - "@type": "PropertyValue"
                        name: "vat"
                        value: "0.00"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/wallet-refills/:
    post:
      summary: Top up a user wallet with non-fiat tokens
      description: >
        Credit non-fiat tokens to a user's wallet from the place wallet, without
        payment. Refillable asset categories: TNF (gift), TIM (time), FID
        (loyalty), BDG (badge); fiat (TLF, FED) and subscription (SUB) are
        excluded. The API key must have a gift_asset set in the admin (this both
        enables the permission and restricts the key to that single asset). The
        requested asset must be in a refillable category and must match the
        key's gift_asset. Per-call cap: 10000 (raw unit). The Idempotency-Key
        header is REQUIRED (this endpoint credits tokens): it is stored in DB
        (LigneArticle.idempotency_key, unique constraint = lock). A repeat with
        the same key and the same body returns 208 Already Reported with the
        stored transaction; the same key with a DIFFERENT body is rejected with
        409 Conflict.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            type: string
          description: |
            Required client-provided dedup key. Same key + same body -> 208
            (stored transaction). Same key + different body -> 409. A key whose
            previous attempt failed (Fedow error) may be retried.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, asset, amount]
              properties:
                email:
                  type: string
                  format: email
                  example: alice@example.org
                asset:
                  type: string
                  format: uuid
                  description: UUID of the refillable asset (TNF/TIM/FID/BDG) authorized on the key
                amount:
                  type: integer
                  minimum: 1
                  maximum: 10000
                  description: Token amount in raw unit (passed as-is to Fedow)
                  example: 500
      responses:
        '201':
          description: Tokens credited; returns a schema.org MoneyTransfer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoneyTransfer'
        '208':
          description: Idempotent replay (same key, same body); returns the stored MoneyTransfer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoneyTransfer'
        '400':
          description: Invalid payload, or missing required Idempotency-Key header
        '403':
          description: Key not allowed, or asset not authorized for this key
        '409':
          description: |
            Idempotency-Key reused with different parameters, or a refill with
            this key is already in progress.
        '422':
          description: Asset category is not refillable (fiat/subscription), or amount above the cap
        '503':
          description: Fedow service unavailable
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      bearerFormat: Api-Key
      description: |
        Pass your key as `Authorization: Api-Key <key>`.
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
          example: Unauthorized
    PostalAddress:
      type: object
      properties:
        '@type':
          type: string
          example: PostalAddress
        name:
          type: string
        streetAddress:
          type: string
        addressLocality:
          type: string
        addressRegion:
          type: string
        postalCode:
          type: string
        addressCountry:
          type: string
        geo:
          type: object
          properties:
            '@type':
              type: string
              example: GeoCoordinates
            latitude:
              type: number
              format: float
            longitude:
              type: number
              format: float
        image:
          type: array
          description: Array of image URLs (main first, then sticker)
          items:
            type: string
            format: uri
    Place:
      type: object
      properties:
        '@type':
          type: string
          example: Place
        address:
          $ref: '#/components/schemas/PostalAddress'
    Event:
      type: object
      description: schema.org/Event JSON-LD representation
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: Event
        identifier:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
          nullable: true
        location:
          $ref: '#/components/schemas/Place'
        url:
          type: string
          format: uri
        additionalType:
          type: string
          description: Human-readable category label (schema.org/Thing.additionalType). Maps to internal category.
        superEvent:
          description: Parent event. Required when the resolved category is ACTION (Volunteering).
          oneOf:
            - type: string
              format: uuid
              description: UUID of the parent Event (recommended for create requests)
            - type: object
              properties:
                '@type':
                  type: string
                  example: Event
                identifier:
                  type: string
                  format: uuid
                name:
                  type: string
        maximumAttendeeCapacity:
          type: integer
        disambiguatingDescription:
          type: string
        eventStatus:
          type: string
          description: e.g. https://schema.org/EventScheduled or https://schema.org/EventCancelled
        audience:
          type: object
          properties:
            '@type':
              type: string
              example: Audience
            audienceType:
              type: string
              example: private
        keywords:
          type: array
          items:
            type: string
        sameAs:
          type: string
          format: uri
        offers:
          type: object
          properties:
            '@type':
              type: string
              example: Offer
            eligibleQuantity:
              type: object
              properties:
                '@type':
                  type: string
                  example: QuantitativeValue
                maxValue:
                  type: integer
            returnPolicy:
              type: object
              properties:
                '@type':
                  type: string
                  example: MerchantReturnPolicy
                merchantReturnDays:
                  type: integer
        additionalProperty:
          type: array
          items:
            type: object
            properties:
              '@type':
                type: string
                example: PropertyValue
              name:
                type: string
                example: optionsRadio
              value:
                oneOf:
                  - type: array
                    items:
                      type: string
                  - type: string
    ProductCreate:
      type: object
      description: schema.org/Product input for creation (with offers and form fields)
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: Product
        name:
          type: string
        description:
          type: string
          nullable: true
        category:
          type: string
          description: Human-readable category or internal code
          example: Ticket booking
        isRelatedTo:
          description: |
            Optional link to one OR several Events. Accepts a single UUID, a
            single schema.org Event object, or an array mixing both. The product
            is attached to every resolved Event (M2M Event.products), so the
            same product can be shared across multiple events.
          oneOf:
            - type: string
              format: uuid
            - type: object
              properties:
                '@type':
                  type: string
                  example: Event
                identifier:
                  type: string
                  format: uuid
            - type: array
              description: Several events (UUID strings and/or Event objects)
              items:
                oneOf:
                  - type: string
                    format: uuid
                  - type: object
                    properties:
                      '@type':
                        type: string
                        example: Event
                      identifier:
                        type: string
                        format: uuid
        offers:
          type: array
          items:
            $ref: '#/components/schemas/ProductOfferInput'
        additionalProperty:
          type: array
          items:
            type: object
    Initiative:
      type: object
      description: schema.org/Project representation for Crowds initiatives
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: Project
        identifier:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        disambiguatingDescription:
          type: string
        dateCreated:
          type: string
          format: date-time
        currency:
          type: string
          example: EUR
        keywords:
          type: array
          items:
            type: string
        additionalProperty:
          type: array
          items:
            type: object
            properties:
              '@type':
                type: string
                example: PropertyValue
              name:
                type: string
              value:
                oneOf:
                  - type: string
                  - type: boolean
                  - type: number
    BudgetItem:
      type: object
      description: MonetaryAmount-like representation for budget items
      properties:
        '@type':
          type: string
          example: MonetaryAmount
        identifier:
          type: string
          format: uuid
        name:
          type: string
        value:
          type: string
          example: "120.00"
        currency:
          type: string
          example: EUR
        actionStatus:
          type: string
          example: approved
        dateCreated:
          type: string
          format: date-time
    BudgetItemCreate:
      type: object
      properties:
        description:
          type: string
        amount:
          type: string
          example: "120.00"
        actionStatus:
          type: string
          example: approved
    Participation:
      type: object
      description: schema.org/Action-like representation for participations
      properties:
        '@type':
          type: string
          example: Action
        identifier:
          type: string
          format: uuid
        description:
          type: string
        actionStatus:
          type: string
        object:
          type: object
          properties:
            '@type':
              type: string
              example: Project
            identifier:
              type: string
              format: uuid
            name:
              type: string
        agent:
          type: object
          properties:
            '@type':
              type: string
              example: Person
            name:
              type: string
            email:
              type: string
        amount:
          type: object
          properties:
            '@type':
              type: string
              example: MonetaryAmount
            value:
              type: string
            currency:
              type: string
        timeSpentMinutes:
          type: integer
        dateCreated:
          type: string
          format: date-time
    ParticipationCreate:
      type: object
      properties:
        description:
          type: string
        amount:
          type: string
          example: "45.00"
    VoteCount:
      type: object
      properties:
        count:
          type: integer
          description: Number of votes for the initiative
        created:
          type: boolean
          description: True if this call created a new vote (POST only)
    ProductOfferInput:
      type: object
      description: Price definition used to create a Product offer
      properties:
        '@type':
          type: string
          example: Offer
        name:
          type: string
          example: Tarif Soutien
        price:
          type: string
          example: "10.00"
        priceCurrency:
          type: string
          example: EUR
        freePrice:
          type: boolean
          description: If true, amount is entered by the user on Stripe
        order:
          type: integer
        stock:
          type: integer
        maxPerUser:
          type: integer
        inventoryLevel:
          type: object
          description: schema.org/Offer.inventoryLevel (optional)
          properties:
            '@type':
              type: string
              example: QuantitativeValue
            value:
              type: integer
        eligibleQuantity:
          type: object
          description: schema.org/Offer.eligibleQuantity (optional)
          properties:
            '@type':
              type: string
              example: QuantitativeValue
            maxValue:
              type: integer
        membershipRequiredProduct:
          type: string
          format: uuid
          description: Product UUID that is required to access this price (adhesion obligatoire)
        additionalProperty:
          type: array
          description: Extra settings as schema.org PropertyValue list
          items:
            type: object
            properties:
              '@type':
                type: string
                example: PropertyValue
              name:
                type: string
                example: recurringPayment
              value:
                oneOf:
                  - type: boolean
                  - type: string
          example:
            - '@type': PropertyValue
              name: recurringPayment
              value: true
            - '@type': PropertyValue
              name: subscriptionType
              value: M
            - '@type': PropertyValue
              name: manualValidation
              value: true
    ReservationCreate:
      type: object
      description: schema.org/Reservation input for creation
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: Reservation
        reservationFor:
          type: object
          properties:
            '@type':
              type: string
              example: Event
            identifier:
              type: string
              format: uuid
        underName:
          type: object
          properties:
            '@type':
              type: string
              example: Person
            email:
              type: string
              format: email
        reservedTicket:
          type: array
          items:
            type: object
            properties:
              '@type':
                type: string
                example: Ticket
              identifier:
                type: string
                format: uuid
                description: Price UUID
              ticketQuantity:
                type: integer
              price:
                type: string
                description: Optional custom amount for free price
        additionalProperty:
          type: array
          items:
            type: object
            properties:
              '@type':
                type: string
                example: PropertyValue
              name:
                type: string
                example: confirmed
              value:
                oneOf:
                  - type: boolean
                  - type: string
                  - type: object
                  - type: array
                    items:
                      type: string
    Reservation:
      type: object
      description: schema.org/Reservation output
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: Reservation
        identifier:
          type: string
          format: uuid
        reservationFor:
          type: object
          properties:
            '@type':
              type: string
              example: Event
            identifier:
              type: string
              format: uuid
            name:
              type: string
        underName:
          type: object
          properties:
            '@type':
              type: string
              example: Person
            email:
              type: string
              format: email
        reservationStatus:
          type: string
          example: https://schema.org/ReservationConfirmed
        reservedTicket:
          type: array
          items:
            type: object
            properties:
              '@type':
                type: string
                example: Ticket
              identifier:
                type: string
                format: uuid
              ticketQuantity:
                type: integer
    ProgramMembershipCreate:
      type: object
      description: schema.org/ProgramMembership input for creation
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: ProgramMembership
        member:
          type: object
          properties:
            '@type':
              type: string
              example: Person
            email:
              type: string
              format: email
            givenName:
              type: string
            familyName:
              type: string
        membershipPlan:
          type: object
          properties:
            '@type':
              type: string
              example: Offer
            identifier:
              type: string
              format: uuid
              description: Price UUID
        validUntil:
          type: string
          format: date-time
        additionalProperty:
          type: array
          items:
            type: object
            properties:
              '@type':
                type: string
                example: PropertyValue
              name:
                type: string
                example: paymentMode
              value:
                oneOf:
                  - type: string
                  - type: object
                  - type: array
                    items:
                      type: string
    ProgramMembership:
      type: object
      description: schema.org/ProgramMembership output
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: ProgramMembership
        identifier:
          type: string
          format: uuid
        member:
          type: object
          properties:
            '@type':
              type: string
              example: Person
            email:
              type: string
              format: email
            givenName:
              type: string
            familyName:
              type: string
        membershipPlan:
          type: object
          properties:
            '@type':
              type: string
              example: Offer
            identifier:
              type: string
              format: uuid
            name:
              type: string
        validUntil:
          type: string
          format: date-time
    ProductFormFieldInput:
      type: object
      description: Dynamic field definition for product forms
      properties:
        label:
          type: string
          example: Nom
        fieldType:
          type: string
          example: shortText
        required:
          type: boolean
        options:
          type: array
          items:
            type: string
        order:
          type: integer
        helpText:
          type: string
    Product:
      type: object
      description: schema.org/Product representation used for sales lines
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: Product
        name:
          type: string
        description:
          type: string
          nullable: true
        image:
          type: string
          format: uri
          nullable: true
        category:
          type: string
          description: Human-readable product category
        sku:
          type: string
          description: Product UUID
        identifier:
          type: string
          description: Product UUID (alias)
        offers:
          $ref: '#/components/schemas/Offer'
        additionalProperty:
          type: array
          items:
            $ref: '#/components/schemas/PropertyValue'
    Offer:
      type: object
      properties:
        '@type':
          type: string
          example: Offer
        identifier:
          type: string
          format: uuid
          description: Price UUID when listing Product offers
        price:
          type: string
          description: Unit price including VAT, as string
          example: "10.00"
        priceCurrency:
          type: string
          example: EUR
    PropertyValue:
      type: object
      properties:
        '@type':
          type: string
          example: PropertyValue
        name:
          type: string
        value:
          type: string
    ItemList:
      type: object
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: ItemList
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        itemListElement:
          type: array
          items:
            $ref: '#/components/schemas/Product'
    MoneyTransfer:
      type: object
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: MoneyTransfer
        identifier:
          type: string
          format: uuid
          description: Fedow transaction UUID
        amount:
          type: integer
          description: Credited token amount in raw unit
          example: 500
        asset:
          type: string
          format: uuid
          description: Refillable asset UUID (TNF/TIM/FID/BDG)
        recipient:
          type: object
          properties:
            '@type':
              type: string
              example: Person
            email:
              type: string
              format: email