Skip to content

Documentação de ERP

Visão Geral

Um ERP (Enterprise Resource Planning) é um sistema de gestão empresarial responsável por centralizar e organizar as principais informações de uma empresa 🏢

Ele integra diferentes áreas do negócio em uma única plataforma, permitindo maior controle, padronização e automação de processos.

Entre os módulos mais comuns de um ERP, estão:

  • Cadastro de produtos, preços e estoque
  • Gestão de pedidos e faturamento
  • Controle financeiro e pagamentos
  • Logística e fretes
  • Relatórios e indicadores operacionais

    • Na prática, o ERP atua como a fonte central de dados da operação, concentrando informações estratégicas que precisam ser sincronizadas com outros sistemas, como lojas virtuais e marketplaces.

    Em cenários de integração, o ERP pode funcionar tanto como origem quanto destino das informações, garantindo consistência e rastreabilidade nos processos 🔄

    Entidades Envolvidas

    No contexto de integração com ERP, diversas entidades de negócio estão diretamente relacionadas ao sistema de gestão 🔗

    Entre as principais, destacam-se:

  • Produtos, responsáveis pela sincronização de catálogo, preços e estoque
  • Pedidos, envolvendo envio, atualização de status e dados de entrega
  • Pagamentos, contemplando opções disponíveis e seus respectivos mapeamentos
  • Fretes, incluindo tabelas, modalidades e valores integrados
  • Status de pedido, garantindo alinhamento do fluxo operacional entre plataforma e ERP

Essas entidades compõem o núcleo da integração, permitindo que as informações trafeguem de forma estruturada entre a loja e o ERP.

Dessa forma, o ERP atua como fonte ou destino das sincronizações, centralizando dados estratégicos da operação 🔄

Credenciais

As credenciais de ERP são o elemento que possibilita interligar uma loja a um sistema de gestão 🔐

Elas armazenam configurações e dados de acesso, viabilizando a troca de informações e sincronização de pedidos, produtos, estoque, pagamentos e fretes, entre outros.

No contexto da Uappi, é possível criar um grupo de credenciais de ERP e mantê-lo registrado na plataforma.

A partir dele, qualquer troca de informação, gerenciamento de filas ou controle de mapeamentos passa a ser realizado com base nessa credencial.

Nesse cenário, a credencial atua como um divisor lógico de integração, permitindo que a plataforma identifique exatamente qual ERP deve ser consultado ou acionado.

Por esse motivo, a maioria dos endpoints depende diretamente das credenciais, garantindo que cada operação seja executada no contexto correto da integração 🔄

Listagem de ERPs disponíveis

GET /erps

Retorna os sistemas de ERPs disponíveis na loja

Descrição

Endpoint responsável por retornar todos os ERPs disponíveis na loja.

Esses dados permitem o gerenciamento das integrações, facilitando a visualização e controle dos sistemas conectados ⚙️

Parâmetros

Headers Obrigatórios

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

Campos Disponíveis (fields)

CampoDescrição
erpStoreCredentialQuantityDetermina quantidade de credenciais vinculadas

Campos de Condição Disponíveis

CampoTipoDescrição
idintegerIdentificador único do ERP
nameintegerNome do ERP
codeintegerCódigo de identificação do ERP

Campos de Ordenação Disponíveis

CampoDescrição
idIdentificador único do ERP
orderCampo que determina ordem do ERP

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 1,
5      "code": "tiny",
6      "name": "Olist Tiny",
7      "image": "https://logoerp.svg",
8      "url": "https://tiny.com.br/",
9      "description": "Olist Tiny é sistema ERP, hub de integrações e conta digital em um só lugar.",
10      "viewable": true,
11      "oauth": false,
12      "order": 0,
13      "erpStoreCredentialQuantity": 0
14    }
15  ],
16  "pagination": {
17    "limit": 10,
18    "offset": 0,
19    "pages": 1,
20    "registers": 10
21  }
22}

Listagem de Credenciais de ERPs

GET /erps/{erpId}/credentials

Retorna lista de credenciais vinculados ao ERP especificado

Descrição

Endpoint responsável por retornar todas as credenciais vinculadas a um ERP.

Essas informações permitem visualizar e gerenciar as configurações associadas à integração 🔐

Parâmetros

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
erpIdintegerSimID único do ERP cujo as credenciais devem ser buscadas

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": [
4		{
5			"code": "client-id",
6			"title": "Client ID",
7			"type": "string",
8			"default": "",
9			"enum": [],
10			"mapKey": "",
11			"mapValue": ""
12		},
13		{
14			"code": "client-secret",
15			"title": "Clint Secret",
16			"type": "string",
17			"default": "",
18			"enum": [],
19			"mapKey": "",
20			"mapValue": ""
21		}
22	]
23}

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

Este endpoint possuí apenas um erro, que ocorre quando o ERP especificado não é encontrado.

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_INTEGRATION_ERP_NOT_FOUND",
6    "message": "The requested ERP was not found."
7  }
8}

Listagem de grupos de credenciais

GET /erps/credentials

Retorna grupos de credenciais de ERPs

Descrição

Endpoint responsável por retornar todos os grupos de credenciais de ERPs integrados à loja 🔐

A listagem contempla todas as integrações configuradas, permitindo visualizar quais sistemas de gestão estão vinculados à plataforma.

Indicado para consulta administrativa e controle de integrações, oferecendo uma visão consolidada das credenciais ativas.

Parâmetros

Headers Obrigatórios

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

Campos Disponíveis (fields)

CampoDescrição
credentialsCarrega as credenciais específicas do ERP
urlsCarrega URLs de webhooks associadas
linkedStoragesCarrega armazéns vinculados

Campos de Condição Disponíveis

CampoTipoDescrição
idintegerIdentificador do grupo de credencial
namestringNome do grupo de credencial
erpIdintegerIdentificador do ERP associado
tradePolicyIdintegerIdentificador da política comercial associada

Campos de Ordenação Disponíveis

CampoDescrição
idIdentificador do grupo de credencial

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 1,
5      "erpId": 1,
6      "tradePolicyId": 1,
7      "name": "Credencial do ERP Legal",
8      "exportStock": true,
9      "exportPrice": true,
10      "generateInvoice": true,
11      "oAuthTokenUpdatedAt": null,
12      "urls": {
13        "productWebhookUrl": "https://minhaloja.com.br/api/v3/erps/webhook/1/product",
14        "orderWebhookUrl": "https://minhaloja.com.br/api/v3/erps/webhook/1/order"
15      },
16      "linkedStorageIds": [],
17      "credentials": []
18    },
19  ],
20  "pagination": {
21    "limit": 10,
22    "offset": 0,
23    "pages": 1,
24    "registers": 10
25  }
26}

Listagem de credenciais vinculadas a armazéns

GET /erps/credentials/link

Lista vínculo de credenciais com armazéns

Descrição

Endpoint responsável por listar todos os vínculos entre credenciais e armazéns 🏬

A resposta apresenta as associações configuradas entre integrações e armazéns, permitindo visualizar como cada credencial está estruturada.

Indicado para validação e controle operacional, garantindo que os armazéns estejam corretamente vinculados aos respectivos ERPs.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Campos de Condição Disponíveis

CampoTipoDescrição
productStorageIdintegerIdentificador do armazém vinculado
erpStoreCredentialIdintegerIdentificador da credencial de ERP vinculada
createdAtstringData de cadastro do vínculo

Campos de Ordenação Disponíveis

CampoDescrição
createdAtData de cadastro do vínculo

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "productStorageId": 1,
5      "erpStoreCredentialId": 1,
6      "productStorageExternalId": "987654321",
7      "createdAt": "2026-02-25 13:36:26"
8    }
9  ],
10  "pagination": {
11    "limit": 10,
12    "offset": 0,
13    "pages": 1,
14    "registers": 10
15  }
16}

Detalhes de grupo de credenciais

GET /api/v3/erps/credentials/{erpStoreCredentialId}

Busca detalhes sobre grupo de credenciais do ERP

Descrição

Endpoint responsável por retornar os detalhes de um grupo de credenciais do ERP 🔎

Permite visualizar informações da credencial cadastrada, como dados de identificação e parâmetros de integração.

Indicado para cenários de validação, auditoria ou conferência de configuração, garantindo maior controle sobre as integrações ativas.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
erpStoreCredentialIdintegerSimIdentificador da credencial de ERP a ser consultada

Campos Disponíveis (fields)

CampoDescrição
credentialsCarrega as credenciais específicas do ERP
urlsCarrega URLs de webhooks associadas
linkedStoragesCarrega armazéns vinculados

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/erps/credentials/1 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "credentials",
7      "urls",
8      "linkedStorages",
9    ]
10  }'

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": {
4		"id": 1,
5		"erpId": 1,
6		"tradePolicyId": 1,
7		"name": "Credenciais Tiny ERP",
8		"exportStock": false,
9		"exportPrice": false,
10		"generateInvoice": false,
11		"oAuthTokenUpdatedAt": "2026-02-25 12:20:18",
12		"urls": {
13			"productWebhookUrl": "https://minhaloja.com.br/api/v3/erps/webhook/1/product",
14			"orderWebhookUrl": "https://minhaloja.com.br/api/v3/erps/webhook/1/order"
15		},
16		"linkedStorageIds": [],
17		"credentials": [
18			{
19				"credentialCode": "credential-id",
20				"type": "string",
21				"value": "987654321987654321987654321",
22				"enum": [],
23				"createdAt": "2026-02-25 12:13:51",
24				"updatedAt": "2026-02-25 12:13:51"
25			}
26		]
27	}
28}

⚠️ 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_ERP_CREDENTIAL_NOT_FOUND404A credencial de ERP solicitada não foi encontrada.

Criar grupo de credenciais para ERP

POST /erps/credentials

Permite criar grupos de credenciais para ERP

Descrição

Endpoint responsável por cadastrar grupos de credenciais para ERP 🔐

Permite configurar a integração entre um ERP e a loja, estabelecendo os dados necessários para autenticação e comunicação.

Esses grupos viabilizam a sincronização de produtos, pedidos, fretes e opções de pagamento, garantindo que as informações trafeguem de forma segura e estruturada entre os sistemas.

⚠️ Sobre a política comercial:

É muito importante escolher a política comercial da credencial corretamente pois é através dela que a plataforma irá obter dados de produtos que variam por política como preço, descrição, etc.

Parâmetros

Headers Obrigatórios

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

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
erpIdinteger✅Identificador do ERP que a credencial pertence
tradePolicyIdinteger✅Identificador da política comercial associada
namestring✅Nome da credencial
exportStockboolean✅Determina exportação de estoque
exportPriceboolean✅Determina exportação de preço
generateInvoicegenerateInvoice✅Determina se a plataforma deverá tentar gerar a nota fiscal do pedido assim que o mesmo for integrado no ERP
credentialsarray✅Array variável que armazena as credenciais do ERP

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/erps/credentials \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "erpId": 1,
6    "tradePolicyId": 1,
7    "name": "Credenciais Tiny ERP",
8    "exportStock": false,
9    "exportPrice": false,
10    "generateInvoice": false,
11    "credentials": {
12      ...
13    }
14  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"id": 1,
5		"erpId": 1,
6		"tradePolicyId": 1,
7		"name": "Credenciais Tiny ERP",
8		"exportStock": false,
9		"exportPrice": false,
10		"generateInvoice": false,
11		"oAuthTokenUpdatedAt": null,
12		"urls": {
13			"productWebhookUrl": "https://minhaloja.com.br/api/v3/erps/webhook/1/product",
14			"orderWebhookUrl": "https://minhaloja.com.br/api/v3/erps/webhook/1/order"
15		},
16		"linkedStorageIds": [],
17		"credentials": [
18			{
19				"credentialCode": "credential-id",
20				"type": "string",
21				"value": "987654321987654321987654321",
22				"enum": [],
23				"createdAt": "2026-02-25 12:13:51",
24				"updatedAt": "2026-02-25 12:13:51"
25			}
26		]
27	}
28}

⚠️ 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_CORE_INVALID_TRADE_POLICY_ID400Os ids de política comercial não são permitidos.
UAPPI_INTEGRATION_ERP_NOT_FOUND404O ERP solicitado não foi encontrado.
UAPPI_INTEGRATION_ERP_CREDENTIAL_NOT_FOUND404A credencial de ERP solicitada não foi encontrada.
UAPPI_EXTERNAL_ERROR_NOT_MAPPED500A aplicação encontrou um erro não mapeado no MS external.uappi.
UAPPI_INTEGRATION_ERP_CREDENTIAL_IS_REQUIRED400A credencial de ERP (código) é requerida
UAPPI_INTEGRATION_ERP_CREDENTIAL_TYPE_IS_INVALID400O tipo da credencial de ERP (código) é requerida

Atualizar grupo de credenciais para ERP

PUT /erps/credentials/{erpStoreCredentialId}

Permite atualizar grupos de credenciais para ERP

Descrição

Endpoint responsável por atualizar grupos de credenciais para ERP 🔄

Permite alterar dados de autenticação ou configuração da integração, mantendo a comunicação com o sistema de gestão ativa e segura.

Indicado para cenários de troca de chaves, ajustes técnicos ou atualização de parâmetros, garantindo continuidade nas sincronizações.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
erpStoreCredentialIdintegerSimIdentificador do grupo de credencial que deve ser atualizado

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
tradePolicyIdinteger✅Identificador da política comercial associada
namestring✅Nome da credencial
exportStockboolean✅Determina exportação de estoque
exportPriceboolean✅Determina exportação de preço
generateInvoicegenerateInvoice✅Determina se a plataforma deverá tentar gerar a nota fiscal do pedido assim que o mesmo for integrado no ERP
credentialsarray✅Array variável que armazena as credenciais do ERP

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/erps/credentials/1 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "tradePolicyId": 1,
6    "name": "Credenciais Tiny ERP",
7    "exportStock": false,
8    "exportPrice": false,
9    "generateInvoice": false,
10    "credentials": {
11      ...
12    }
13  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"id": 1,
5		"erpId": 1,
6		"tradePolicyId": 1,
7		"name": "Credenciais Tiny ERP",
8		"exportStock": false,
9		"exportPrice": false,
10		"generateInvoice": false,
11		"oAuthTokenUpdatedAt": null,
12		"urls": {
13			"productWebhookUrl": "https://minhaloja.com.br/api/v3/erps/webhook/1/product",
14			"orderWebhookUrl": "https://minhaloja.com.br/api/v3/erps/webhook/1/order"
15		},
16		"linkedStorageIds": [],
17		"credentials": [
18			{
19				"credentialCode": "credential-id",
20				"type": "string",
21				"value": "987654321987654321987654321",
22				"enum": [],
23				"createdAt": "2026-02-25 12:13:51",
24				"updatedAt": "2026-02-25 12:13:51"
25			}
26		]
27	}
28}

⚠️ 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_CORE_INVALID_TRADE_POLICY_ID400Os ids de política comercial não são permitidos.
UAPPI_INTEGRATION_ERP_NOT_FOUND404O ERP solicitado não foi encontrado.
UAPPI_INTEGRATION_ERP_CREDENTIAL_NOT_FOUND404A credencial de ERP solicitada não foi encontrada.
UAPPI_EXTERNAL_ERROR_NOT_MAPPED500A aplicação encontrou um erro não mapeado no MS external.uappi.
UAPPI_INTEGRATION_ERP_CREDENTIAL_IS_REQUIRED400A credencial de ERP (código) é requerida
UAPPI_INTEGRATION_ERP_CREDENTIAL_TYPE_IS_INVALID400O tipo da credencial de ERP (código) é requerida

Atualização de vínculo entre credenciais e armazéns

PUT /erps/credentials/link

Possibilita atualizar vínculo de credencial com armazém

Descrição

Endpoint responsável por cadastrar ou remover vínculo entre credenciais de ERP e armazéns 🔗

Permite associar ou desassociar armazéns a uma credencial de ERP, controlando como o estoque será integrado.

Essencial para ajustes operacionais e reorganizações de integração, garantindo que cada armazém esteja corretamente vinculado ao respectivo sistema de gestão.

⚠️ Atenção:

É muito importante notar que um armazém só pode ser ligado a 1 credencial de ERP mas as credenciais de ERP pode se conectar com vários armazéns.

Parâmetros

Headers Obrigatórios

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

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
linksarray✅Lista de vínculos entre credenciais de ERP e armazém
links.*.productStorageIdinteger✅Identificador do armazém a ser vinculado
links.*.productStorageExternalIdstring✅Identificador do armazém no ERP
links.*.erpStoreCredentialIdinteger✅Identificador da credencial de ERP a ser vinculado
links.*.actionstring✅Determina ação que deve ser realização (add/remove)

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/erps/credentials/link \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "links": [
6      {
7        "productStorageId": 1,
8        "productStorageExternalId": "628819394",
9        "erpStoreCredentialId": 1,
10        "action": "add"
11      }
12    ]
13  }'

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": [
4		{
5			"erpStoreCredentialId": 1,
6			"productStorageId": 1,
7			"productStorageExternalId": "628819394",
8			"action": "add"
9		}
10	]
11}

⚠️ 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_ERP_CREDENTIAL_NOT_FOUND404As credenciais de ERP solicitadas não foram encontradas (1, 2, 3).
UAPPI_STORE_STORAGE_NOT_FOUND404Os armazéns solicitados não foram encontrados (1, 2, 3).

Remoção de grupos de credenciais

DELETE /erps/credentials/{erpStoreCredentialId}

Possibilita a exclusão de um grupo de credenciais

Descrição

Endpoint responsável por excluir um grupo de credenciais de ERP 🗑️

Realiza a remoção da integração configurada, desativando a comunicação entre a loja e o sistema de gestão vinculado.

Indicado para cenários de descontinuidade de integração ou reconfiguração completa, garantindo controle sobre as credenciais ativas.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
erpStoreCredentialIdintegerSimIdentificador do grupo de credencial que deve ser excluído

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ Possíveis erros:

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_INTEGRATION_ERP_CREDENTIAL_NOT_FOUND",
6    "message": "The requested ERP credential was not found."
7  }
8}

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

Institucional

;