Receive version v1

https://github.com/folio-org/mod-orders

Orders Business Logic API

API for receiving pieces

Receive items

Receive items spanning one or more PO lines. The endpoint is used to:

  • receive pieces and associated inventory items
  • move a received piece back to "Expected" in case "receivedItems" element's "itemStatus" is "On order"

post

post

Receive items spanning one or more PO lines

Receive items spanning one or more PO lines

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A collection of receiving items",
  "type": "object",
  "properties": {
    "toBeReceived": {
      "description": "List of receivings",
      "id": "toBeReceived",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "poLineId": {
            "description": "The id of the receiving PO line",
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
          },
          "received": {
            "description": "The number of items received",
            "type": "integer"
          },
          "receivedItems": {
            "description": "List of receiving items details",
            "id": "receivedItems",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "barcode": {
                  "description": "The barcode assigned to the item",
                  "type": "string"
                },
                "callNumber": {
                  "description": "The call number assigned to the piece",
                  "type": "string"
                },
                "comment": {
                  "description": "The free form notes pertaining to this item",
                  "type": "string"
                },
                "displaySummary": {
                  "description": "Display summary of the item",
                  "type": "string"
                },
                "itemStatus": {
                  "description": "The status of the item",
                  "$schema": "http://json-schema.org/draft-04/schema#",
                  "type": "string",
                  "enum": [
                    "In process",
                    "On order",
                    "Available",
                    "In transit",
                    "Order closed",
                    "Aged to lost",
                    "Awaiting pickup",
                    "Awaiting delivery",
                    "Checked out",
                    "Claimed returned",
                    "Declared lost",
                    "In process (non-requestable)",
                    "Intellectual item",
                    "Long missing",
                    "Lost and paid",
                    "Missing",
                    "Paged",
                    "Restricted",
                    "Unavailable",
                    "Unknown",
                    "Withdrawn"
                  ],
                  "default": "In process"
                },
                "locationId": {
                  "description": "The id of the location",
                  "type": "string",
                  "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
                },
                "holdingId": {
                  "description": "UUID of the holding record",
                  "$schema": "http://json-schema.org/draft-04/schema#",
                  "type": "string",
                  "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
                },
                "displayOnHolding": {
                  "description": "Whether or not receiving history should be displayed in holding record view",
                  "type": "boolean",
                  "default": false
                },
                "enumeration": {
                  "type": "string",
                  "description": "Enumeration is the descriptive information for the numbering scheme of a serial. Synchronized with inventory item."
                },
                "chronology": {
                  "type": "string",
                  "description": "Chronology is the descriptive information for the dating scheme of a serial. Synchronized with inventory item."
                },
                "copyNumber": {
                  "type": "string",
                  "description": "Copy number of the piece"
                },
                "pieceId": {
                  "description": "UUID of this piece record",
                  "type": "string",
                  "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
                }
              },
              "required": [
                "pieceId"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "poLineId"
        ],
        "additionalProperties": false
      }
    },
    "totalRecords": {
      "description": "The total number of receiving items in the list",
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "toBeReceived",
    "totalRecords"
  ]
}

Example:

{
  "toBeReceived": [
    {
      "poLineId": "0804ddec-6545-404a-b54d-a693f505681d",
      "received": 2,
      "receivedItems": [
        {
          "barcode": "0987654321",
          "callNumber": "PR 8923 W6 L36 1990 c.3",
          "comment": "Very important note",
          "displaySummary": "Vol. 1",
          "itemStatus": "In process",
          "locationId": "eb2d063a-5b4c-4cab-8db1-5fc5c5941df6",
          "pieceId": "c18c49b7-d970-44d6-b5d4-bd76c1c62d83"
        },
        {
          "barcode": "0987654111",
          "callNumber": "BF2050 .M335 1999",
          "comment": "Very important note",
          "displaySummary": "Vol. 2",
          "itemStatus": "In process",
          "holdingId": "df798357-0bda-4ad4-b0a3-86f5edec3703",
          "pieceId": "cb9b0468-f2b4-4a13-b64c-662c4c9ec3ed"
        }
      ]
    },
    {
      "poLineId": "7f0c4975-885e-47d5-8d5a-793dffbba9b2",
      "received": 1,
      "receivedItems": [
        {
          "barcode": "0987654333",
          "callNumber": "PR 8923 W6 L36 1990 c.4",
          "comment": "Very important note",
          "displaySummary": "Vol. 286",
          "itemStatus": "In transit",
          "locationId": "279f42ce-17d1-463e-b890-deeebd1baeee",
          "pieceId": "20241b8c-9076-4cf5-817b-f2c1e2cb242f"
        }
      ]
    }
  ],
  "totalRecords": 3
}

HTTP status code 200

Returns processing result of the receive

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A collection of receiving results",
  "type": "object",
  "properties": {
    "receivingResults": {
      "description": "List of receiving/checkin results",
      "id": "receivingResults",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "poLineId": {
            "description": "The id of the receiving/checkin po line",
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
          },
          "processedSuccessfully": {
            "description": "The number of items processed successfully",
            "type": "integer"
          },
          "processedWithError": {
            "description": "The number of items processed with error",
            "type": "integer"
          },
          "receivingItemResults": {
            "description": "List of processed receiving item details",
            "id": "receivingItemResults",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "pieceId": {
                  "description": "UUID of this piece record",
                  "type": "string",
                  "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
                },
                "processingStatus": {
                  "description": "The status describing item processing result",
                  "type": "object",
                  "properties": {
                    "type": {
                      "description": "Resulting status of the processed piece record",
                      "type": "string",
                      "enum": [
                        "success",
                        "failure"
                      ]
                    },
                    "error": {
                      "description": "Error details in case receiving/check-in process for the piece record has failed",
                      "type": "object",
                      "readonly": true,
                      "$schema": "http://json-schema.org/draft-04/schema#",
                      "id": "error.schema",
                      "properties": {
                        "message": {
                          "type": "string",
                          "description": "Error message text"
                        },
                        "type": {
                          "type": "string",
                          "description": "Error message type"
                        },
                        "code": {
                          "type": "string",
                          "description": "Error message code"
                        },
                        "parameters": {
                          "description": "Error message parameters",
                          "$schema": "http://json-schema.org/draft-04/schema#",
                          "id": "parameters.schema",
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "key": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      },
                      "required": [
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "type"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "pieceId",
                "processingStatus"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "poLineId",
          "receivingItemResults"
        ],
        "additionalProperties": false
      }
    },
    "totalRecords": {
      "description": "The total number of receiving/check-in items in the list",
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "receivingResults",
    "totalRecords"
  ]
}

Example:

{
  "receivingResults": [
    {
      "poLineId": "0804ddec-6545-404a-b54d-a693f505681d",
      "processedSuccessfully": 1,
      "processedWithError": 1,
      "receivingItemResults": [
        {
          "pieceId": "c18c49b7-d970-44d6-b5d4-bd76c1c62d83",
          "processingStatus": {
            "type": "success"
          }
        },
        {
          "pieceId": "cb9b0468-f2b4-4a13-b64c-662c4c9ec3ed",
          "processingStatus": {
            "type": "failure",
            "error": {
              "code": "pieceAlreadyReceived",
              "message": "The piece record is already received"
            }
          }
        }
      ]
    },
    {
      "poLineId": "7f0c4975-885e-47d5-8d5a-793dffbba9b2",
      "processedSuccessfully": 1,
      "processedWithError": 0,
      "receivingItemResults": [
        {
          "pieceId": "20241b8c-9076-4cf5-817b-f2c1e2cb242f",
          "processingStatus": {
            "type": "success"
          }
        }
      ]
    }
  ],
  "totalRecords": 3
}

HTTP status code 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: application/json

Type: any

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Media type: text/plain

Type: any

Example:

"unable to update receive -- malformed JSON at 13:4"

HTTP status code 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

HTTP status code 500

Internal server error, e.g. due to misconfiguration

Body

Media type: application/json

Type: any

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Media type: text/plain

Type: any

Example:

internal server error, contact administrator