Newstore cashboxes API

openapi: 3.2.0
info:
  version: '1.0'
  title: NewStore Cashboxes API
  description: NewStore public APIs
  contact:
    email: support@newstore.com
    name: NewStore API Support
    url: https://developer.newstore.com
servers:
- url: https://dodici-demo.p.newstore.net/
security: []
tags:
- name: cashboxes
  description: Fiscal cashboxes
paths:
  /stores/{storeId}/cashboxes:
    get:
      description: List cashboxes for the given store identifier.
      summary: listCashboxes
      tags:
      - cashboxes
      operationId: listCashboxes
      deprecated: false
      parameters:
      - name: storeId
        in: path
        required: true
        description: ''
        schema:
          type: string
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: List of cashboxes.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CashboxListV1Dto'
            application/json:
              schema:
                $ref: '#/components/schemas/CashboxListV1Dto'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:read
    post:
      description: Activate cashbox by using the given cashbox configuration for the given store identifier.
      summary: createCashbox
      tags:
      - cashboxes
      operationId: createCashbox
      deprecated: false
      parameters:
      - name: storeId
        in: path
        required: true
        description: ''
        schema:
          type: string
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: Cashbox that was activated.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CashboxCreatedV1Dto'
            application/json:
              schema:
                $ref: '#/components/schemas/CashboxCreatedV1Dto'
        '400':
          description: Bad request.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Cashbox was already activated.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashboxCreateV1Dto'
        required: true
  /stores/{storeId}/cashboxes/{cashboxId}:
    get:
      description: Get cashbox for the given store and cashbox identifiers.
      summary: showCashbox
      tags:
      - cashboxes
      operationId: showCashbox
      deprecated: false
      parameters:
      - name: storeId
        in: path
        required: true
        description: ''
        schema:
          type: string
      - name: cashboxId
        in: path
        required: true
        description: ''
        schema:
          type: string
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: Cashbox.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CashboxGetV1Dto'
            application/json:
              schema:
                $ref: '#/components/schemas/CashboxGetV1Dto'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Cashbox not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:read
  /stores/{storeId}/cashboxes/{cashboxId}/release:
    post:
      description: "\n<div style=\"background-color: rgba(243, 156, 18, 0.15); border: 1px solid #f39c12; border-left: 4px solid #f39c12; padding: 12px; margin: 10px 0; border-radius: 4px; color: #f39c12;\">\n  <strong>\U0001F6A7 BETA:</strong> This endpoint is in beta and may change.\n  <br />\n  See <a href=\"https://docs.newstore.com/docs/api-lifecycle\" target=\"_blank\" style=\"color: #f39c12; text-decoration: underline;\">API Lifecycle Documentation</a> for details.\n</div>\n\n[Italy] Create a release for the deactivated fiscal printer so it can be reassigned to another tenant or store."
      summary: createCashboxRelease
      tags:
      - cashboxes
      operationId: createCashboxRelease
      deprecated: false
      parameters:
      - name: storeId
        in: path
        required: true
        description: ''
        schema:
          type: string
      - name: cashboxId
        in: path
        required: true
        description: ''
        schema:
          type: string
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: Cashbox that was released for reassignment.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CashboxV1Dto'
            application/json:
              schema:
                $ref: '#/components/schemas/CashboxV1Dto'
        '400':
          description: Bad request.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Cashbox not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Cashbox cannot be released.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CashboxReleaseV1Dto'
        required: true
components:
  schemas:
    CashboxState:
      title: CashboxState
      description: The state of the cashbox, whether it is activated or deactivated.
      example: activated
      type: string
      enum:
      - activated
      - deactivated
    CashboxListV1Dto:
      title: CashboxListV1Dto
      type: object
      properties:
        items:
          description: List of cashboxes.
          type: array
          items:
            $ref: '#/components/schemas/CashboxV1Dto'
      required:
      - items
    FiscalProviderId:
      title: FiscalProviderId
      description: The fiscal provider id being used.
      example: axena-se
      type: string
      enum:
      - axena-se
      - dummy
      - epson-it
      - fiskaltrust-at
      - fiskaltrust-de
      - fiskaltrust-fr
      - newstore-ie
      - newstore-no
      - posnet-pl
      - ycs-pr
      - newstore-in
      - newstore-th
      - newstore-es
      - newstore-be
      - efsta-pt
    CashboxCreatedV1Dto:
      title: CashboxCreatedV1Dto
      type: object
      properties:
        activated_at:
          description: Timestamp of the cashbox activation.
          type: string
          format: date-time
        config:
          description: Fiscal provider configuration.
        deactivated_at:
          description: Timestamp of the cashbox deactivation.
          type: string
          format: date-time
        fiscal_provider_id:
          $ref: '#/components/schemas/FiscalProviderId'
        id:
          description: Cashbox identifier.
          example: dodici-f9ab99c2-d4ba-4752-ac9b-20e5cbeba82a-1
          type: string
        state:
          $ref: '#/components/schemas/CashboxState'
        store_id:
          description: Store identifier that the cashbox belongs to.
          example: f9ab99c2-d4ba-4752-ac9b-20e5cbeba82a
          type: string
        tenant:
          description: Tenant identifier.
          example: dodici
          type: string
        warning_codes:
          description: List of warning codes that were indicated by the fiscal provider during fiscal activation.
          type: array
          items:
            $ref: '#/components/schemas/F11nWarningCode'
          maxItems: 3
      required:
      - activated_at
      - config
      - fiscal_provider_id
      - id
      - state
      - store_id
      - tenant
    F11nWarningCode:
      title: F11nWarningCode
      description: Fiscalization warning codes that are propagated to the clients (e.g. Associate App) for providing information on possible action items.
      example: f11n_fiscal_printer_paper_running_out
      type: string
      enum:
      - f11n_fiscal_printer_paper_running_out
      - f11n_fiscal_printer_charger_disconnected
      - f11n_fiscal_printer_fiscal_memory_nearly_full
    Problem:
      title: Problem
      type: object
      properties:
        detail:
          description: A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: some description for the error situation
          type: string
        error_code:
          type: string
        instance:
          description: A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.
          example: /some/uri-reference#specific-occurrence-context
          type: string
        message:
          type: string
        messages:
          type: array
          items:
            type: string
        request_id:
          type: string
        status:
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          type: integer
          minimum: 100.0
          format: int32
          exclusiveMaximum: 600.0
        title:
          description: A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: some title for the error situation
          type: string
        type:
          description: A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferenceable and point to a human-readable documentation nor globally unique for the problem type.
          example: /some/uri-reference
          type: string
          default: about:blank
    CashboxV1Dto:
      title: CashboxV1Dto
      type: object
      properties:
        activated_at:
          description: Timestamp of the cashbox activation.
          type: string
          format: date-time
        config:
          description: Fiscal provider configuration.
        deactivated_at:
          description: Timestamp of the cashbox deactivation.
          type: string
          format: date-time
        fiscal_provider_id:
          $ref: '#/components/schemas/FiscalProviderId'
        id:
          description: Cashbox identifier.
          example: dodici-f9ab99c2-d4ba-4752-ac9b-20e5cbeba82a-1
          type: string
        state:
          $ref: '#/components/schemas/CashboxState'
        store_id:
          description: Store identifier that the cashbox belongs to.
          example: f9ab99c2-d4ba-4752-ac9b-20e5cbeba82a
          type: string
        tenant:
          description: Tenant identifier.
          example: dodici
          type: string
      required:
      - activated_at
      - config
      - fiscal_provider_id
      - id
      - state
      - store_id
      - tenant
    CashboxGetV1Dto:
      title: CashboxGetV1Dto
      type: object
      properties:
        activated_at:
          description: Timestamp of the cashbox activation.
          type: string
          format: date-time
        config:
          description: Fiscal provider configuration.
        deactivated_at:
          description: Timestamp of the cashbox deactivation.
          type: string
          format: date-time
        fiscal_provider_id:
          $ref: '#/components/schemas/FiscalProviderId'
        id:
          description: Cashbox identifier.
          example: dodici-f9ab99c2-d4ba-4752-ac9b-20e5cbeba82a-1
          type: string
        state:
          $ref: '#/components/schemas/CashboxState'
        store_id:
          description: Store identifier that the cashbox belongs to.
          example: f9ab99c2-d4ba-4752-ac9b-20e5cbeba82a
          type: string
        tenant:
          description: Tenant identifier.
          example: dodici
          type: string
        transaction_series:
          description: The series used to generate the transaction sequence numbers. This field will have a value only for cashboxes that support multiple series otherwise it will be an empty array.
          example:
          - S24-ABCDE
          - R24-ABCDE
          type: array
          items:
            type: string
      required:
      - activated_at
      - config
      - fiscal_provider_id
      - id
      - state
      - store_id
      - tenant
      - transaction_series
    CashboxCreateV1Dto:
      title: CashboxCreateV1Dto
      type: object
      properties:
        config:
          description: Fiscal provider configuration.
        fiscal_provider_id:
          $ref: '#/components/schemas/FiscalProviderId'
      required:
      - config
      - fiscal_provider_id
    CashboxReleaseV1Dto:
      title: CashboxReleaseV1Dto
      type: object
      properties:
        acknowledge_fiscal_printer_reset:
          description: Confirmation that the fiscal printer was deactivated/reset by an authorised technician and is legally ready to be reassigned to another store. NewStore does not perform or verify the fiscal/legal deregistration; the retailer is responsible for completing all applicable fiscal authority requirements first.
          type: boolean
      required:
      - acknowledge_fiscal_printer_reset
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            catalog:import-schemas:read: Grants privileges to read import schema
            catalog:import-schemas:write: Grants privileges to write import schema
            catalog:pricebook-export:read: Grants privileges to export pricebook data
            catalog:product-export:read: Grants privileges to export product data
            checkout:carts:read: Grants privileges to read cart data
            checkout:carts:write: Grants privileges to write cart data
            clienteling:profile:read: Grants privileges to read clienteling profiles
            customer:profile:read: Grants privileges to read API customer data
            customer:profile:write: Grants privileges to modify API customer data
            newstore:configuration:read: Grants privileges to read configuration
            newstore:configuration:write: Grants privileges to write configuration
            fiscalization:orders:read: View orders with fiscal transactions and signatures
            fiscalization:orders:write: Create orders with fiscal transactions and signatures
            shipments:read: Read Shipping Options and Audits
            iam:providers:read: ' Grants read privileges to provider resources'
            iam:providers:write: ' Grants write privileges to provider resources'
            iam:roles:read: ' Grants privileges to read roles data'
            iam:roles:write: ' Grants privileges to write roles data'
            iam:users:read: ' Grants privileges to read user data'
            iam:users:write: ' Grants privileges to write user data'
            inventory:reservations:read: Allows access to retrieve reservations
            inventory:reservations:write: Allows access to create and update reservations
            promotions:config:read: Grants privileges to read configuration
            promotions:config:write: Grants privileges to write into configuration
            promotions:reason-codes:read: Grants privileges to list reason codes
            promotions:reason-codes:write: Grants privileges to create and update reason codes
            audit-events:read: Grants read access to the tenant's audit events.
            taxes:preview-transactions:write: Preview tax transactions
            taxes:transactions:read: Read tax transactions
          tokenUrl: https://id.p.newstore.net/auth/realms/dodici-demo/protocol/openid-connect/token