Newstore orders API

openapi: 3.2.0
info:
  version: '1.0'
  title: NewStore Orders 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: orders
  description: Fiscal orders
paths:
  /orders/{orderId}:
    get:
      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\nGet fiscal transactions and signatures for an order (sale or exchange). \n  This API should be used to get the fiscal transaction for returned items that were part of an exchange.\n  Based on the country, the transactions array in the response for exchanges will contain one of the following:\n  * 1 `exchange` transaction that represents both the returned and the sold part of the exchanged items.\n  * 2 transactions, 1 `sale` transactions and `return` transaction each representing their respective parts of the exchanged items."
      summary: showOrder
      tags:
      - orders
      operationId: showOrder
      deprecated: false
      parameters:
      - name: orderId
        in: path
        required: true
        description: ''
        schema:
          type: string
      - name: state
        in: query
        required: false
        description: Order state.
        schema:
          type: string
          enum:
          - OK
          - FAILED
      - name: transaction_state
        in: query
        required: false
        description: Fiscal transaction state.
        schema:
          type: string
          enum:
          - OK
          - FAILED
          - TEMP_SIGNED
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: ''
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/SignatureResponseV1Dto'
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureResponseV1Dto'
        '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: 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:
        - fiscalization:orders:read
  /orders/{orderId}/returns/{returnId}:
    get:
      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\nGet fiscal transactions and signatures for an item return. \n    This API covers returns that are not part of an exchange. For getting the return part of the exchange use the GET `/orders/{orderId}` API"
      summary: showReturn
      tags:
      - orders
      operationId: showReturn
      deprecated: false
      parameters:
      - name: orderId
        in: path
        required: true
        description: ''
        schema:
          type: string
      - name: returnId
        in: path
        required: true
        description: ''
        schema:
          type: string
      - name: state
        in: query
        required: false
        description: Order state.
        schema:
          type: string
          enum:
          - OK
          - FAILED
      - name: transaction_state
        in: query
        required: false
        description: Fiscal transaction state.
        schema:
          type: string
          enum:
          - OK
          - FAILED
          - TEMP_SIGNED
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: ''
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/SignatureResponseV1Dto'
            application/json:
              schema:
                $ref: '#/components/schemas/SignatureResponseV1Dto'
        '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: 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:
        - fiscalization:orders:read
components:
  schemas:
    FiscalMode:
      title: FiscalMode
      description: 'Fiscal mode.

        * Defaults to `standard` if not provided.'
      example: standard
      type: string
      enum:
      - standard
      - offline
    TransactionSignatureStrategy:
      title: TransactionSignatureStrategy
      description: "Offline transaction signature strategy that will be used while processing offline transactions.\n* `standard-signing`\n\n\n  * Offline orders will be fiscally signed according to regulations.\n  * Can be used in cases if the receipt would be emailed once the offline order is processed.\n* `late-signing`\n\n\n  * Offline orders will be signed with late signing flag.\n  * Can be used in cases if the receipt would be emailed once the offline order is processed.\n* `manual-receipts`\n\n\n  * Offline orders will be signed with manual flag.\n  * A receipt for the offline orders and do not need to be emailed later.\n  * Can be used in cases if the a manual receipt was issued by the store, and an electronic receipt should not be sent.\n* `no-signing`\n\n\n  * Offline orders will not be signed and should be considered completed without any signature needed.\n  * Can be used in cases if the fiscal signature was issued outside of the NewStore platform."
      example: no-signing
      type: string
      enum:
      - standard-signing
      - late-signing
      - manual-receipts
      - no-signing
    ContextV1Dto:
      title: ContextV1Dto
      type: object
      properties:
        associate_created_at:
          description: Associate creation timestamp.
          example: '2021-01-19T09:57:01.112Z'
          type: string
          format: date-time
        associate_id:
          description: Associate ID.
          example: 012345678-abcd-0123-abcd-0123456789ab
          type: string
        associate_name:
          example: Peter Smith
          type: string
        cashbox_id:
          description: 'Cashbox ID for which fiscal transaction is executed.

            * Used in multi-cashbox stores.'
          example: 012345678-abcd-0123-abcd-0123456789ab
          type: string
        store_id:
          description: Store ID where fiscal transaction is executed.
          example: 494362b0-5240-4a94-ad1c-74407b005310
          type: string
      required:
      - associate_id
      - store_id
    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
    OrderManagementState:
      title: OrderManagementState
      description: Order state.
      example: OK
      type: string
      enum:
      - OK
      - FAILED
    TransactionMinV1Dto:
      title: TransactionMinV1Dto
      type: object
      properties:
        country_code:
          type: string
        id:
          description: Transaction ID.
          type: string
        signature:
          description: Transaction signature.
        state:
          $ref: '#/components/schemas/TransactionState'
        temporary_signature:
          description: Temporary transaction signature.
        transaction_number:
          description: Sequential transaction number.
          type: integer
          format: int32
        transaction_series:
          description: Transaction series (if defined).
          type: string
        type:
          $ref: '#/components/schemas/F11nTransactionType'
      required:
      - country_code
      - id
      - state
      - temporary_signature
      - transaction_number
      - type
    F11nTransactionType:
      title: F11nTransactionType
      description: Transaction type.
      example: sale
      type: string
      enum:
      - sale
      - return
      - exchange
      - cancellation
      - void
      - create_void
      - foreign_sale
      - foreign_return
      - foreign_exchange
      - foreign_cancellation
      - create_x_report
      - create_z_report
      - manual_create_report
      - document_printed
      - document_emailed
      - cash_drawer_transaction
    F11nTaxMethod:
      title: F11nTaxMethod
      description: Defines the tax method used (tax inclusive or exclusive).
      example: tax_included
      type: string
      enum:
      - tax_included
      - tax_excluded
    SignatureResponseV1Dto:
      title: SignatureResponseV1Dto
      type: object
      properties:
        context:
          type: object
          allOf:
          - $ref: '#/components/schemas/ContextV1Dto'
          - description: Context.
        country_code:
          type: string
        created_at:
          description: Signature creation timestamp to be used on the receipt.
          type: string
          format: date-time
        external_order_id:
          description: Sales order identifier used in external system.
          example: GD000225827
          type: string
        fiscal_mode:
          $ref: '#/components/schemas/FiscalMode'
        id:
          description: ID (idempotency key).
          example: 012345678-abcd-0123-abcd-0123456789ab
          type: string
        original_created_at:
          description: 'Transaction creation timestamp.

            * If set, will override the fiscal transaction timestamp.'
          example: '2022-05-25T12:00:00.000Z'
          type: string
        reference_order_id:
          description: ID of a reference order (e.g. referencing an original order).
          example: 012345678-abcd-0123-abcd-0123456789ab
          type: string
        signature_strategy_override:
          $ref: '#/components/schemas/TransactionSignatureStrategy'
        state:
          $ref: '#/components/schemas/OrderManagementState'
        tax_method:
          $ref: '#/components/schemas/F11nTaxMethod'
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/TransactionMinV1Dto'
        updated_at:
          description: Signature update timestamp.
          type: string
          format: date-time
      required:
      - context
      - country_code
      - created_at
      - id
      - state
      - transactions
      - updated_at
    TransactionState:
      title: TransactionState
      description: Fiscal transaction state.
      example: OK
      type: string
      enum:
      - OK
      - FAILED
      - TEMP_SIGNED
  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