🚚 Documentação de Transportadoras

📋 Visão Geral

As Transportadoras são as empresas de frete cadastradas na plataforma e vinculadas à loja.

Cada transportadora agrupa seus dados de identificação, contato e documentação, além de manter um ou mais endereços operacionais e vínculos com as tabelas de frete associadas.

O gerenciamento de transportadoras permite que a loja mantenha um cadastro estruturado das empresas responsáveis pelas entregas, servindo como base para a configuração de credenciais e cálculo de fretes.

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

1GET /api/v3/shipping/carrier
2Authorization: Bearer SEU_TOKEN_AQUI

🔄 Entidades Envolvidas

Transportadora (ShippingCarrier)

Representa a empresa de frete cadastrada na loja.

• id — identificador único da transportadora.
• code — código de identificação interna da transportadora. Campo obrigatório com limite de 255 caracteres.
• name — nome de exibição da transportadora. Campo obrigatório com limite de 255 caracteres.
• corporateName — razão social da transportadora. Campo opcional, com limite de 255 caracteres.
• phone — telefone de contato. Campo opcional, validado pelo formato de telefone aceito pela plataforma.
• email — endereço de e-mail de contato. Campo opcional, deve ser um e-mail válido com até 255 caracteres.
• document — número do documento de identificação. Campo opcional, exige o preenchimento de documentType quando informado.
• documentType — tipo do documento informado. Campo opcional, aceita os valores cnpj, document1, document2 ou document3. Exige o preenchimento de document quando informado.
• addresses — lista de endereços cadastrados para a transportadora.
• shippingTableIds — lista de IDs das tabelas de frete vinculadas à transportadora.
• createdAt — data de criação do registro.
• updatedAt — data da última atualização do registro.

Endereço da Transportadora (ShippingCarrierAddress)

Sub-recurso gerenciado por meio do caminho /{shippingCarrierId}/address.

• id — identificador único do endereço.
• shippingCarrierId — referência à transportadora proprietária do endereço.
• countryCode — código do país com exatamente 3 caracteres, validado pela regra de países aceitos na plataforma.
• stateCode — código do estado com até 10 caracteres, validado de acordo com o countryCode informado.
• zipCode — CEP ou código postal. Campo obrigatório com limite de 100 caracteres.
• address — logradouro. Campo obrigatório com limite de 100 caracteres.
• number — número do endereço. Campo obrigatório com limite de 100 caracteres.
• city — cidade. Campo obrigatório com limite de 100 caracteres.
• district — bairro. Campo obrigatório com limite de 100 caracteres.

Listagem simplificada (/all)

O endpoint GET /all retorna um mapa simples de id => nome de todas as transportadoras cadastradas na loja, sem paginação.

O nome exibido concatena o code e o name da transportadora para facilitar a identificação.

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

📌 Notas e Considerações

• O escopo SHIPPING_CARRIER_READ é exigido em todas as operações de leitura — listagem paginada, detalhe e listagem simplificada. Operações de escrita requerem adicionalmente o escopo SHIPPING_CARRIER_WRITE.
• Os campos document e documentType são mutuamente dependentes: sempre que um for informado, o outro também deve ser preenchido.
• A remoção de uma transportadora exclui o registro de forma permanente e, em caso de sucesso, dispara automaticamente um evento de notificação (delete-carrier) para os serviços dependentes — garantindo a consistência das tabelas de frete e demais vínculos.
• Os endereços da transportadora são gerenciados como sub-recurso: criação e atualização retornam o endereço persistido; a remoção retorna true em caso de sucesso.
• A criação de transportadora retorna o registro criado com status HTTP 201; a atualização retorna o registro atualizado com status 200.

📋 Listagem de Transportadoras

📄 Descrição

Endpoint utilizado para listar as transportadoras cadastradas na loja, com suporte a paginação, filtros e ordenação.

Por padrão, cada registro retorna os campos principais da transportadora. Campos opcionais como addresses (endereços vinculados) e shippingTableIds (IDs de tabelas de frete) podem ser solicitados via parâmetro fields.

Requer o escopo SHIPPING_CARRIER_READ.

📋 Parâmetros

🏷️ Headers Obrigatórios

📦 Campos Disponíveis (fields)

Os campos abaixo são opcionais e devem ser solicitados explicitamente via parâmetro fields.

🔍 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/carrier \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "limit": 10,
7    "offset": 0,
8    "fields": ["addresses"]
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "code": "TRANSP-001",
8        "name": "Transportes Rápidos",
9        "corporateName": "Transportes Rápidos Ltda",
10        "email": "contato@transportesrapidos.com.br",
11        "phone": "11999990001",
12        "document": "12.345.678/0001-90",
13        "addresses": [
14          {
15            "id": 10,
16            "shippingCarrierId": 1,
17            "zipCode": "01310-100",
18            "address": "Avenida Paulista",
19            "number": "1000",
20            "district": "Bela Vista",
21            "city": "São Paulo",
22            "stateCode": "SP"
23          }
24        ],
25        "shippingTableIds": null,
26        "createdAt": "2025-02-05 08:00:00",
27        "updatedAt": "2025-04-10 11:20:00"
28      },
29      {
30        "id": 2,
31        "code": "TRANSP-002",
32        "name": "Logística Express",
33        "corporateName": "Logística Express S/A",
34        "email": "operacoes@logisticaexpress.com.br",
35        "phone": "11988880002",
36        "document": "98.765.432/0001-11",
37        "addresses": [],
38        "shippingTableIds": null,
39        "createdAt": "2025-03-01 10:30:00",
40        "updatedAt": "2025-03-01 10:30:00"
41      }
42    ],
43    "pagination": {
44      "limit": 10,
45      "offset": 0,
46      "pages": 1,
47      "registers": 2
48    }
49  }
50}

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

📄 Descrição

Endpoint utilizado para obter todas as transportadoras da loja em um formato compacto de id => "Nome (CÓDIGO)", sem paginação e sem os dados completos de cada registro.

Requer o escopo SHIPPING_CARRIER_READ.

Formato de retorno

A resposta é um objeto simples onde cada chave é o ID da transportadora (como string) e o valor é o nome concatenado com o código entre parênteses.

O campo name exibido já contém o code da transportadora ao final, no padrão "Nome Fantasia (CODIGO)" — por exemplo: "Transportes Rápidos (TRANSP-001)".

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

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/carrier.

📋 Parâmetros

🏷️ Headers Obrigatórios

💡 Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "1": "Transportes Rápidos (TRANSP-001)",
5    "2": "Logística Express (LOG-EXP-002)",
6    "3": "Entrega Veloz (ENV-003)"
7  }
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.

🔍 Detalhe de Transportadora

📄 Descrição

Endpoint utilizado para buscar os dados completos de uma transportadora pelo seu identificador único (shippingCarrierId).

O campo addresses é sempre retornado neste endpoint, contendo todos os endereços vinculados à transportadora. O campo shippingTableIds não é carregado nesta rota e retorna null.

Requer o escopo SHIPPING_CARRIER_READ.

📋 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "code": "TRANSP-001",
6    "name": "Transportes Rápidos",
7    "corporateName": "Transportes Rápidos Ltda",
8    "email": "contato@transportesrapidos.com.br",
9    "phone": "11999990001",
10    "document": "12.345.678/0001-90",
11    "addresses": [
12      {
13        "id": 10,
14        "shippingCarrierId": 1,
15        "zipCode": "01310-100",
16        "address": "Avenida Paulista",
17        "number": "1000",
18        "district": "Bela Vista",
19        "city": "São Paulo",
20        "stateCode": "SP"
21      }
22    ],
23    "shippingTableIds": null,
24    "createdAt": "2025-02-05 08:00:00",
25    "updatedAt": "2025-04-10 11:20:00"
26  }
27}

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

📄 Descrição

Endpoint responsável por criar uma nova transportadora na loja. O registro representa uma empresa de transporte que pode ser associada a tabelas de frete e endereços de coleta.

O campo code deve ser único por loja — caso o código já esteja em uso, a API retorna o erro UAPPI_INTEGRATION_SHIPPING_INVALID_CARRIER_CODE com HTTP 400.

Os campos document e documentType são mutuamente dependentes: se um for informado, o outro também se torna obrigatório. O campo documentType aceita os valores cnpj, document1, document2 ou document3 e é utilizado apenas para validação — ele não é armazenado no registro final.

Requer os escopos SHIPPING_CARRIER_READ e SHIPPING_CARRIER_WRITE. Em caso de sucesso, retorna o registro criado com HTTP 201.

📋 Parâmetros

🏷️ Headers Obrigatórios

📝 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/shipping/carrier \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "Logística Expressa Sul",
7    "code": "LOG-SUL-001",
8    "corporateName": "Logística Expressa Sul Ltda",
9    "phone": "+55519999900011",
10    "email": "contato@logisticasul.com.br",
11    "documentType": "cnpj",
12    "document": "98.765.432/0001-10"
13  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 42,
5    "code": "LOG-SUL-001",
6    "name": "Logística Expressa Sul",
7    "corporateName": "Logística Expressa Sul Ltda",
8    "email": "contato@logisticasul.com.br",
9    "phone": "+55519999900011",
10    "document": "98.765.432/0001-10",
11    "addresses": [],
12    "shippingTableIds": [],
13    "createdAt": "2026-05-15 09:00:00",
14    "updatedAt": "2026-05-15 09:00:00"
15  }
16}

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

📄 Descrição

Endpoint responsável por atualizar os dados de uma transportadora existente identificada pelo parâmetro shippingCarrierId na URL.

As mesmas regras de validação do cadastro se aplicam. O campo code deve ser único por loja, excluindo o registro atual da verificação — caso o código já esteja em uso por outra transportadora, a API retorna o erro UAPPI_INTEGRATION_SHIPPING_INVALID_CARRIER_CODE com HTTP 400.

Os campos document e documentType são mutuamente dependentes: se um for informado, o outro também se torna obrigatório. O campo documentType aceita os valores cnpj, document1, document2 ou document3 e é utilizado apenas para validação — ele não é armazenado no registro final.

Requer os escopos SHIPPING_CARRIER_READ e SHIPPING_CARRIER_WRITE. Em caso de sucesso, retorna o registro atualizado com HTTP 200. Os campos addresses e shippingTableIds sempre retornam como [] nesta resposta.

📋 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/carrier/42 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "Transportes Rápidos Norte",
7    "code": "TRN-002",
8    "corporateName": "Transportes Rápidos Norte Ltda",
9    "phone": "+55519999900011",
10    "email": "contato@transportesnorte.com.br",
11    "documentType": "cnpj",
12    "document": "12.345.678/0001-99"
13  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 42,
5    "code": "TRN-002",
6    "name": "Transportes Rápidos Norte",
7    "corporateName": "Transportes Rápidos Norte Ltda",
8    "email": "contato@transportesnorte.com.br",
9    "phone": "+55519999900011",
10    "document": "12.345.678/0001-99",
11    "addresses": [],
12    "shippingTableIds": [],
13    "createdAt": "2026-03-10 08:30:00",
14    "updatedAt": "2026-05-15 14:45:00"
15  }
16}

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

📄 Descrição

Endpoint responsável por remover permanentemente uma transportadora, identificada pelo shippingCarrierId na URL.

Após a exclusão bem-sucedida, o evento delete-carrier é disparado automaticamente para os serviços dependentes. Tabelas de frete e demais vínculos associados à transportadora são atualizados sem necessidade de ação adicional.

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

Requer os escopos SHIPPING_CARRIER_READ e SHIPPING_CARRIER_WRITE.

📋 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

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