Documentation Powered by ReDoc

Digipix API (1.0.0)

Download OpenAPI specification:Download

The Digipix API is RESTful API.

The HTTP response codes 200 and 201 are positive responses, all other response codes must be considered as error.

Data will only be returned for HTTP response code 200/201.

Error descriptions can be returned on 4xx or 5xx response codes.

All requests to the api must contain the access token.

Find more info about oauth

Authentication

OAuth2

Authorization used by resources

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: /v1/oauth/token
Refresh URL: /v1/oauth/token
Scopes:
  • orders -

    handle with orders

  • quote -

    handle with quote

  • products -

    handle with products

Auth

The Digipix API uses authentication based on OAuth 2.0.

This is the endpoint to generate your access token, all other operations will require it.

Find more info about OAuth 2.0

Generate an access token

Uses your client_id and client_secret to generate a new time limited access token. Be mindful that there are different credentials for development and production environments.

The generated access token will last for one hour and can be reused within this expiration period.

When requesting the access token, you must specify the scope of your token to include all the resources you will use with it. Available scopes at this moment are "orders", "quote" and "products". You can add as many as necessary on the same request.

All other API requests must have the token in the header Authorization: Bearer <access_token>.

header Parameters
Content-Type
required
string
Example: application/json

Request Content Type

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

Information to generate the access token

client_id
required
string

unique client id - provided by Digipix

client_secret
required
string

client secret - provided by Digipix

grant_type
required
string
Default: "client_credentials"

permission type

scope
Array of strings
Items Enum: "orders" "quote" "products"

token permissions

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "client_id": "abc123",
  • "client_secret": "abc123",
  • "grant_type": "client_credentials",
  • "scope":
    [
    ]
}

Response samples

Content type
application/json
{
  • "access_token": "<access_token>",
  • "token_type": "Bearer",
  • "expires_in": 3600
}

Orders

Endpoint for creating, approving, cancelling and getting the status of your orders.

Create new order

scope: orders

Allows you to create a new order.

There are two distinct ways to create an order: pre-approved or to be approved:

  1. To be aproved means you will first make an API call to create an order with a "quote" status. And it will require a second API call to change the status to "approved". Orders will only be printed after the status become "approved".
  1. Pre-Approved means you will do a single call to create the order straight to an "approved" status. For an order to be pre-aproved it's mandatory to send the shipment option.

Those are the possible flows:

  1. To be aproved - two API calls: Use this endpoint to create an order without a shipmentMethodId and without a shipmentId.
    • The order status will be "quote" and you'll get the shipping options, with the cost,estimatedDeliveryDays and shipmentMethodId of each, on the return data.
    • Then you will need to PATCH the created order to either approve it with a chosen shipmentMethodId or cancel it.
    • That's two API calls to create and approve an order - but you will know the shipping cost and estimatedDeliveryDays before approval.
    • You have up to seven days to PATCH the created order.
  1. Pre-Approved - two API calls: Use this endpoint to create an order with a shipmentId using the as its value the id you get from a Quote endpoint return data.
    • The order status will be imediatelly "approved".
    • That's two API calls to create and approve an order: one request to \quote and one to \orders - but you will know the shipping cost and estimatedDeliveryDays before approval.
  1. Pre-Approved - one API call, use this endpoint to create an order with status "approved" and with a shipmentMethodId from the table bellow.
    shipmentMethodId Description
    1 Cheapest
    2 Fastest
    3 Collect (only for specific contracts with Digipix)
  • The order status will be imediatelly "approved".
  • It is a single API call to create and approve an order - but you will not know the shipping cost and estimatedDeliveryDays before approval.

Important: Digipix expects the files to be available for 60 days to be downloaded again if necessary.

Authorizations:
OAuth2 (orders)
header Parameters
Content-Type
required
string
Example: application/json

Request Content-Type

Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJGZXN0Y29sb3IiLCJleHAiOjE1OTgzOTA1ODYsImp0aSI6IiIsImlhdCI6MTU5ODM4Njk4NiwiaXNzIjoiYXBpLmRpZ2lwaXguZGV2Iiwic3ViIjoiIn0.Sfp5Js009Hk5Ikq7uwnxkh-NoFX8O7S38yjP_H_X5jE

Header with Bearer <access_token> using access_token received on /oauth/token

Request Body schema: application/json

Data to create a new order

customData
object

You can add your own data to this object and Digipix will not use it, just send it back to you when posting to your endpoint

statusNotificationUrl
string

The URL that digipix will send status notifications to

required
object

Contact and shipment details

required
Array of objects

Items data

status
string

If you are sending a ShipmentId you can send APPROVED here to have your order pre-approved

shipmentId
string

If you have an if from \Quote request, you can send it as a ShipmentId to create an approved order with that shipment

shipmentMethodId
number

Please refer to the 3 possible flows text above

shipmentMethod
string

Equivalent to shipmentMethodId but a label instead of an id

shipmentKey
string
Deprecated
partnerOrderID
string <= 64 characters

You can use this entry to insert your internal order/invoiceID

Responses

Callbacks

Request samples

Content type
application/json
Example
create
create
create-with-custom-data
create-approved-order
create-with-shipmentMethodId
create-with-shipmentId
{
  • "recipient":
    {
    },
  • "items":
    [],
  • "statusNotificationUrl": "https://my-server.com/order-callback/123456"
}

Response samples

Content type
application/json
Example
success
success
success-with-custom-data
success-create-approved-order
success-create-with-shipmentMethodId
success-create-with-methodKey
{
  • "id": "tFN9mEXgro9feZ7Fjf61",
  • "partnerId": "eHxI1wQ5stcOsmTG5aAr",
  • "partnerName": "Partner Name",
  • "status": "QUOTE",
  • "createdAt": "2020-08-26T21:31:10.7582058Z",
  • "statusNotificationUrl": "https://my-server.com/order-callback/123456",
  • "recipient":
    {
    },
  • "items":
    [
    ],
  • "shipments":
    [
    ],
  • "subtotal": 41.4,
  • "total": 41.4
}

Callback payload samples

Callback
POST: Callback to your Endpoint
Content type
application/json
{
  • "id": "string",
  • "status": "string",
  • "customData": { },
  • "tracking_items":
    [
    ]
}

Change order status Approve/Cancel

scope: orders

Allows you to either aapprove or cancel an order.

To approve it is necessary to inform either the shipmentId or the shipmentMethodId.

Only orders that are not yet in production can be canceled.

Authorizations:
OAuth2 (orders)
path Parameters
orderId
required
string

Order ID

header Parameters
Content-Type
required
string
Example: application/json

Request Content-Type

Authorization
required
string

Header with Bearer <access_token> using access_token received on /oauth/token

Request Body schema: application/json

Data for patching an order. Use Status and either shipmentId or shipmentMethodId.

status
string

Status to patch order ("approved" or "canceled")

shipmentId
string

Selected ShipmentId from the created Order

shipmentMethodId
number

Selected ShipmentMethodId, refer to table at Create New Order

shipmentKey
string
Deprecated

Responses

Request samples

Content type
application/json
Example
approve
approve
cancel
{
  • "status": "approved",
  • "shipmentId": "ZP2ckind4FwRhfIlt5dI"
}

Response samples

Content type
application/json
{
  • "id": "skR3yfgC9AfpDq6ixDzt",
  • "partnerId": "eHxI1wQ5stcOsmTG5aAr",
  • "partnerName": "Partner Name",
  • "status": "APPROVED",
  • "createdAt": "2020-08-26T22:02:32.970683Z",
  • "statusNotificationUrl": "https://my-server.com/order-callback/123456",
  • "recipient":
    {
    },
  • "items":
    [
    ],
  • "shipment":
    {
    },
  • "subtotal": 41.4,
  • "shippingCost": 2.09,
  • "total": 43.49
}

Get existing order

scope: orders

Retrieves an existing order

Authorizations:
OAuth2 (orders)
path Parameters
orderId
required
string

Order ID

header Parameters
Authorization
required
string

Header with Bearer <access_token> using access_token received on /oauth/token

Responses

Response samples

Content type
application/json
Example
order-new
order-new
order-shipped
{
  • "id": "icTwB5S3rtfEgvE41DEo",
  • "partnerId": "eHxI1wQ5stcOsmTG5aAr",
  • "partnerName": "Partner Name",
  • "status": "NEW",
  • "createdAt": "2020-08-26T22:00:24.6153558Z",
  • "statusNotificationUrl": "https://my-server.com/order-callback/123456",
  • "recipient":
    {
    },
  • "items":
    [
    ],
  • "shipment":
    {
    },
  • "subtotal": 41.4,
  • "shippingCost": 2.09,
  • "total": 43.49
}

Products

Endpoint for listing all the products avaiable to you or the data of a single product.

List products

scope: products

Retrieves a list of products

Authorizations:
OAuth2 (products)
header Parameters
Authorization
required
string

Header with Bearer <access_token> using access_token received on /oauth/token

Content-Type
required
string

Request Content-Type

Responses

Response samples

Content type
application/json
Example
response
response
multi-parts-response
[
  • {
    }
]

Get product

scope: products

Retrieves a product by id

Authorizations:
OAuth2 (products)
path Parameters
productId
required
string
header Parameters
Authorization
required
string

Header with Bearer <access_token> using access_token received on /oauth/token

Content-Type
required
string

Request Content-Type

Responses

Response samples

Content type
application/json
Example
response
response
example-2
{
  • "id": "photobook",
  • "name": "Photobook",
  • "internalCode": 123,
  • "price": 10.9,
  • "weight": 400,
  • "productionTime": 5,
  • "parts":
    [
    ]
}

Quote

Endpoint for creating a quote.

It requires less data than an order, only an array of items and a zipCode, and returns the cost and estimatedDeliveryDays of our shipping options and a id for each.

It does not generate an order. But you can create an order with the id from the selected shipping.

Create new quote

scope: quote

This calculation is not saved, and only for consultation

Authorizations:
OAuth2 (quote)
header Parameters
Content-Type
required
string
Example: application/json

Request Content-Type

Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJGZXN0Y29sb3IiLCJleHAiOjE1OTgzOTA1ODYsImp0aSI6IiIsImlhdCI6MTU5ODM4Njk4NiwiaXNzIjoiYXBpLmRpZ2lwaXguZGV2Iiwic3ViIjoiIn0.Sfp5Js009Hk5Ikq7uwnxkh-NoFX8O7S38yjP_H_X5jE

Header with Bearer <access_token> using access_token received on /oauth/token

Request Body schema: application/json

A JSON object containing info about quote

zipCode
required
string 8 characters ^[0-9]{8}

ZipCode (any non-numeric characters will be removed)

required
Array of objects

Array of items

Responses

Request samples

Content type
application/json
{
  • "zipCode": "01311100",
  • "items":
    [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Notifications

This is the POST that Digipix will do to your endpoint, if you send its URL in the statusNotificationUrl of an order.

Although recommended, it is not necessary for you to implement this endpoint. You can also GET an order status with our order endpoint or manually consult our dashboard.

Order status update notifications

Attention: this endpoint is implemented by the partner, and not by Digipix.

The Digipix API provides functionality for notifying the status change of an order placed on the platform.

To make use of this functionality, just specify the statusNotificationUrl field when creating an order.

path Parameters
statusNotificationUrl
required
string
Request Body schema: application/json

Depending on the status extra information can be sent

  • SHIPPED, DELIVERED send track info
id
required
string non-empty
status
required
string non-empty
object
Array of objects

Responses

Request samples

Content type
application/json
Example
simple-notify
simple-notify
simple-with-custom-data
simple-shipped
simple-delivered
{
  • "id": "abc123",
  • "status": "IN_MANUFACTURING"
}