Atualização de Rastreamento da Entrega

Descrição

Este endpoint permite a atualização em lote dos dados logísticos de entrega. O acesso exige o escopo de permissão ORDER_WRITE.

É a rota principal para informar códigos de rastreamento, URLs de acompanhamento das transportadoras e dados de logística reversa.

A sincronização dessas informações dispara eventos sistêmicos que podem notificar o cliente automaticamente sobre a postagem e o progresso da entrega, melhorando a experiência de compra.

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url https://sua-loja-uappi.com.br/api/v3/orders/shipping/tracking \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "orders": [
7      {
8        "orderId": 123,
9        "trackingCode": "AA123456789BR",
10        "trackingUrl": "https://correios.com.br/rastreio/AA123456789BR"
11      }
12    ]
13  }'

✅ Resposta de Sucesso

1[
2  {
3    "orderId": 123,
4    "trackingCode": "AA123456789BR",
5    "trackingUrl": "https://correios.com.br/rastreio/AA123456789BR",
6    "reserveLogisticsCode": null,
7    "error": null
8  }
9]

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

Criação de Remessas na Integração de Frete

Descrição

Este endpoint envia em lote as remessas para a integração de frete (ex.: Intelipost), criando a remessa no gateway. Apenas remessas cujo frete pertence a uma integração com gerenciamento de remessas podem ser enviados.

O status do pedido precisa estar entre os status configurados na credencial da integração para a criação de remessas.

O acesso exige o escopo de permissão ORDER_WRITE.

Como funciona

1. Cada remessa informada é validada antes de qualquer envio.

2. Se todas as remessas forem válidas, a operação é disparada de forma assíncrona e a resposta é devolvida imediatamente, apenas com o resultado da validação.

3. Se ao menos uma remessa for inválida, nenhuma remessa é enviada à integração de frete. Corrija as remessas com erro e envie a requisição novamente.

4. Após a criação, o código da remessa no gateway e os dados de rastreio (código e URL) são gravados no pedido. O status do pedido só é alterado quando o gateway indicar uma situação mapeada na credencial da integração (consulte os status disponíveis em GET /shipping/{shippingId}/order-status), e apenas se ela avançar a etapa do pedido. Um status filho da mesma etapa só é aplicado se for diferente do atual, e pedidos cancelados ou devolvidos não têm o status alterado.

Importante: O campo error vazio (null) indica que a remessa passou na validação, e não que a operação já foi concluída. O resultado real de cada chamada ao gateway de frete fica registrado na Listagem de Logs de Integração das Remessas.

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/orders/shipping/create \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "orderIds": [123, 124]
7  }'

✅ Resposta de Sucesso

A resposta é uma lista com um item para cada remessa informada.

1{
2  "status": true,
3  "data": [
4    {
5      "orderId": 123,
6      "error": null
7    },
8    {
9      "orderId": 124,
10      "error": null
11    }
12  ]
13}

Exemplo com remessa inválida

1{
2  "status": true,
3  "data": [
4    {
5      "orderId": 123,
6      "error": null
7    },
8    {
9      "orderId": 124,
10      "error": {
11        "errorCode": "UAPPI_STORE_ORDER_SHIPPING_ALREADY_INTEGRATED",
12        "code": 400,
13        "message": "The shipping of the requested order is already integrated and cannot be created again.",
14        "details": []
15      }
16    }
17  ]
18}

Neste exemplo, nenhuma remessa é enviada ao gateway, pois a remessa 124 é inválida.

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

Os erros abaixo são retornados no campo error do item da remessa correspondente.

Consulta de Remessas na Integração de Frete

Descrição

Este endpoint consulta em lote a situação das remessas já criadas no gateway de frete. Só podem ser consultados remessas já criadas na integração.

O acesso exige o escopo de permissão ORDER_WRITE.

Como funciona

1. Cada remessa informada é validada antes de qualquer envio.

2. Se todas as remessas forem válidas, a operação é disparada de forma assíncrona e a resposta é devolvida imediatamente, apenas com o resultado da validação.

3. Se ao menos uma remessa for inválida, nenhuma remessa é enviada à integração de frete. Corrija as remessas com erro e envie a requisição novamente.

4. Após a consulta, o rastreio (código e URL) é atualizado no pedido e o status do pedido é atualizado conforme a situação informada pelo gateway, usando o mapeamento de status configurado na credencial da integração (consulte os status disponíveis em GET /shipping/{shippingId}/order-status). Situações do gateway sem mapeamento não alteram o pedido.

5. O status só é trocado quando avança a etapa do pedido, e o mapeamento pode apontar para um status filho (por exemplo, um sub-status de "Enviado"): - o status nunca retrocede para uma etapa anterior; - dentro da mesma etapa, o pedido só troca para um status filho diferente do atual e nunca volta para o status pai; - pedidos cancelados ou devolvidos não têm o status alterado.

Importante: O campo error vazio (null) indica que a remessa passou na validação, e não que a operação já foi concluída. O resultado real de cada chamada ao gateway de frete fica registrado na Listagem de Logs de Integração das Remessas.

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/orders/shipping/consult \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "orderIds": [123, 124]
7  }'

✅ Resposta de Sucesso

A resposta é uma lista com um item para cada remessa informada.

1{
2  "status": true,
3  "data": [
4    {
5      "orderId": 123,
6      "error": null
7    },
8    {
9      "orderId": 124,
10      "error": null
11    }
12  ]
13}

Exemplo com remessa inválida

1{
2  "status": true,
3  "data": [
4    {
5      "orderId": 123,
6      "error": null
7    },
8    {
9      "orderId": 124,
10      "error": {
11        "errorCode": "UAPPI_STORE_ORDER_SHIPPING_NOT_INTEGRATED",
12        "code": 400,
13        "message": "The shipping of the requested order is not integrated yet.",
14        "details": []
15      }
16    }
17  ]
18}

Neste exemplo, nenhuma remessa é enviada ao gateway, pois a remessa 124 é inválida.

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

Os erros abaixo são retornados no campo error do item da remessa correspondente.

Cancelamento de Remessas na Integração de Frete

Descrição

Este endpoint cancela em lote as remessas já criadas no gateway de frete. Só podem ser cancelados remessas já criadas na integração.

O status do pedido precisa estar entre os status configurados na credencial da integração para o cancelamento de remessas.

O acesso exige o escopo de permissão ORDER_WRITE.

Como funciona

1. Cada remessa informada é validada antes de qualquer envio.

2. Se todas as remessas forem válidas, a operação é disparada de forma assíncrona e a resposta é devolvida imediatamente, apenas com o resultado da validação.

3. Se ao menos uma remessa for inválida, nenhuma remessa é enviada à integração de frete. Corrija as remessas com erro e envie a requisição novamente.

4. Após o cancelamento, o resultado da chamada ao gateway fica registrado no log de integração da remessa.

Importante: O campo error vazio (null) indica que a remessa passou na validação, e não que a operação já foi concluída. O resultado real de cada chamada ao gateway de frete fica registrado na Listagem de Logs de Integração das Remessas.

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/orders/shipping/cancel \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "orderIds": [123, 124]
7  }'

✅ Resposta de Sucesso

A resposta é uma lista com um item para cada remessa informada.

1{
2  "status": true,
3  "data": [
4    {
5      "orderId": 123,
6      "error": null
7    },
8    {
9      "orderId": 124,
10      "error": null
11    }
12  ]
13}

Exemplo com remessa inválida

1{
2  "status": true,
3  "data": [
4    {
5      "orderId": 123,
6      "error": null
7    },
8    {
9      "orderId": 124,
10      "error": {
11        "errorCode": "UAPPI_STORE_ORDER_SHIPPING_NOT_INTEGRATED",
12        "code": 400,
13        "message": "The shipping of the requested order is not integrated yet.",
14        "details": []
15      }
16    }
17  ]
18}

Neste exemplo, nenhuma remessa é enviada ao gateway, pois a remessa 124 é inválida.

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

Os erros abaixo são retornados no campo error do item da remessa correspondente.

Listagem de Logs de Integração das Remessas

Descrição

Este endpoint lista o histórico de integração das remessas com os gateways de frete.

Cada registro representa uma chamada feita ao gateway (ou um evento recebido dele) e permite acompanhar o resultado das operações de criação, consulta e cancelamento, inclusive as que ocorrem automaticamente. O acesso exige o escopo de permissão ORDER_READ.

Os campos request e response são gravados com os dados pessoais mascarados (nome, e-mail, telefone e documentos).

Importante: Os registros são mantidos por 3 meses. Registros mais antigos são removidos automaticamente.

Operaçõ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}}/orders/shipping/logs?orderId=123&operation=create" \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 10,
7        "orderId": 123,
8        "operation": "create",
9        "success": true,
10        "url": "https://api.intelipost.com.br/api/v1/shipment_order",
11        "httpStatus": 200,
12        "request": {
13          "order_number": "ABC123-123"
14        },
15        "response": {
16          "status": "OK"
17        },
18        "userName": "Administrador",
19        "userEmail": "admin@uappi.com.br",
20        "createdAt": "2026-10-14 10:00:00"
21      }
22    ],
23    "pagination": {
24      "limit": 10,
25      "offset": 0,
26      "pages": 1,
27      "registers": 1
28    }
29  }
30}

Rastreio de Pedido

Descrição

Consulta o rastreio em tempo real de um pedido (remessa) percorrendo a canalização completa: store.uappi → integration.uappi → external.uappi → API da transportadora.

O acesso exige o escopo de permissão ORDER_READ.

O campo error da resposta indica se o rastreio não pôde ser obtido — quando não-nulo, os demais campos de rastreio serão null ou []. Consulte a seção de erros para os valores possíveis.

Parâmetros

Headers Obrigatórios

Parâmetros de URL

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "orderId": 123,
3  "trackingCode": "AA123456789BR",
4  "trackingUrl": "https://correios.com.br/rastreio/AA123456789BR",
5  "status": "em_transito",
6  "events": [
7    {
8      "date": "2026-05-01T10:30:00",
9      "description": "Objeto em trânsito",
10      "location": "São Paulo / SP"
11    }
12  ],
13  "invoiceNumber": "000123",
14  "invoiceKey": "35260412345678901234550010001234561234567890",
15  "invoiceSerie": "1",
16  "error": null
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.

Erros de domínio (pedido sem código de rastreio, integração não configurada etc.) são retornados com HTTP 200 — o campo error no corpo indica a falha específica.