Authenticated Routes
Learn how to interact with our API using user credentials.
Authenticated Routes
Introduction
API Keys alone do not provide complete security, we use them as a way to identify the calling client, but not for authentication and authorization. Here is an article to read more about why:
API Keys ≠ Security: Why API Keys Are Not Enough | Nordic APIs |
To provide additional security we use the API Key together with the JWT authentication scheme (for third-party non-browser clients). Some routes might be protected to only authorized users. To read more about JWT in the following article:
Refresh Tokens: When to Use Them and How They Interact with JWTs
How does it work?
Use the provided email
and password
credentials to obtain an Access token.
This token will authenticate the request and grant you authorization to call the Vitau API’s protected resources, therefore, it should be included within the header of each request.
Access tokens must be short lived, decoding the token will show the access_lifetime
field in seconds. For example, an expiry value of 3600 expires in one hour. To handle token expiration you might want to:
- Set a timer to update the access token before it expires.
- Keep track of obtained time +
access_lifetime
.
Re-use the access token until it expires, then get a new token.
See more of decoding-encoding jwt: JWT IO
Obtaining token
Responses
Status | Meaning |
---|---|
200 OK | Authentication completed successfully and you’ll receive a valid access token. |
401 Unauthorized | The given email/password pair is not correct. |
Prove authentication
The access token must be present in the Authorization header.
An expired token will return 401 Unauthorized
Orders
An order is a customer’s request to purchase products from Vitau. The Order object consists primarily of:
- Patient’s personal information
- Delivery address. (This might also be picked up at Vitau Store).
- Details is an array with the quantity of each product to be purchased
- Payment method
- Relevant dates such as creation, expected delivery, etc.
- Invoicing details. (Optional)
- Order status
- Payment status
CREATE
This service creates an ORDER object, along with the USER, SHIPPING, and INVOICING information if they’re included within the payload.
The products and quantities of the Order are specified inside an array of DETAIL
objects. Each detail has {"product": ID, "quantity":INT}
.
The payment_method
ID must be the one given along with the Client’s API KEY.
Request objects:
- USER
- ”email”: STRING & UNIQUE
- ”phone”: UNIQUE, Format: +(COUNTRY-CODE)(PHONE) e.g. +528188888888
- ”first_name”: STRING
- ”last_name”: STRING
- INVOICING
- ”full_name”: STRING
- ”email”: STRING
- ”rfc”: STRING
- ”street”: STRING
- ”exterior_number”: STRING
- ”neighborhood”: STRING
- ”city”: STRING
- ”state”: STRING
- ”country”: STRING
- ”zipcode”: STRING
- SHIPPING
- ”street”: STRING
- ”exterior_number”: STRING
- ”interior_number”: STRING
- ”neighborhood”: STRING
- ”city”: STRING
- ”state”: STRING
- ”country”: STRING
- ”zipcode”: STRING
- ”phone”: STRING
- PRESCRIPTION
- ”document”: BASE64 STRING
- ”document_name”: STRING OPTIONAL
- ”issue_date”: DATE (Y-m-d)
- “expiring_date”: DATE (Y-m-d) OPTIONAL
Purchase order status ENUM values:
- patient_order_status
- ”in_process” : The order has been created successfully.
- ”shipped”: The order has been dispatched and is on its way.
- ”delivered”: The order has been delivered to the client.
- ”cancelled”: The order has been cancelled.
- payment_status
- ”unpaid”: The order has not been paid.
- ”credit”: The order is placed under credit and will be paid within a specified timeframe.
- ”paid”: The order has been paid.
- ”rejected”: The payment processor rejected the transaction.
- ”in_process”: The payment processor is processing the transaction.
Error messages
Status | Meaning |
---|---|
400 Bad Request | This response may be the result if any value from the payload is missing or incorrect, and the service will respond with the corresponding message explaining the error. |
201 Created. Invoice error | When generating an invoice fails the order will be created along with the other resources, however the order will not have a value in the cfdi attribute, and the email will not be sent. |
201 Created. Coupon invalid | As with calculate, the order will be created along with the other resources, however, it will not have a value in the coupon attribute, and the corresponding discount will not be applied. |
GET
- Searchable lookup fields
- Patient’s full name
- Filterable fields
- patient=INT
- order_status__in=ENUMs separated by commas
- exclude_order_status__in=ENUMs separated by commas
- payment_status__in=ENUMs separated by commas
- expected_delivery_date_before DATE
- expected_delivery_date_after DATE
- max_delivery_date_before DATE
- max_delivery_date_after DATE
- Ordering fields
- created_at This is the default by descending order
- expected_delivery_date
Details
You might want to fetch a specific order and view more details.
The API will respond with 404 if the order is not found or you don’t have permission to view it.
UPDATE
After the order is created you may only change the products if the status is quoted
or approved
. The URL includes the ID of the order to be modified. As you may only edit certain attributes we recommend using PATCH
.
Besides updating the order details you can also cancel the order when we have not started building or dispatching it. Simply, send the order status with value cancelled
. This operation cannot be undone.
Request Invoice
After creating an order you may request to generate an invoice simply by sending the ID of the corresponding invoicing information, however, there are some limitations:
- After creating the order you have up to 3 days
- Orders of past months cannot request invoice
- INVOICING
- ”full_name”: STRING
- ”email”: STRING
- ”rfc”: STRING
- ”street”: STRING
- ”exterior_number”: STRING
- ”neighborhood”: STRING
- ”city”: STRING
- ”state”: STRING
- ”country”: STRING
- ”zipcode”: STRING
- ”cfdi_use”: STRING
- ”fiscal_regime”: STRING
Example request:
Was this page helpful?