Documentação de Pedidos em ERP

Visão Geral

No contexto de ERP, o pedido é uma das principais entidades da integração, pois representa a formalização de uma venda realizada na loja 📦

---

Filas de Entrada e Saída:

Quando integrado, o pedido pode trafegar em dois sentidos: da plataforma para o ERP ou do ERP para a plataforma.

No fluxo de entrada, os pedidos recebidos são direcionados para uma fila de entrada, onde aguardam processamento interno antes de serem efetivamente persistidos ou atualizados no sistema.

Já no fluxo de saída, pedidos criados ou atualizados na loja podem ser enviados para uma fila de saída, responsável por organizar o envio estruturado dessas informações ao ERP.

---

Mapa de Pedido e Status de Pedido:

Outro ponto essencial são os mapas de pedido, que realizam a correspondência entre identificadores da loja e do ERP, assegurando que ambos os sistemas reconheçam o mesmo registro.

Além disso, o mapeamento de status de pedido é fundamental para manter o fluxo operacional alinhado, permitindo que alterações como “pago”, “enviado” ou “cancelado” sejam refletidas corretamente entre os ambientes 🔄

Listagem de histórico da integração de ERPs

GET /erps/orders/history

Retorna lista de histórico de integrações

Descrição

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

Aqui são exibidas as principais ações de processamento realizadas, bem como seus respectivos status, permitindo maior rastreabilidade da integração 📊

---

Tipos de ações retornadas

export – exportação de pedidos para o ERP
update-status – atualização de status do pedido
update-invoice – atualização de faturamento do pedido
update-shipping – atualização de frete
generate-invoice – geração de faturamento do pedido

---

O retorno também auxilia na identificação de falhas no processamento.

Em alguns casos, podem ser exibidas respostas da integração indicando erros como bad request ou unauthorized, facilitando a análise e correção do problema 🔎

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {token}	Token de autenticação

Campos de Condição Disponíveis

Campo	Tipo	Descrição
orderId	integer	Identificador do pedido em contexto Uappi
externalId	string	Identificador do pedido gerado na integração ERP
erpStoreCredentialId	integer	Identificador da credencial
action	string	Tipo da ação que foi processada no ERP
createdAt	stroing	Data de cadastro do histórico

Campos de Ordenação Disponíveis

Campo	Descrição
id	Identificador do histórico
createdAt	Data de cadastro do histórico

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 1,
5      "erpStoreCredentialId": 1,
6      "externalId": "",
7      "action": "export",
8      "request": null,
9      "response": "Bad Request",
10      "trace": null,
11      "createdAt": "2025-12-19 17:24:11",
12      "orderId": 1
13    },
14    {
15      "id": 2,
16      "erpStoreCredentialId": 2,
17      "externalId": "",
18      "action": "export",
19      "request": null,
20      "response": "Bad Request",
21      "trace": null,
22      "createdAt": "2026-01-05 20:47:08",
23      "orderId": 2
24    },
25  ],
26  "pagination": {
27    "limit": 10,
28    "offset": 0,
29    "pages": 1,
30    "registers": 10
31  }
32}
{
  "registers": [
    {
      "id": 1,
      "erpStoreCredentialId": 1,
      "externalId": "",
      "action": "export",
      "request": null,
      "response": "Bad Request",
      "trace": null,
      "createdAt": "2025-12-19 17:24:11",
      "orderId": 1
    },
    {
      "id": 2,
      "erpStoreCredentialId": 2,
      "externalId": "",
      "action": "export",
      "request": null,
      "response": "Bad Request",
      "trace": null,
      "createdAt": "2026-01-05 20:47:08",
      "orderId": 2
    },
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "pages": 1,
    "registers": 10
  }
}

Listagem de pedidos mapeados

GET /erps/maps/orders

Retorna lista de pedidos mapeados do ERP

Descrição

Endpoint responsável por retornar a lista completa de pedidos mapeados do ERP.

Esse retorno permite acompanhar os pedidos já processados pela integração, facilitando auditorias e validações entre a loja e o ERP 📦

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {userToken}	Token de autenticação

Campos de Condição Disponíveis

Campo	Tipo	Descrição
orderId	integer	Identificador do pedido em contexto Uappi
externalId	string	Identificador do pedido no ERP
erpStoreCredentialId	integer	Identificador da credencial de ERP na loja
createdAt	string	Data de cadastro do mapeamento

Campos de Ordenação Disponíveis

Campo	Descrição
createdAt	Data de cadastro do mapeamento

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "erpStoreCredentialId": 1,
7        "externalId": "123456789",
8        "createdAt": "2025-03-26 14:32:33",
9        "orderId": 1
10      },
11      {
12        "erpStoreCredentialId": 2,
13        "externalId": "987654321",
14        "createdAt": "2025-03-26 14:25:41",
15        "orderId": 2
16      }
17    ],
18    "pagination": {
19      "limit": 10,
20      "offset": 0,
21      "pages": 1,
22      "registers": 10
23    }
24  }
25}
{
  "status": true,
  "data": {
    "registers": [
      {
        "erpStoreCredentialId": 1,
        "externalId": "123456789",
        "createdAt": "2025-03-26 14:32:33",
        "orderId": 1
      },
      {
        "erpStoreCredentialId": 2,
        "externalId": "987654321",
        "createdAt": "2025-03-26 14:25:41",
        "orderId": 2
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 10
    }
  }
}

Exportação de pedidos para ERPs

POST /erps/orders/export

Possibilita exportação de pedidos da integração

Descrição

Endpoint responsável por exportar pedidos da integração com o ERP.

Essa operação envia os pedidos para processamento no sistema externo, garantindo a sincronização entre a loja e o ERP 🔄

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {userToken}	Token de autenticação

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`orderIds`	array	✅	lista de ids de pedidos que devem ser exportados
`orderIds.*`	integer	✅	id do pedido que será exportado

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ 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 Interno	Código Http	Descrição
UAPPI_INTEGRATION_ERP_CREDENTIAL_NOT_FOUND	404	A credencial de ERP solicitada não foi encontrada.
UAPPI_INTEGRATION_ERP_ORDER_ALREADY_MAPPED	400	Os pedidos solicitados (1, 2, 3) já estão mapeados e a operação não pode ser continuada.

Atualização de mapeamento dos pedidos

PUT /erps/{erpStoreCredentialId}/maps/orders

Possibilita atualização de pedidos mapeados

Descrição

Endpoint responsável por atualizar pedidos mapeados já processados pela integração com o ERP.

Essa operação permite adicionar ou remover informações previamente integradas, garantindo a consistência dos dados entre a loja e o ERP 🔄

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {token}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
erpStoreCredentialId	integer	Sim	Identificador da credencial de ERP onde o mapeamento será atualizado

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`maps`	array	✅	Lista de pedidos mapeados que devem ser inseridos ou removidos
`maps.*.orderId`	integer	✅	Identificador do pedido em contexto Uappi
`maps.*.externalId`	string	✅	Identificador do pedido no ERP
`maps.*.action`	string	✅	Ação que deve ser realizada (add, remove)

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/erps/{erpId}/maps/orders \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "maps": [
6      {
7        "orderId": 1,
8        "externalId": "123456789",
9        "action": "add"
10      },
11      {
12        "orderId": 2,
13        "externalId": "987654321",
14        "action": "remove"
15      }
16    ]
17  }'
curl --request PUT \
  --url {{MAIN_URL}}/erps/{erpId}/maps/orders \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "maps": [
      {
        "orderId": 1,
        "externalId": "123456789",
        "action": "add"
      },
      {
        "orderId": 2,
        "externalId": "987654321",
        "action": "remove"
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "orderId": 1,
6      "externalId": "123456789",
7      "action": "add"
8    },
9    {
10      "orderId": 2,
11      "externalId": "987654321",
12      "action": "remove"
13    }
14  ]
15}
{
  "status": true,
  "data": [
    {
      "orderId": 1,
      "externalId": "123456789",
      "action": "add"
    },
    {
      "orderId": 2,
      "externalId": "987654321",
      "action": "remove"
    }
  ]
}

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

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}
{
  "status": false,
  "data": {
    "code": 404,
    "errorCode": "UAPPI_INTEGRATION_ERP_CREDENTIAL_NOT_FOUND",
    "message": "The requested ERP credential was not found."
  }
}

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Documentação de Pedidos em ERP

Visão Geral

Listagem de histórico da integração de ERPs

Descrição

Parâmetros

Headers Obrigatórios

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

✅ Resposta de Sucesso

Listagem de pedidos mapeados

Descrição

Parâmetros

Headers Obrigatórios

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

✅ Resposta de Sucesso

Exportação de pedidos para ERPs

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Atualização de mapeamento dos pedidos

Descrição

Parâmetros

Headers Obrigatórios