#%RAML 0.8 --- title: OpenLMIS Stock Management version: "@version@" baseUri: "@baseUrl@" protocols: [ HTTP, HTTPS ] documentation: - title: Getting Started content: | OpenLMIS Stock Management is based around the concept of Stock Cards and the creation of a permanent ledger accounting for all changes to the Stock on Hand over time. Each Stock Card is composed of line items, each representing a specific change to a particular set of Stock in Inventory. These ledgers expect that they may be updated as part of a larger distributed system with occassional internet connectivity and so changes to the ledger may come out of order and after the physical change to stock on hand occurred. This service also has Resources for: * Perparing and submitting a Physical Inventory. * Stock Events: the only way to update (write operation) a Stock Card. Not only are these events the only way to change a Stock Card, one event is one atomic transaction to the type of Stock Event being described: a single adjustment, a batch, a receipt, etc. * The types of Organizations (facility, free text). * Configuring the types of Reasons that might be given when adjusting, issuing, or otherwise accounting for stock. * Configuring the lists of valid desitnations and sources (places you may send and receive stock). This service does not currently support bin cards (ledgers for Stock in Inventory in a particular bin, room, shelf, etc), though it's expected that functionality will be added soon. schemas: - program: !include schemas/program.json - facility: !include schemas/facility.json - orderable: !include schemas/orderable.json - lot: !include schemas/lot.json - lineItem: !include schemas/lineItem.json - facilityType: !include schemas/facilityType.json - reason: !include schemas/reason.json - reasons: | { "type": "array", "items": { "type": "object", "$ref": "schemas/reason.json" } } - geographicZone: !include schemas/geographicZone.json - stockCardTemplate: !include schemas/stockCardTemplate.json - stockEventDto: !include schemas/stockEventDto.json - stockEventLineItemDto: !include schemas/stockEventLineItemDto.json - stockCard: !include schemas/stockCard.json - stockCardPage: !include schemas/stockCard.json - stockCardSummariesPage: !include schemas/stockCardSummaryV2Page.json - stockCardSummaries: !include schemas/stockCardSummaries.json - stockCardReasonSummaryPage: !include schemas/stockCardRangeSummaryPage.json - validSourceDestination: !include schemas/validSourceDestination.json - validSourceDestinations: | { "type": "array", "items": {"type": "object", "$ref": "schemas/validSourceDestination.json"} } - validReasonAssignment: !include schemas/validReasonAssignment.json - validReasonAssignments: | { "type": "array", "items": {"type": "object", "$ref": "schemas/validReasonAssignment.json"} } - organization: !include schemas/organization.json - organizations: | { "type": "array", "items": {"type": "object", "$ref": "schemas/organization.json"} } - physicalInventoryLineItem: !include schemas/physicalInventoryLineItem.json - physicalInventory: !include schemas/physicalInventory.json - physicalInventories: | { "type": "array", "items": {"type": "object", "$ref": "schemas/physicalInventory.json"} } - stockAdjustment: !include schemas/stockAdjustment.json - localizedMessage: !include schemas/localizedMessage.json - uuid: | { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } - arrayOfStrings: | { "type": "array", "items": { "type": "string" } } resourceTypes: - collection: get: responses: 200: description: Collection retrieved successfully headers: X-Content-Type-Options: X-XSS-Protection: body: application/json: schema: <> 404: description: Collection is empty. headers: X-Content-Type-Options: X-XSS-Protection: post: body: application/json: schema: <> responses: 201: description: Item created successfully headers: X-Content-Type-Options: X-XSS-Protection: body: application/json: schema: <> - member: get: responses: 200: body: application/json: schema: <> post: body: application/json: schema: <> responses: 200: body: application/json: schema: <> delete: responses: 200: traits: - secured: queryParameters: access_token: displayName: access_token description: OAuth2 access token type: string required: false repeat: false headers: Authorization: displayName: Authorization description: OAuth2 authorization token header. Takes the form of 'Bearer '. type: string required: false repeat: false - paginated: queryParameters: page: description: The page number which should be displayed. Note that the first page is numbered zero rather than one. Additionally, negative and undefined values are interpreted as zero. type: integer required: false repeat: false size: description: The desired size of each page. This specifies the maximum number of values that should be returned by the server. Zero, undefined, and negative values should result in all possible values being returned. type: integer required: false repeat: false - sorted: queryParameters: sort: description: Sorting criteria in the format "property(,asc|desc)". Default sort order is ascending. Multiple sort criteria are supported. type: string required: false repeat: true /api: /stockCardTemplates: get: is: [ secured ] description: Get stock card template queryParameters: facilityType: required: false program: required: false responses: 200: description: | Returns a default templte with all fields set to not display when no query parameters are passed. Returns template that matches facility type and program when query parameters are given. headers: X-Content-Type-Options: X-XSS-Protection: body: application/json: schema: stockCardTemplate 404: description: Stock card template not found for the given query parameter. body: application/json: schema: localizedMessage 400: body: application/json: schema: localizedMessage description: Provided query parameters are not correctly formatted. post: is: [ secured ] description: | Create stock card template for a facility-type&program combination. This is for administrators only. It requires the permission STOCK_CARD_TEMPLATES_MANAGE. body: application/json: schema: stockCardTemplate responses: 201: description: Indicates that stock card template has been created. body: application/json: schema: stockCardTemplate 400: description: Indicates that request body is not correctly formated(incorrect fileds names, non-existing program or facility ids, etc). body: application/json: schema: localizedMessage /stockEvents: post: is: [ secured ] description: Create a new stock event with one or more orderables. body: application/json: schema: stockEventDto responses: 201: description: Stock event has been processed with no validatoin error or persistence error. headers: Keep-Alive: body: application/json: schema: uuid 400: description: Failed to process stock event due to validation error. body: application/json: schema: localizedMessage 403: description: User does not have permission to create stock events for given facility and program. body: application/json: schema: localizedMessage /stockCardSummaries: get: is: [ secured , paginated ] description: Get summaries of stock cards, which contains SOH, product name, and other essential information. This will NOT return any line items. This could be used by front end for list view. This endpoint is deprecated. queryParameters: facility: required: true description: Facility id, indicates the facility that the queried stock card summaries should belong to. program: required: true description: Program id, indicates the program that the queries stock card summaries is under. responses: 200: body: application/json: schema: stockCardSummaries 404: description: No stock cards were found that matches given facility and program. body: application/json: schema: localizedMessage 403: description: User does not have permission to view stock cards of given facility and program. body: application/json: schema: localizedMessage /print: get: is: [ secured ] description: Get stock card summary report in PDF format to print. queryParameters: facility: required: true description: Facility id program: required: true description: Program id responses: 200: description: Stock card summary report generated successfully. body: application/pdf: 404: description: No stock cards were found that matches given facility and program. body: application/json: schema: localizedMessage 403: description: User does not have permission to get stock card summary report. body: application/json: schema: localizedMessage /v2/stockCardSummaries: get: is: [ secured, paginated ] description: Get summaries of stock cards, which contains SOH, product name, and other essential information. This will NOT return any line items. (This could be used by front end for list view.) queryParameters: facilityId: required: true description: Facility id, indicates the facility that the queried stock card summaries should belong to. repeat: false type: string programId: required: true description: Program id, indicates the program that the queries stock card summaries is under. repeat: false type: string orderableId: required: false description: Orderable id, indicates the orderable that the queries stock card summaries is under, can specify multiple orderable ids. repeat: true type: string asOfDate: required: false description: Stock Card data will be calculated as of given date. repeat: false type: string nonEmptyOnly: required: false description: Flag defining whether only summaries with non empty set of canFulfillForMe should be returned. Defaults to false. repeat: false type: boolean orderableCode: required: false description: Code of orderable repeat: false type: string orderableName: required: false description: Name of orderable repeat: false type: string lotCode: required: false description: Lot code of orderables which can fulfill stock card repeat: false type: string responses: 200: body: application/json: schema: stockCardSummariesPage 400: body: application/json: schema: localizedMessage 403: description: User does not have permission to view stock cards of given facility and program. body: application/json: schema: localizedMessage /stockCardRangeSummaries: get: is: [ secured, paginated ] description: Get summaries of stock cards with reason info and amount assigned. Range of line items taken is specified by date params. Results are grouped by using /api/orderableFulfills. queryParameters: facilityId: required: true description: Facility id, indicates the facility that the queried stock card summaries should belong to. repeat: false type: string programId: required: true description: Program id, indicates the program that the queries stock card summaries is under. repeat: false type: string orderableId: required: false description: Filters summaries matching the orderable id, can specify multiple orderable ids. If none is given all stock cards will be used. repeat: true type: string tag: required: false description: Used for filtering reasons by their tags for summary info. repeat: false type: string startDate: required: false description: The date to start including stock data for the summaries. If not provided summaries will be retrieved starting with the earliest. repeat: false type: string endDate: required: false description: The date to stop including stock data for the summaries. If not provided current day will be used. repeat: false type: string responses: 200: headers: Keep-Alive: body: application/json: schema: stockCardReasonSummaryPage 400: description: Request has paramters that are not recognized by this endpoint. body: application/json: schema: localizedMessage 403: description: User does not have permission to view stock cards of given facility and program. headers: Keep-Alive: body: application/json: schema: localizedMessage /stockCardSummaries/noCards: get: is: [ secured ] description: Get dummy stock card summaries for approved products and lots that don't have cards yet. This can be used by front end to determine what new stock cards can be created. queryParameters: facility: required: true description: Facility id, indicates the facility. program: required: true description: Program id, indicates the program. responses: 200: body: application/json: schema: stockCardSummaries 403: description: User does not have permission to view stock cards of given facility and program. body: application/json: schema: localizedMessage /stockCards: get: is: [ secured, paginated, sorted ] description: Search for Stock Cards, result is an intersection of user rights and request parameters. queryParameters: id: required: false description: Stock Card Id repeat: true type: string responses: 200: body: application/json: schema: stockCardPage /{id}: get: is: [ secured ] description: Get full details of one stock card. responses: 200: body: application/json: schema: stockCard 404: description: Stock card with given id does not exist. body: application/json: schema: localizedMessage 403: description: User does not have permission to view stock card. body: application/json: schema: localizedMessage /print: get: is: [ secured ] description: Get stock card report in PDF format to print. responses: 200: body: application/pdf: 403: description: User does not have permission to get stock card report. body: application/json: schema: localizedMessage 404: description: Stock card with given id does not exist, can not get report. body: application/json: /deactivate: put: is: [ secured ] description: Set stock card as inactive. responses: 200: body: application/json: schema: stockCard 404: description: Stock card with given id does not exist, can not make inactive. body: application/json: /validDestinations: get: is: [ secured, paginated ] description: Get a list of valid destinations of a program and a facility. The filtration works only if both params are provided. If no params are present all assignments are returned. queryParameters: programId: required: false description: Program ID, indicates the program that the valid destinations are under. facilityId: required: false description: Facility ID, indicates the facility that the valid destinations are under. responses: 200: body: application/json: schema: validSourceDestinations 400: description: Program or facility type does not exist. body: application/json: schema: localizedMessage 403: description: User does not have permission to view valid destination. body: application/json: schema: localizedMessage post: is: [secured] description: Configure a destination to program and facility. queryParameters: body: application/json: schema: validSourceDestination responses: 200: description: Given destination already exist. body: application/json: schema: validSourceDestination 201: description: Given destination is configured successfully. body: application/json: schema: validSourceDestination 400: description: Destination id is null. Or program or facility type or destination is not found. body: application/json: schema: localizedMessage 403: description: User is not allowed to configure destination. body: application/json: schema: localizedMessage /{id}: delete: is: [ secured ] description: Remove a destination assignment from a valid destination assignment list. responses: 204: description: Given destination assignment has been removed success. 400: description: Destination assignment is not found. body: application/json: schema: localizedMessage 403: description: User is not allowed to remove destination assignment from the list. body: application/json: schema: localizedMessage /validSources: get: is: [ secured, paginated ] description: Get a list of valid sources of a program and a facility. The filtration works only if both params are provided. If no params are present all assignments are returned. queryParameters: programId: required: false description: Program ID, indicates the program that the valid sources are under. facilityId: required: false description: Facility ID, indicates the facility that the valid sources are under. responses: 200: body: application/json: schema: validSourceDestinations 400: description: Program or facility type does not exist. body: application/json: schema: localizedMessage 403: description: User does not have permission to view valid sources. body: application/json: schema: localizedMessage post: is: [secured] description: Configure a source to program and facility type. queryParameters: body: application/json: schema: validSourceDestination responses: 200: description: Given source already exist. body: application/json: schema: validSourceDestination 201: description: Given source is configured successfully. body: application/json: schema: validSourceDestination 400: description: Source id is null. Or program or facility type or source is not found. body: application/json: schema: localizedMessage 403: description: User is not allowed to configure source. body: application/json: schema: localizedMessage /{id}: delete: is: [ secured ] description: Remove a source assignment from a valid source assignment list. responses: 204: description: Given source assignment has been removed success. 400: description: Source assignment is not found. body: application/json: schema: localizedMessage 403: description: User is not allowed to remove source assignment from the list. body: application/json: schema: localizedMessage /reasonTypes: get: is: [ secured ] description: Returns a list reason types to choose from, for admin user to configure reasons. responses: 200: body: application/json: 403: description: User does not have permission to manage reasons. body: application/json: schema: localizedMessage /reasonCategories: get: is: [ secured ] description: Returns a list reason categories to choose from, for admin user to configure reasons. responses: 200: body: application/json: 403: description: User does not have permission to manage reasons. body: application/json: schema: localizedMessage /validReasons: get: is: [ secured ] description: Return a list of valid reasons based on program and facility type. queryParameters: program: description: Program id type: string required: false facilityType: description: Facility type id type: string required: false reasonType: description: Reason type type: string required: false repeat: true enum: - CREDIT - DEBIT - BALANCE_ADJUSTMENT reason: description: Stock card line item reason id type: string required: false responses: 200: description: Valid reason response headers: Keep-Alive: body: application/json: schema: validReasonAssignments 400: description: Facility type or program is not found. body: application/json: schema: localizedMessage 403: description: Facility type given is no match with home facility or given program is not supported by home facility. body: application/json: schema: localizedMessage post: is: [ secured ] description: Configure a reason to program and facility type. body: application/json: schema: validReasonAssignment responses: 200: description: Given reason is already configured. body: application/json: schema: validReasonAssignment 201: description: Given reason is configured. headers: Keep-Alive: body: application/json: schema: validReasonAssignment 400: description: Reason id is null. Or program or facility type or reason is not found. body: application/json: schema: localizedMessage 403: description: User is not allowed to configure reason. body: application/json: schema: localizedMessage /{id}: delete: is: [ secured ] description: Remove a reason assignment from a valid reason assignment list. responses: 204: description: Given reason assignment has been removed success. 400: description: Reason assignment is not found. body: application/json: schema: localizedMessage 403: description: User is not allowed to remove reason assignment from the list. body: application/json: schema: localizedMessage /stockCardLineItemReasons: displayName: Stock Card Line Item Reason get: is: [ secured ] description: | Retrieve all reasons. responses: 200: description: Return a list of stock line item reasons. headers: Keep-Alive: body: application/json: schema: reasons post: is: [ secured ] description: Create a new stock card line item reason. body: application/json: schema: reason responses: 201: description: Created a new reason. headers: Keep-Alive: body: application/json: schema: reason 400: description: Some Reason required value not found or reason name is duplicate. body: application/json: schema: localizedMessage 403: description: User does not have permission to manage stock card line item reasons. body: application/json: schema: localizedMessage /{id}: uriParameters: id: displayName: id type: string required: true repeat: false get: is: [ secured ] description: Get a stock card line item reason. responses: 200: headers: Keep-Alive: body: application/json: schema: reason 404: headers: Keep-Alive: body: application/json: schema: localizedMessage post: is: [ secured ] description: Update a stock card line item reason. body: application/json: schema: reason responses: 200: description: Updated a reason. headers: Keep-Alive: body: application/json: schema: reason 400: description: Some reason requires value not found. Or update reason content is duplicate. body: application/json: schema: localizedMessage 403: description: User does not have permission to manage stock card line item reasons. body: application/json: schema: localizedMessage /stockCardLineItemReasonTags: get: is: [ secured ] description: | Retrieve all tags that are assosiated with any reason. The result list does no contain duplicates. responses: 200: headers: Keep-Alive: body: application/json: schema: arrayOfStrings /organizations: get: is: [ secured ] description: | Retrieve all organizations. This is for administrators only. It requires the permission STOCK_ORGANIZATIONS_MANAGE. Regular users can get the list of sources or destinations they can use through /api/validSources and /api/validDestinations. responses: 200: description: Return a list of organizations. body: application/json: schema: organizations 403: description: User does not have permission to manage organizations. body: application/json: schema: localizedMessage post: is: [ secured ] description: Create a new organization. body: application/json: schema: organization responses: 201: description: Created a new organization. body: application/json: schema: organization 200: description: Try to create organization, but there is a same content organization checkSourceAssignmentIdExists. body: application/json: schema: organization 400: description: Some organization required value missing. body: application/json: schema: localizedMessage 403: description: User does not have permission to manage organization. body: application/json: schema: localizedMessage /{id}: uriParameters: id: displayName: id type: string required: true repeat: false put: is: [ secured ] description: Update an organization. body: application/json: schema: organization responses: 200: description: Updated an organization. body: application/json: schema: organization 400: description: Some organization requires value missing. Or update organization content is duplicate. body: application/json: schema: localizedMessage 403: description: User does not have permission to manage organization. body: application/json: schema: localizedMessage /physicalInventories: get: is: [ secured ] description: Get a list of saved physical inventory. If inventories do not exist, will return empty list. queryParameters: facility: required: true program: required: true isDraft: required: false responses: 200: description: list of physical inventories. headers: Keep-Alive: body: application/json: schema: physicalInventories 403: description: User does not have permission to view draft physical inventory. body: application/json: schema: localizedMessage post: is: [ secured ] description: Create empty draft physical inventory. Only one draft is allowed at the same time for one facility&program. body: application/json: schema: physicalInventory responses: 201: description: Draft saved. headers: Keep-Alive: body: application/json: schema: physicalInventory 400: body: application/json: schema: localizedMessage description: An error occured during request processing. 403: description: User does not have permission to save draft physical inventory. body: application/json: schema: localizedMessage /{id}: uriParameters: id: displayName: physicalInventoryId type: string required: true repeat: false get: is: [ secured ] description: Get a physical inventory with format specified in query param. Json format is default. queryParameters: format: description: "This parameter specifies return format of this endpoint. If it is not specified json format is returned. Supported types: csv, html, pdf, xls, xlsx." type: string required: false repeat: false responses: 200: headers: Keep-Alive: body: application/pdf: application/json: schema: physicalInventory 404: body: application/json: schema: localizedMessage 403: body: application/json: schema: localizedMessage put: is: [ secured ] description: Save a draft physical inventory. Only one draft is allowed at the same time for one facility&program. body: application/json: schema: physicalInventory responses: 200: description: Draft saved. headers: Keep-Alive: body: application/json: schema: physicalInventory 400: body: application/json: schema: localizedMessage description: An error occured during request processing. 403: description: User does not have permission to save draft physical inventory. body: application/json: schema: localizedMessage delete: is: [ secured ] description: Delete a draft physical inventory. responses: 204: description: Draft deleted. headers: Keep-Alive: 400: description: Physical inventory is submittted. body: application/json: schema: localizedMessage 403: description: User does not have permission to delete draft physical inventory. body: application/json: schema: localizedMessage 404: description: Physical inventory not found. headers: Keep-Alive: body: application/json: schema: localizedMessage /physicalInventoryTemplates: displayName: Physical Inventory report template. post: is: [ secured ] description: Save Physical Inventory report template in database. body: multipart/form-data: formParameters: file: displayName: Template with .jrxml format type: file required: false repeat: false responses: 200: 403: body: application/json: schema: localizedMessage get: is: [ secured ] description: Download Physical Inventory report template with jrxml format. responses: 200: body: application/xml: 403: body: application/json: schema: localizedMessage 404: body: application/json: