.. api-tracking.rst .. _api-tracking-label: ===================================================================== API Shipment Requests: Listing, Tracking, Searching and Status ===================================================================== Listing Shipment Requests ========================= **There is a 100-record limit on all API calls**. To illustrate, using ``/shipments_exact`` to retrieve a list of all shipments would be unsuccessful unless there were only one hundred or fewer shipments, as only the first 100 records are returned. .. Note:: The ``/shipments_exact{id}`` route returns the shipment type ('Automated' or ‘Manual’) as part of the response. The field is sortable. The ``/shipments/search-description`` route returns the ``Type`` field as a filterable field. Obtaining Further Records ------------------------- In cases where there are more than 100 shipments, iterate through the shipments based on the number of shipments provided by the ``total_count`` parameter. Use the optional parameters to obtain more records. For example: .. code-block:: bash // get the first 100 /shipments_exact?limit=100&offset=0 // get the second 100 /shipments_exact?limit=100&offset=100 // get the third 100 /shipments_exact?limit=100&offset=200 Single Shipment Request Tracking Example ======================================== A successful response from the ``shipments_exact`` resource will include a ``shipment_id`` which can be used to get the tracking information for this shipment request. .. code-block:: Json { "shipment_id": "U89bvfKKCtQfhnqaFBrAZW", "shipment_items": [ { "inventory_product_id": 15, "shipment_product_id": "MZ9bmEYFpKKviHe8nSiq4W", "shipment_id": "U89bvfKKCtQfhnqaFBrAZW", "product_id": 3, "product_name": "YubiKey 5C", "product_sku": "5060408461488", "product_tier": 2, "shipment_product_quantity": 16 } ], "organization_id": "UEayb8v4LTHdAshpnk1gMd", "user_id": "WMktp3sgPSFt4zsgpLDF46", "country_code_2": "US", "is_delivered": false, "is_sent_to_fulfillment": false, "is_shipped": false, "recipient": "Example Inc.", "recipient_email": "jan.lindberg@example.com", "recipient_firstname": "Jan", "recipient_lastname": "Lindberg", "recipient_telephone": "555-5555", "street_line1": "7788 Foxrun Street", "city": "Dedham", "region": "MA", "postal_code": "02026", "delivery_type": 1, "shipment_state_code": "ShipmentStateAwaitingValidation", "shipment_state_id": 3, "shipment_state_message": "Awaiting Validation", "shipment_summary_description": "Total Keys: 16 yk5c:16", "shipment_request_date": "2020-12-10T19:56:57Z", "shipment_updated_date": "2020-12-10T19:56:57Z", "total_keys_shipped": 16 } .. _track-shipment-label: Tracking a Shipment Using the ``shipment_id`` ============================================= .. code-block:: Bash curl "https://api.console.yubico.com/v1/shipments_exact/Bj4pfrBJ1SCvkTbTP88Ak2" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer eyJhb..." \ Search ====== Some of the lines of code are very long, so it may be necessary to click in the line and scroll horizontally. You can get a list of shipments filtered by query parameters. We introduced ``/search-description`` on searchable resources to provide a description of the searchable fields. To look up a shipment using the parameter "Shipping error, contact support" state, for example, set the ``search_field`` to ``shipment_state_id`` and set the ID to ``99``, which is the ID for that shipment state. (See the :ref:`shipment-status-label` table below for explanations of the various shipment states.) Example ------- .. code-block:: Bash curl "https://api.console.yubico.com/v1/shipments_exact?search=99&search_field=shipment_state_id" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer eyJhb..." .. include:: includes/search.rst Filtering and Pagination ======================== Refer to the `API docs for the GetShipmentsExact operation `_. Status ====== .. _shipment-status-label: Shipment Status Codes --------------------- A shipment request can be edited at any of the states between 1 and 9. From this point on, a shipment request is either processed through to an end state, or set back to state 99. For information on how address validation affects the success of a shipping request, see the :ref:`Troubleshooting-label` chapter. .. include:: includes/shipment-states-incl.rst Shipment Status Messages ------------------------- .. include:: includes/shipment-status-messages.rst Response Request Status Codes ----------------------------- The responses to your requests indicate what is happening on the server side. Below are the common status codes in responses from the YubiEnterprise Delivery API, and what they mean. .. table:: **Status codes** +-----+------------+--------------------------------------------------------------------------------------+ |Code |Meaning |Explanation | +=====+============+======================================================================================+ |200 |OK | | The request was successful and the response | | | | | body contains the representation requested | +-----+------------+--------------------------------------------------------------------------------------+ |302 |FOUND | | A common redirect response; this will | | | | | redirect to the OAUTH login page | +-----+------------+--------------------------------------------------------------------------------------+ |400 |BAD REQUEST |API validation failed for the request | +-----+------------+--------------------------------------------------------------------------------------+ |403 |FORBIDDEN | | API denied permission to fulfill the | | | | | requested resource | +-----+------------+--------------------------------------------------------------------------------------+ |404 |NOT FOUND |The requested resource was not found | +-----+------------+--------------------------------------------------------------------------------------+ .. _deprecated-apis-label: Deprecated APIs =============== The following table lists deprecated APIs related to listing, tracking, searching, and status for shipment requests. For more information, see :ref:`deprecated-api-list-label`. .. include:: includes/deprecated-apis+replacements.rst ------------------------------------- To file a support ticket for YubiEnterprise Delivery, click `Support `_.