Documentação de Produtos em ERP

Visão Geral

No contexto de ERP, o produto é uma das principais entidades da integração, pois representa os itens comercializados e controlados entre a loja e o sistema de gestão 📦

Ele concentra informações como dados cadastrais, preços, variações e estoque, sendo fundamental para a consistência operacional.

---

Filas de Entrada e Saída:

Quando integrado, o produto também pode trafegar nos dois sentidos: do ERP para a plataforma ou da plataforma para o ERP.

No fluxo de entrada, produtos vindos do ERP são inseridos em uma fila de entrada, onde aguardam processamento antes de serem cadastrados ou atualizados na loja.

Já no fluxo de saída, produtos criados ou modificados na plataforma podem ser enviados para uma fila de saída, organizando o envio estruturado dessas informações ao ERP.

Esse modelo garante controle, rastreabilidade e processamento assíncrono da integração 🔄

---

Mapa de Produto e Estoque:

Outro ponto essencial são os mapas de produto, responsáveis por relacionar os identificadores da loja com os identificadores do ERP, assegurando que ambos os sistemas reconheçam o mesmo item.

Além disso, a sincronização de estoque e preços depende desse mapeamento, garantindo que atualizações realizadas em um ambiente sejam corretamente refletidas no outro, evitando divergências operacionais.

Listagem de produtos do ERP

Descrição

Endpoint responsável por retornar a lista de produtos disponíveis no ERP 📦

A requisição exige as credenciais do ERP, pois a consulta é realizada diretamente no sistema de gestão.

Dessa forma, os dados retornados refletem exatamente o catálogo ativo no ERP, garantindo alinhamento com as informações oficiais da integração.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/erps/{erpStoreCredentialId}/products \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "productId": 987654321,
5      "brandId": null,
6      "brandName": null,
7      "mainCategoryId": null,
8      "mainCategoryName": null,
9      "type": "product",
10      "sku": "SKU123321",
11      "name": "A saga do bruxo Geral de Rivia - O último desejo",
12      "active": true,
13      "url": "",
14      "comparisonPrice": 30,
15      "stock": null,
16      "medias": [],
17      "combination": [],
18      "currentAttributes": []
19    },
20  ],
21  "pagination": {
22    "limit": 10,
23    "offset": 0,
24    "pages": 1,
25    "registers": 10
26  }
27}

⚠️ 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.

Listagem de histórico da integração

Descrição

Endpoint responsável por retornar a lista de histórico da integração de produtos com o ERP 🕓

A resposta apresenta registros das operações realizadas, como envios, importações ou falhas no processo de integração.

Ideal para auditoria e monitoramento, permitindo identificar inconsistências, validar sincronizações e acompanhar o status das integrações.

Parâmetros

Headers Obrigatórios

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/erps/products/history \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 1,
5      "erpStoreCredentialId": 1,
6      "externalId": "1",
7      "action": "update-stock",
8      "request": [],
9      "response": [],
10      "trace": null,
11      "createdAt": "2026-02-10 13:33:00",
12      "productId": 1
13    }
14  ],
15  "pagination": {
16    "limit": 10,
17    "offset": 0,
18    "pages": 1,
19    "registers": 10
20  }
21}

Listagem de produtos mapeados com o ERP

Descrição

Endpoint responsável por retornar a lista de produtos mapeados com o ERP 🔗

A resposta contempla apenas produtos que já possuem vínculo ativo com o sistema de gestão, garantindo visibilidade sobre o que está efetivamente integrado.

Indicado para cenários de consulta, validação ou auditoria de integração, facilitando a identificação de itens sincronizados.

Parâmetros

Headers Obrigatórios

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/erps/maps/products \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "status":true,
3  "data": {
4    "registers": [
5      {
6        "erpStoreCredentialId": 1,
7        "externalId": "2077",
8        "createdAt": "2025-11-19 14:01:41",
9        "productId": 1
10      }
11    ],
12    "pagination": {
13      "limit": 10,
14      "offset": 0,
15      "pages": 1,
16      "registers": 10
17    }
18  }
19}

Atualização de mapeamento dos produtos com ERP

Descrição

Endpoint responsável por atualizar o mapeamento de produtos com o ERP 🔄

Permite corrigir vínculos existentes ou estabelecer novos mapeamentos, garantindo consistência entre a loja e o sistema de gestão.

A operação requer as credenciais do ERP, pois pode envolver validações ou consultas diretas no ambiente integrado.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/erps/maps/{erpStoreCredentialId}/products \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5	  "maps": [
6      {
7        "productId": 1,
8        "externalId": "987654321",
9        "action": "add"
10      }
11    ]
12  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4		{
5			"externalId": "987654321",
6			"erpStoreCredentialId": 1,
7			"action": "add",
8			"productId": 1
9		},
10		{
11			"externalId": "987654322",
12			"erpStoreCredentialId": 1,
13			"action": "add",
14			"productId": 2
15		}
16	]
17}

⚠️ 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.

Exporta produtos da loja para o ERP

Descrição

Endpoint responsável por exportar produtos da loja para o ERP 📤

A operação é realizada mediante o envio dos IDs dos produtos desejados, permitindo controle granular sobre quais itens serão integrados.

Ideal para cenários em que é necessário sincronizar produtos específicos, evitando reprocessamentos desnecessários.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/erps/5/products/export \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "productIds": [
6      1, 2, 3
7    ]
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1true

⚠️ 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.

Importação de produtos do ERP

Descrição

Endpoint responsável por permitir a importação de produtos do ERP para a loja 📥

Realiza a sincronização dos produtos cadastrados no sistema de gestão, trazendo-os para a plataforma de forma estruturada.

Indicado para cenários de integração inicial ou atualização de catálogo, garantindo alinhamento entre o ERP e a loja.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/erps/{erpStoreCredentialId}/products/import \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "externalProductIds": [
6      "1","2","3"
7    ]
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ 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.

Importação estoque de produtos do ERP

Descrição

Endpoint responsável por importar o estoque do produto do ERP para a loja 📥

Atua como uma rotina de atualização de estoque, sincronizando as quantidades disponíveis entre o sistema de gestão e a plataforma.

Indicado para manter consistência nas informações de disponibilidade, reduzindo riscos de venda sem estoque ou divergências operacionais.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/erps/{erpStoreCredentialId}/products/import/stock \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "productIds": [
6      1,2,3
7    ]
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ 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.