Technical documentation
- Home
- Technical documentation
Find the complete list of available Sellers endpoints here (Download YAML) :
Authentification Allows you to retrieve your API Bearer Token, in order to use our API's. 1 endpoint
Use this route to generate your API Bearer Token.
Functional Rules:
-
Use
application/x-www-form-urlencodedasContent-Typeheader -
Use
client_credentialsasgrant_type -
Your token is available for 2h
-
Use the generated token
access_tokenin theAuthorizationheader as:Authorization:Bearer {access_token}
Server : https://auth.octopia-io.net
Request body
|
application/x-www-form-urlencoded |
Response codes
200 - OKapplication/json |
||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
Seller configuration List of endpoints to get seller's information 6 endpoints
Retrieves seller information.
Example:
-
Retrieve seller's information:
/sellers
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Retrieves seller addresses.
Example:
-
Retrieve seller's addresses:
/sellers/addresses
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Get seller indicators.
Example:
-
Retrieve seller's indicators:
/sellers/indicators
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Retrieves seller susciptions
Example:
-
Retrieve seller's subscriptions:
/sellers/subscriptions
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
⚠️ This endpoint is deprecated
Retrieves seller delivery modes.
Example:
-
Retrieve seller's delivery-modes:
/sellers/delivery-modes
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Response codes
200 - Successapplication/json |
||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
List of supported carriers with high Tracking retrieval performance.
The list provides the associated mandatory carrierCode requested for tracking POST
Example:
-
Retrieve all carries:
/carriers
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Response codes
200 - List of supported carriers.application/json |
||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Products Referential List of endpoints to manage the product referential 5 endpoints
This route allows you to count all the categories.
Example:
-
Count categories:
/categories/count
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| Accept-Language | header |
string
|
The Example : fr-FR |
Response codes
200 - OKapplication/json
|
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This route allows you to retrieve all the categories with a paginated result.
Functional Rule
Accept-Language allows you to get the details for one of these three languages (EN, FR, ES)
Example:
-
Retrieve categories:
/categories
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| Accept-Language | header |
string
|
The Example : fr-FR |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| pageIndex | query |
number
|
The
Example : 2 |
| pageSize | query |
number
|
The
Example : 25 |
| sort | query |
string
|
The
Example : reference,label,parentReference |
| desc | query |
string
|
The
Example : reference,parentReference |
| fields | query |
string
|
The
Example : label,level,isActive |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This route allows you to get the details of a given category.
Functional Rule:
Accept-Language allows you to get the details for one of these three languages (EN, FR, ES)
Example:
-
Retrieve categoriy
010H0R:/categories/010H0R
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| Accept-Language | header |
string
|
The Example : fr-FR |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| categoryReference* | path |
string
|
The category reference is a string value and must have:
Letters must be capital letters. Example : 010H0R |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This route allows you to retrieve the properties information of a given category.
Functional Rules:
-
If a property is ranged, its possible choices will be filled in.
-
3 kind of necessities exists and are useful when using Products submission :
-
Mandatory: These properties must be filled in when creating a product in this category (if not, product creation will be denied)
-
Recommended: These properties will improve the visibility of the products, in this category, on the sales channels (doesn't impact product creation)
-
Optional: These properties can be useful for some products in this category (doesn't impact product creation)
-
-
Accept-Languageallows you to get the details for one of these three languages (EN, FR, ES)
Example:
-
Retrieve properties of category
010H0R:/categories/010H0R/properties
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| Accept-Language | header |
string
|
The Example : fr-FR |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| categoryReference* | path |
string
|
The category reference is a string value and must have:
Letters must be capital letters. |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||
409 - Conflictapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This route allows you to retrieve all the brands with a paginated result.
Examples:
-
Retrieve the first page of results with a maximum of 25 brands:
/brands?pageIndex=1&pageSize=25 -
Retrieve only the name of the first page of results with a maximum of 25 brands:
/brands?pageIndex=1&pageSize=25&fields=name
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| pageIndex | query |
number
|
The
Example : 1 |
| pageSize | query |
number
|
The
Example : 25 |
| fields | query |
string
|
The
Example : name |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Products Management List of endpoints to create and retriveve products 4 endpoints
This route allows you to get the number of products for a given seller.
The products counted are the marketable products you created and the non-marketable products you modified.
Functional Rules:
-
You can filter with EN/ES or FR language (if none FR language by default) and CategoryReference.
-
The filter gtin is not supported anymore.
-
The filter isMarketable has been deprecated due to performance reasons.
Examples:
-
Get the number of products based on their categories:
/products/count?categoryReference=010101,010102
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
| Accept-Language | header |
string
|
The Accept-Language header defines the language of the submission and must be a valid IETF BCP47 tag (default: fr-FR) Example : fr-FR |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| categoryReference | query |
string
|
The CategoryReference parameter allows you to filter the products based on their categories Example : 010201 |
Response codes
200 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This route allows you to get a list of products for a given seller.
The products displayed are the marketable products you created and the non-marketable products you modified.
If a product is marketable and you didn't created it, some fields will not be displayed.
For each product, it is indicated whether it is editable or enrichable (you can only modify data that you created or enrich new data).
You can filter with gtin, EN/ES or FR language (if none FR language by default) and categoryReference.
If you filter by gtin and the seller is not the creator, the following fields will be displayed:
- reference
- label
- gtin
- language
- category
- brand
When using the cursor/limit pagination, products are sorted by update date, with the most recently updated products first. It is not possible to sort otherwise.
IMPORTANT NOTES:
- The filter isMarketable has been deprecated due to performance reasons.
- The pagination by pageIndex/pageSize has been deprecated due to performance reasons. Use the pagination by cursor/limit.
Examples:
-
Get a list of products by GTIN (10 GTIN max. separated by comma):
/products?gtin=88381883016,8452136259876 -
Get a list of products based on their categories:
/products?categoryReference=010101,010102 -
Get a list of products using pagnitation by cursor:
/products?cursor=NjdjNmE1MzcxNzE5Y2ViOGI4MDc0Y2IxfG5leHQ=&limit=25 -
Get a list of products with some fields displayed:
/products?fields=label,description
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
| Accept-Language | header |
string
|
The Accept-Language header defines the language of the submission and must be a valid IETF BCP47 tag (default: fr-FR) Example : fr-FR |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| limit | query |
integer
|
The Limit parameter allows you to precised the number of elements should be displayed when using cursor (default: 25 / min: 0 / max: 100) Default : 50 Example : 25 |
| cursor | query |
string
|
The Cursor parameter allows you to navigate through paginated results by specifying a position in the dataset for the next retrieval Example : NjdjNmE1MzcxNzE5Y2ViOGI4MDc0Y2IxfG5leHQ= |
| gtin | query |
integer
|
The Gtin parameter allows you to filter the products based on their gtin Example : 88381883016 |
| categoryReference | query |
string
|
The CategoryReference parameter allows you to filter the products based on their categories Example : 010201 |
| fields | query |
string
|
The Field parameter allows you to precise which fields should be displayed (default: *) Example : label,description |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this API to integrate your products on Octopia
Functional Rules:
-
Octopia accepts products in English, French and Spanish. The values accepted for the language field are en-US, fr-FR, and es-ES.
-
Only products with fr-FR language will be available for Cdiscount
-
This process is asynchronous, check the integration results using the packageId provided in the API response and the API:
- GET
/products-integration-reports
- GET
-
If you are creating a standard product:
- Use gtin attribute only
-
If you are creating a variant product:
-
Use GTIN field to determine the public identifier of the product
-
Use variantGroupReference field to determine the parent product linking a variant family
-
-
If you want to add an associated file on an authorized property, make sure that:
-
The file doesn't exceed 1Mo
-
The file respect the expected format (pdf/jpg/...etc). You can get this information by consulting the route properties/{reference}
-
The file is provided via URL format
-
The number of items cannot be more than the following limit (min: 1 / max: 10 000)
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
| Accept-Language* | header |
string
|
The Accept-Language header allows you to precise which language to use for the request. Example : fr-FR |
Request body
|
The products to submit application/json |
Response codes
202 - Acceptedapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
406 - Not Acceptableapplication/problem+json |
||||||||||||||||
415 - Unsupported Media Typeapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This route allows you to obtain technical and functional information about product submissions.
Functional Rules:
The Status field is the result of the integration process:
-
Refused: Your product cannot be integrated (every element of your submission has been ignored) -
Validated: Your product has been validated and is being processed -
Integrated: Your product has been successfully integrated (some elements may have been ignored)
The OperationType field is the type of product integration
-
Creation: New product created -
Modification: Existing product modified -
Identical: Existing product not modified
If no Accept-language is filled then you will receive your products in all integrated languages.
Examples:
-
Get a list of informations about product submission based on their package:
/products-integration-reports?PackageId=d8cccfa2-b2d0-431a-a627-e078febc78a7 -
Get a list of informations about product submission based on their gtin`:
/products-integration-reports?Gtin=7569824569870,4569877569820 -
Get a list of informations about product submission using pagnitatio`:
/products-integration-reports?PageIndex=1&PageSize=25 -
Get a list of informations about product submission with some fields displayed:
/products-integration-reports?Fields=title,description -
Get a list of informations about product submission with some fields sorted in ascending order:
/products-integration-reports?Sort=title,description -
Get a list of informations about product submission with some fields sorted in descending order:
/products-integration-reports?Desc=title,description
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
| Accept-Language | header |
string
|
The Example : fr-FR |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| packageId | query |
string
|
The PackageId parameter allows you to filter the products based on their package |
| gtin | query |
integer
|
The Gtin parameter allows you to filter the products based on their gtin |
| pageIndex | query |
integer
|
The PageIndex parameter allows you to precise which page of results should be displayed (default: 1 / min: 1) Default : 1 |
| pageSize | query |
integer
|
The PageSize parameter allows you to precised the number of elements should be displayed (default: 25 / min: 0 / max: 100) Default : 25 |
| fields | query |
string
|
The Field parameter allows you to precise which fields should be displayed *(default: )** |
| sort | query |
string
|
The Sort parameter allows you to precise which fields should be sorted in ascending order |
| desc | query |
string
|
The Desc parameter allows you to precise which fields should be sorted in descending order |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Offers integration (JSON) List of endpoints to create or update offers with JSON 6 endpoints
This method allows you to create an offer package to manage your offer catalog on a sales channel.
Please note: This feature is not available for Cdiscount yet
Functional Rules:
- What is the purpose of this method ?
Once your offer package is created, you will be able to upload offer requests in it that will create, update or delete offers from your catalog according to your package type.
- What are the package types ?
You can use one of the following packages type to manage your offer catalog:
-
Upsert: (case sensitive) allows to create new offers or replace an existing one with new information. Requires all the mandatory information of the offer. -
Update: (case sensitive) allows to update partially existing offers. Requires the seller external reference and one or several of the information (field) that you want to update. -
Delete: (case sensitive) allows Allows to delete existing offers. Requires only the seller external reference.
- Where can you find the package id ?
The package id is available into the Content-Location in the Headers.
- What is the Accept-Language use ?
The Accept-Language will define the offer requests results message localization when your package will be treated. You can choose from French (fr-FR), English (en-US) and Spanish (es-ES).
- What are the limits ?
Here are the guidelines:
-
Each package can only target one sales channel.
-
Each package can only have one type.
- I have created an offer package, what do I do now ?
Once your offer package is created, you can:
-
Check the information of about your package through
GET
/offer-packages -
Start uploading your offer requests through
POST
/offer-packages/{packageId}/offer-requests.
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| Accept-Language | header |
string
|
The Default : en-US Example : en-US |
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
| SalesChannelId* | header |
string
|
The sales channel identifier Example : CDISFR |
Request body
|
application/json |
Response codes
201 - CreatedHeaders:
|
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
429 - Too Many Requestsapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This method allows you to get your existing packages and gives you the ability to filter them by status.
Functional Rules:
-
What are the packages status that can be used as a filter?
By state:
-
WaitingForCompletion: offer packages open to new offer requests uploads.
- GET
/offer-packages?state=WaitingForCompletion
- GET
-
Ready: offer packages ready to be treated.
- GET
/offer-packages?state=Ready
- GET
-
IntegrationPending: offer packages currently being treated
- GET
/offer-packages?state=IntegrationPending
- GET
-
Integrated: offer packages successfully treated
- GET
/offer-packages?state=Integrated
- GET
-
Rejected: offer packages rejected
- GET
/offer-packages?state=Rejected
- GET
By Sales Channel Id:
-
salesChannelId: filter all your packages created on the sales channel
- GET
/offer-packages?salesChannelId=SCID
- GET
-
-
Your package is on Waiting for completion status?
You can upload your offer requests through the method:
POST
/offer-packages/{packageId}/offer-requests -
Your package is on Integrated status?
You can check your offer requests results through the method:
GET
/offer-packages/{packageId}/offer-requests-results -
Your package is on Rejected status?
You can check the reason on the result message
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| state | query |
string
|
The state of a package Example : Integrated |
| salesChannelId | query |
string
|
Format - string. The sales channel identifier of a package Example : SCIDFR |
| limit | query |
integer
|
The number of items in a page Default : 100 Example : 10 |
Response codes
200 - List of packages foundapplication/json
|
||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||
429 - Too Many Requestsapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This method allows you to check your package using the packageId
Functional Rules:
-
Your package is on Waiting for completion status?
You can upload your offer requests through the method: POST
/offer-packages/{packageId}/offer-requests -
Your package is on Integrated status?
You can check your offer requests results through the method: GET
/offer-packages/{packageId}/offer-requests-results -
Your package is on Rejected status?
You can check the reason on the result message
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| packageId* | path |
string
|
The unique identifier of the package Example : AAA0000001 |
Response codes
200 - the package with specified idapplication/json |
||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||
429 - Too Many Requestsapplication/problem+json |
||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This method allows you to indicate that the offer request upload is complete and the package can be treated.
The Patch method with the status "Ready" is sending the package to the offer integration system.
Functional Rules:
-
What are the limits?
-
You can only update packages that have the status "Waiting for completion"
-
Once you declare your package "Ready", you will no longer be able to upload offer requests. You will need to create another package.
-
-
You have indicated that your package is ready?
-
The package is being processed.
During the treatment, the statuses of your package will evolve from Ready to IntegrationPending. The length of this process can be different depending on the size of the package. Once treated, the status of the package will be Integrated or Rejected.
-
-
What's next?
-
You can check the progress of one package through the method GET
/offer-packages/{packageId} -
You can check your packages using filters through the method GET
/offer-packages/ -
If the package is Integrated, you can check your offer requests results through the method GET
/offer-packages/{packageId}/offer-requests-results
-
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| packageId* | path |
string
|
The package identifier Example : AAA0000001 |
Request body
|
application/json |
Response codes
204 - No content |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
429 - Too Many Requestsapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This method allows to upload offer requests in an existing offer package before sending it to be treated.
You can upload offer requests as many times as you want until you consider your offer package complete.
Functional Rules:
-
What kind of offer requests should I upload according to my package type?
According to your package types, here are the expected offer request:
-
Upsert: Every offer request must contain all the mandatory information of an offer.
-
If no other offer on this sales channel share the same seller external reference, GTIN/EAN code and condition, your offer will be created.
-
Else, the existing offer information will be replaced with the offer request information.
-
-
Update: Only the Seller External Reference and the updated information should be added.
-
If no other offer on this sales channel share the same seller external reference, your offer requests will be rejected. You will have to create the offer thanks to the upsert package type to be able to update then
-
Else, the existing offer will be updated with the information submitted. The offer information submitted can concern at least one information otherwise the offer request will be rejected. You can update one or several information of your offer. For example, you update only the price for one offer and for another offer the price AND the quantity. Every kind of offer information can be updated. The remaining information will stay the same.
-
Please note that:
-
If you wish to update information expressed as array in the offer request, please include the full list of attributes as it will replace the existing arrays
-
If you upload several times the same seller external reference with different offer information in each, the offer request will be rejected for all information because we do not manage duplicated offer information
-
If one or several fields of offer are not correct, the fieds will be ignored. And if none of them are correct, the offer request will be rejected
-
If you update the deliveryModes, the preparationTime field and value are mandatory in the offer request.
-
The information about the product (Gtin, reference, condition) can not be updated
-
By Example:
The examples of offer requests update bellow are just samples of what is possible to update. All the combinaison are possible. Only the recognised field will be updated.
-
-
Delete: Only the offer Seller external reference should be included
-
If no other offer on this sales channel share the same seller external reference, your request offer will be rejected.
-
Else, the existing offer will be deleted from this sales channel offer catalog, and then unpublished from this sales channel.
-
-
-
What about your stock quantity?
Your stock quantities are mutualised with each sales channel in which you have a corresponding offer for this product and condition. Updating your stock will update it on each of these sales channels.
You can remove an offer from a specific sales channel by deleting it rather than updating its stock quantity to 0.
-
What are the limits?
-
Each upload of offer request into the package must not exceed 100 offer requests
-
One offer package can only gather a maximum of 200 000 offer requests
-
You can only upload offers in packages which status is Waiting for completion
-
Only a json surface check is made at this stage. The real offer request control is made when you submit the package
-
You can check your package status through the method
GET
/offer-packages/{packageId}
-
-
Where can you find more information on the fields of an offer request?
You can consult the offer schemas for more information on the fields
-
You have uploaded all of the offer requests you wanted, what's next?
You can now indicate that your package is ready to be treated through the method PATCH
/offer-packages/{packageId}
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| packageId* | path |
string
|
The package identifier Example : AAA0000001 |
Request body
|
application/json |
Response codes
201 - Created |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
429 - Too Many Requestsapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This methods allows you to get the integration results of your offer requests to check if they have been integrated or rejected.
Functional Rules:
-
How can I check if my offer request was integrated ?
You can check the
integrationStatus:-
Integrated: Your offer request has been created, updated or deleted.
-
Rejected: Your offer request has been rejected, check the results for more information
-
Duplicated: Your offer request is duplicated, check the result for more information. It means that the information of your offer request is rejected.
-
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| packageId* | path |
string
|
The package identifier Example : AAA0000001 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| limit | query |
integer
|
The number of items in a page Default : 100 Example : 10 |
Response codes
200 - List of packages foundapplication/json
|
||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||
429 - Too Many Requestsapplication/problem+json |
||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Offers integration (XML) List of endpoints to create or update offers with XML zip packages 2 endpoints
Retrieve offer package logs.
Example:
-
Retrieve a package with its package Id:
/offer-integration-packages/424325363619
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| packageId* | path |
integer
|
Format - int64. Package identifier. Example : 424325363619 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| $limit | query |
integer
|
Format - int32. Must be written as follows $limit Example : 50 |
| $page | query |
integer
|
Format - int32. Must be written as follows $page Example : 1 |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Submits an zip package to update your offers (stock, prices, delivery costs...).
Example of zip package
-
Full package (With Sales Channel filter)
-
Stock & Price (Only for Cdiscount sale channel)
More information here
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Request body
|
Url to the package zip file. application/json |
Response codes
200 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Offers Management List of endpoints to get informations about offers 4 endpoints
Retrieves offers that match the query from the offer repository.
Please note:
-
The limit of offers per request has increased. You can now paginate your results up to 1 000 offers.
-
If parameters
fieldsandexpandare both sent, theexpandparameter will be ignored.
Functional rules:
There are some differences in the attributes you can retrieve from Cdiscount (CDISFR) compared with other channels
-
Attributes only available on Cdiscount:
-
comments -
offerCompetition -
Best offer information into
salesChannelFeedback.bestOfferDetails -
expandparameter withsalesChannelFeedbackvalue -
Qualiscore: more details on offerQuality.scoreReasons into the FAQ
-
-
Attributes only available on other sales channels:
-
salesChannelAcceptanceStatus -
deliveryOffers.storageCountry -
Best offer information into
isBestOffer&BestOffer
-
New features:
-
Fields parameter:
The
fieldsparameter lets you fetch only the data you need.The payload will always contain basis information as:
-
offerId -
sellerExternalReference -
offerState -
createdAt -
updatedAt
To retrieve only the useful information, specify the field (e.g.,
condition) or the node name (e.g.,salesChannelFeedback) or the node name with the field name separated by a dot (e.g.,facialPrice.price). -
-
Expand parameter (Cdiscount Only):
To include sales-channel feedback information, set the
expandparameter to:salesChannelFeedback
This node contains information returned by the sales channels' APIs. Because this data may take time to update, several
updatedAtfields are provided.If the sales channel does not return the information, the fields will be
null.Please note: Sales channel feedbacks are currently only available for Cdiscount, but other channels will be added soon.
Examples:
-
Retrieve the first 1 000 offers on Cdiscount:
/offers?salesChannelId=CDISFR&limit=1000 -
Retrieve an offer based on it external reference on saleschannel Seller Sandbox:
/offers?salesChannelId=SELLZZ&sellerExternalReferences=ABC1234 -
Retrieve the first 1 000 offers with only specific attributes (offerId & integrationPrice):
/offers?salesChannelId=SELLZZ&fields=integrationPrice.price -
[Cdiscount Only] Retrieve the first 1 000 offers with saleschannel feedbacks:
/offers?salesChannelId=CDISFR&expand=salesChannelFeedback
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| salesChannelId* | query |
string
|
Sales channel identifier you want to retrieve,. Example : SCIDFR |
| limit | query |
number
|
Limits the number of offers per page, maximum 1000, default 100 Default : 100 Example : 500 |
| fields | query |
string
|
The fields parameter lets you fetch only the data you need. By default, the payload will always contains basis information as offerId, sellerExternalReference and offerState Example : condition, product, salesChannelFeedback.competingOffers |
| expand | query |
string|enum
|
In order to display the sales channel feedback information in addition of the standard payload you must fill the expand parameter with salesChannelFeedback Example : salesChannelFeedback Available values : ["salesChannelFeedback"] |
| offerIds | query |
string
|
Offers identifiers you want to retrieve, separated by a comma. Example : 1234_HAM0028178207328_6_SCIDFR,1234_AUC4894626011153_6_SCIDFR |
| offerStates | query |
string
|
Offers state you want to retrieve, separated by a comma. Example : inactive,active |
| gtins | query |
string
|
Products gtin you want to retrieve, separated by a comma. Example : 1234567890123, 2345678901234 |
| sellerExternalReferences | query |
string
|
Seller external references you want to retrieve, separated by a comma. Example : REF001,REF002 |
| updatedAtMin | query |
string
|
Format - date-time (as date-time in RFC3339). Return offers only if "updatedAt" property is bigger or equal to parameter value. Example : 2023-04-20T10:10:00.0000000+00:00 |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
⚠️ This endpoint is deprecated
Use this API in order to searches offers by criteria.
Functional Rules:
-
If you want to retrieve some offers from spesific marketplace you MUST send the attribute:
sales_channel_idin the request body. -
If the
sales_channel_idis shared in the request body the response will be returned with cursor indexing ortherwise the response will be returned with index indexing.
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| $limit | query |
integer
|
Format - int32. Must be written as follows $limit Example : 50 |
| $page | query |
integer
|
Format - int32. Must be written as follows $page Example : 1 |
Request body
|
Search offers request. application/json |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
⚠️ This endpoint is deprecated
Allow you to retrieve competing offers.
This operation makes it possible to obtain competing offers as soon as a price change has taken place.
Functional Rules:
-
Please note: This endpoint is subject to a specific opening.
-
The seller must request access by opening an API ticket from his seller zone.
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Response codes
200 - Successapplication/jsontext/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Request |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
⚠️ This endpoint is deprecated
To get competing offers.
This operation gets, for a specified list of products, competing offers with price informations.
Functional Rules:
-
Please note: This endpoint is subject to a specific opening.
-
The seller must request access by opening an API ticket from his seller zone.
Exemples:
-
Get the product: 2009842947663
/competing-offers?products=2009842947663 -
Get the products: 2009842947663, 2009842947664, 2009842947665
/competing-offers?products=2009842947663&products=2009842947664&products=2009842947665
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| products* | query |
array[string]
|
the seller products IDs. Example : List: ["2009842947663", "2009841234763"] |
Response codes
200 - Successapplication/jsontext/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Request |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Orders List of endpoints to manage orders 10 endpoints
Use this method to validate a specific order.
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| orderId* | path |
string
|
The order unique identifier in Octopia's system. Example : SCID01210525142759UT8E |
Request body
|
List of validation request for the given order. A request may contain several lines validation of the order. application/json |
Response codes
201 - Created. |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
409 - Conflictapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Retrieve the total count of all orders matching the request parameters
Functional Rules:
-
You can query on multiple sales channel using comma separated values
-
Filters are restrictive, if you don't provide a filter then no filtering is applied on this field
Example:
-
Retrieve the count of orders
InPreparationfor the sales channelSCID01:/orders/count?salesChannelId=SCID01&status=InPreparation -
Retrieve the count of orders
ShippedorDeliveredsince the first of march 2023 for the sales channelSCID01:/orders/count?salesChannelId=SCID01&status=Shipped,Delivered&updatedAtMin=2023-03-01T00:00:00.000Z
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| reference | query |
string
|
Seller reference for the ressource. Example : 0223258 |
| salesChannelId | query |
string|null
|
The Identifier of the sales channel Example : TEST |
| businessOrder | query |
boolean
|
Gets whether order is for business |
| status | query |
string|enum|null
|
The status of the ressource. Example : InPreparation Available values : ["Processing", "WaitingAcceptance", "Accepted", "Refused", "InPreparation", "Shipped", "Delivered", "Cancelled", "Rejected"] |
| supplyMode | query |
string|enum|null
|
The supply mode. Example : Seller Available values : ["Seller", "Fulfillment"] |
| shippingCountry | query |
string
|
The shipping country code. Example : FR |
| updatedAtMin | query |
string
|
The updated at minimum date of orders. Example : 2023-12-25T14:30:00Z |
| updatedAtMax | query |
string
|
The updated at maximum date of orders. Example : 2023-12-25T15:30:00Z |
| createdAtMin | query |
string
|
The created at minimum date of the ressource. Example : 2023-12-25T14:30:00Z |
| createdAtMax | query |
string
|
The created at maximum date of the ressource. Example : 2023-12-25T15:30:00Z |
| shippedAtMin | query |
string
|
The shipped at minimum date of orders. Example : 2023-12-25T14:30:00Z |
| shippedAtMax | query |
string
|
The shipped at maximum date of orders. Example : 2023-12-25T15:30:00Z |
Response codes
200 - Successful response with the count of orders matching the criteriaapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
500 - An internal server error occurredapplication/problem+json |
Use this method to retrieve a list of orders using a set of filters.
Functional Rules:
-
You may filter your search by adding the following criteria in your request body:
-
A list of order
status -
An order reference
-
Is a business order
-
A shipping country
-
A supply mode
-
A sales channel identifier
-
A time range on order creation using
createdAtMin/createdAtMax -
A time range on order update using
updatedAtMin/updatedAtMax -
A time range on order shipping using
shippedAtMin/shippedAtMax
-
-
You may also sort your search by date using the following fields:
-
createdAt -
updatedAt -
shippedAtMax
-
-
To ensure a faster answer, the number of items retrieved per page is limited to 100 items maximum.
-
For Fulfillment orders, the shipping address of the order lines will only be available after the order has been shipped by our Fulfillment service.
-
For Seller orders, the shipping address of the order lines will only be available once the line is ready to be shipped (InPreparation).
Examples:
-
Retrieve orders without filters:
/orders?pageIndex=1&pageSize=100 -
Retrieve orders sorted by
createdAtby ascending order:/orders?pageIndex=1&pageSize=100&sort=createdAt -
Retrieve orders sorted by
createdAtby ascending order,updatedAtby descending order and filtered using a list of status:/orders?pageIndex=1&pageSize=100&sort=createdAt&desc=updatedAt&status=Accepted,Shipped
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| reference | query |
string
|
Seller reference for the ressource. Example : 0223258 |
| salesChannelId | query |
string|null
|
The Identifier of the sales channel Example : TEST |
| businessOrder | query |
boolean
|
Gets whether order is for business |
| status | query |
string|enum|null
|
The status of the ressource. Example : InPreparation Available values : ["Processing", "WaitingAcceptance", "Accepted", "Refused", "InPreparation", "Shipped", "Delivered", "Cancelled", "Rejected"] |
| supplyMode | query |
string|enum|null
|
The supply mode. Example : Seller Available values : ["Seller", "Fulfillment"] |
| shippingCountry | query |
string
|
The shipping country code. Example : FR |
| updatedAtMin | query |
string
|
The updated at minimum date of orders. Example : 2023-12-25T14:30:00Z |
| updatedAtMax | query |
string
|
The updated at maximum date of orders. Example : 2023-12-25T15:30:00Z |
| createdAtMin | query |
string
|
The created at minimum date of the ressource. Example : 2023-12-25T14:30:00Z |
| createdAtMax | query |
string
|
The created at maximum date of the ressource. Example : 2023-12-25T15:30:00Z |
| shippedAtMin | query |
string
|
The shipped at minimum date of orders. Example : 2023-12-25T14:30:00Z |
| shippedAtMax | query |
string
|
The shipped at maximum date of orders. Example : 2023-12-25T15:30:00Z |
| pageIndex | query |
integer
|
The index of the current page of items Default : 1 Example : 1 |
| pageSize | query |
integer
|
Maximum number of items to return per page. Default : 50 Example : 50 |
| sort | query |
string
|
Ascending sort Example : asc:createdAt |
| desc | query |
string
|
Descending sort Example : desc:createdAt |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - An internal server error occurredapplication/problem+json |
Use this method to get a specific order details, using the orderId as parameter.
Functional Rules:
-
For
Fulfillmentorders, the shipping address of the order lines will only be available after the order has been shipped by our Fulfillment service. -
For
Sellerorders, the shipping address of the order lines will only be available once the line is ready to be shipped (InPreparation).
Example:
-
Get the order with id
SCID123456789:/orders/SCID123456789
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| orderId* | path |
string
|
The order unique identifier in Octopia's system. Example : SCID123456789 |
Response codes
200 - Successful response with a single order detailsapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - An internal server error occurredapplication/problem+json |
Use this method to ship a specific order, or order lines.
Functional Rules:
- Please note that this endpoint should only be called for orders or order lines with the
InPreparationstatus and a supplyMode equal toSeller
Example:
-
To create a new shipment for the order with id
SCID123456789:/orders/SCID123456789/shipments
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| orderId* | path |
string
|
The order unique identifier in Octopia's system. Example : SCID123456789 |
Request body
|
List of parcels for the given order. A parcel may contain several products of the order (e.g. small products shipped in one parcel), or a product may be shipped in several parcels (e.g. large products). application/json |
Response codes
201 - Successful response after creating a shipment for an order |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not foundapplication/problem+json |
||||||||||||||||
409 - Conflictapplication/problem+json |
||||||||||||||||
500 - An internal server error occurredapplication/problem+json |
Allows to filter the list of reasons to only include those applicable for the given order status.
Functional Rules:
- The cancellation reasons returned depend on the order status provided in parameter.
Example:
-
Retrieve cancellation reasons for shipped orders with sales channel ID
SCID01, user typeSellerand order statusShipped:/cancellation-reasons?salesChannel=SCID01&userType=Seller&orderStatus=Shipped
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| salesChannel | query |
string|null
|
The Identifier of the sales channel Example : SALESC |
| userType | query |
string|enum|null
|
The type of user Example : Seller Available values : ["Customer", "Seller", "SalesChannel", "CustomerCareService"] |
| orderStatus | query |
string|enum
|
Allows to filter the list of reason to only include those applicable for the given order status. Example : Accepted Available values : ["Accepted", "InPreparation", "Shipped", "Delivered"] |
Response codes
200 - Successful response with the list of cancellation reasonsapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
500 - Server Errorapplication/problem+json |
This API is used to retrieve total and partial cancellation requests.
Functional Rules:
-
At least one of the two parameters is mandatory:
-
OrderSellerId -
CancellationRequestId
-
-
By default the result list is sorted by descending order on
updatedAt.
Examples
Retrieve partial cancellation request for the order 547654:
/order-cancellation-requests?orderSellerId=547654
Retrieve the partial cancellation request for the offer 4596 in the order 547654:
/order-cancellation-requests?orderSellerId=547654&offerId=4596
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| orderSellerId | query |
string
|
Order seller identifier. Example : CASIFR23110913520O9RW9 |
| cancellationRequestId | query |
string
|
The order cancellation request Id Example : 3 |
| lineId | query |
string
|
The order line Id Example : AY01 |
| offerId | query |
string
|
The order offer Id Example : 5645851 |
| salesChannel | query |
string|null
|
The Identifier of the sales channel Example : SALESC |
| pageIndex | query |
integer
|
The index of the current page of items Default : 1 Example : 1 |
| pageSize | query |
integer
|
Maximum number of items to return per page. Default : 50 Example : 50 |
Response codes
200 - Successful response with cancellation requests detailsapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Server Errorapplication/problem+json |
This API is used to send a full cancellation request:
Functional Rules:
-
You can call
Get /cancellation-reasonsendpoint before calling this method to get eligible reasons for cancellation based on the order status. -
You can choose to refund the shipping costs or not.
-
You cannot create a full cancellation request on an order with one or more lines already cancelled.
-
Note that the cancellation reasons that can be used "depends" on the order status
-
In case of an order with a Fullfilment line(s), cancellation is only possible if the line(s) status is/are either
ShippedorDelivered, otherwise the cancellation will be rejected -
Once the cancellation request is accepted, the status of the order changes to
Cancelledand the seller's refund is triggered.
Example:
-
To create a new order cancellation request:
/order-cancellation-requests
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Request body
|
The order and reason for cancellation application/json |
Response codes
201 - Successful response after creating a total cancellation requestapplication/jsonLinks:
|
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
409 - Conflictapplication/problem+json |
||||||||||||||||
500 - Server Errorapplication/problem+json |
This API is used to request a partial cancellation.
Functional Rules:
-
Before calling this API you must retrieve the cancellation reason from the
Get /cancellation-reasons -
Note that the cancellation reason that can be used depends on the order line status
-
In case of an order with a Fullfilment line(s), cancellation is only possible if the line(s) status is/are either
ShippedorDelivered, otherwise the cancellation will be rejected -
If you do not want to request the refund of shipping costs, you must express your choice in the property
shippingCostRefund, and usefalseas value.
Example:
-
To create a new order partial cancellation request:
/order-partial-cancellation-requests
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Request body
|
The list of lines to cancel on the given order alongside their reasons application/json |
Response codes
201 - Successful response after creating a partial cancellation requestapplication/jsonLinks:
|
||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||
409 - Conflictapplication/problem+json |
||||||||||||||||||
500 - Server Errorapplication/problem+json |
This API allows you to retrieve the maximum allowable commercial gesture amount for a given order. It provides both the maximum amount that can be applied as a commercial gesture and the amounts of any previous commercial gestures applied to the order.
Functional Rules:
-
The maximum allowable commercial gesture is calculated by subtracting the previously granted commercial gestures from the maximum commercial gesture amount as well as any cancelled line of the order.
Example:
Max commercial gesture = €40 (Refer to Post /order-commercial-gesture-requests for details on calculating this amount). Sum of previous commercial gestures = €17. Max allowable commercial gesture = €40€ - €17 = €23`
-
In case of a Cdiscount order the maximum allowable commercial gesture amount will include refunds, and may not match with the commercial gestures sum.
Example:
-
To get the maximum allowable commercial gesture amount for the order with
orderIdSCID123456789:/orders/SCID123456789/commercial-gestures-available-amounts
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| orderId* | path |
string
|
The order unique identifier in Octopia's system. Example : SCID123456789 |
Response codes
200 - Successapplication/json |
||||||||||||||||
400 - The order does not existsapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
500 - Internal server errorapplication/problem+json |
Commercial gesture List of endpoints to manage commercial gestures 4 endpoints
This API is used to retrieve commercial gesture requests.
Functional Rules:
-
The default sort is descending on
updatedAt. -
You can use the
cursorto navigate through the data.
Example:
-
To retrieve another page of commercial gesture requests for order
MARJMA01210525142759UT8E:/order-commercial-gesture-requests?orderId=MARJMA01210525142759UT8E&cursor=c29ydDpkZXNjJmluY2x1ZGVfaXRlbT10cnVlJmlkPTE2ODIwNzA2Mzk=
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| limit | query |
integer
|
The amount of commercial gesture to retrieve. Default to 100. Default : 100 Example : 100 |
| cursor | query |
string
|
Pagination cursor. Use together with Example : eyJDdXJzb3JUeXBlIjoyLE9mZmVyVGVjaG5pY2FsSWQiOiIxMjM0NTZfQUFBQkI2MTEyM182X0NESVNGUiJ9 |
| orderId | query |
string
|
The order unique identifier in Octopia's system. Example : 54hgfioazlk1297867 |
| status | query |
string|enum|null
|
The status of the ressource. Example : InPreparation Available values : ["Processing", "WaitingAcceptance", "Accepted", "Refused", "InPreparation", "Shipped", "Delivered", "Cancelled", "Rejected"] |
| createdAtMin | query |
string
|
The created at minimum date of the ressource. Example : 2023-12-25T14:30:00Z |
| createdAtMax | query |
string
|
The created at maximum date of the ressource. Example : 2023-12-25T15:30:00Z |
| updatedAtMin | query |
string
|
The updated at minimum date of orders. Example : 2023-12-25T14:30:00Z |
| updatedAtMax | query |
string
|
The updated at maximum date of orders. Example : 2023-12-25T15:30:00Z |
Response codes
200 - Successful response with a list of commercial gesture requestsapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Server Errorapplication/problem+json |
This API is used to create an order commercial gesture.
The processing of commercial gestures is asynchronous.
Requests will be created, and if any of the functional rules are not met, they will be rejected.
Use /order-commercial-gesture-requests to check the status of the request
Functional Rules:
-
You can request a commercial gesture on a post-shipment order (
Shipped,Delivered) -
You can request multiple order commercial gesture with the same or different
reason -
If the
reasonproperty is set toOther, thereasonDetailsproperty becomes mandatory and must be provided to describe why this commercial gesture is being submitted. -
You can request a commercial gesture for orders that the sales channel has chosen to enable this option, use
/sales-channel-commercial-gesture-configurations/{salesChannelId}to check if this option is enabled. -
The maximum total amount of commercial gestures on an order depends on the sales channel configuration, use
/sales-channel-commercial-gesture-configurations/{salesChannelId}to check the available maximum gesture amount. -
The sales channel can choose a maximum rate and a maximum amount over the price of the order. The commercial gesture limit is the maximum amount between the specified fixed amount added to the order amount and the specified rate of the order amount.
Example:
Sales channel configuration: maximumAmount = €20, maximumRate = 120% Order amount (selling price shipping fees included) = €18. Max commercial gesture = Max ((18 + 20), (18 * 120% )) = Max (38, 21.6) = €38`
- The maximum total amount of commercial gestures does take into consideration the status of the order. If an order line is
Cancelled, its price is not taken into account in the calculation of the order amount.
Example:
Order line 1 amount = €10 and Order line 2 (Cancelled) amount = €10. Order amount = €10 (line 1) + €0 (line 2) = €10`
- In case of a Cdiscount order the maximum allowable commercial gesture amount will include refunds, and may not match with the commercial gestures sum.
- The commercial gesture currency matches that of the sales channel, use
/sales-channel-commercial-gesture-configurations/{salesChannelId}to check your sales channel currency. - Once the commercial gesture request is accepted, the amount of the commercial gesture will be deducted from your available balance
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Request body
|
The order and reason for commercial gesture application/json |
Response codes
201 - Successful response after creating a commercial gesture requestapplication/json |
||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||
500 - Server Errorapplication/problem+json |
This API is used to retrieve commercial gesture requests by unique identifier
Functional Rules:
-
Refer to the schema for status values
-
You can only have errors in
Rejectedstate
Example:
-
To retrieve the commercial gesture request with
requestId641832a0f35c2e8828e4612d:/order-commercial-gesture-requests/641832a0f35c2e8828e4612d
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| requestId* | path |
string
|
The order commercial gesture request Id Example : 641832a0f35c2e8828e4612d |
Response codes
200 - Successful response with a single commercial gesture request detailsapplication/json |
||||||||||||||||||||||||||||||||||
404 - NotFoundapplication/problem+json |
||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||
500 - Server Errorapplication/problem+json |
Retrieve the sales channel commercial gesture configuration
Functional Rules:
-
The
maximumAmountis the largest flat gesture you can do on an order. -
The
maximumRateis the largest amount relative to order price you can do on an order. -
The total gesture calculation cannot exceed the value given by the following rules:
Max(order price + maximumAmount, order price * maximumRate)
Example:
-
To get the sales channel commercial gesture configuration for sales channel
SALESC:/sales-channel-commercial-gesture-configurations/SALESC
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| salesChannelId* | path |
string
|
The sales channel identifier Example : TEST |
Response codes
200 - Successful response with commercial gesture configuration for a sales channelapplication/json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
500 - Server Errorapplication/problem+json |
Orders Invoices List of endpoints to send invoice to the client 5 endpoints
Use this endpoint to retrieve the status of your previously uploaded invoices.
Functional Rules:
-
The response will always be sorted by
createdAtdate in descending order. -
You can use the pagination token to navigate through the data.
Example:
-
To retrieve the second page of invoice imports:
/order-invoice-imports?cursor=c29ydDpkZXNjJmluY2x1ZGVfaXRlbT10cnVlJmlkPTE2ODIwNzA2Mzk=
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| pageSize | query |
integer
|
Maximum number of items to return per page. Default : 100 Example : 100 |
| cursor | query |
string
|
Pagination cursor. Use together with Example : eyJDdXJzb3JUeXBlIjoyLE9mZmVyVGVjaG5pY2FsSWQiOiIxMjM0NTZfQUFBQkI2MTEyM182X0NESVNGUiJ9 |
Response codes
200 - The list of importsapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal server errorapplication/problem+json |
Upload file(s) as the invoice for multiple orders.
Functional Rules:
-
The files may be in the following format: PDF, XML (UBL2.1 format), ZIP containing the above
-
If an order already had invoice documents, they will be replaced with the newly provided files.
-
This route will return
201and create an import report as long as the request is valid, the detail of whether or not the upload succeed will be available via the/order-invoice-importsendpoint. -
The file name must be a valid order identifier. If a zip is provided, then the inner file name must be a valid order identifier.
Example:
-
To upload invoice files for multiple orders:
/order-invoice-imports
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Response codes
201 - The result of the upload. Each file will have an entry with the name property matching the multipart request name property.application/json |
||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||
500 - Internal server errorapplication/problem+json |
Retrieve a single invoice import via its unique identifier
Functional Rules:
- The
importIdis an id that is returned when you upload an invoice file using thePOST /order-invoice-imports.
Example:
-
Get the order invoice import with id
738abbf4-320c-4689-bf88-d40bff03fb36:/order-invoice-imports/738abbf4-320c-4689-bf88-d40bff03fb36
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| importId* | path |
string
|
The unique invoice import identifier Example : 4ee9e071-7c3b-4494-be14-662f9c1af793 |
Response codes
200 - Successful response with a single invoice import detailsapplication/json |
||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||
404 - Not foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||
500 - Internal server errorapplication/problem+json |
Retrieve the invoice documents for the specified order
Functional Rules:
- You can retrieve the file once the invoice import is in
status=Success
Example:
-
Retrieve invoice documents for the order with
orderIdSCID123456789:/orders/SCID123456789/invoice-documents
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| orderId* | path |
string
|
The order unique identifier in Octopia's system. Example : SCID123456789 |
Response codes
200 - Successful response with the list of invoice documents for an orderapplication/zipapplication/pdfapplication/xml |
||||||||||||||||
400 - The order does not existapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - No invoice exists for the given order.application/problem+json |
||||||||||||||||
500 - Internal server errorapplication/problem+json |
Upload file(s) as the invoice for a given order.
Functional rules:
-
The files may be in the following format: PDF, XML (UBL2.1 format), ZIP containing the above
-
If an order already had invoice documents, they will be replaced with the newly provided files.
-
This route will return
201and create an invoice report as long as the request is valid, the detail of whether or not the upload succeed will be returned in the response body.
Example:
To upload invoice documents for the order with orderId SCID123456789:
/orders/SCID123456789/invoice-documents
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
The identifier of the seller Example : 135 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| orderId* | path |
string
|
The order unique identifier in Octopia's system. Example : SCID123456789 |
Response codes
201 - Successful response after uploading invoice documents for an order, import will begin shortlyapplication/json |
||||||||||||||||||||||||||||||||||||||
400 - The payload does not match the expected format or no order exists for the specified idapplication/problem+json |
||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||
500 - Internal server errorapplication/problem+json |
Discussions List of endpoints to manage the discussions 10 endpoints
Use this endpoint before initiating a discussion to get the sales channel configuration, serving the following functions:
-
Identify whether the sales channel allows or disallows the seller to initiate a discussion.
-
Identify recipients eligible for the seller when initiating a discussion.
Example:
-
Retrieve sales channel configuration by identifer
SALESC:/sales-channel-configurations/SALESC
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| salesChannelId* | path |
string
|
The sales channel identifier Example : CASIFR |
Response codes
200 - Successapplication/json |
||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this route to search discussion subtypologies.
Example
Retrieve typologies for typology order and sales channel MARJMA:
/typologies?salesChannel=MARJMa&typologyCode=order&orderStatus=Shipped
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| salesChannel* | query |
string
|
The sales channel for which to retrieve the valid typologies from |
| orderStatus* | query |
string|enum|null
|
The order status for which the typology is allowed. You can specify multiple statuses by separating them with commas.
Example Default : Delivered Example : Delivered Available values : ["Accepted", "InPreparation", "Shipped", "Delivered", "Cancelled", "Undefined"] |
| typologyCode* | query |
string|enum
|
The type of typology to retrieve Available values : ["order"] |
| userType | query |
string|enum
|
The type of user that is allowed to open a discussion with this subtypology. You can specify multiple user types by separating them with commas.
Example Available values : ["Customer", "Seller"] |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this route to get the count of discussions according filter parameters.
Example:
-
Count discussions:
/discussions/count
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| salesChannel | query |
string
|
The sales channel Id Example : CASIFR |
| graduationCode | query |
string|enum
|
The discussion graduation code Available values : ["Discussion", "Level_1", "Claim"] |
| processStatus | query |
string|enum
|
The discussion process status Available values : ["ToTreat", "Treated"] |
Response codes
200 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this API to search discussions by filter parameters.
Functional rules:
-
By default the result list is sorted by descending order on the date of the last update.
-
The maximum period of research discussions may not exceed 6 months
-
For discussionId you can use one value or multiple values separated by comma.
-
Sorting is available with attributes:
-
desc:updatedAt -
asc:updatedAt
-
-
Default:
desc:updatedAt
Examples:
-
Retrieve the second page of 20 items among all open discussions:
/discussions?isOpen=true&pageIndex=2&pageSize=20 -
Retrieve the first Page of 50 items of discussion updated in January:
/discussions?isOpen=true&pageIndex=1&pageSize=100&updatedAtMin=2021-01-01&updatedAtMax=2021-01-31 -
Retrieve the discussion by id
60afb211f41c9700016d92ae:/discussions?isOpen=true&discussionId=60afb211f41c9700016d92ae -
Retrieve discussions about an order with the status "in progress":
/discussions?isOpen=true&processStatus=inProgress&typologyCode=Order
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| discussionId | query |
string
|
The discussion Id. You can use one value or multiple values separate by comma. Example : 60afb211f41c9700016d92ae |
| orderSellerId | query |
string
|
The order reference of the seller Example : 507f1f77bcf8 |
| salesChannel | query |
string
|
The sales channel. You can use one value or multiple values separate by comma. Example : CASIFR |
| isOpen | query |
boolean
|
Filter on the opening state of the discussion Example : 1 |
| processStatus | query |
string|enum
|
Filter on the status of the discussion Available values : ["ToTreat", "Treated"] |
| typologyCode | query |
string
|
Filter on the typology of the discussion. Example : Order |
| subTypologyCode | query |
string
|
Filter on the sub typology of the discussion.
To retrieve available values you can use |
| updatedAtMin | query |
string
|
Format - date (as full-date in RFC3339). Format - date (as full-date in RFC3339). Filter discussions last updated after date. (format: 2020-10-05T12:03:45.000Z) Expected date at ISO 8601 format (UTC as default time-zone). Example : 2020-10-05 |
| updatedAtMax | query |
string
|
Format - date (as full-date in RFC3339). Format - date (as full-date in RFC3339). Filter discussions last updated before date. (format: 2020-10-05T12:03:45.000Z) Expected date at ISO 8601 format (UTC as default time-zone). Example : 2020-10-10 |
| pageSize | query |
integer
|
Maximum number of returned items in a page Maximum value: 50 Minimum value: 1 Default : 50 |
| pageIndex | query |
integer
|
Page number to return. Minimum value: 1 Default : 1 |
| sort | query |
string|enum
|
Sort the result set based on this parameter. If not provided, the result set will be sorted in descending order of the updatedAt date. Default : desc:updatedAt Available values : ["desc:updatedAt", "asc:updatedAt"] |
| includeMessages | query |
string|enum
|
Request that the first or last message of each discussion is included in the response. If not set, no message will be included Available values : ["FirstMessage", "LastMessage"] |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this API to create a new discussion.
The discussion can be created if only the sales channel activates the functionality for the seller to initiate a discussion.
It is preferable to use the exact sub-typology spelling that matches the spelling in the GET /typologies endpoint.
This will help you retrieve your discussion when filtering with sub-typology.
Functional rules:
-
The discussion should be created with the sub-typology for the seller.
-
The discussion is limited to one per sub-typology per order or product from order.
-
Multiple discussions with different sub-typologies can be created.
-
The maximum attachments per message cannot exceed 3 attachments.
-
The maximum attachments size per message cannot exceed 4 MB.
-
The character length of the subject should be a minimum of 5 chars and a maximum of 50 chars.
-
The character length of the message body should be a minimum of 13 chars and a maximum of 5000 chars.
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Request body
|
Create discussion application/json |
Response codes
201 - Createdapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
409 - Conflictapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this route to get full discussion:
-
Discussion
-
Messages
-
Attachments (metadata only)
with discussion Id
Example:
-
Get full discussion by id
21554654retregf6548:/discussions/21554654retregf6548
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| discussionId* | path |
string
|
The discussion ID Example : 21554654retregf6548 |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This route allows you to replace properties in the discussion object.
Functional Rule:
Currently you can change only the isOpen property.
Example:
-
Update isOpen property for a specific discussion:
/discussions/21554654retregf6548
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| discussionId* | path |
string
|
The discussion ID Example : 21554654retregf6548 |
Request body
|
Patch body application/json |
Response codes
204 - Success |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this route to add a new message in an existing discussion.
Functional rules:
-
The maximum attachments per message cannot exceed 3 attachments.
-
The maximum attachments size per message cannot exceed 4 MB.
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Request body
|
application/json |
Response codes
201 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
409 - Conflictapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
This route allows you to replace properties in the message object.
Functional Rule:
Currently you can change only the hasRead property.
Examples:
Update hadRead status for a specific message:
/messages/21554654retregf6548
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| messageId* | path |
string
|
The identifier of the message you want to modify Example : 21554654retregf6548 |
Request body
|
cancel order application/json |
Response codes
204 - Success |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this route to retrieve attachments either by discussionId, messageId or by attachmentId.
Functional Rule:
At least one of the three parameters is mandatory
Examples:
-
Retrive attachments linked to the discussion
547654:/attachments?discussionId=547654 -
Retrive attachments linked to the message
4589614:/attachments?messageId=4589614 -
Retrive attachment with attachment Id
986536:/attachments?attachmentId=986536
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| salesChannelId* | query |
string
|
The ID of sales channel Example : CASIFR |
| discussionId | query |
string
|
The ID of the discussion Example : 507f1f77bcf86cd799439011 |
| messageId | query |
string
|
The ID of the message Example : 807f1f77bcf86cd799439044 |
| attachmentId | query |
string
|
The ID of the attachment Example : 60ab64fa37efec0001dd39b6 |
Response codes
200 - Successapplication/json |
||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Fulfillment List of endpoints to manage Octopia Fulfillment 19 endpoints
Use this endpoint to create a new fulfillment product.
Functional Rules:
-
Product Identification:
-
The product creation is a mandatory step to successfully proceed with all other fulfillment flows.
-
If the product does not exist, the supply order request (InboundShipment) will be refused.
-
The sellerProductReference must be the same as in your sales channels to ensure successful stock synchronization later.
-
The sellerProductReference must be unique.
-
Each GTIN (Global Trade Item Number) / productCondition pair has a corresponding sellerProductReference.
Example:
gtin&productCondition-->sellerProductReference-
9448415636567&New-->MyRef01 -
9448415636567&LikeNew-->MyRef02
-
Please note:
-
The measurements provided should correspond to the packaged product.
-
Some storage locations accept only new products.
-
-
Retrieving and Checking Product Information:
-
To retrieve and check your sellerProductReference and productCondition, use the endpoint:
/stock-seller-references?sellerProductReference=MyRef01&limit=100. -
To retrieve and check the rest of the product information, use the endpoint:
/products?Gtin=9448415636567
You will find more details about retrieving product information in the endpoints documentation.
Please note:
-
If the product already exists, your call will not update the existing product information.
-
This means that if you send, for example, a new label, but the product already exists, you might retrieve a different label when checking the product information.
-
Empty fields will be added, but existing information will not be modified.
-
Request body
|
Command used to create a new fulfillment product. application/json |
Response codes
201 - Resource created |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows to retrieve the amount of inbound-shipments for a specified seller according to several filters.
Examples:
-
Retrieves list of inbound-shipments for a specified seller
/inbound-shipments/count -
Retrieves list of inbound-shipments for a specified seller by seller the reference: REFERENCE_001
/inbound-shipments/count?reference=REFERENCE_001 -
Retrieves list of inbound-shipments for a specified seller by supplyMode: Fulfillment
/inbound-shipments/count?supplyMode=Fulfillment -
Retrieves list of inbound-shipments for a specified seller by code: Appro_01
/inbound-shipments/count?code=Appro_01 -
Retrieves list of inbound-shipments for a specified seller by the country: FR
/inbound-shipments/count?country=FR -
Retrieves list of inbound-shipments for a specified seller using date range
/inbound-shipments/count?createdAtMin=2020-04-20T10:10:00&createdAtMax=2020-04-20T10:11:00 -
Retrieves list of inbound-shipments for a specified status
/inbound-shipments/count?status=Created
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| reference | query |
string
|
the seller reference of the inbound. Example : REF01 |
| code | query |
string
|
the auto generate code of an inbound. Example : 100_1663661129600 |
| supplyMode | query |
string|enum
|
Supply mode. Example : Fulfillment Available values : ["Seller", "Fulfillment", "Xdock"] |
| country | query |
string|enum
|
Inbound destnation country. Example : FR Available values : ["FR", "ES", "MA", "PT", "GB"] |
| createdAtMin | query |
string
|
Format - date-time (as date-time in RFC3339). Filter on the minimum creation date. Return items only if "createAtMin" property is bigger or equal to parameter value. Expected date at ISO 8601 format (UTC as default time-zone). Example : 2022-09-23T04:43:24.0000000+00:00 |
| createdAtMax | query |
string
|
Format - date-time (as date-time in RFC3339). Filter on the maximum creation date. Return items only if "createAtMax" property is smaller or equal to parameter value. Expected date at ISO 8601 format (UTC as default time-zone). Example : 2022-09-24T04:43:24.0000000+00:00 |
| status | query |
array[string]
|
order inbound status. Example : List: ["Created", "Referencing"] |
Response codes
200 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows to retrieve an inbound-shipment list for a specified seller, according to several filters.
This API delivers inbound-shipments using a cursor pagination. A cursor parameter is used to navigate to the previous or the next page.
This parameter is encoded and acts as a pointer to the first or the last item in the page. When the parameter is not provided, the first inbound is returned until the expected limit.
Examples:
-
Retrieves list of inbound-shipments for a specified seller
/inbound-shipments -
Retrieve inbound-shipments with a cursor linked to the next page.
/inbound-shipments?cursor=bmV4dF9fMTIzX0FCMzMzXzNfNQ -
Retrieve products with a limit of 1000 outbound-shipments. The next page is provided using a link header.
/outbound-shipments?limit=1000 -
Retrieves list of inbound-shipments for a specified seller by seller the reference: REF_001
/inbound-shipments?reference=REFERENCE_001 -
Retrieves list of inbound-shipments for a specified seller by supplyMode: Fulfillment
/inbound-shipments?supplyMode=Fulfillment -
Retrieves list of inbound-shipments for a specified seller by code: Appro_01
/inbound-shipments?code=Appro_01 -
Retrieves list of inbound-shipments for a specified seller by the country: FR
/inbound-shipments?country=FR -
Retrieves list of inbound-shipments for a specified seller using date range
/inbound-shipments?createdAtMin=2020-04-20T10:10:00&createdAtMax=2020-04-20T10:11:00 -
Retrieves list of inbound-shipments for a specified seller ordered
/inbound-shipments?orderBy=Asc -
Retrieves list of inbound-shipments for a specified status
/inbound-shipments?status=Created
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| createdAtMin | query |
string
|
Format - date-time (as date-time in RFC3339). Filter on the minimum creation date. Return items only if "createAtMin" property is bigger or equal to parameter value. Expected date at ISO 8601 format (UTC as default time-zone). Example : 2022-09-23T04:43:24.0000000+00:00 |
| createdAtMax | query |
string
|
Format - date-time (as date-time in RFC3339). Filter on the maximum creation date. Return items only if "createAtMax" property is smaller or equal to parameter value. Expected date at ISO 8601 format (UTC as default time-zone). Example : 2022-09-24T04:43:24.0000000+00:00 |
| cursor | query |
string|null
|
Pagination cursor. Example : bmV4dF9fMTIzX0FCMzMzXzNfNQ== |
| limit | query |
integer
|
Format - int32. Maximum number of products retrieved per page. Example : 10 |
| reference | query |
string
|
the seller reference of the inbound. Example : REF01 |
| code | query |
string
|
the auto generate code of an inbound. Example : 100_1663661129600 |
| supplyMode | query |
string|enum
|
Supply mode. Example : Fulfillment Available values : ["Seller", "Fulfillment", "Xdock"] |
| country | query |
string|enum
|
Inbound destnation country. Example : FR Available values : ["FR", "ES", "MA", "PT", "GB"] |
| orderBy | query |
string|enum
|
order inbound by created date. Example : Desc Available values : ["Desc", "Asc"] |
| status | query |
array[string|enum]
|
Order inbound status. Example : List: ["Created", "Referencing"] Available values : ["Created", "Referencing", "Referenced", "Processing", "Accepted", "Refused", "AppointmentScheduled", "InProgress", "PartiallyDone", "Done", "AutomaticallyDone"] |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Used this route to create a new inbound-shipment.
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Request body
|
Command used to create a new inbound-shipment. application/json |
Response codes
201 - Resource createdHeaders:
|
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
415 - Unsupported Media Typeapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Please note: Standard and Express delivery modes will be depreciated by 15 of june 2024, use THD and EHD delivery methods instead..
Allows to retrieve a single outbound-shipment by it's unique identifier for a specified seller.
Example:
Retrieves the outbound-shipment with this unique identifier: cd795c4c-b9c6-403e-96f3-2ee049c80bf1
/outbound-shipments/cd795c4c-b9c6-403e-96f3-2ee049c80bf1
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| inboundShipmentId* | path |
string
|
Format - uuid. Inbound unique identifier Example : cd795c4c-b9c6-403e-96f3-2ee049c80bf1 |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows to retrieve a single delivery note by it's inbound shipment unique identifier for a specified seller.
Example:
Retrieves the inbound-shipment with this unique identifier: cd795c4c-b9c6-403e-96f3-2ee049c80bf1.
/inbound-shipments/cd795c4c-b9c6-403e-96f3-2ee049c80bf1/delivery-notes
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| inboundShipmentId* | path |
string
|
Format - uuid. Inbound unique identifier Example : cd795c4c-b9c6-403e-96f3-2ee049c80bf1 |
Response codes
200 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
A route used to get list stocks fulfillment by sellerId & limit as
required and any of those parameter sellerProductReference,
productId, productCondition, productState, storageCountry,
cursor.
Using a cursor pagination. A cursor parameter is used to navigate to the previous
or the next page. This parameter is encoded and acts as a pointer to the first
or the last item in the page. When the parameter is not provided, the first
products are returned until the expected limit.
Functional Rules:
The parameter deliveryCountry cannot be combined with updatedAtMin, updatedAtMax, storageCountry, sort or order parameters.
Exemples:
-
Retrieves list of stock fulfillment for a specified seller
/stocks?limit=100 -
Retrieve seller stock fulfillment with a cursor linked to the next or previous page.
/stocks?limit=100&cursor=bmV4dF9fMTIzX0FCMzMzXzNfNQ -
Retrieve seller stock fulfillment with a a sort On available quantity and order type.
/stocks?limit=100&order=Desc&Sort=Available -
Retrieve seller stock fulfillment with a cursor linked to next or previous page with a sort type and an order.
/stocks?limit=100&order=Asc&Sort=Available&cursor=bmV4dF9fMTIzX0FCMzMzXzNfNQ -
Retrieves list of stocks fulfillment for a specified seller and sellerProductReference.
/stocks?sellerProductReference=SELLERX1204&limit=100 -
Retrieves list of stocks seller fulfillment for a specified seller and productId.
/stocks?productId=product01&limit=100 -
Retrieves list of stocks fulfillment for a specified seller and productCondition.
/stocks?productCondition=New&limit=100 -
Retrieves list of stocks fulfillment for a specified seller and productState.
/stocks?productState=New&limit=100 -
Retrieves list of stocks fulfillment for a specified seller and storageCountry.
/stocks?storageCountry=ES&limit=100 -
Retrieves list of stocks fulfillment for a specified seller and deliveryCountry.
/stocks?deliveryCountry=FR&limit=100 -
Retrieves list of stocks fulfillment for a specified seller that were updated on the 26th of october 2024.
/stocks?updatedAtMin=2024-10-26T00:00:00&updatedAtMax=2024-10-26T23:59:59&limit=100 -
Retrieves list of stocks fulfillment for a specified seller with a sellerproductReference value that's not empty or null.
/stocks?hasSellerProductReference=true&limit=100
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| limit | query |
integer
|
number of items in response Example : 10 |
| sellerProductReference | query |
string
|
seller Product Reference Example : product01X98979 |
| productId | query |
string
|
Product Id Example : product01 |
| productCondition | query |
string|enum
|
Product Condition Example : New Available values : ["New", "LikeNew", "VeryGoodState", "AverageState", "RefurbishedLikeNew", "RefurbishedVeryGoodState", "RefurbishedCorrectState"] |
| productState | query |
string|enum
|
Product state Example : New Available values : ["New", "Used", "Refurbished"] |
| hasSellerProductReference | query |
boolean
|
SellerProductReference is filled Example : 1 |
| storageCountry | query |
string
|
Country of stock's storage - ISO 3166-1 alpha-2. This parameter cannot be combined with the Example : FR |
| deliveryCountry | query |
string
|
Filters the stock that can be delivered to the specified country - ISO 3166-1 alpha-2. This parameter cannot be combined with Example : FR |
| updatedAtMin | query |
string
|
Date of stock's minumum update (UTC). This parameter cannot be combined with the Example : 2020-04-20 10:10:00 |
| updatedAtMax | query |
string
|
Date of stock's maximum update (UTC). This parameter cannot be combined with the Example : 2020-04-21 10:10:00 |
| cursor | query |
string|null
|
Pagination cursor. Example : QXNjXzE2OTA0NjI3NzYyNzI= |
| sort | query |
string|enum
|
Field to order by the stock's sort field. This parameter cannot be combined with the Example : Available Available values : ["Available", "Blocked", "Allocated", "Removal", "Litigation", "Return", "LogisticOperations"] |
| order | query |
string|enum
|
Field to order by the stock's sort field. This parameter cannot be combined with the Example : Desc Available values : ["Desc", "Asc"] |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
A route used to get stock fulfillment by unique identifier for a specified seller.
Exemple:
Retrieves list of stock fulfillment by id
/stocks/792b3249-8b65-404b-b8ec-1f7f205ae423
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| stockId* | path |
string
|
Stock unique identifier. |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
415 - Unsupported Media Typeapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
A route used to get stock seller reference fulfillment by sellerId & limit as required and any of those parameters sellerProductReference, productId, productCondition, cursor. Results are ordered by creation date descendant by default.
Exemples:
-
Retrieves list of stock seller reference fulfillment for a specified seller.
/stock-seller-references?limit=100 -
Retrieve seller reference fulfillment with a cursor linked to the next page.
/stock-seller-references?limit=100&cursor=91425db0-d61a-410a-9e69-cfa02a103216 -
Retrieves list of stock seller reference fulfillment for a specified seller and sellerProductReference.
/stock-seller-references?sellerProductReference=SELLERX1204&limit=100 -
Retrieves list of stock seller reference fulfillment for a specified seller and productId.
/stock-seller-references?productId=product01&limit=100 -
Retrieves list of stock seller reference fulfillment for a specified seller and productCondition.
/stock-seller-references?productCondition=New&limit=100 -
Retrieves list of stock seller reference fulfillment for a specified seller and order the response by creation date ascendant.
/stock-seller-references?limit=100&orderBy=Asc
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| limit | query |
integer
|
limit items by request Example : 10 |
| sellerProductReference | query |
string|null
|
seller Product Reference Example : product01X98979 |
| productId | query |
string|null
|
product Id Example : product01 |
| productCondition | query |
string|enum
|
product Condition Example : New Available values : ["New", "LikeNew", "VeryGoodState", "AverageState", "RefurbishedLikeNew", "RefurbishedVeryGoodState", "RefurbishedCorrectState"] |
| orderBy | query |
string|enum
|
Field to order by the outbound-shipment created date. Example : Desc Available values : ["Desc", "Asc"] |
| cursor | query |
string|null
|
Pagination cursor. Example : 91425db0-d61a-410a-9e69-cfa02a103216 |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Request to cancel an outbound-shipment by its unique identifier.
Functional Rules:
-
When the outbound-shipment status is
createdorpending, the outbound-shipment isrejected. -
When the outbound-shipment status is
acceptedorinPreparation, a cancellation request is sent. This request will beacceptedorrejectedby the logistic partner.
If request is accepted, the outbound-shipment status is Cancelled.
-
When the status outbound-shipment is
partiallyShipped,shipped,delivered,cancelorrejectedthe cancellation request is forbidden. -
Reason must be filled with following values:
Customer details errorPrice errorCancellation at customer's requestSuspected fraudOther
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Request body
|
Command used to create an outbound-shipment cancellation request. application/json |
Response codes
201 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
409 - Conflictapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows to retrieve a single outbound-shipment by its unique identifier for a specified seller.
Example:
-
Retrieves the outbound-shipment with this unique identifier: cd795c4c-b9c6-403e-96f3-2ee049c80bf1.
/outbound-shipments/cd795c4c-b9c6-403e-96f3-2ee049c80bf1
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| outboundShipmentId* | path |
string
|
Outbound-shipment identifier. Example : ea5f27b3-92e8-4c2a-9212-af892989b985 |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows to retrieve an outbound-shipment list for a specified seller, according to several filters.
Functional Rules:
-
This API delivers outbound-shipments using a cursor pagination.
A cursor parameter is used to navigate to the previous or the next page.
This parameter is encoded and acts as a pointer to the first or the last item in the page. When the parameter is not provided, the first products are returned until the expected limit.
Examples:
-
Retrieves list of outbound-shipments for a specified seller
/outbound-shipments -
Retrieve products with a cursor linked to the next page.
/outbound-shipments?cursor=QXNjXzE2OTA0NjI3NzYyNzI= -
Retrieve products with a limit of 1000 outbound-shipments. The next page is provided using a link header.
/outbound-shipments?limit=1000 -
Retrieves list of outbound-shipments for a specified seller by seller the reference: REFERENCE_001
/outbound-shipments?reference=REFERENCE_001 -
Retrieves list of outbound-shipments for a specified seller by status: Accepted
/outbound-shipments?status=Accepted -
Retrieves list of outbound-shipments for specified cancellation request status: Accepted
/outbound-shipments?cancellationRequestStatus=Accepted -
Retrieves list of outbound-shipments for a specified seller by state: Valid
/outbound-shipments?state=Valid -
Retrieves list of outbound-shipments for a specified seller using date range
/outbound-shipments?createdAtMin=2020-04-20T10:10:00.000Z&createdAtMax=2020-04-20T10:11:00.000Z/outbound-shipments?statusUpdatedAtMin=2020-04-20T10:10:00.000Z&statusUpdatedAtMax=2020-04-20T10:11:00.000Z -
Retrieves list of outbound-shipments for a specified seller ordered
/outbound-shipments?orderBy=Asc
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| reference | query |
string
|
Seller reference for the ressource. Example : 0223258 |
| storageCountry | query |
string|null
|
Storage country to filter the shipments. Example : FR |
| deliveryCountryCode | query |
array[string]|null
|
List of delivery country codes Example : List: ["FR", "ES"] |
| status | query |
string|enum|null
|
The status of the ressource. Example : InPreparation Available values : ["Processing", "WaitingAcceptance", "Accepted", "Refused", "InPreparation", "Shipped", "Delivered", "Cancelled", "Rejected"] |
| cancellationRequestStatus | query |
string|enum
|
The current status of cancellation request. Example : Accepted Available values : ["Created", "InProgress", "Accepted", "Rejected"] |
| deliveryModes | query |
string|enum
|
deliveryModes. Example : THD Available values : ["THD", "EHD", "SHD", "PPMR", "WSHD", "SRHD", "FDHD", "SB2B"] |
| state | query |
string|enum
|
The current state of the outbound-shipmentOutbound-shipment state. Example : Valid Available values : ["Valid", "Invalid"] |
| limit | query |
integer
|
Maximum number of products retrieved per page. Example : 10 |
| cursor | query |
string
|
Pagination cursor. Use together with Example : eyJDdXJzb3JUeXBlIjoyLE9mZmVyVGVjaG5pY2FsSWQiOiIxMjM0NTZfQUFBQkI2MTEyM182X0NESVNGUiJ9 |
| createdAtMin | query |
string
|
The created at minimum date of the ressource. Example : 2023-12-25T14:30:00Z |
| createdAtMax | query |
string
|
The created at maximum date of the ressource. Example : 2023-12-25T15:30:00Z |
| statusUpdatedAtMin | query |
string
|
Minimum date of status update of the outbound-shipment. Example : 2020-04-20 10:10:00 |
| statusUpdatedAtMax | query |
string
|
Maximum date of status update of the outbound-shipment. Example : 2020-04-20 10:11:00 |
| salesChannelName | query |
string
|
Sales channel name to help users identify which store the outbound shipment is coming from. Example : MYWEBISTE |
| orderBy | query |
string|enum
|
Field to order by the outbound-shipment created date. Example : Desc Available values : ["Desc", "Asc"] |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows to create a new outbound-shipment for a specified seller.
Functional Rules:
-
When the outbound-shipment is created, a
productIdand aproductConditionor asellerProductReferenceis required to retrieve the current product in the system.If both are specified only the
sellerProductReferenceis used. -
When the outbound-shipment
deliveryModeisPPMR, thepickupIdis mandatory. -
When in the
deliveryAddressof the outbound-shipment thecountryCodeisCH, theunitSalesPrice,shippingCostandcurrencyCodeare mandatory.
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Request body
|
Command used to create a new outbound-shipment. application/json |
Response codes
201 - SuccessHeaders:
|
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
409 - Conflictapplication/problem+json |
||||||||||||||||
415 - Unsupported Media Typeapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows to retrieve a single outbound-shipment cancellation request by its unique identifier for a specified seller.
Example:
Retrieves the outbound-shipment with this unique identifier: cd795c4c-b9c6-403e-96f3-2ee049c80bf1.
/outbound-shipments/cd795c4c-b9c6-403e-96f3-2ee049c80bf1
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| outboundCancellationRequestId* | path |
string
|
Outbound-shipment cancellation request identifier. Example : cd795c4c-b9c6-403e-96f3-2ee049c80bf1 |
Response codes
200 - Successapplication/json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this route to retrieve the total count of returns for a specified seller matching the provided filters. This endpoint supports the same filter parameters as the list endpoint but returns only the count instead of the full return data.
Examples:
-
Retrieve the return with the
outboundShipmentId(expedition order unique identifier)dac98618-83a9-4c34-9b45-d3f8ba9f92e9/returns/count?outboundShipmentId=dac98618-83a9-4c34-9b45-d3f8ba9f92e9 -
Retrieve the return with the reference (used on the delivery order by the seller)
Uk_Q4PXaP060lfRPPrSS2A/returns/count?reference=Uk_Q4PXaP060lfRPPrSS2A -
Retrieve a returns paginated list of 10 items and with a cursor linked to the next page.
/returns?limit=10&cursor=QXNjXzE2OTIxOTk0NTc4ODE= -
Retrieve a returns list created between the
2022-12-04 at 09:00and2022-12-24 at 18:00./returns/count?createdAtMin=2022-12-04T09:00:00.000Z&createdAtMax=2022-12-24T18:00:00.000Z -
Retrieve a returns list updated between the
2022-12-04 at 09:00and2022-12-24 at 18:00./returns/count?updatedAtMin=2022-12-04T09:00:00.000Z&updatedAtMax=2022-12-24T18:00:00.000Z -
Retrieve returns with the
Createdstatus./returns/count?status=Created -
Retrieve returns with the
CarrierandCustomertypes./returns/count?types=Carrier&types=Customer -
Retrieve returns with the
ReferenceErrorandDamagedreasons./returns/count?reasons=ReferenceError&reasons=Damaged -
Retrieve returns with the
CustomerRefusalandTransportDamagecarrierReasons./returns/count?carrierReasons=CustomerRefusal&carrierReasons=TransportDamage
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| createdAtMin | query |
string
|
The created at minimum date of the ressource. Example : 2023-12-25T14:30:00Z |
| createdAtMax | query |
string
|
The created at maximum date of the ressource. Example : 2023-12-25T15:30:00Z |
| updatedAtMin | query |
string
|
The updated at minimum date of orders. Example : 2023-12-25T14:30:00Z |
| updatedAtMax | query |
string
|
The updated at maximum date of orders. Example : 2023-12-25T15:30:00Z |
| reference | query |
string
|
Reference which is used on the delivery order by the seller. Example : Uk_Q4PXaP060lfRPPrSS2A |
| outboundShipmentId | query |
string
|
The expedition order unique identifier. Example : ad36144a-902c-4953-8d5d-98f423cace36 |
| orderSellerId | query |
string
|
Order seller identifier. Example : CASIFR23110913520O9RW9 |
| status | query |
array[string|enum]
|
Filter by return status. Multiple values can be provided to match returns with any of the specified statuses. Example : List: ["Created"] Available values : ["Created", "Accepted", "Pending", "Completed"] |
| types | query |
array[string|enum]
|
Filter by return type. Multiple values can be provided to match returns with any of the specified types (Carrier or Customer). Example : List: ["Customer"] Available values : ["Carrier", "Customer"] |
| reasons | query |
array[string|enum]
|
Filter by customer return reason. Multiple values can be provided to match returns with any of the specified reasons. Example : List: ["ReferenceError"] Available values : ["ReferenceError", "Damaged", "Retraction", "MultipleDelivery", "MissingItem", "UnpackingDefect", "Undeliverable", "CustomerRefusal", "TransportDamage", "NotRetrieved"] |
| carrierReasons | query |
array[string|enum]
|
Filter by carrier return reason. Multiple values can be provided to match returns with any of the specified carrier reasons. Example : List: ["TransportDamage"] Available values : ["Undeliverable", "CustomerRefusal", "TransportDamage", "NotRetrieved"] |
| parcelId | query |
string
|
Identifier of the returned parcel. Example : 0204261429HZEMY |
Response codes
200 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this route to create a new return for the specified seller.
Functional Rules:
-
This return is associated with a parcel shipment that needs to be returned to the warehouse.
-
The seller must have the appropriate rights to perform this action.
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Request body
|
Request body containing the return creation data including outbound shipment identifier, reference, reason, comment, and return lines. application/json |
Response codes
201 - Return successfully createdHeaders:
|
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
409 - Conflictapplication/problem+json |
||||||||||||||||
415 - Unsupported Media Typeapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this route to retrieve a paginated list of returns with optional filters such as outboundShipmentId, reference, date ranges, status, type, and reasons.
Functional Rules:
-
If
limitparameter is omitted, default value 20 is used. -
If
limitparameter value is less than 1 or greater than 100, then a400 - Bad Requestis returned.
Examples:
-
Retrieve the return with the
outboundShipmentId(expedition order unique identifier)dac98618-83a9-4c34-9b45-d3f8ba9f92e9/returns?outboundShipmentId=dac98618-83a9-4c34-9b45-d3f8ba9f92e9 -
Retrieve the return with the reference (used on the delivery order by the seller)
Uk_Q4PXaP060lfRPPrSS2A/returns?reference=Uk_Q4PXaP060lfRPPrSS2A -
Retrieve a returns paginated list of 10 items and with a cursor linked to the next page.
/returns?limit=10&cursor=QXNjXzE2OTIxOTk0NTc4ODE= -
Retrieve a returns list created between the
2022-12-04 at 09:00and2022-12-24 at 18:00./returns?createdAtMin=2022-12-04T09:00:00.000Z&createdAtMax=2022-12-24T18:00:00.000Z -
Retrieve a returns list updated between the
2022-12-04 at 09:00and2022-12-24 at 18:00./returns?updatedAtMin=2022-12-04T09:00:00.000Z&updatedAtMax=2022-12-24T18:00:00.000Z -
Retrieve returns with the
Createdstatus./returns?status=Created -
Retrieve returns with the
CarrierandCustomertypes./returns?types=Carrier&types=Customer -
Retrieve returns with the
ReferenceErrorandDamagedreasons./returns?reasons=ReferenceError&reasons=Damaged -
Retrieve returns with the
CustomerRefusalandTransportDamagecarrierReasons./returns?carrierReasons=CustomerRefusal&carrierReasons=TransportDamage
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| limit | query |
integer|enum
|
Maximum number of items requested for the page (pagination). Example : 10 Available values : ["1", "10", "20", "50", "100"] |
| cursor | query |
string|null
|
Pagination cursor used to retrieve the next page of results. This value is provided in the response Link header. Example : QXNjXzE2OTg3OTMyMDA= |
| createdAtMin | query |
string
|
The created at minimum date of the ressource. Example : 2023-12-25T14:30:00Z |
| createdAtMax | query |
string
|
The created at maximum date of the ressource. Example : 2023-12-25T15:30:00Z |
| orderBy | query |
string|enum
|
Sort order for returns by creation date.
Example : Asc Available values : ["Asc", "Desc"] |
| updatedAtMin | query |
string
|
The updated at minimum date of orders. Example : 2023-12-25T14:30:00Z |
| updatedAtMax | query |
string
|
The updated at maximum date of orders. Example : 2023-12-25T15:30:00Z |
| reference | query |
string
|
Reference which is used on the delivery order by the seller. Example : Uk_Q4PXaP060lfRPPrSS2A |
| outboundShipmentId | query |
string
|
The expedition order unique identifier. Example : ad36144a-902c-4953-8d5d-98f423cace36 |
| orderSellerId | query |
string
|
Order seller identifier. Example : CASIFR23110913520O9RW9 |
| status | query |
array[string|enum]
|
Filter by return status. Multiple values can be provided to match returns with any of the specified statuses. Example : List: ["Created"] Available values : ["Created", "Accepted", "Pending", "Completed"] |
| types | query |
array[string|enum]
|
Filter by return type. Multiple values can be provided to match returns with any of the specified types (Carrier or Customer). Example : List: ["Customer"] Available values : ["Carrier", "Customer"] |
| reasons | query |
array[string|enum]
|
Filter by customer return reason. Multiple values can be provided to match returns with any of the specified reasons. Example : List: ["ReferenceError"] Available values : ["ReferenceError", "Damaged", "Retraction", "MultipleDelivery", "MissingItem", "UnpackingDefect", "Undeliverable", "CustomerRefusal", "TransportDamage", "NotRetrieved"] |
| carrierReasons | query |
array[string|enum]
|
Filter by carrier return reason. Multiple values can be provided to match returns with any of the specified carrier reasons. Example : List: ["TransportDamage"] Available values : ["Undeliverable", "CustomerRefusal", "TransportDamage", "NotRetrieved"] |
| parcelId | query |
string
|
Identifier of the returned parcel. Example : 0204261429HZEMY |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Use this route to retrieve a specific return by its unique identifier.
Example:
-
Retrieve the return with the ID
abbf3123-f914-42d9-ab98-886e731672a5/returns/abbf3123-f914-42d9-ab98-886e731672a5
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| returnId* | path |
string
|
The unique identifier of the return (UUID format). Example : 70583ff4-bc95-495d-9694-37c73d35d33e |
Response codes
200 - Successapplication/json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Used this route to get the label of a return.
Example
-
Retrieve the label of the return with the id
abbf3123-f914-42d9-ab98-886e731672a5/returns/abbf3123-f914-42d9-ab98-886e731672a5/label
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| returnId* | path |
string
|
The identifier return. Example : 5f472fd6-489e-4aa3-92b5-9998419d6dc5 |
Response codes
200 - Successapplication/pdfimage/png |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Finance List of endpoints to retrieve financial information 8 endpoints
Allows you to retrieve the details of an invoice in order to reconcile the operations concerned (sales, refunds, shipments).
Functional Rules:
-
Default
PageSize: 20 -
Recommended call frequency:
-
One time after each 10 days (on 9, 19 and 29 of each month).
-
This is because the invoices are generated before the payout.
-
Example:
-
Retrive details of the invoice
1400178408:/invoices/1400178408/details?pageIndex=1&pageSize=25
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| invoiceId* | path |
integer
|
Invoice ID Example : 1801067043 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| pageIndex | query |
integer
|
The index of the page (Min: 1 / Max: 100) Default : 1 Example : 1 |
| pageSize | query |
number
|
The maximum number of elements in a page. (Min: 1 / Max: 100) Default : 20 Example : 10 |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows you to count the number of orders/operations in an invoice.
Functional Rules:
-
Recommended call frequency:
-
One time after each 10 days (on 9, 19 and 29 of each month).
-
This is because the invoices are generated before the payout.
-
Example:
-
Count the number of details for the invoice
1400178408:/invoices/1400178408/details/count
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| invoiceId* | path |
integer
|
Invoice ID Example : 1801067043 |
Response codes
200 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows you to download the PDF of a specific invoice.
Functional Rules:
-
Recommended call frequency:
-
One time after each 10 days (on 9, 19 and 29 of each month).
-
This is because the invoices are generated before the payout.
-
Example:
-
Download the document of the invoice
1400178408:/invoices/1400178408/documents
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| invoiceId* | path |
integer
|
Invoice ID Example : 1801067043 |
Response codes
200 - Successapplication/pdf |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows you to download up to 10 invoices at the same time in an archived file.
Functional Rules:
-
Recommended call frequency:
-
One time after each 10 days (on 9, 19 and 29 of each month).
-
This is because the invoices are generated before the payout.
-
Example:
-
Download a zip file containing documents of invoices
1400178408,1400178409,1400178410:/invoice-documents?invoiceIds=1400178408,1400178409,1400178410
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| invoiceIds* | query |
array[integer(int64)]
|
Invoice ID list Example : List: ["1900000000", "1900000001"] |
Response codes
200 - Successapplication/zip |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows you to:
-
Retrieve all financial informations related to a payment (order, commissions, invoices, guarantee reserve...).
-
Search for a financial operation (order/refund) and retrieves its details.
Functional Rules:
-
Default
PageSize: 20 -
At least one of these filters is required:
orderReference,invoiceId, or a full date range (paidAtMin+paidAtMaxorchangedAtMin+changedAtMax). -
Recommended call frequency:
On each payout in order to reconcile accouting items.
-
The following fields display the gross amount (VAT included): sales, refunds, commissions, and service financial flow.
Examples:
-
Retrieve all operations paid between two dates:
/operations?paidAtMin=2021-09-01&paidAtMax=2021-09-15 -
Retrieve all operations linked to a specific order:
/operations?orderReference=1601302358PGI56 -
Retrieve all operations linked to a specific invoice and a specific event type:
/operations?invoiceId=1400178408&eventType=Refund,Commission
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| pageIndex | query |
integer
|
The index of the page (Min: 1 / Max: 100) Default : 1 Example : 1 |
| pageSize | query |
number
|
The maximum number of elements in a page. (Min: 1 / Max: 100) Default : 20 Example : 10 |
| orderReference | query |
string
|
External reference of the order used by the sales channel to communicate with the customer. Example : 1601302358PGI56 |
| paidAtMin | query |
string
|
Minimum payment date - Expected date-time at ISO 8601 format (UTC as default time-zone) It also requests to complete the filter Example : 2024-05-27T00:00:00Z |
| paidAtMax | query |
string
|
Maximum payment date - Expected date-time at ISO 8601 format (UTC as default time-zone) It also requests to complete the filter Example : 2024-09-27T23:59:59Z |
| eventTypes | query |
array[string|enum]
|
Operation type Example : List: ["Refund"] Available values : ["Sale", "Commission", "Refund", "CommissionRestitution", "Subscription", "CdiscountServices", "LogisticFee", "SecurityDeposit", "FfmOrdersReturns", "FfmStorage", "FfmShippingCost", "SplittedPaymentFees", "TradeMarketingFees", "AgecLawFees"] |
| states | query |
array[string|enum]
|
Payment status of the financial operation Example : List: ["Paid"] Available values : ["NotPayable", "Estimated", "Paid", "Blocked", "InProcess"] |
| invoiceId | query |
integer
|
Invoice ID Example : 1801067043 |
| changedAtMin | query |
string
|
Minimum date of last change - Expected date-time at ISO 8601 format (UTC as default time-zone). It also requests to complete the filter Please combine this filter with another to secure the request performance. Example : 2024-05-27T00:00:00Z |
| changedAtMax | query |
string
|
Maximum date of last change - Expected date-time at ISO 8601 format (UTC as default time-zone). It also requests to complete the filter Please combine this filter with another to secure the request performance. Example : 2024-09-27T23:59:59Z |
| salesChannelId | query |
string
|
The Unique identifier of the sales channel the data comes from Example : CDISFR |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows you to:
-
Count the number of operations related to a payment (order, commissions, invoices, guarantee reserve...).
-
Count item details related to a financial operation (order/refund).
Functional Rules:
-
At least one of these filters is required:
orderReference,invoiceId, or a full date range (paidAtMin+paidAtMaxorchangedAtMin+changedAtMax). -
Recommended call frequency:
-
Daily in order to monitor business accounting.
-
On each payout in order to reconcile accouting items.
-
Example:
-
Count all operations paid between two dates
/operations/count?paidAtMin=2021-09-01&paidAtMax=2021-09-15 -
Count all operations linked to a specific order
/operations/count?orderReference=1601302358PGI56 -
Count all operations linked to a specific invoice and a specific event type
/operations/count?invoiceId=1400178408&eventType=Refund,Commission
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| orderReference | query |
string
|
External reference of the order used by the sales channel to communicate with the customer. Example : 1601302358PGI56 |
| paidAtMin | query |
string
|
Minimum payment date - Expected date-time at ISO 8601 format (UTC as default time-zone) It also requests to complete the filter Example : 2024-05-27T00:00:00Z |
| paidAtMax | query |
string
|
Maximum payment date - Expected date-time at ISO 8601 format (UTC as default time-zone) It also requests to complete the filter Example : 2024-09-27T23:59:59Z |
| eventTypes | query |
array[string|enum]
|
Operation type Example : List: ["Refund"] Available values : ["Sale", "Commission", "Refund", "CommissionRestitution", "Subscription", "CdiscountServices", "LogisticFee", "SecurityDeposit", "FfmOrdersReturns", "FfmStorage", "FfmShippingCost", "SplittedPaymentFees", "TradeMarketingFees", "AgecLawFees"] |
| states | query |
array[string|enum]
|
Payment status of the financial operation Example : List: ["Paid"] Available values : ["NotPayable", "Estimated", "Paid", "Blocked", "InProcess"] |
| invoiceId | query |
integer
|
Invoice ID Example : 1801067043 |
| changedAtMin | query |
string
|
Minimum date of last change - Expected date-time at ISO 8601 format (UTC as default time-zone). It also requests to complete the filter Please combine this filter with another to secure the request performance. Example : 2024-05-27T00:00:00Z |
| changedAtMax | query |
string
|
Maximum date of last change - Expected date-time at ISO 8601 format (UTC as default time-zone). It also requests to complete the filter Please combine this filter with another to secure the request performance. Example : 2024-09-27T23:59:59Z |
| salesChannelId | query |
string
|
The Unique identifier of the sales channel the data comes from Example : CDISFR |
Response codes
200 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows you to retrieve the payment overall for each payout.
Functional Rules:
-
All operations are group by date, sales channel and payment status.
-
Default
pageSize: 20 -
Recommended call frequency:
-
On each payout in order to reconcile payments with the amount received by the Seller on his bank account
-
On demand in order to check payment history.
-
Examples:
-
Retrieve all seller payments from the last received payment (
state=Paid) to all incommings payments (state=Estimated):/payments -
Retrieve all seller payments between two dates:
/payments?payedAtMin=2021-09-013&payedAtMax=2021-09-15 -
Retrieve all seller payments between two dates with a specific payment state:
/payments?payedAtMin=2021-09-013&payedAtMax=2021-09-15&paymentStates=Estimated,NotPayable
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| paidAtMin | query |
string
|
Minimum payment date - Expected date-time at ISO 8601 format (UTC as default time-zone) It also requests to complete the filter Example : 2024-05-27T00:00:00Z |
| paidAtMax | query |
string
|
Maximum payment date - Expected date-time at ISO 8601 format (UTC as default time-zone) It also requests to complete the filter Example : 2024-09-27T23:59:59Z |
| paymentStates | query |
array[string|enum]
|
The payment states Example : List: ["Paid"] Available values : ["NotPayable", "Estimated", "Paid", "Blocked", "InProcess"] |
| salesChannelId | query |
string
|
The Unique identifier of the sales channel the data comes from Example : CDISFR |
| pageIndex | query |
integer
|
The index of the page (Min: 1 / Max: 100) Default : 1 Example : 1 |
| pageSize | query |
number
|
The maximum number of elements in a page. (Min: 1 / Max: 100) Default : 20 Example : 10 |
Response codes
200 - Successapplication/json
|
||||||||||||||||||||||||||||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Allows you to count the number of payments according to date, sales channel and payment status.
Functional Rules:
-
Recommended call frequency:
-
On each payout in order to reconcile payments with the amount received by the Seller on his bank account
-
On demand in order to check payment history.
-
Examples:
-
Count all seller payments:
/payments/count -
Count all seller payments between two dates:
/payments/count?payedAtMin=2021-09-013&payedAtMax=2021-09-15 -
Count all seller payments between two dates with a specific payment state:
/payments/count?payedAtMin=2021-09-013&payedAtMax=2021-09-15&paymentStates=Estimated,NotPayable
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| paidAtMin | query |
string
|
Minimum payment date - Expected date-time at ISO 8601 format (UTC as default time-zone) It also requests to complete the filter Example : 2024-05-27T00:00:00Z |
| paidAtMax | query |
string
|
Maximum payment date - Expected date-time at ISO 8601 format (UTC as default time-zone) It also requests to complete the filter Example : 2024-09-27T23:59:59Z |
| paymentStates | query |
array[string|enum]
|
The payment states Example : List: ["Paid"] Available values : ["NotPayable", "Estimated", "Paid", "Blocked", "InProcess"] |
| salesChannelId | query |
string
|
The Unique identifier of the sales channel the data comes from Example : CDISFR |
Response codes
200 - Successapplication/json |
||||||||||||||||
400 - Bad Requestapplication/problem+json |
||||||||||||||||
401 - Unauthorizedapplication/problem+json |
||||||||||||||||
403 - Forbiddenapplication/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |
Transaction Reports List of endpoints to get the transaction reports (DAC7 law) 2 endpoints
Retrieve sales summaries reports (PDF) from Saleschannel, rely on DAC7 Law.
Functional rules:
-
This is a cursor paginated route, so when a call is done, it is required to check the response Header to search for a link 'next' to see if there's another page otherwise you can miss data.
-
You can retrieve up to 1000 items per page.
Example:
-
Retrieve french
reportsonsalesChannelIdCASIFR with avalidityYearuntil 2023 with 150 items per pages:/reports?countryCode=FR&salesChannelId=CASIFR&validityYear=2023&limit=150
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Query
| Name | In | Type | Description |
|---|---|---|---|
| countryCode | query |
string
|
The ISO 3166-1 alpha-2 country code concerned by DAC7 regulation. Refer to the ISO standard for valid values. Example : FR |
| reportId | query |
string
|
Intern Octopia reference of the register. Example : 2023-135-MKP-FR |
| salesChannelId | query |
string
|
Sales Channel reserved to the sellerId Example : CDISFR |
| validityYear | query |
integer
|
Year of the validity Example : 2023 |
| cursor | query |
string
|
Cursor value used for pagination. This is used when using the 'link' links provided in the response to navigate in pages. You should not create it manually. Example : NjQ4ODI3MzE5NTIwZmU3ZmM5ZmEyNTUwLUFTQw== |
| limit | query |
integer
|
Count of expected results that is used for pagination. Range is 1 to 20 (20 by default). Example : 10 |
Response codes
200 - Successful responseapplication/json
|
||||||||||||||||||||||||||||||||||||
400 - Bad requestapplication/problem+json |
||||||||||||||||||||||||||||||||||||
401 - Unauthorized.application/problem+json |
||||||||||||||||||||||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||||||||||||||||||||||
500 - Internal Server error.application/problem+json |
Download Octopia MKP's seller transaction reports file from the reportId.
Example:
-
Retrieve & download the report with
2023-135-MKP-FRreportId:/reports/2023-135-MKP-FR/report-documents
Parameters - Headers
| Name | In | Type | Description |
|---|---|---|---|
| SellerId* | header |
string
|
Octopia Seller Identifier. Example : 98979 |
Parameters - Path
| Name | In | Type | Description |
|---|---|---|---|
| reportId* | path |
string
|
Intern Octopia reference of the register. Example : 2024_135_CASIFR_FR |
Response codes
200 - File downloaded with successapplication/pdf
|
||||||||||||||||
400 - Bad requestapplication/problem+json |
||||||||||||||||
401 - Unauthorized.application/problem+json |
||||||||||||||||
404 - Not Foundapplication/problem+json |
||||||||||||||||
500 - Internal Server Errorapplication/problem+json |