Rates will vary by carrier_code and service_code (such as "usps_priority_mail" for USPS Priority Mail) and may be further customized with any available advanced_options (such as Signature Confirmation or Insurance). Once selected, the integration can use those rate details when creating a label. Using the response, it is up to the user or integration’s logic to select the desired rate. If looking for a broad list of rates (for example, to populate a selection dialog), omit specific package information to receive an unfiltered list of available rates. When searching for a specific rate, try to include as much information as possible in the initial request to receive a list of available rates more closely filtered to what is needed. If available, add information such as the To and From addresses (or even just ZIP codes), along with package weight, type, and dimensions to the request body to receive a list of rates filtered for those attributes. This endpoint optionally accepts details about the shipment to narrow down the available rates. In order to create a shipping label, a specific rate should be selected from the numerous available options and combinations. Users can search for and compare different rates with calls to this SERA endpoint. Rates contains all of a single shipment’s details, from origin and destination addresses to weight, carrier, and service options. Integrators are not required to upgrade versions to maintain existing functionality but may be required to upgrade to gain access to new features as they’re introduced. New versions are created to avoid impacting existing integrations when backwards-incompatible changes are introduced to SERA. For example, to add funds to an account, call POST /v1/balance/add-funds. VersioningĮvery SERA endpoint contains a version number in the URL. If an invalid Idempotency-key is included with an request, an error will be returned. Most programming languages support generating random UUIDs out-of-the-box. Idempotency-keys must be a randomly-generated version-4 UUID. If the key is new, SERA will process the request as normal. If SERA already processed a request within the past 24 hours with the same Idempotency-key, it will replay the same response without duplicating the transaction. Whenever any request does not get a response within a reasonable timeout period, simply send it again with the same Idempotency-key value. To guard against cases like this, be sure to include a unique Idempotency-key value in the request header when calling any SERA endpoint with the POST method. If this happens, it’s usually impossible to know if the request was received and processed successfully, or if not, should be sent again and possibly duplicated. Idempotencyīecause the internet is not a guaranteed service, sometimes network messages (like REST API requests and responses) get lost in transit and are not received. Calls made over plain-text HTTP or with an obsolete TLS version will fail. Īll SERA requests must be made over HTTPS using TLS v1.2+. To do the same in the production environment, POST the request to. For example, to add funds to an account in the staging environment, POST the request to. Endpoint Base URLs Sign-In/AuthenticationĪll Endpoint URLs given in this document are relative to the specific environment host you are connecting to. The production environment allows you to take your SERA integration live and rate-shop across multiple carriers, create real shipping labels, schedule pickups, track in-transit shipments, and more. Other services in staging, such as tracking and pickups, do not reflect any real-world data. Note that shipping rates in the staging environment may vary from production and should not be relied on. Access to the staging environment is available once you register for a developer account. Labels created in the staging environment cannot be used to ship and must be destroyed if printed. There are no service or transaction fees charged for staging accounts and labels. The staging environment allows you to develop SERA integrations without using real funds to create test labels. Staging and Production Versioned Environments If you’d like more information, click here. SERA is a REST (REpresentational State Transfer) API, which means that it follows certain HTTP conventions for things like URLs, methods, headers, and status codes.
0 Comments
Leave a Reply. |