mirror of
https://github.com/inventree/inventree-docs.git
synced 2025-10-31 12:55:37 +00:00
API docs (#379)
* Move API documentation into separate directory * Rearrange main docs bar * Split python examples into separate page * Fix broken links * Adds page for browseable API * Fix image links * Add entrypoint page for barcodes * Update barcode docs * Add (empty) pages for internal and external barcods * Add documentation on "internal" barcode format * Documentation for external barcode functionality * Skeleton page for custom barcode information * Extend docs for custom barcodesplugins * Add stubs for new API docs * Add documentation for downloading data via the AP * API metadata information * docs for pythonic metadata access * docs for bulk delete
This commit is contained in:
Oliver
GitHub
58
docs/barcodes/barcodes.md
Normal file
58
docs/barcodes/barcodes.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Barcodes
|
||||
---
|
||||
|
||||
## Barcode Support
|
||||
|
||||
InvenTree has native support for barcodes, which provides powerful functionality "out of the box", and can be easily extended:
|
||||
|
||||
- Barcodes can be scanned [via the API](../api/api.md)
|
||||
- The web interface supports barcode scanning
|
||||
- Barcodes integrate natively [with the mobile app](../app/barcode.md)
|
||||
- Custom barcodes can be assigned to items
|
||||
- Barcodes can be embedded in [labels or reports](../report/barcodes.md)
|
||||
- Barcode functionality can be [extended via plugins](../extend/plugins/barcode.md)
|
||||
|
||||
### Barcode Data Types
|
||||
|
||||
Barcodes can be linked with the following data model types:
|
||||
|
||||
- [Part](../part/part.md#part)
|
||||
- [Stock Item](../stock/stock.md#stock-item)
|
||||
- [Stock Location](../stock/stock.md#stock-location)
|
||||
- [Supplier Part](../buy/supplier.md#supplier-parts)
|
||||
|
||||
## Web Integration
|
||||
|
||||
Barcode scanning can be enabled within the web interface. Barcode scanning in the web interface supports scanning via:
|
||||
|
||||
- Keyboard style scanners (e.g. USB connected)
|
||||
- Webcam (image processing)
|
||||
|
||||
### Configuration
|
||||
|
||||
Barcode scanning may need to be enabled for the web interface:
|
||||
|
||||
{% with id="barcode_config", url="barcode/barcode_settings.png", description="Barcode settings" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
### Scanning
|
||||
|
||||
When enabled, select the barcode icon in the top-right of the menu bar to scan a barcode. If the barcode is recognized by the system, the web browser will automatically navigate to the correct item:
|
||||
|
||||
{% with id="barcode_scan", url="barcode/barcode_scan.png", description="Barcode scan" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
#### No Match Found
|
||||
|
||||
If no match is found for the scanned barcode, the following error message is displayed:
|
||||
|
||||
{% with id="barcode_no_match", url="barcode/barcode_no_match.png", description="No match for barcode" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
## App Integration
|
||||
|
||||
Barcode scanning is a key feature of the [companion mobile app](../app/barcode.md).
|
||||
28
docs/barcodes/custom.md
Normal file
28
docs/barcodes/custom.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Custom Barcodes
|
||||
---
|
||||
|
||||
## Custom Barcode Functionality
|
||||
|
||||
With the provision of [internal](./internal.md) and [external](./external.md) barcode support, a lot of potential use-cases are already supported directly by InvenTree.
|
||||
|
||||
However, if further customization is required, or a bespoke barcode workflow which is not supported already, then this can easily be implemented using the [plugin system](../extend/plugins/barcode.md).
|
||||
|
||||
A custom barcode plugin can be used to (for example) perform a particular action when a barcode is scanned.
|
||||
|
||||
### Scanning a Barcode
|
||||
|
||||
To scan (process) a barcode, the barcode data is sent via a `POST` request to the `/api/barcode/` API endpoint.
|
||||
|
||||
### Barcode Scanning Priority
|
||||
|
||||
When a barcode is scanned (sent to the `/barcode/scan/` endpoint), each available "plugin" is checked to see if it returns a valid result for the provided barcode data. The first plugin to return a result prevents any further plugins from being checked.
|
||||
|
||||
The barcode is tested as follows, in decreasing order of priority:
|
||||
|
||||
- [Internal Barcode Plugin](./internal.md)
|
||||
- [External Barcode Plugin](./external.md)
|
||||
- [Custom Barcode Plugins](../extend/plugins/barcode.md)
|
||||
|
||||
!!! tip "Plugin Loading Order"
|
||||
The first custom plugin to return a result "wins". As the loading order of custom plugins is not defined (or configurable), take special care if you are running multiple plugins which support barcode actions.
|
||||
45
docs/barcodes/external.md
Normal file
45
docs/barcodes/external.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: External Barcodes
|
||||
---
|
||||
|
||||
## External Barcodes
|
||||
|
||||
In addition to defining an [internal barcode format](./internal.md), models which have associated barcode information also allow arbitrary external (third party) barcodes to be assigned or "linked" to items in the database.
|
||||
|
||||
For example, you have just purchased a reel of capacitors from a supplier, which comes provided with a sufficiently unique barcode or qr-code. Instead of printing an *internal* barcode, the existing barcode can be scanned and *linked* to the specific reel (which is a [Stock Item](../stock/stock.md#stock-item)).
|
||||
|
||||
Linking to external barcodes allows an alternative barcode workflow, which may be especially useful when dealing with in-feed components which are received from external suppliers.
|
||||
|
||||
!!! tip "Dealer's Choice"
|
||||
The use of external barcodes is entirely up to the user, if it is deemed to be convenient.
|
||||
|
||||
## Linking Barcodes
|
||||
|
||||
### Via the API
|
||||
|
||||
Facility for barcode linking (and un-linking) is provided via the [API](../api/api.md).
|
||||
|
||||
- The `/api/barcode/link/` API endpoint is used to link a barcode with an existing database item
|
||||
- The `/api/barcode/unlink/` API endpoint is used to unlink a barcode from an existing database item
|
||||
|
||||
### Via the Web Interface
|
||||
|
||||
To link an arbitrary barcode, select the *Link Barcode* action as shown below:
|
||||
|
||||
{% with id="barcode_link_1", url="barcode/barcode_link_1.png", description="Link barcode" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
{% with id="barcode_link_2", url="barcode/barcode_link_2.png", description="Link barcode" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
If an item already has a linked barcode, it can be un-linked by selecting the *Unlink Barcode* action:
|
||||
|
||||
{% with id="barcode_unlink", url="barcode/barcode_unlink.png", description="Unlink barcode" %}
|
||||
{% include 'img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
### Via the App
|
||||
|
||||
External barcodes can be linked to (or unlinked from) database items via the [mobile app](../app/barcode.md)
|
||||
36
docs/barcodes/internal.md
Normal file
36
docs/barcodes/internal.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Internal Barcodes
|
||||
---
|
||||
|
||||
## Internal Barcodes
|
||||
|
||||
InvenTree defines an internal format for generating barcodes for various items. This format uses a simple JSON-style string to uniquely identify an item in the database.
|
||||
|
||||
Some simple examples of this format are shown below:
|
||||
|
||||
| Model Type | Example Barcode |
|
||||
| --- | --- |
|
||||
| Part | `{% raw %}{"part": 10}{% endraw %}` |
|
||||
| Stock Item | `{% raw %}{"stockitem": 123}{% endraw %}` |
|
||||
| Supplier Part | `{% raw %}{"supplierpart": 99}{% endraw %}` |
|
||||
|
||||
The numerical ID value used is the *Primary Key* (PK) of the particular object in the database.
|
||||
|
||||
## Report Integration
|
||||
|
||||
This barcode format can be used to generate 1D or 2D barcodes (e.g. for [labels and reports](../report/barcodes.md))
|
||||
|
||||
To access the raw barcode information string within a template, use the `.barcode` attribute, and pass it into a barcode generation method.
|
||||
|
||||
### Example: QR Code
|
||||
|
||||
For example, to render a QR-Code image for a part instance:
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
<img src='{% qrcode part.barcode %}'>
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
!!! info "Barcode Formatting"
|
||||
Refer to the [report documentation](../report/barcodes.md) for further information on formatting barcode data
|
||||
Reference in New Issue
Block a user