Skip to content

Mapeamentos de marketplace

Visão Geral

Os mapeamentos são outra parte vital da integração, pois permitem que a Uappi 3 e a API do marketplace relacionem informações. Por exemplo: através dos mapeamentos pode-se relacionar os atributos criados na loja e os atributos possíveis no marketplace.

O mapeamento também será usado em partes essências como no recebimento de pedidos, para entender de qual armazém veio o estoque vendido no pedido.

Notas e Considerações

O Hub de marketplace, diferentemente de outros marketplaces, não necessita de diversos mapeamentos para funcionar pois o mesmo utiliza um processo de sincronização de entidades fora do protocolo de marketplace.

Listagem de mapeamentos de marketplace

GET /marketplace/maps/{entity}

Listagem de mapeamentos de marketplace

Descrição

Endpoint responsável por listar os mapeamentos de marketplace já criados em todas as credenciais da loja.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Parâmetros de rota

ParâmetroTipoDescrição
entityintegerEntidade sendo listada, os valores permitidos são: brands, attributes, storages, carriers, shipping-tables, filters, products.

Campos de Condição Disponíveis

CampoTipoDescrição
marketplaceStoreCredentialIdintegerID da credencial de marketplace.
entityIdintegerID da entidade (produto, marca, categoria, etc).
externalEntityIdstringID da entidade no marketplace.
createdAtstringData de criação do mapeamento.

Campos de Ordenação Disponíveis

CampoDescrição
entityIdID da entidade (produto, marca, categoria, etc).

Campos de Solicitação

CampoDescrição
productCampo exclusivo para o mapeamento de produtos, retorna os dados simples dos mesmos no campo product.

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/marketplaces/maps/brands \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6	"fields": [],
7	"order": [],
8	"condition": {
9		"type": "AND",
10		"conditions": []
11	}
12}'

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": {
4		"registers": [
5			{
6				"marketplaceStoreCredentialId": 2,
7				"entityId": 1,
8				"externalEntityId": "1",
9				"externalEntityLabel": null,
10				"createdAt": "2026-02-23 11:48:50",
11        "updatedAt": "2026-02-23 11:48:50"
12			},
13			{
14				"marketplaceStoreCredentialId": 2,
15				"entityId": 2,
16				"externalEntityId": "2",
17				"externalEntityLabel": null,
18        "createdAt": "2026-02-23 11:48:50",
19        "updatedAt": "2026-02-23 11:48:50"
20			},
21			{
22				"marketplaceStoreCredentialId": 2,
23				"entityId": 3,
24				"externalEntityId": "3",
25				"externalEntityLabel": null,
26        "createdAt": "2026-02-23 11:48:50",
27        "updatedAt": "2026-02-23 11:48:50"
28			}
29		],
30		"pagination": {
31			"limit": 3,
32			"offset": 0,
33			"pages": 446,
34			"registers": 1338
35		}
36	}
37}

Exemplo de Requisição de Produtos

1curl --request GET \
2  --url '{{MAIN_URL}}/marketplaces/maps/products?limit=3' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6	"fields": [
7		"product"
8	],
9	"order": [],
10	"condition": {
11		"type": "AND",
12		"conditions": []
13	}
14}'

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": {
4		"registers": [
5			{
6				"marketplaceStoreCredentialId": 2,
7				"entityId": 1,
8				"externalEntityId": "1",
9				"externalEntityLabel": null,
10				"createdAt": "2026-02-23 11:48:50",
11				"updatedAt": "2026-03-11 18:45:17",
12				"product": {
13					"productId": 1,
14					"brandId": 1,
15					"brandName": "Uappi",
16					"mainCategoryId": 3,
17					"mainCategoryName": "Proteí­na -> Whey Protein",
18					"type": "product",
19					"sku": "WHEYCONCENTRADO",
20					"name": "Whey muito concentrado",
21					"active": true,
22					"url": "",
23					"comparisonPrice": 0,
24					"stock": 0,
25					"medias": [
26						{
27							"id": 101,
28							"type": "image",
29							"title": "Whey Protein",
30							"alternativeText": "Whey Protein",
31							"file": "/upload/media/bcdae9e997f3029cc64681a929efae22.webp",
32							"originalFile": "/upload/media/8fb896a9b205470df0c1cd1bc21207a6.jpeg",
33							"size": 32428,
34							"originalSize": 46275,
35							"width": 630,
36							"height": 780,
37							"url": null
38						},
39						{
40							"id": 102,
41							"type": "image",
42							"title": "Scoop",
43							"alternativeText": "Scoop",
44							"file": "/upload/media/3c7558387964be10da6bd67b9ba6ce9f.webp",
45							"originalFile": "/upload/media/bcdae9e997f3029cc64681a929efae22.jpeg",
46							"size": 53916,
47							"originalSize": 97750,
48							"width": 1140,
49							"height": 740,
50							"url": null
51						},
52						{
53							"id": 103,
54							"type": "file",
55							"title": "Sheikera",
56							"alternativeText": "Sheikera",
57							"file": "/upload/media/9ed330409829fa2858ad0379d02e6ea9.pdf",
58							"originalFile": "/upload/media/9ed330409829fa2858ad0379d02e6ea9.pdf",
59							"size": 75011,
60							"originalSize": 75011,
61							"width": null,
62							"height": null,
63							"url": null
64						}
65					],
66					"combination": [],
67					"currentAttributes": []
68				}
69			},
70			{
71				"marketplaceStoreCredentialId": 2,
72				"entityId": 2,
73				"externalEntityId": "2",
74				"externalEntityLabel": null,
75				"createdAt": "2026-02-10 14:56:30",
76				"updatedAt": "2026-03-11 18:45:17",
77				"product": {
78					"productId": 2,
79					"brandId": 1,
80					"brandName": "Uappi",
81					"mainCategoryId": 19,
82					"mainCategoryName": "Aminoácidos -> Creatina",
83					"type": "product",
84					"sku": "CREAPURE",
85					"name": "CREATINA (250G) Creapure® - GROWTH SUPPLEMENTS",
86					"active": false,
87					"url": "",
88					"comparisonPrice": 0,
89					"stock": 0,
90					"medias": [],
91					"combination": [],
92					"currentAttributes": []
93				}
94			},
95			{
96				"marketplaceStoreCredentialId": 2,
97				"entityId": 3,
98				"externalEntityId": "3",
99				"externalEntityLabel": null,
100				"createdAt": "2026-02-10 14:56:30",
101				"updatedAt": "2026-03-11 18:45:17",
102				"product": {
103					"productId": 3,
104					"brandId": 1,
105					"brandName": "Uappi",
106					"mainCategoryId": 0,
107					"mainCategoryName": "",
108					"type": "product",
109					"sku": "HAZE",
110					"name": "PRÉ-TREINO HAZE HARDCORE 300G - GROWTH SUPPLEMENTS",
111					"active": true,
112					"url": "",
113					"comparisonPrice": 0,
114					"stock": 0,
115					"medias": [],
116					"combination": [],
117					"currentAttributes": []
118				}
119			}
120		],
121		"pagination": {
122			"limit": 3,
123			"offset": 0,
124			"pages": 446,
125			"registers": 1338
126		}
127	}
128}

Criação/atualização de mapeamentos de marketplace

POST /marketplace/maps/{entity}

Criação/atualização de mapeamentos de marketplace

Descrição

Endpoint responsável por criar ou atualizar (caso já existam) os mapeamentos de marketplace. Esse endpoint possui uma request e response em lote, ou seja, cada item na response terá um campo error indicando se ouve falha ou null em caso de sucesso.

Itens onde o entityId já esteja cadastrado serão considerados como atualização.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Parâmetros de rota

ParâmetroTipoDescrição
entitystringEntidade sofrendo atualização de mapeamento, os valores permitidos são: brands, attributes, storages, carriers, shipping-tables, filters, products.

Parâmetros de corpo

CampoTipoObrigatórioDescrição
entitiesarraySimArray contendo os mapeamentos para criação/atualização (máximo de 100 itens).
entities.*.marketplaceStoreCredentialIdintegerSimID do grupo de credencial de marketplace.
entities.*.entityIdintegerSimID da entidade sendo mapeada.
entities.*.externalEntityIdstringSimID no marketplace equivalente da entidade sendo mapeada.
entities.*.externalEntityLabelstring ou nullSimTexto opcional para facilitar a identificação do mapeamento (tamanho máximo de 255 caractéres).

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/marketplaces/maps/attributes \
3  --header 'Authorization: SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6	"entities": [
7		{
8			"marketplaceStoreCredentialId": 2,
9			"entityId": 1,
10			"externalEntityId": "cores",
11			"externalEntityLabel": null
12		},
13		{
14			"marketplaceStoreCredentialId": 45,
15			"entityId": 2,
16			"externalEntityId": "Voltagem",
17			"externalEntityLabel": null
18		},
19		{
20			"marketplaceStoreCredentialId": 2,
21			"entityId": 3,
22			"externalEntityId": "Tamanhos",
23			"externalEntityLabel": "Tamanho de roupa"
24		}
25	]
26}'

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": [
4		{
5			"marketplaceStoreCredentialId": 2,
6			"entityId": 1,
7			"externalEntityId": "cores",
8			"externalEntityLabel": null,
9			"error": null
10		},
11		{
12			"marketplaceStoreCredentialId": 45,
13			"entityId": 2,
14			"externalEntityId": "Voltagem",
15			"externalEntityLabel": null,
16			"error": "UAPPI_INTEGRATION_MARKETPLACE_CREDENTIAL_NOT_FOUND"
17		},
18		{
19			"marketplaceStoreCredentialId": 2,
20			"entityId": 3,
21			"externalEntityId": "Tamanhos",
22			"externalEntityLabel": "Tamanho de roupa",
23			"error": null
24		}
25	]
26}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código InternoCódigo HttpDescrição
UAPPI_INTEGRATION_MARKETPLACE_CREDENTIAL_NOT_FOUND404A credencial de marketplace solicitada não foi encontrada.

Remoção de mapeamentos de marketplace

DELETE /marketplace/maps/{entity}

Remoção de mapeamentos de marketplace

Descrição

Endpoint responsável por remover mapeamentos de marketplace em lote.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Parâmetros de rota

ParâmetroTipoDescrição
entitystringEntidade sofrendo atualização de mapeamento, os valores permitidos são: brands, attributes, storages, carriers, shipping-tables, filters, products.

Parâmetros de corpo

CampoTipoObrigatórioDescrição
entitiesarraySimArray contendo os mapeamentos para remoção.
entities.*.marketplaceStoreCredentialIdintegerSimID do grupo de credencial de marketplace.
entities.*.entityIdintegerSimID da entidade sendo removida do mapeamento.

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/marketplaces/maps/storages \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6	"entities": [
7		{
8			"marketplaceStoreCredentialId": 2,
9			"entityId": 2
10		},
11		{
12			"marketplaceStoreCredentialId": 2,
13			"entityId": 3
14		}
15	]
16}'

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": true
4}

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;