Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Compatibility between items and vehicle accessories
Check cross domain compatibility
Before creating compatibility between items and products, you should check that the category item and product domains are compatible.
By consulting the next dump, you get the list of domains and categories in which you can or need to report compatibility by site..
Request:
curl -X GET http://api.mercadolibre.com/catalog/dumps/domains/$SITE_ID/compatibilitiesRequest example:
curl -X GET https://api.mercadolibre.com/catalog/dumps/domains/MLM/compatibilitiesResponse example:
[
{
"domain_id": "MLM-AUTOMOTIVE_SHOCK_ABSORBERS",
"main": false,
"compatibilities": [
{
"compatible_domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"type": "EXTENSION",
"required": false,
"restrictions": [],
"categories": [
{
"id": "MLM45878",
"required": true,
"note_status": "ENABLED",
"restrictions_status": "DISABLED",
"universal_status": "DISABLED"
}
]
}
]
},
…
}]
The new fields indicate:
- categories: categories that support loading compatibilities..
- required: categories in which it is mandatory to load compatibilities.
- type: type of compatibility. Only the EXTENSION type supports loading compatibilities.
- note_status and restrictions_status: indicate if the category allows reporting notes and positions.
- universal_status: indicates if the category allows the communication of universal compatibilities. ENABLED: allows the communication of universal compatibilities or DISABLED : does not allow the communication of universal compatibilities.
Get more information about Domains, products and attributes vehicle accessories references.
Count products from a domain
To check the number of existing products per domain (product family) that meet certain attributes and values, you can perform the following POST. This will allow you to validate, prior to associating the compatibilities, the number of products and avoid errors in the assignment of compatibilities.
This is important as only a maximum of 200 products can be assigned per request.
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_compatibilities/products_search/count_family_products
{
"domain_id": "$domainId",
"attributes": [{
"id": "$attributeId1",
"value_id": "$valueId1"
}, {
"id": "$attributeId2",
"value_name": "$valueName2"
}]
}Example:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_compatibilities/products_search/count_family_products
{
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"attributes": [{
"id": "BRAND",
"value_name": "Volkswagen"
},
{
"id": "CAR_AND_VAN_MODEL",
"value_name": "VENTO"
}
]
}Response:
{
"count":141
}Identify items requiring compatibilities
With the following resource through the incomplete_compatibilities tag you can identify items that require mandatory compatibilities reporting to avoid moderations.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_IDExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1417560910Response:
{
"id": "MLA743626587",
"site_id": "MLA",
"title": "Paragolpe Trasero Peugeot 307 Linea Nueva 5 Puertas",
"seller_id": 65711207,
"category_id": "MLA60954",
"official_store_id": null,
.
.
.
.
"tags": [
"good_quality_picture",
"brand_verified",
"loyalty_discount_eligible",
"good_quality_thumbnail",
"ahora-paid-by-buyer",
"incomplete_compatibilities",
"immediate_payment"
],
"warranty": "CON GARANTIA DEL FABRICANTE",
"catalog_product_id": null,
"domain_id": "MLA-VEHICLE_REAR_BUMPERS",
"parent_item_id": null,
"deal_ids": [
],
"automatic_relist": false,
"date_created": "2018-08-17T20:36:54.000Z",
"last_updated": "2023-12-15T17:18:35.000Z",
"health": 0.83,
"catalog_listing": false
}
Filter items that require matching
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/items/search?tags=incomplete_compatibilitiesExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/items/search?tags=incomplete_compatibilitiesResponse:
{
"seller_id": "1373279576",
"results": [
"MLA1417560910",
"MLA1373565211",
"MLA1371734513",
"MLA1396609243"
],
"paging": {
"limit": 50,
"offset": 0,
"total": 4
},
"query": null,
.
.
.
.
}
Identifique itens com sugestões de compatibilidade
With the following resource you will be able to know the list of all the items of the seller that have compatibilities suggestions, that is to say that they have the tag "pending_compatibilities".
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/items/search?tags=pending_compatibilitiesExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1695976736/items/search?tags=pending_compatibilitiesRequest:
{
"seller_id": "1373279576",
"results": [
"MLB4462690924"
],
"paging": {
"limit": 50,
"offset": 0,
"total": 4
},
"query": null,
.
.
.
.
}
With the following call and through the pending_compatibilities tag found in the response, you can identify for a specific item if it has compatibilities suggestions.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_IDExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB4462690924Response:
{
"id": "MLB4462690924",
"site_id": "MLB",
"title": "Pastilha Freio Dianteira Gm Blazer 4.3 V6 Mpfi 1996 À 2003 ",
"seller_id": 1695976736,
"category_id": "MLB439261",
"official_store_id": null,
.
.
.
.
.
"tags": [
"pending_compatibilities"
],
"catalog_product_id": "MLB31779615",
"domain_id": "MLB-VEHICLE_BRAKE_PADS",
"parent_item_id": null,
"deal_ids": [
],
"automatic_relist": false,
"date_created": "2024-02-22T16:51:37.577Z",
"last_updated": "2024-03-22T20:49:39.772Z",
"health": 0.75,
"catalog_listing": false
}
Filter items that have suggested compatibilities.
Get the number of suggestions and complaints
With the following resource you will be able to know the number of compatibility suggestions and complaints that a specific publication has..
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/catalog_domains/$DOMAIN_ID/compatibilities/cardsExample:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d
{
"item_id": "MLB4462690924",
"product_id": "MLB31779615",
"filters": ["REPUTATION", "SUGGESTED"]
}
https://api.mercadolibre.com/catalog_domains/MLB-CARS_AND_VANS/compatibilities/cards
Attributes request
- item_id: mandatory attribute corresponding to the item identifier.
- product_id: attribute corresponding to the product that is associated to the item, it is optional, however performance and response times are improved when this attribute is informed.
- filters: mandatory attribute to indicate whether you want to obtain the number of complaints ["REPUTATION"], the number of compatibility suggestions ["SUGGESTED"] that the item has; or both ["REPUTATION", "SUGGESTED"].
Response:
[
{
"title": "Tienes 293 vehículos sugeridos pendientes por agregar",
"subtitle": "Identificamos vehículos compatibles con tu producto que te ayudarán a vender más",
"filter": "SUGGESTED",
"quantity": 293
},
{
"title": "Vehículos con reclamos por incompatibilidad",
"subtitle": "Revisalos y eliminalos para evitar nuevos reclamos.",
"filter": "REPUTATION",
"quantity": 1
}
]
Reputation: all the compatibilities that are generating complaints.
Suggested: all new compatibility cases suggested to your publications.
If you want to know how to obtain the suggested compatibilities for each item you can see more details in identifying suggested compatibilities.
SIf you want to know which are the problematic compatibilities that are generating complaints and affecting the seller's reputation you can see more details in know compatibilities that generate complaints.
Add compatibilities
To add compatibility of an item with a product and / or domain, you can check up to a maximum of 200 products per request (including those defined in the domains) and do it in 3 different ways:
- By product: To add new compatibility to an item, you must send the compatibility you want to add. It is not necessary to send existing ones to keep current ones.
- By product domain: you can specify a set of attributes that define the product domain. For each domain, you must specify its domain and for each attribute, a value made up of id and / or name.
- By product and domain: You can add compatibility with a published item of another product and a product domain, that is, it allows you to add the first 2 together.
Get the possible values for a restriction
When associating a compatibility you can also indicate the position restriction of the same, with the following request you will be able to know the possible values to inform it.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_compatibilities/restrictions/values?main_domain_id=MLA-CARS_AND_VANS&secondary_domain_id=MLA-VEHICLE_SHOCK_ABSORBERSResponse:
{
"attributes_values": [
{
"attribute_id": "POSITION",
"values":
[
{
"value_id": "23536",
"value_name": "Superior",
},
{
"value_id": "23537",
"value_name": "Inferior"
}
]
}
]
}
Add by product
To add a compatibility to one or more individual products, you can use the product search.
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products": [{
"id": "$PRODUCT_ID",
"note": "texto",
"restrictions": [{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}]
}]
}'
Example:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products": [{
"id": "MLB155254",
"note": "Modelos posteriores a Mayo de 2018",
"restrictions": [{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
},
{
"values":[{"value_id": "65432","value_name": "Trasero"},
{"value_id": "87675","value_name": "Inferior"}]
}
]
}]
}]
}
Response:
{
"created_compatibilities_count": 72
}
It is also possible to add a note and position to more than one compatibility, for this it is necessary to replace the products node by products_group, example:
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products_group": [{
"ids": ["MLB155254", "MLB155255"],
"note": "texto",
"restrictions": [{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}]
}]
}
Add by product domain
To add compatibilities defined by a group of attributes that determine a domain, learn more about vehicle accessories domains and attributes.
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products_families": [{
"domain_id": "$DOMAIN_ID",
"attributes": [{
"id": "$ATTRIBUTE_ID",
"value_id": "$VALUE_ID"
},
{
"id": "$ATTRIBUTE_ID",
"value_id": "$VALUE_ID"
},
],
"note": "Texto",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}]
}Example (except MLM):
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA794706391/compatibilities
{
"products_families": [{
"domain_id": "MLA-CARS_AND_VANS",
"attributes": [{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "YEAR",
"value_name": "2010"
},
],
"note": "Solamente para vehículos de fabricación Europea",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}]
}
Response:
{
"created_compatibilities_count": 23
}
Ejemplo MLM:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities
{
"products_families": [{
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"attributes": [{
"id": "DRIVE_TYPE",
"value_id": "8182649"
},
{
"id": "CAR_AND_VAN_BODY_TYPE",
"value_id": "8183109"
},
{
"id": "YEAR",
"value_name": "2010"
}
],
"note": "Solamente para vehículos de fabricación Europea",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
},
{
"values":[{"value_id": "65432","value_name": "Trasero"},
{"value_id": "87675","value_name": "Inferior"}]
}
]
}
]
}
Response:
{
"created_compatibilities_count": 23
}
Add by product and domain product
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products": [{
id": "$PRODUCTIID",
"note": "texto",
"restrictions": [{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}],
"products_families": [{
"domain_id": "$DOMAIN_ID",
"attributes": [{
"id": "ATTRIBUTE_ID",
"value_id": "$VALUE_ID"
},
{
"id": "ATTRIBUTE_ID",
"value_id": "$VALUE_ID"
},
],
"note": "Texto",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}]
}
Example:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities
{
"products": [{
"id": "MLB155254",
"note": "Modelos posteriores a Mayo de 2018",
"restrictions": []
}],
"products_families": [{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "YEAR",
"value_name": "2010"
},
],
"note": "Solamente para vehículos de fabricación Europea",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
},
{
"values":[{"value_id": "65432","value_name": "Trasero"},
{"value_id": "87675","value_name": "Inferior"}]
}
]
}]
}
In the note
Response:
{
"created_compatibilities_count": 23
}
Possible errors
400: consistency validations:
- Required fields are incomplete.
- The format of the ids is wrong.
- More than 200 products were found and / or specified for the product domains.
- More than 10 product domains were specified.
- The products and / or domains do not belong to the same site as the item.
- The products must all be children.
- The item's domain is compatible with the specified product domains and / or with the specified domains in the specified product domains.
403: Invalid token or lack of permissions on the item.
404: the specified item, products or domains do not exist.
Copy and Paste Compatibilities
The first step to copy the compatibilities is to obtain a list of active items that have configured compatibilities. To do this, you need to start by retrieving all the seller's active items using the following query:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
"https://api.mercadolibre.com/users/$USER_ID/items/search?status=active"
Once the active items have been obtained, it is necessary to identify those that have compatibilities. Perform a query to the /items endpoint and verify if the item contains the "HAS_COMPATIBILITIES" attribute.
To obtain the list of items with the number of compatibilities, notes, and positions, make the following request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/compatibilities_summary
{
"domain_id": "$domainId",
"items": [
"$item_id",
"item_id",
"item_id"
]
}
'
Example:
curl --location 'https://api.mercadolibre.com/items/compatibilities_summary' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"domain_id": "MLB-CARS_AND_VANS",
"items": [
"MLB4816242302",
"MLB3845318745",
"MLB3845318797"
]
}
Response:
[
{
"item_id": "MLB4816242302",
"item_title": "Pastilha Dianteira Anuncio De Teste 2",
"compatibilities_count": 1001,
"compatibilities_claims_count": 0,
"notes_count": 65,
"restrictions_count": 64
},
{
"item_id": "MLB3845318797",
"item_title": "Pastilha Dianteira Anuncio De Teste",
"compatibilities_count": 400,
"compatibilities_claims_count": 0,
"notes_count": 64,
"restrictions_count": 64
},
{
"item_id": "MLB3845318745",
"item_title": "Pastilha Dianteira Anuncio De Teste",
"compatibilities_count": 200,
"compatibilities_claims_count": 0,
"notes_count": 64,
"restrictions_count": 64
}
]
To copy the compatibilities from an item to an item without loaded compatibilities, make this request:
curl --location 'https://api.mercadolibre.com/items/$ITEM_ID/compatibilities' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"item_to_copy": {
"item_id": "$ITEM_ID",
"extended_information": true
}
}'
Example:
curl --location 'https://api.mercadolibre.com/items/MLB3863097751/compatibilities' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"item_to_copy": {
"item_id": "MLB4816242302",
"extended_information": true
}
}'
Response:
200 OKTo copy the compatibilities from an item to an item that already has loaded compatibilities, make this request:
curl --location --request PUT 'https://api.mercadolibre.com/items/$ITEM_ID/compatibilities' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"create": {
"item_to_copy": {
"item_id": "$ITEM_ID",
"extended_information": true
}
}
}
Example:
curl --location --request PUT 'https://api.mercadolibre.com/items/MLB3863034063/compatibilities' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"create": {
"item_to_copy": {
"item_id": "MLB4816242302",
"extended_information": true
}
}
}
'
Response:
{
"create": {
"products": [
{
"id": "MLB7864691",
"note": "frente",
"restrictions": [
{
"attribute_id": "POSITION",
"attribute_code": 1,
"attribute_values": [
{
"values": [
{
"value_id": "13701104",
"value_code": 5
}
]
}
]
}
]
},
.
.
.
"universal": false,
"item_to_copy": {
"item_id": "MLB4816242302",
"extended_information": true
}
}
}
Considerations
- Without compatibilities: Copies all compatibilities from the source listing.
- With compatibilities: Performs a comparison between the two listings and only copies the vehicles from the source listing that are not yet in the target listing.
To add a universal compatibility
To indicate that an item is compatible with any product, in the request, the universal field is available, which shall be informed in true. This indicates that this item is universal (none of the compatibilities should be add to it since it is compatible with all products from the same domain).
When indicating a universal compatibility, it is not possible to specify products or families. If both fields are sent, an error will be returned.
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products": [],
"products_families": [],
"products_group": [],
"universal": true
}
Example:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM12456789/compatibilities
{
"products": [],
"products_families": [],
"products_group": [],
"universal": true,
}
Response:
{
"created_compatibilities_count": 1
}
Possible errors when assigning universal compatibilities
400: consistency validations:
- Message: "Invalid arguments for specific request. Please check details to satisfy validations".
- Details: "at least one of products, products_groups, products_families or universal must be specified, if universal no products can be specified".
- Message: Item has compatibilities and these must be removed before setting it as universal.
- Message: There is no configured compatibility for the category $CATEGORY_ID
- Message: Item has universal setting and must be removed before creating compatibilities.
403: invalid token or lack of permissions on the item.
404: the item does not exist.
Update Compatibilities
With this method, it is possible to create, update, and delete compatibilities, notes, and restrictions for an item using the same data structure as for creating compatibilities. This action can be performed for one or multiple compatibilities.
Request:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/items/$ITEM_ID/compatibilities?/code>Example for Creating and Deleting Compatibilities:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d
'{
"create": {
"products": [
{
"id": "MLB22015088"
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "MODEL",
"value_name": "Gol"
},
{
"id": "YEAR",
"value_name": "2023"
}
]
}
]
},
"delete": {
"products": [
{
"id": "MLB22015074"
},
{
"id": "MLB7427549"
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "MODEL",
"value_id": "62109"
},
{
"id": "YEAR",
"value_name": "2023"
}
]
}
]
}
}
Response:
{
"create": {
"products": [
{
"id": "MLB22015088"
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "MODEL",
"value_name": "Gol"
},
{
"id": "YEAR",
"value_name": "2023"
}
]
}
],
"universal": false
},
"delete": {
"products": [
{
"id": "MLB22015074"
},
{
"id": "MLB7427549"
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "MODEL",
"value_id": "62109"
},
{
"id": "YEAR",
"value_name": "2023"
}
]
}
],
"universal": false
}
}
Example for Creating and Updating Compatibilities with Notes and/or Restrictions:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d
'{
"create": {
"products": [
{
"id": "MLB28049481",
"note": "nota para teste",
"restrictions": []
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60395"
},
{
"id": "MODEL",
"value_ids": [
"389577",
"16696"
]
}
]
}
]
},
"update": {
"products": [
{
"id": "MLB22567898",
"note": "nota para teste 10",
"restrictions": [
{
"attribute_id": "POSITION",
"attribute_values": [
{
"values": [
{
"value_id": "13701104",
"value_name": "Dianteira"
}
]
}
]
}
]
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "67781"
},
{
"id": "MODEL",
"value_name": "ARGO"
}
],
"note": "somente as versões de freios traseiros",
"restrictions": [
{
"attribute_id": "POSITION",
"attribute_values": [
{
"values": [
{
"value_id": "13701104",
"value_name": "Dianteira"
}
]
}
]
}
]
}
]
}
}
Response:
{
"create": {
"products": [
{
"id": "MLB28049481",
"note": "nota para teste",
"restrictions": []
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60395"
},
{
"id": "MODEL",
"value_ids": [
"389577",
"16696"
]
}
]
}
],
"universal": false
},
"update": {
"products": [
{
"id": "MLB22567898",
"note": "nota para teste 10",
"restrictions": [
{
"attribute_id": "POSITION",
"attribute_code": 1,
"attribute_values": [
{
"values": [
{
"value_id": "13701104",
"value_name": "Dianteira",
"value_code": 5
}
]
}
]
}
]
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "67781"
},
{
"id": "MODEL",
"value_name": "ARGO"
}
],
"note": "somente as versões de freios traseiros",
"restrictions": [
{
"attribute_id": "POSITION",
"attribute_code": 1,
"attribute_values": [
{
"values": [
{
"value_id": "13701104",
"value_name": "Dianteira",
"value_code": 5
}
]
}
]
}
]
}
],
"universal": false
}
}
Possible Errors:
400 - Consistency Validations:
- Completeness of required fields.
- Correctness of ID formats.
- Products and/or domains belong to the same site as the item.
- The item's domain is compatible with the domains of the specified products.
- The maximum of 200 products for a single request has been exceeded.
403: Caller ID does not have permissions for the item.
404: Item or one of the products does not exist.
Modify or delete notes and position restrictions
To modify or delete a note and position constraint, execute a PUT on the compatibility reporting resource changing the information you need in the update field. To delete one or both of them, just send the note field and/or the empty restrictions array, as in the example below, where both fields are deleted.
Example:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"update": {
"products": [{
"id": "MLB155254",
"note": "",
"restrictions":[]
}
]
}
}
Identify compatible items
With the following resource you can identify that an item is already compatibilized through the attribute id = “HAS_COMPATIBILITIES”. If this attribute is not observed in the output of the call, it means that the item does not have compatibilities reported.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_IDExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1417560910Response:
{
"id": "MLA1417560910",
"site_id": "MLA",
"title": "Interruptor Columna (palanca) Tamatel 15104 - No Ofertar",
"seller_id": 1373279576,
"category_id": "MLA435058",
.
.
.
.
"attributes": [
{
"id": "HAS_COMPATIBILITIES",
"name": "Tiene compatibilidades",
"value_id": "242085",
"value_name": "Sí",
"values": [],
"value_type": "boolean"
},
{},
{}
],
.
.
.
}
List compatibilities
With this resource, you can list all the compatibilities for a particular item.
Get all compatibilities for an item
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities?extended=trueRequest example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities?extended=trueResponse example:
{
"products": [
{
"id": "bcbd413f-cd65-0e0f-88c9-5eb4aebb5372",
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"catalog_product_id": "MLM15847548",
"catalog_product_name": "Volkswagen Jetta 2010 GLI Manual 5",
"source": "SELLER",
"note": "Solo modelos de caja automática"
},
{
"id": "58bd413f-cd65-a719-9570-2ca8f2b528af",
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"catalog_product_id": "MLM15847546",
"catalog_product_name": "Volkswagen Jetta 2010 GLI Automática 6",
"source": "SELLER",
"note": "Modelos posteriores a Junio 2010",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
},
{
"values":[{"value_id": "65432","value_name": "Trasero"},
{"value_id": "87675","value_name": "Inferior"}]
}]
}],
"reputation:" {
"level": "RED",
"total_claims": 2
}
}
],
"catalog_compatibilities_count": 15
}
Response fields
- products: array arreglo con todos los vehículos (compatibilidades) informadas por el vendedor.
- ID: compatibility ID.
- domain_id: main product domain.
- catalog_product_id: product ID of the primary domain.
- catalog_product_name: product name of the primary domain.
- source: source flow of compatibility.
- note: specification of compatibility conditions between the item and the main product.
- restrictions: compatibility restrictions between item and main product (ex. installation position of the part).
- reputation: color and total number of vehicles that generated complaints.
- level: will take the RED value for compatibilities with a high number of incompatibility complaints.
- total claims: number of incompatibility complaints related to compatibility.
Obtain compatibilities of a universal item
In case the item is configured as universal, an additional field called universal is added in the response, containing a list of top domains with which the item is compatible..
Ejemplo respuesta:
{
"universal": {
“domain_ids”: [“MLM_CARS_AND_VANS_FOR_COMPATIBILITIES”]
}
}
Get a specific compatibility of an item by its id
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/$compatibility_idExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities/$compatibility_idResponse:
{
"id": "bcbd413f-cd65-0e0f-88c9-5eb4aebb5372",
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"catalog_product_id": "MLM15847548",
"catalog_product_name": "Volkswagen Jetta 2010 GLI Manual 5",
"note": "Solo para versiones con frenos a disco en las ruedas traseras",
"note_status": "PENDING",
"restrictions": [{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
}]
}] ,
"reputation:" {
"level": "RED",
"total_claims": 2
}
}
The notes only appear on the front of the item in the APPROVED or CHECKED status.
A 404 error means that the item does not exist.
Identifying if an item has notes or restrictions position
The endpoint allows to identifying if the item has notes or restrictions:
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/extended/checkExample:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM12456789/compatibilities/extended/checkResonse:
{
"note": "true",
"restrictions": "false"
}
Obtain a compatibility note
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/$COMPATIBILITY_ID/note
Example:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM12456789/compatibilities/bcbd413f-cd65-0e0f-88c9-5eb4aebb5372/noteResponse:
{
"note": "Solo para versiones con frenos a disco en las ruedas traseras"
}
Delete compatibilities
In case of having add an incorrect compatibility with the item, you can eliminate it as long as it has been made by the seller.
Delete a specific compatibility for the indicated item
Request:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/$COMPATIBILITY_IDExample:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities/4cb9af35-8e9b-ebfd-9e7f-2245ac363d10The response will be http 200.
Delete compatibilities for an item
Request:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilitiesExample:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilitiesResponse:
{
"deleted_compatibilities": [
"d0ba2aeb-7409-0037-7b23-0b91266fd00e",
"72ba233d-16d8-218b-4062-7a97dab166c8"
]
}Delete compatibilities by product domain for an item
Request:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products_families": [{
"domain_id": "$domain_id",
"attributes": [{
"id": "$attribute_id1",
"values":[{
"id": "$value_id1",
"name": "$value_name1"
}]
},{
"id": "$attribute_id2",
"values":[{
"id": "$value_id1",
"name": "$value_name1"
}]
}]
}]
}
Example:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities
{
"products_families": [{
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"attributes": [{
"id": "DRIVE_TYPE",
"value_id": "8182649"
},
{
"id": "CAR_AND_VAN_BODY_TYPE",
"value_id": "8183109"
},
{
"id": "YEAR",
"value_name": "2010"
}]
}]
}
Response:
{
"deleted_compatibilities": [
"d0ba2aeb-7409-0037-7b23-0b91266fd00e",
"72ba233d-16d8-218b-4062-7a97dab166c8"
]
}Possible errors
400: incorrect format / more than 200 products for the domain / more than 10 domains specified.
403: inválid token or lack of permits on the ítem.
404: the ítem or the compatibility not exist.
How to report exceptions
In cases of car and truck parts, in which the category requires compatibility information,but cannot find any available vehicle, model or version in the catalog. These items are part of the exceptions flow and to inform them, we provide the following resource:
Request:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$item_id/compatibilities/exception
{
"comment": “free text with a maximum of 255 characters”
}
Example:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB12345678/compatibilities/exception
{
"comment": “free text with a maximum of 255 characters” [Required]
}
Response:
200 OKPossible errors
400: item is closed or inactive.
400: item has existing compatibilities.
400: item category has no compatibilities.
400: item has existing compatibilities exception.
400: comment is required.
Check if an item has an exception
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$item_id/compatibilities/exceptionExample
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB12345678/compatibilities/exception
Response
{
"has_exception": true/false
}
- Returns true only when the item has no compatibility loaded and an exception has been reported.
- Returns false whenever an item has at least one vehicle reported as compatible (regardless of whether an exception was reported or not).
Identify compatibilities that generate complaints
In order for you to correct incorrectly indicated compatibilities, with the following endpoint you can identify the car that the buyer chose from the moment a claim for incompatibility was generated.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/$ORDER_IDExample:
Order with claim where the buyer selected different filters during the purchase of the product and it was confirmed that the selected product “Yes was indeed compatible” with the item (compatibility_status.compatibility = CONFIRMED).
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/2000006372967416Response:
{
"item_id": "MLM2187940074",
"product_id": "MLM15879678",
"seller_id": "61597650",
"user_selection": {
"label_values": [
{
"label": "Marca",
"value_name": "Jeep",
"values": [
{
"attribute_id": "BRAND",
"value_id": "60395"
}
]
},
{
"label": "Modelo",
"value_name": "Grand Cherokee",
"values": [
{
"attribute_id": "CAR_AND_VAN_MODEL",
"value_id": "8236932"
}
]
},
{
"label": "Año",
"value_name": "1998",
"values": [
{
"attribute_id": "YEAR",
"value_id": "60500"
}
]
},
{
"label": "Versión",
"value_name": "Limited - SUV 4 Puertas",
"values": [
{
"attribute_id": "CAR_AND_VAN_SUBMODEL",
"value_id": "8238101"
},
{
"attribute_id": "CAR_AND_VAN_BODY_TYPE",
"value_id": "8183114"
},
{
"attribute_id": "BODY_DOORS_NUMBER",
"value_id": "8239302"
}
]
},
{
"label": "Mecánica",
"value_name": "5.2L V8 Gasolina Aspirado Caja Automática 4 Marchas - Tracción RWD",
"values": [
{
"attribute_id": "CAR_AND_VAN_ENGINE",
"value_id": "8753511"
},
{
"attribute_id": "ASPIRATION",
"value_id": "8183201"
},
{
"attribute_id": "TRANSMISSION_CONTROL_TYPE",
"value_id": "8183158"
},
{
"attribute_id": "TRANSMISSION_SPEEDS_NUMBER",
"value_id": "8239312"
},
{
"attribute_id": "DRIVE_TYPE",
"value_id": "8182651"
}
]
}
]
},
"compatibility_status": {
"compatibility": "CONFIRMED",
"compatibility_id": "bec40b54-c7de-1ad2-a7e2-00a5e34376a4"
},
"compatibility_deleted": true,
"date_created": "2023-08-31T20:08:41Z",
"date_updated": "2023-08-31T22:37:39Z"
}
Order with claim where the buyer did not select a vehicle during the purchase of the product.
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/2000006372967424Response:
{
"item_id": "MLM2038068352",
"seller_id": "186880296",
"compatibility_status": {
"compatibility": "NO_USER_SELECTION",
"note": "We don't have the compatibility information for this order. The user made the order without completing the widget. ",
"restrictions": []
},
"date_created": "2023-08-23T12:30:57Z"
}
Order with claim where prior to purchase it was confirmed to the buyer that the product selected "was not compatible" with the item (compatibility_status.compatibility = INCOMPATIBLE).
Request:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/2000006372967684Response:
{
"item_id": "MLM693204319",
"seller_id": "56493851",
"compatibility_status": {
"compatibility": "INCOMPATIBLE"
},
"compatibility_deleted": true,
"date_created": "2023-08-25T14:45:48Z"
}
The fields indicate:
- compatibility_id: identifier of the compatibility selected during purchase.
- product_id: ID of the selected vehicle prior to purchase.
- user_selection: detail of the filters selected by the buyer at the time of purchase.
- compatibility_status.compatibility:
- CONFIRMED: indicates that it was confirmed to the buyer that the selected vehicle was compatible with the purchased item.
- INCOMPATIBLE: indicates that it was confirmed to the buyer that the selected vehicle was not compatible with the purchased item.
- compatibility_deleted::
- "true" indicates that the compatibility for the vehicle selected by the buyer has already been deleted by the item at the time of the query.
Possible mistakes:
| Error_code | Error message | Description |
|---|---|---|
| 400 | Compatibility snapshot for order with id $ORDER_ID not found. | The order is not valid. |
| 401 | Invalid access token. | Invalid Access Token. |
| 403 | The compatibility snapshot can only be retrieved for orders with claims. | The order has no associated claim. |
| 403 | Caller must be the seller of the item. | An attempt is being made to query the order of a seller that does not correspond to the Access Token provided. |