Newstore fulfillment-requests API

openapi: 3.2.0
info:
  version: '1.0'
  title: NewStore Fulfillment Requests 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: fulfillment-requests
  description: Fulfillment Requests
paths:
  /v0/fulfillment_request/{ffr_uuid}/set_items_states:
    post:
      description: 'Update the shipment status for items in the specified fulfillment request.


        **Important:** Do not confuse this API with

        [Fulfillment Provider API](/newstore-cloud/order_management/dc_fulfillment_node_api.html). For

        DC orders please use the Fulfillment Provider API.


        Items in a fulfillment request can be marked as shipped or rejected. When you use this API you can''t mix

        shipment and rejection actions on the same call.


        **Important:** If you are doing a partial rejection of items in a fulfillment request, the reroute

        attempt will not happen until all items in the fulfillment request are in a terminal state.


        For fulfillment requests which are routed to store fulfillment nodes, the item state update

        will only be accepted if the request has not been picked by a store associate. The change in

        status is only valid for items that are not in a final state (the fulfillment process for the

        item is considered as complete). The remaining items are not

        affected by this change.


        **Important**: When you reject items that are currently fulfilled in DC we don''t notify DC about items rejection.

        You are responsible for communicating with DC API to ensure these items will not be shipped.


        **Rejection reason**:


        For fulfillment requests which are routed to store fulfillment nodes, to reject a fulfillment request you must provide the rejection reason "rescinded". This will initiate

        a re-routing attempt without any changes to inventory levels.


        **Edge Cases:**

        - If your organization''s settings allows rerouting by setting `reroute_to_rejected_fulfillment_nodes` (

        described in this

        [API](https://docs.newstore.net/api/configuration/inventory-fulfillment/logistic_order_config#operation/set-reroute-to-rejected-fulfillment-nodes))

        to `true`, rejected fulfillment nodes will be downgraded in priority during the routing process. If all possible

        nodes for a given `location_group` in [routing configuration](https://docs.newstore.net/api/integration/delivery/routing_ruleset_api#operation/get-routing-rules)

        are exhausted, it will take the first available fulfillment node as part of the mechanism, resulting in a

        potential route to the same location on further attempts.

        - Setting `reroute_to_rejected_fulfillment_nodes` to `false`, fulfillment nodes will be ignored during future

        routing attempts. If all fulfillment nodes are rejected and you don''t want to reroute to these nodes, the

        rejected items will be put on hold.


        **Important**: The platform emits a separate event for each line item that is marked as

        shipped, and not a single event for all items. This should be considered when reconciling these

        events in the ERP you are using to manage such events.

        '
      summary: updateFulfillmentRequestItemStates
      tags:
      - fulfillment-requests
      operationId: updateFulfillmentRequestItemStates
      deprecated: false
      parameters:
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      - name: ffr_uuid
        in: path
        required: true
        description: ''
        schema:
          type: string
      responses:
        default:
          description: Unexpected error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '204':
          description: Operation succeeded
          headers: {}
        '400':
          description: Bad Request Error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Not found Error.
          headers: {}
          content:
            application/problem+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'
        '500':
          description: Internal Server Error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FulfillmentRequestItemsStatesRequest'
        required: true
  /v0/fulfillment_requests/{order_uuid}:
    get:
      description: "\n<div style=\"background-color: rgba(23, 162, 184, 0.15); border: 1px solid #17a2b8; border-left: 4px solid #17a2b8; padding: 12px; margin: 10px 0; border-radius: 4px; color: #17a2b8;\">\n  <strong>ℹ️ Rate Limit:</strong> This endpoint is rate limited to 70 requests per second.\n</div>\n\nReturns all fulfillment requests created for an order, sorted by creation date in the\nascending order (earliest first).\n\nIf order wasn't found, then the empty list of fulfillment requests will be returned.\n\nIf order wasn't routed yet, then the empty list of fulfillment requests will be returned.\n\n**Important:** As for now this API will return fulfillment requests even for orders without\nrouting (like in_store_purchase) but this behavior will change soon. And this API will only\nwork for orders where routing is needed. So, build your integrations accordingly.\n\n**Important:** Maximum number of fulfillment requests this API will return is **2000**. If\nthere are more than **2000** fulfillment requests for the order, then the response will have\n400 status code (although it is actually not a bad request) and **2000** latest (according\nto the creaiton date) fulfillment requests.\n"
      summary: listFulfillmentRequestsForOrder
      tags:
      - fulfillment-requests
      operationId: listFulfillmentRequestsForOrder
      deprecated: false
      parameters:
      - name: order_uuid
        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: Successful response
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/OrderFulfillmentRequestsResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/OrderFulfillmentRequestsResponse'
        '400':
          description: Order has too many fulfillment requests
          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: An internal error occurred.
          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: []
components:
  schemas:
    OrderFulfillmentRequestsResponse:
      title: OrderFulfillmentRequestsResponse
      description: Fulfillment requests for an order
      type: object
      properties:
        fulfillment_requests:
          description: All fulfillment requests that belongs to the order. Can be empty if order not routed yet, or if order doesn't exist.
          type: array
          items:
            $ref: '#/components/schemas/FulfillmentRequest'
          maxItems: 2000
      required:
      - fulfillment_requests
    FulfillmentRequest:
      title: FulfillmentRequest
      description: The fulfillment request.
      type: object
      properties:
        created_at:
          description: Date and time when fulfillment request was created.
          type: string
          format: date-time
        fulfillment_node_id:
          description: Fulfillment node where fulfillment request was routed to.
          type: string
          minLength: 1
        fulfillment_request_id:
          description: The identifier of the fulfillment request.
          type: string
          minLength: 1
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item8'
          minItems: 1
        service_level:
          description: Service level fulfillment request was routed with.
          type: string
          minLength: 1
        status:
          type: object
          allOf:
          - $ref: '#/components/schemas/Status11'
          - description: 'Current status of fulfillment request: dispatched - fulfillment request was sent to sent to store/DC services, but wasn''t acknowledged yet; acknowledged - fulfillment request was acknowledged by store/DC service and will be send to store/DC for fulfillment; partially_completed - some items of fulfillment request were already processed (cancelled, rejected, shipped) but not all of them; completed - all items of fulfillment request were processed (cancelled, rejected, shipped).'
      required:
      - created_at
      - fulfillment_node_id
      - fulfillment_request_id
      - items
      - service_level
      - status
    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
    State:
      title: State
      description: New state that should be applied to this item defined by sales order item UUID.
      type: string
      enum:
      - shipped
      - rejected
    Status11:
      title: Status11
      description: 'Current status of fulfillment request: dispatched - fulfillment request was sent to sent to store/DC services, but wasn''t acknowledged yet; acknowledged - fulfillment request was acknowledged by store/DC service and will be send to store/DC for fulfillment; partially_completed - some items of fulfillment request were already processed (cancelled, rejected, shipped) but not all of them; completed - all items of fulfillment request were processed (cancelled, rejected, shipped).'
      type: string
      enum:
      - dispatched
      - acknowledged
      - partially_completed
      - completed
    FulfillmentRequestItemsStatesRequest:
      title: FulfillmentRequestItemsStatesRequest
      description: Request payload for marking fulfillment request items as shipped or rejected.
      type: object
      properties:
        associate_id:
          description: Identifier of the associate who is changing the items's states.
          type: string
          minLength: 1
        carrier:
          description: Carrier used to ship items, which state is being changed to `shipped`.
          type: string
        line_items:
          description: List of fulfillment request items with the target state.
          type: array
          items:
            $ref: '#/components/schemas/LineItem11'
        reason: {}
        tracking_code:
          description: Tracking code applied to items, which state is being changed to `shipped`.
          type: string
          minLength: 1
      required:
      - line_items
    Status2:
      title: Status2
      description: 'Status of this item: dispatched - item was routed to a store/DC (check status of fulfillment request to see whether DC/store service has already accepted this fulfillment request or not); shipped - item was marked as shipped; rejected - item was rejected by fulfillment node and going to be rerouted (or was rerouted if fulfillment request already completed); cancelled - item was cancelled.'
      type: string
      enum:
      - dispatched
      - shipped
      - rejected
      - cancelled
    LineItem11:
      title: LineItem11
      description: Line item
      type: object
      properties:
        item_id:
          description: Sales order item UUID.
          type: string
          format: uuid
        state:
          type: object
          allOf:
          - $ref: '#/components/schemas/State'
          - description: New state that should be applied to this item defined by sales order item UUID.
      required:
      - item_id
      - state
    Item8:
      title: Item8
      type: object
      properties:
        carrier:
          description: Carrier for the item, if it was provided during after shipment. Otherwise `null`.
          type: string
        item_id:
          description: Unique identifier of the line item.
          type: string
          minLength: 1
        product_id:
          type: string
          minLength: 1
        status:
          type: object
          allOf:
          - $ref: '#/components/schemas/Status2'
          - description: 'Status of this item: dispatched - item was routed to a store/DC (check status of fulfillment request to see whether DC/store service has already accepted this fulfillment request or not); shipped - item was marked as shipped; rejected - item was rejected by fulfillment node and going to be rerouted (or was rerouted if fulfillment request already completed); cancelled - item was cancelled.'
        tracking_code:
          description: Tracking code for the item, if it was provided after shipment. Otherwise `null`.
          type: string
      required:
      - carrier
      - item_id
      - product_id
      - status
      - tracking_code
  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