Username
:Password
Basic authentication is a simple authentication scheme built into the HTTP protocol.
To use it, send your HTTP requests with an Authorization header that contains the word Basic
followed by a space and a base64-encoded string username:password
.
Example: Authorization: Basic ZGVtbzpwQDU1dzByZA==
The API allows creating purchase orders and retrieving order status for authorized consuming applications.
API documentation can be viewed as a web page at the root path /
.
(Also available in yaml
or json
formats depending on Accept
header).
Information about API releases (introduced features and bugfixes) can be viewed as a web page at the releases path /releases
or be downloaded as a Markdown file, with Accept: text/md
header.
Currently, 3 types of consuming applications are recognized:
Special roles: Additional roles are needed to query Product Prices and Product limits (Please note, these operations are currently available only for DE market). These roles are subject to approval. To request the access, please send an email to cl-api-support@merck.com
All API endpoints in this document are relative. In order to be properly used, they need to be prefixed with the base URL of the API.
For example:
should be translated into:
where HOSTNAME
is the hostname of the corresponding API environment.
Direct customers can use the /customers/@me
endpoint to retrieve basic information about themselves:
GET https://HOSTNAME/customer-link/v1/customers/@me200 OKContent-Type: application/hal+json; charset=utf-8{"_links": {"self": {"href": "https://iapi.merck.com/customer-link/v1/customers/@me"}},"id": "0000123456","name": "CLINICA ABCDE","_embedded": {"billingAddresses": [...],"shippingAddresses": [...]}}
Broker companies can use the /broker/@me
endpoint to retrieve basic information about themselves:
GET https://HOSTNAME/customer-link/v1/brokers/@me200 OKContent-Type: application/hal+json; charset=utf-8{"name": "Broker company","_embedded": {"customers": [{"id": "0000012345","_links": {"self": {"href": "https://iapi.merck.com/customer-link/v1/customers/0000012345"}}},{"id": "0000067890","_links": {"self": {"href": "https://iapi.merck.com/customer-link/v1/customers/0000067890"}}}]}}
The payload contains the list of customer companies, on behalf of which the broker company is authorized to place orders.
The broker company is also authorized to retrieve basic information about a specific customer from the list:
GET https://HOSTNAME/customer-link/v1/customers/0000012345200 OKContent-Type: application/hal+json; charset=utf-8{"_links": {"self": {"href": "https://iapi.merck.com/customer-link/v1/customers/0000012345"}},"id": "0000012345","name": "CLINICA ABCDE","_embedded": {"billingAddresses": [...],"shippingAddresses": [...]}}
This may be needed particularly when the customer company has more than one shipping or billing address registered. In order to use a non-default address in the order, you need to specify the address ID explicitly. All the billing and shipping address IDs are available within the customer company information.
Both direct customers and broker companies can create purchase orders. The direct customers can place orders for themselves only, while the broker companies can create orders on behalf of all customers, for which they are authorized to do so.
The workflow of creating a new order is as follows:
POST /orders
request with all the order data in the payload201
. The response will also contain a location
header with the link to the newly created order.GET /orders/<ID>
to retrieve details and status information about the newly created order.For example:
POST https://HOSTNAME/customer-link/v1/ordersContent-Type: application/json{"customerId": "0000123456","shippingAddressId": "0000123456","products": [{"productId": '1012345',"quantity": 2},{"ean": '8765432',"quantity": 7}]}201 CreatedLocation: https://HOSTNAME/customer-link/v1/orders/20123456
If the order is created successfully, the response code will be 201
without any payload. The link to the newly created resource will be available in the Location
HTTP header:
In order to retrieve the order status, the consuming application should follow the link:
GET https://HOSTNAME/customer-link/v1/orders/20123456{"_links": {"self": {"href": "https://iapi.merck.com/customer-link/v1/orders/20123456"}},"id": "20123456","deliveryDate": "2021-11-12","createTime": "2021-11-12T08:18:40.000Z","status": "open","shippingStatus": "Not Shipped","totalOrderPrice": 2574.88,"currencyCode": "EUR","customerId": "0000124297","billToAddress": {...},"shipToAddress": {...},"products": [{"productId": '1012345',"ean": '9876',"name": "PRODUCT #1 0.5MG 2X21TAB","quantity": 2,"confirmedQuantity": 2,"unitPrice": 1042.44,"totalPrice": 2084.88"batch": "U012961","contractNumber": "","shippingStatus": "Sent","shippingDate": "2021-12-01T22:31:40.000Z"},{"productId": '2012345',"ean": '8765432',"name": "PRODUCT #2 50MG DFL","quantity": 7,"confirmedQuantity": 7,"unitPrice": 70,"totalPrice": 490"batch": "U012960","contractNumber": "","shippingStatus": "Sent","shippingDate": "2021-12-01T22:31:40.000Z"}]}
Read Only Profile can use the /customers/{customerId}/orders?orderDate=YYYY-MM-DD
endpoint to retrieve same salesOrg customer orders history:
GET https://HOSTNAME/customer-link/v1//customers/50081044/orders?orderDate=2022-03-22200 OKContent-Type: application/hal+json; charset=utf-8{"totalCount": 1,"_links": {"self": {"href": "https://iapi.merck.com/customer-link/v1/customers/50081044/orders?orderDate=2022-03-22"}},"orders": [{"_links": {"self": {"href": "https://iapi.merck.com/customer-link/v1/orders/3027214065"}},"orderNumber": "3027214065","purchaseOrderNumber": "ZOR-22-03-2022 10:02","createTime": "2022-03-22T06:05:28.000Z","status": "Completed","shippingStatus": "Not Shipped","totalOrderPrice": 123.45,"products": [{"productId": "000000000001023929","name": "JANUVIA 25MG 2X14FTBL","quantity": 1},{"productId": "000000000001034386","name": "KEYTRUDA 100MG DFL","quantity": 1}]}]}
The following common errors may occur on various API endpoints:
Code | Title | Description | What to do |
---|---|---|---|
400 | Bad Request | Bad incoming request from the client | The server cannot or will not process the request due to something that is perceived to be a client error. This may happen when parameters or payloads are not in the correct formats. |
401 | Unauthorized | Unauthenticated client application | Check the error message for more details and verify that the client application credentials are correct. |
403 | Forbidden | The client application does not have permission to perform the action on the resource. For example, when trying to retrieve other customer's order. | Check if all request data are correct. |
404 | Not Found | Invalid resource URL or non-existent record. | Check the API documentation for the right URL and make sure that you use the right resource identifier. |
405 | Method Not Allowed | The HTTP method (GET, POST, ...) used for the request is not allowed for the given resource. | Check the API documentation for the right HTTP method to use. |
429 | Too Many Requests | The API has encountered too many requests in a short period of time and it cannot process your request right now. | Retry the request after a short period of time. |
500 | Internal Server Error | General error on the API side. | If it happens consistently, contact support. |
502 | Bad Gateway | Connection issues within the API infrastructure. | If it happens consistently, contact support. |
504 | Gateway Timeout | Connection issues within the API infrastructure. | If it happens consistently, contact support. |