🚛 Documentação de Tipos de Carga

📋 Visão Geral

Os Tipos de Carga são as modalidades de transporte cadastradas na plataforma para classificar as opções de envio disponíveis na loja — como transporte rodoviário, aéreo ou marítimo.

Cada tipo de carga agrupa tabelas de frete e produtos sob uma mesma categoria logística, permitindo que a loja organize suas opções de envio de forma estruturada e escalável.

Todas as operações exigem autenticação via Bearer token no cabeçalho Authorization.

1GET /api/v3/shipping/cargo-type
2Authorization: Bearer SEU_TOKEN_AQUI

🔄 Entidades Envolvidas

Tipo de Carga (ShippingCargoType)

Representa a modalidade de transporte cadastrada na loja. Cada registro contém:

• id — identificador único do tipo de carga.
• name — nome de identificação do tipo de carga, com limite de 255 caracteres. É o único campo editável e obrigatório nas operações de criação e atualização.
• shippingTableQuantity — quantidade de tabelas de frete atualmente vinculadas ao tipo de carga. Calculado na listagem com base no relacionamento direto no banco de dados.
• productQuantity — quantidade de produtos associados ao tipo de carga. Obtido via consulta ao serviço de loja (store.uappi) e enriquece a listagem principal.
• createdAt — data de criação do registro.
• updatedAt — data da última atualização do registro.

Listagem simplificada (/all)

O endpoint GET /all retorna um mapa simples de id => nome de todos os modais cadastrados na loja, sem paginação e sem campos de contagem.

É ideal para popular dropdowns e seletores no painel administrativo com custo mínimo de resposta.

📌 Notas e Considerações

• O escopo SHIPPING_CARGO_TYPE_READ é exigido em todas as operações de leitura (listagem paginada e listagem simplificada). Operações de escrita — criação, atualização e remoção — requerem adicionalmente o escopo SHIPPING_CARGO_TYPE_WRITE.
• A listagem principal (GET /) suporta busca por name e ordenação pelos campos id, name e createdAt. Filtros adicionais não são aceitos.
• A operação de criação retorna o registro criado com status HTTP 201; a atualização retorna o registro atualizado com status 200.
• A remoção de um tipo de carga opera diretamente no banco de dados — o registro é excluído de forma permanente e a operação retorna true em caso de sucesso.
• Os campos shippingTableQuantity e productQuantity estão presentes apenas na listagem paginada (GET /); a listagem simplificada (GET /all) retorna exclusivamente id e name.

📋 Listagem de Tipos de Carga

📄 Descrição

Endpoint utilizado para listar os tipos de carga cadastrados na loja, com suporte a paginação, filtros e ordenação.

Cada registro retornado inclui a quantidade de tabelas de frete vinculadas ao tipo de carga e a quantidade de produtos associados, enriquecendo a visão operacional sem a necessidade de consultas adicionais.

Requer o escopo SHIPPING_CARGO_TYPE_READ.

📋 Parâmetros

🏷️ Headers Obrigatórios

🔍 Campos de Condição Disponíveis

🔃 Campos de Ordenação Disponíveis

💡 Exemplo de Requisição

> Nota: esta API aceita corpo JSON em requisições GET, seguindo a convenção da plataforma. Utilize o header Content-Type: application/json e envie os parâmetros no corpo da requisição.

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/cargo-type \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "limit": 10,
7    "offset": 0
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "name": "Rodoviário",
8        "shippingTableQuantity": 4,
9        "productQuantity": 120,
10        "createdAt": "2025-01-10 09:00:00",
11        "updatedAt": "2025-03-15 14:30:00"
12      },
13      {
14        "id": 2,
15        "name": "Aéreo",
16        "shippingTableQuantity": 2,
17        "productQuantity": 35,
18        "createdAt": "2025-01-12 10:15:00",
19        "updatedAt": "2025-02-20 08:45:00"
20      }
21    ],
22    "pagination": {
23      "limit": 10,
24      "offset": 0,
25      "pages": 1,
26      "registers": 2
27    }
28  }
29}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

📦 Listagem Completa de Tipos de Carga

📄 Descrição

Endpoint utilizado para obter todos os tipos de carga da loja em um formato compacto de id => nome, sem paginação e sem os dados completos de cada registro.

Requer o escopo SHIPPING_CARGO_TYPE_READ.

Formato de retorno

A resposta é um objeto simples onde cada chave é o ID do tipo de carga (como string) e o valor é o nome correspondente.

Esse formato é ideal para popular dropdowns, seletores e autocompletes no painel administrativo, sem o custo de trafegar todos os campos de cada tipo de carga.

Sem filtros e sem paginação

Este endpoint não aceita parâmetros de filtro ou ordenação — retorna sempre todos os registros da loja.

Para listagens com filtros, paginação e dados completos, utilize o endpoint GET /shipping/cargo-type.

📋 Parâmetros

🏷️ Headers Obrigatórios

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/cargo-type/all \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "1": "Transportadora",
3  "2": "Motoboy",
4  "3": "Retirada na Loja"
5}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

➕ Criar Tipo de Carga

📄 Descrição

Endpoint responsável por criar um novo tipo de carga na loja. O modal representa uma categoria de transporte (ex.: aéreo, rodoviário, expresso) que pode ser associada a tabelas de frete e produtos.

Requer o escopo SHIPPING_CARGO_TYPE_WRITE. Após a criação, a resposta retorna o registro completo com os contadores de vínculos já calculados.

📋 Parâmetros

🏷️ Headers Obrigatórios

📝 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/shipping/cargo-type \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "Aéreo"
7  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "id": 1,
3  "name": "Aéreo",
4  "shippingTableQuantity": 0,
5  "productQuantity": 0,
6  "createdAt": "2026-05-14 10:00:00",
7  "updatedAt": "2026-05-14 10:00:00"
8}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

✏️ Atualizar Tipo de Carga

📄 Descrição

Endpoint responsável por atualizar um tipo de carga existente na loja, identificado pelo shippingCargoTypeId na URL.

A operação substitui integralmente os dados do registro — todos os campos obrigatórios devem ser enviados mesmo que não tenham sido alterados.

Requer o escopo SHIPPING_CARGO_TYPE_WRITE. Após a atualização, a resposta retorna o registro completo com os contadores de vínculos já calculados.

📋 Parâmetros

🏷️ Headers Obrigatórios

🔑 Parâmetros da URL

📝 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/shipping/cargo-type/1 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "Rodoviário"
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "name": "Rodoviário",
4  "shippingTableQuantity": 2,
5  "productQuantity": 5,
6  "createdAt": "2026-05-10 08:00:00",
7  "updatedAt": "2026-05-14 10:30:00"
8}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🗑️ Remover Tipo de Carga

📄 Descrição

Endpoint responsável por remover permanentemente um tipo de carga, identificado pelo shippingCargoTypeId na URL.

A remoção é permanente e não pode ser desfeita. Quando bem-sucedida, o campo data da resposta retorna true.

Requer o escopo SHIPPING_CARGO_TYPE_WRITE.

📋 Parâmetros

🏷️ Headers Obrigatórios

🔑 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/shipping/cargo-type/1 \
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

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.