Best Practices & Troubleshooting

Best Practices

Note

The best practices specific to YubiEnterprise APIs are in the API Onboarding Playbook.

  • Have at least two Org Owners who can manage members (see Settings).
  • Inform both your YubiEnterprise users and your end-users in advance that they will receive email from Yubico’s YubiEnterprise Delivery. Without this advance notice, they are likely to regard these emails as phishing attempts.
  • Subscription customers:
    • To ensure that you do not let keys in any of your inventories expire unused, create a spreadsheet to plan the allocation of products across users and inventory types. See Example Subscription.
    • When creating a shipment request, select the inventory type before selecting the item(s) to be shipped.

Limits and Constraints

When planning and executing shipment requests, keep in mind the limits and constraints:

  • Each shipping request is limited to 500 items. You can order 500 keys of a single type, or 250 lanyards plus 250 keys of different types, etc.
  • Each CSV file is limited to 1000 shipment requests (bulk shipment)
  • Each CSV file is limited to 10 MB
  • Address validation takes place every 15 minutes. This means that you might have to wait up to 15 minutes to find out if your shipment request has been queued for fulfillment (see Shipping Status Codes).
  • Non-subscription purchases: Shipment requests can be made for up to one year after a PO is submitted.
  • Subscription purchases: Time limits for shipment requests depend on the stock/inventory from which the products are drawn.

The full list of options potentially available is given below. The actual list depends on what you have purchased. Explanations for the terms in the list are given in the table below the list.

With the release of YubiEnterprise Delivery 1.6.0, the distinction between Primary Subscription and Backup Subscription is made explicit, thus facilitating requesting shipment.

Full List of Inventory Types

  • Primary Subscr - Base Tier: Initial
  • Primary Subscr - Base Tier: Buffer
  • Primary Subscr - Base Tier: Replacement
  • Primary Subscr - Adv. Tier: Initial
  • Primary Subscr - Adv. Tier: Buffer
  • Primary Subscr - Adv. Tier: Replacement
  • Primary Subscr - Prem. Tier: Initial
  • Primary Subscr - Prem. Tier: Buffer
  • Primary Subscr - Prem. Tier: Replacement
  • Primary Subscr - FIPS Tier: Initial
  • Primary Subscr - FIPS Tier: Buffer
  • Primary Subscr - FIPS Tier: Replacement
  • Backup Subscr - Base Tier: Initial
  • Backup Subscr - Base Tier: Buffer
  • Backup Subscr - Base Tier: Replacement
  • Backup Subscr - Adv. Tier: Initial
  • Backup Subscr - Adv. Tier: Buffer
  • Backup Subscr - Adv. Tier: Replacement
  • Backup Subscr - Prem. Tier: Initial
  • Backup Subscr - Prem. Tier: Buffer
  • Backup Subscr - Prem. Tier: Replacement
  • Backup Subscr - FIPS Tier: Initial
  • Backup Subscr - FIPS Tier: Buffer
  • Backup Subscr - FIPS Tier: Replacement
  • Non-subscription - Base Tier
  • Non-subscription - Advanced Tier
  • Non-subscription - Premium Tier
  • Non-subscription - FIPS Tier
  • Standard Products
Standard Products Subscription Non-subscription
Standard products are
physical keys purchased
outright (on your PO
you will not find
“Standard Products”,
but instead the actual
products/models that
you purchased).



There is a primary
subscription and a backup
subscription for each
tier (product grouping):
Base, Advanced, Premium,
and FIPS. Each of those
tiers has Initial,
Buffer, and Replacement
sub-categories, explained
in the table below,
The non-subscription
tiers are for virtual
keys. Unlike
subscription tiers,
non-subscription
tiers have no
sub-categories.




Troubleshooting

This section addresses issues that can arise with shipping. YubiEnterprise Delivery notifies you of the situation of any given shipment via the codes in the Status column of the Shipments tab. The table below, Shipping Status Codes, lists the error codes and their explanations.

YubiEnterprise Delivery uses an address validation service to reduce the incidence of issues, but it is important to be aware that just because an address exists in Google Maps, it does not mean that the address is deliverable. ‘Deliverable address’ is a United States Postal Service (USPS) classification for designating addresses to which the USPS has historically been able to deliver. YubiEnterprise Delivery’s ability to deliver is based on address information being input in the format acceptable to the USPS. These formats are laid out in detail in the USPS’s Postal Addressing Standards.

Note

When revising an address, the quickest option is to use the format Google Maps presents, because it usually does use the address format preferred by the USPS. In the screenshot below, the address format that was input appears in the upper field, and Google Maps’ format (preferred by USPS) is presented below the photo of the location.

_images/crestline.png

Also, when revising addresses, ZIP / Postal Code is generally a good place to start.

Address Validation Outside the US and Canada

For parts of the world with less standardized address formats, the fact that we can accept an address does not mean that it is deliverable. An address will often be classified as “partially deliverable”, which means that we rely on local couriers who are familiar with the complexities of their urban systems and their delivery routes to deliver to the intended recipient.

Typically packages sent to European addresses and some parts of Asia reach their destination. Packages sent to Southeast Asia and Eastern Europe typically arrive at the right street. In those parts of the world where there are no numbers in the postal addresses, the local courier’s capability is crucial to ensuring that the package does not just end up in the right general area.

Shipping Status Codes

At any of the states between 1 and 9, a shipment request can be edited. From this point on, a shipment request is either processed through to an end state, or set back to state 99.

This table is very wide; scroll horizontally to see all four columns.

Shipment State Codes
shipment_state_id shipment_state_code shipment_state_description shipment_state_message
1 ShipmentStateIncomplete
Shipment request received
by YubiEnterprise Delivery
system but contained some
data that could not be
processed. (2), (3)
Incomplete Shipping Request
2 ShipmentStateDraft
Shipment request is being
edited and is not ready for
processing.
Draft
3 ShipmentStateAwaitingValidation
Shipment request received,
no validation done yet.
Awaiting Validation
4 ShipmentStateProcessingAddress
Shipment request locked as
it undergoes country check,
address validation, sales
tax rate lookup (US), DPL
check.
Processing
5 ShipmentStateAddressValid
Shipment request address has
been validated, ready to be
picked up by fulfillment
processor.
Accepted for Fulfillment
6 ShipmentStateAddressInvalid
Shipment request address is
invalid but an alternative
address has been found and
suggested. (2), (3)
Incomplete
7 ShipmentStateAddressFail
Shipment request address
could not be validated and
no alternative could be
found for suggesting.
(2), (3)
Address is undeliverable
or could not be
understood
8 ShipmentStateError
Shipment request has failed
processing due to
insufficient credits
or insufficient inventory.
Error: Processing Error,
contact Support
9 ShipmentStateDPLMatch
Shipment request recipient
found on DPL, therefore it
is illegal to fulfill this
shipment request. (4)
Error: DPL Match
99 ShipmentStateShipmentError
Shipment request rejected
from ShipmentState-
ProcessingFulfillment
with “%s” error message;
could not be fulfilled by
processor.
Error: Shipping error,
contact Support
100 ShipmentStateProcessingShipment
Shipment request was locked
at 1600hrs UTC to calculate
and deduct tax, inventory,
and credits. (1)
Processing: Inventory &
Tax Deductions
101 ShipmentStateFulfillmentReady
Shipment request ready to be
queued for fulfillment.
Processing: Ready for
Fulfillment
102 ShipmentStateProcessingFulfillment
Shipment sent for fulfill-
ment at 10:00am (or cutoff
time). (1)
Processing: Sent for
Fulfillment
103 ShipmentStateShipped
Shipment sent out by
fulfillment processor and is
in transit.
Shipped: In transit
104 ShipmentStateDelivered Shipment delivered. Delivered
105 ShipmentStateLost
Shipment lost and delivery
is no longer expected.
Shipment Lost/Missing
106 ShipmentStateDeliveryException
Customs hold or undelivered
or returned shipment to
sender or any other shipping
exceptions.
Delivery Exception
1025 ShipmentStateShippingQueue
Shipment queued for
fulfillment.
Processing:
Queued for Fulfillment
2000 ShipmentStateManualFulfillment
Shipment is being fulfilled
manually. No further action
by shipment requestor is
required.
Manual Processing

(1) Refer to Timing for cutoff times.

(2) Incomplete Address: Secondary line information such as apartment (apt), suite, unit is missing. Therefore it is not possible to guarantee delivery to the correct recipient.

(3) Address is Undeliverable or could not be understood: The address is either not physically deliverable or it could not be resolved to a real location.

(4) Any shipping request with a recipient name and/or address found on the US government’s DPL (Denied Parties/Persons List) cannot be fulfilled.

Shipment Status Messages

As the following table is wide, you may need to scroll horizontally. In the Explanation column, the source of the message is given: YubiEnterprise Delivery system for internal messages, US Validation for the US Postal Service, and finally, International Validation. Messages originating from the last two are simply passed on to you by YubiEnterprise Delivery.

YubiEnterprise Delivery API /shipment_exact Status Messages
Message Explanation
InventoryProductId not specified for ProductId %d - ShipmentStateError
YubiEnterprise Delivery system
Too many keys in shipment - TotalKeysShipped %d > %d - ShipmentStateError
YubiEnterprise Delivery system
Not enough Inventory for Shipment - ShipmentStateError
YubiEnterprise Delivery system
Re-enter the address differently; some parts of it are invalid. See
the YubiEnterprise documentation for more guidance.
US Validation
The address is invalid. See the YubiEnterprise documentation for more
guidance.
US Validation
The address is valid.
No further explanation required
US Validation
Remove the ‘secondary unit designator’ (apt, suite, department, etc.)
because it is superfluous.
Remove the apartment number, unit, etc.:
it is considered wrong or unnecessary
US Validation
Enter second line information (apartment, unit, etc.).
The information in the primary line is not specific enough.
Add the apartment number, unit, etc.
US Validation
The address is a valid military address.
No further explanation required
US Validation
The address is a valid General Delivery address where individuals without
permanent addresses can receive mail.
No further explanation required
US Validation
The address is valid. An organization such as a government agency can
can have its own zipcode because it receives a large volume of mail.
No further explanation required
US Validation
Enter a street number; for example, for Yubico ‘Lytton Ave’ alone is not
sufficient, it needs to be ‘530 Lytton Ave’.
The number on the primary line, e.g., the
“185” in “185 Berry Street” is missing
Enter a valid street number.
The number on the primary line, e.g., the
“185” in “185 Berry Street” is not valid
US Validation
Enter a PO Box, Rural Route, or Highway Contract box number.
US Validation
Enter a valid PO Box, Rural Route, or Highway Contract box number.
US Validation
Enter the Private Mailbox (PMB) identifier or the # sign, followed by the
PMB number.
PMB number is Private Mailbox Number
US Validation
This address is not eligible to receive mail.
US Validation
The address is that of a Commercial Mail Receiving Agency (CMRA) a private
business that accepts mail for recipients, and the required private
mailbox information is present.
US Validation
The address is missing some important secondary line information
(apartment, unit, etc).
No further explanation required
International Validation
Mail is unlikely to arrive at this destination - please verify input.
No further explanation required
International Validation
This street could not be found within the city or postal code.
No further explanation required
International Validation
Invalid OrganizationId for Shipment YubiEnterprise Delivery system
Country Code not set for Shipment YubiEnterprise Delivery system
Country could not be found from CountryCode2: %s
Country code entered is not in
YubiEnterprise Delivery system list
Shipment has no shipment items YubiEnterprise Delivery system
DeliveryType not set for Shipment, defaulting to 1 - normal YubiEnterprise Delivery system
Invalid DeliveryType %s for Shipment YubiEnterprise Delivery system
InventoryType not set for Shipment, defaulting to 1 YubiEnterprise Delivery system
InventoryType %s not valid set for Shipment
You cannot use this InventoryType for this
shipment - YubiEnterprise Delivery system
Negative quantity entered for ShipmentItem with ProductId=%d defaulting to 0
You set the quantity of the specified
ProductID to be shipped to less than zero.
YubiEnterprise Delivery system
Invalid ShipmentProductQuantity for ShipmentItem %d
You probably do not have sufficient
inventory - YubiEnterprise Delivery system
Invalid ShipmentProductLineCost for ShipmentItem %d YubiEnterprise Delivery system
Invalid Shipment - Total keys in shipment greater than 500
You cannot ship more than 500 items at
once - YubiEnterprise Delivery system
Shipment has zero total item quantity
The number of items to be shipped must be
> than 0 - YubiEnterprise Delivery system
US Address is missing the state name/abbreviation in region field
No further explanation required
YubiEnterprise Delivery system
Bad ProductId in ShipmentProduct for NewShipmentProduct
ProductID is wrongly specified or invalid
YubiEnterprise Delivery system
Input for %s exceeded limit of %d characters
Specified field cannot accept the number
of characters that were entered.
YubiEnterprise Delivery system

To file a support ticket with Yubico, click Support.