OpenAPI Specification
swagger: '2.0'
info:
version: '1.0'
title: NewStore address orders API
description: NewStore public APIs
contact:
email: support@newstore.com
name: NewStore API Support
url: https://developer.newstore.com
host: dodici-demo.p.newstore.net
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json
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
produces:
- application/problem+json
- application/json
parameters:
- name: orderId
in: path
required: true
type: string
description: ''
- name: state
in: query
required: false
enum:
- OK
- FAILED
type: string
description: Order state.
- name: transaction_state
in: query
required: false
enum:
- OK
- FAILED
- TEMP_SIGNED
type: string
description: Fiscal transaction state.
responses:
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'200':
description: ''
schema:
$ref: '#/definitions/SignatureResponseV1Dto'
headers: {}
'401':
description: Unauthorized.
schema:
$ref: '#/definitions/Problem'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Not found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
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
produces:
- application/problem+json
- application/json
parameters:
- name: orderId
in: path
required: true
type: string
description: ''
- name: returnId
in: path
required: true
type: string
description: ''
- name: state
in: query
required: false
enum:
- OK
- FAILED
type: string
description: Order state.
- name: transaction_state
in: query
required: false
enum:
- OK
- FAILED
- TEMP_SIGNED
type: string
description: Fiscal transaction state.
responses:
default:
description: Unexpected error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'200':
description: ''
schema:
$ref: '#/definitions/SignatureResponseV1Dto'
headers: {}
'401':
description: Unauthorized.
schema:
$ref: '#/definitions/Problem'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Not found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- fiscalization:orders:read
definitions:
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
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
maximum: 600.0
exclusiveMaximum: true
format: int32
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
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
FiscalMode:
title: FiscalMode
description: 'Fiscal mode.
* Defaults to `standard` if not provided.'
example: standard
type: string
enum:
- standard
- offline
SignatureResponseV1Dto:
title: SignatureResponseV1Dto
type: object
properties:
context:
type: object
allOf:
- $ref: '#/definitions/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: '#/definitions/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: '#/definitions/TransactionSignatureStrategy'
state:
$ref: '#/definitions/OrderManagementState'
tax_method:
$ref: '#/definitions/F11nTaxMethod'
transactions:
type: array
items:
$ref: '#/definitions/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
TransactionMinV1Dto:
title: TransactionMinV1Dto
type: object
properties:
country_code:
type: string
id:
description: Transaction ID.
type: string
signature:
description: Transaction signature.
state:
$ref: '#/definitions/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: '#/definitions/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
securityDefinitions:
oauth:
type: oauth2
flow: application
tokenUrl: https://id.p.newstore.net/auth/realms/dodici-demo/protocol/openid-connect/token
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