📍 Documentação de Pontos de Retirada

📋 Visão Geral

Os Pontos de Retirada representam locais físicos cadastrados na loja onde o cliente pode optar por retirar seu pedido pessoalmente, em vez de recebê-lo via entrega convencional.

Cada ponto armazena informações completas de identificação, endereço, coordenadas geográficas e horário de funcionamento — dados que o front-end pode utilizar para exibir ao cliente durante o checkout ou em páginas de localização de lojas.

O vínculo entre um ponto de retirada e as tabelas de frete determina em quais opções de envio ele aparecerá disponível.

🔄 Entidades Envolvidas

Ponto de retirada (PickupPoint)

Representa o local físico cadastrado.

Os campos de endereço seguem o padrão da plataforma: countryCode em formato ISO 3166-1 alpha-3 (BRA, USA...) e stateCode no formato XX-YY (BR-SP, BR-RJ...).

O campo openingHours é uma string livre — pode ser um texto simples ou um JSON serializado com os turnos de funcionamento. A loja define o formato conforme sua necessidade de exibição.

O campo active controla se o ponto está disponível para seleção no checkout. Pontos inativos não são oferecidos ao cliente, mas permanecem cadastrados.

O campo linkedShippingTables lista os IDs das tabelas de frete às quais o ponto está vinculado. Esse vínculo determina em quais opções de frete o ponto de retirada será exibido.

Listagem simplificada (/all)

O endpoint /all retorna um mapa simples de id => nome de todos os pontos cadastrados, sem paginação.

É ideal para popular dropdowns e seletores no painel administrativo, sem precisar carregar os dados completos de cada ponto.

Vínculo com tabelas de frete (/link)

O endpoint /link permite adicionar ou remover o vínculo entre um ponto de retirada e uma tabela de frete em uma única requisição em lote.

Cada item do array informa shippingTableId, shippingPickupPointId e a action desejada: add para vincular ou remove para desvincular.

📌 Notas e Considerações

O escopo SHIPPING_PICKUP_POINT_READ é exigido em todas as operações de leitura. Operações de escrita — criação, atualização, vínculo e remoção — requerem o escopo SHIPPING_OPTION_WRITE.
O campo complement é obrigatório estar presente no corpo da requisição, mas pode ser enviado como string vazia. Os demais campos de endereço são todos obrigatórios.
O campo phone é validado pelo formato de telefone da plataforma — deve incluir o código de país com o prefixo + (ex: +5511999999999).
Alterações em pontos de retirada e nos vínculos com tabelas invalidam o cache de cotação de frete (PRODUCT_QUOTE) automaticamente.
A remoção de um ponto de retirada não é reversível — todos os vínculos com tabelas de frete são removidos junto com o registro.

📋 Listagem de Pontos de Retirada

GET /shipping/pickup-points

Retorna a listagem paginada de pontos de retirada cadastrados na loja

📄 Descrição

Endpoint utilizado para listar todos os pontos de retirada da loja, com suporte a paginação, filtros por condição e ordenação.

Requer o escopo SHIPPING_PICKUP_POINT_READ.

Resposta paginada

A listagem retorna os registros dentro de data.registers, acompanhados do objeto data.pagination com informações de limite, offset, total de páginas e total de registros.

Campo linkedShippingTables

Cada ponto retorna o array linkedShippingTables com os IDs das tabelas de frete às quais ele está vinculado.

Para vincular ou desvincular tabelas, utilize o endpoint PUT /shipping/pickup-points/link.

📋 Parâmetros

🏷️ Headers Obrigatórios

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

🔍 Campos de Condição Disponíveis

Campo	Tipo	Descrição
id	integer	ID do ponto de retirada
name	string	Nome do ponto de retirada
city	string	Cidade do ponto de retirada
stateCode	string	Código do estado (ex: `BR-SP`)
countryCode	string	Código do país ISO alpha-3 (ex: `BRA`)
zipCode	string	CEP do ponto de retirada
active	boolean	Status de ativação do ponto

🔃 Campos de Ordenação Disponíveis

Campo	Descrição
id	ID do ponto de retirada
name	Nome do ponto de retirada

💡 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/pickup-points \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "fields": [],
7    "order": [],
8    "condition": {
9      "type": "AND",
10      "conditions": []
11    }
12  }'
curl --request GET \
  --url {{MAIN_URL}}/shipping/pickup-points \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "fields": [],
    "order": [],
    "condition": {
      "type": "AND",
      "conditions": []
    }
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "name": "Loja Centro - SP",
8        "phone": "+5511999990001",
9        "address": "Rua das Flores",
10        "number": "100",
11        "district": "Centro",
12        "city": "São Paulo",
13        "countryCode": "BRA",
14        "stateCode": "BR-SP",
15        "zipCode": "01310100",
16        "complement": "",
17        "latitude": "-23.550520",
18        "longitude": "-46.633308",
19        "openingHours": "Segunda a Sexta: 08:00 às 18:00",
20        "active": true,
21        "linkedShippingTables": [3, 7, 20]
22      },
23      {
24        "id": 2,
25        "name": "Loja Campinas",
26        "phone": "+5519988880002",
27        "address": "Avenida Brasil",
28        "number": "500",
29        "district": "Jardim Guanabara",
30        "city": "Campinas",
31        "countryCode": "BRA",
32        "stateCode": "BR-SP",
33        "zipCode": "13073320",
34        "complement": "Sala 12",
35        "latitude": "-22.905530",
36        "longitude": "-47.062920",
37        "openingHours": "Segunda a Sábado: 09:00 às 17:00",
38        "active": false,
39        "linkedShippingTables": []
40      }
41    ],
42    "pagination": {
43      "limit": 10,
44      "offset": 0,
45      "pages": 1,
46      "registers": 2
47    }
48  }
49}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 1,
        "name": "Loja Centro - SP",
        "phone": "+5511999990001",
        "address": "Rua das Flores",
        "number": "100",
        "district": "Centro",
        "city": "São Paulo",
        "countryCode": "BRA",
        "stateCode": "BR-SP",
        "zipCode": "01310100",
        "complement": "",
        "latitude": "-23.550520",
        "longitude": "-46.633308",
        "openingHours": "Segunda a Sexta: 08:00 às 18:00",
        "active": true,
        "linkedShippingTables": [3, 7, 20]
      },
      {
        "id": 2,
        "name": "Loja Campinas",
        "phone": "+5519988880002",
        "address": "Avenida Brasil",
        "number": "500",
        "district": "Jardim Guanabara",
        "city": "Campinas",
        "countryCode": "BRA",
        "stateCode": "BR-SP",
        "zipCode": "13073320",
        "complement": "Sala 12",
        "latitude": "-22.905530",
        "longitude": "-47.062920",
        "openingHours": "Segunda a Sábado: 09:00 às 17:00",
        "active": false,
        "linkedShippingTables": []
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 2
    }
  }
}

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

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_PICKUP_POINT_READ`.

🗺️ Listagem Simplificada de Pontos de Retirada

GET /shipping/pickup-points/all

Retorna um mapa simplificado de todos os pontos de retirada da loja no formato id => nome, sem paginação

📄 Descrição

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

Requer o escopo SHIPPING_PICKUP_POINT_READ.

Formato de retorno

A resposta é um objeto simples onde cada chave é o ID do ponto de retirada (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 endereço, coordenadas e vínculos de cada ponto.

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/pickup-points.

📋 Parâmetros

🏷️ Headers Obrigatórios

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

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/pickup-points/all \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"
curl --request GET \
  --url {{MAIN_URL}}/shipping/pickup-points/all \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "1": "Loja Centro - SP",
5    "2": "Loja Campinas",
6    "3": "Loja Santos",
7    "16": "Uappi Birigui",
8    "17": "Uappi Canoas"
9  }
10}
{
  "status": true,
  "data": {
    "1": "Loja Centro - SP",
    "2": "Loja Campinas",
    "3": "Loja Santos",
    "16": "Uappi Birigui",
    "17": "Uappi Canoas"
  }
}

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

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_PICKUP_POINT_READ`.

🔍 Detalhe de Ponto de Retirada

GET /shipping/pickup-points/{pickupPointId}

Retorna os dados completos de um ponto de retirada a partir do seu ID

📄 Descrição

Endpoint utilizado para obter os dados completos de um ponto de retirada específico a partir do seu identificador.

Requer o escopo SHIPPING_PICKUP_POINT_READ.

Dados retornados

A resposta inclui todas as informações do ponto: identificação, endereço completo, coordenadas geográficas, horário de funcionamento, status de ativação e os IDs das tabelas de frete vinculadas.

HTTP Status de sucesso

Este endpoint retorna HTTP 201 em caso de sucesso — comportamento específico desta rota que difere do padrão 200 das demais leituras.

📋 Parâmetros

🏷️ Headers Obrigatórios

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

🔗 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
pickupPointId	integer	✅	ID único do ponto de retirada

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/shipping/pickup-points/1 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"
curl --request GET \
  --url {{MAIN_URL}}/shipping/pickup-points/1 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "name": "Loja Centro - SP",
6    "phone": "+5511999990001",
7    "address": "Rua das Flores",
8    "number": "100",
9    "district": "Centro",
10    "city": "São Paulo",
11    "countryCode": "BRA",
12    "stateCode": "BR-SP",
13    "zipCode": "01310100",
14    "complement": "",
15    "latitude": "-23.550520",
16    "longitude": "-46.633308",
17    "openingHours": "Segunda a Sexta: 08:00 às 18:00",
18    "active": true,
19    "linkedShippingTables": [3, 7, 20]
20  }
21}
{
  "status": true,
  "data": {
    "id": 1,
    "name": "Loja Centro - SP",
    "phone": "+5511999990001",
    "address": "Rua das Flores",
    "number": "100",
    "district": "Centro",
    "city": "São Paulo",
    "countryCode": "BRA",
    "stateCode": "BR-SP",
    "zipCode": "01310100",
    "complement": "",
    "latitude": "-23.550520",
    "longitude": "-46.633308",
    "openingHours": "Segunda a Sexta: 08:00 às 18:00",
    "active": true,
    "linkedShippingTables": [3, 7, 20]
  }
}

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

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_PICKUP_POINT_READ`.
UAPPI_AUTH_NOT_FOUND	404	❌ Nenhum ponto de retirada encontrado com o ID informado.

➕ Criar Ponto de Retirada

POST /shipping/pickup-points

Cria um novo ponto de retirada na loja

📄 Descrição

Endpoint responsável por cadastrar um novo ponto de retirada na loja.

Requer o escopo SHIPPING_OPTION_WRITE.

Campos de endereço

Todos os campos de endereço são obrigatórios, exceto complement — que deve estar presente no corpo mas pode ser enviado como string vazia.

O countryCode segue o padrão ISO 3166-1 alpha-3 (BRA, USA...) e o stateCode segue o formato XX-YY (BR-SP, BR-RJ...).

Campo phone

O telefone é validado pelo formato da plataforma e deve incluir o código do país com o prefixo + (ex: +5511999999999).

Campo openingHours

É uma string livre — pode ser um texto simples ou um JSON serializado com os turnos de funcionamento.

A loja define o formato conforme sua necessidade de exibição no front-end.

Campo active

Controla se o ponto estará disponível para seleção no checkout imediatamente após a criação.

Cache

Ao criar um ponto de retirada, o cache de cotação de frete (PRODUCT_QUOTE) é invalidado automaticamente.

📋 Parâmetros

🏷️ Headers Obrigatórios

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

📋 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
name	string	✅	Nome do ponto de retirada (máximo 100 caracteres)
phone	string	✅	Telefone com código de país (ex: `+5511999999999`)
countryCode	string	✅	Código do país ISO alpha-3 (ex: `BRA`)
stateCode	string	✅	Código do estado (ex: `BR-SP`, máximo 10 caracteres)
city	string	✅	Cidade (máximo 50 caracteres)
district	string	✅	Bairro (máximo 50 caracteres)
address	string	✅	Logradouro (máximo 100 caracteres)
number	string	✅	Número do endereço (máximo 10 caracteres)
zipCode	string	✅	CEP (máximo 15 caracteres)
complement	string	✅ presente	Complemento — pode ser string vazia (máximo 255 caracteres)
latitude	numeric	✅	Latitude do ponto geográfico
longitude	numeric	✅	Longitude do ponto geográfico
openingHours	string	✅	Horário de funcionamento (texto livre ou JSON serializado)
active	boolean	✅	Define se o ponto está disponível no checkout

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/shipping/pickup-points \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "Loja Centro - SP",
7    "phone": "+5511999990001",
8    "countryCode": "BRA",
9    "stateCode": "BR-SP",
10    "city": "São Paulo",
11    "district": "Centro",
12    "address": "Rua das Flores",
13    "number": "100",
14    "zipCode": "01310100",
15    "complement": "",
16    "latitude": -23.55052,
17    "longitude": -46.633308,
18    "openingHours": "Segunda a Sexta: 08:00 às 18:00",
19    "active": true
20  }'
curl --request POST \
  --url {{MAIN_URL}}/shipping/pickup-points \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Loja Centro - SP",
    "phone": "+5511999990001",
    "countryCode": "BRA",
    "stateCode": "BR-SP",
    "city": "São Paulo",
    "district": "Centro",
    "address": "Rua das Flores",
    "number": "100",
    "zipCode": "01310100",
    "complement": "",
    "latitude": -23.55052,
    "longitude": -46.633308,
    "openingHours": "Segunda a Sexta: 08:00 às 18:00",
    "active": true
  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 74,
5    "name": "Loja Centro - SP",
6    "phone": "+5511999990001",
7    "address": "Rua das Flores",
8    "number": "100",
9    "district": "Centro",
10    "city": "São Paulo",
11    "countryCode": "BRA",
12    "stateCode": "BR-SP",
13    "zipCode": "01310100",
14    "complement": "",
15    "latitude": "-23.55052",
16    "longitude": "-46.633308",
17    "openingHours": "Segunda a Sexta: 08:00 às 18:00",
18    "active": true,
19    "linkedShippingTables": []
20  }
21}
{
  "status": true,
  "data": {
    "id": 74,
    "name": "Loja Centro - SP",
    "phone": "+5511999990001",
    "address": "Rua das Flores",
    "number": "100",
    "district": "Centro",
    "city": "São Paulo",
    "countryCode": "BRA",
    "stateCode": "BR-SP",
    "zipCode": "01310100",
    "complement": "",
    "latitude": "-23.55052",
    "longitude": "-46.633308",
    "openingHours": "Segunda a Sexta: 08:00 às 18:00",
    "active": true,
    "linkedShippingTables": []
  }
}

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

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_OPTION_WRITE`.
UAPPI_VALIDATION_ERROR	422	❌ Um ou mais campos obrigatórios estão ausentes, inválidos ou no formato incorreto.

✏️ Atualizar Ponto de Retirada

PUT /shipping/pickup-points/{pickupPointId}

Atualiza os dados de um ponto de retirada existente

📄 Descrição

Endpoint responsável por atualizar os dados de um ponto de retirada já cadastrado na loja.

Requer o escopo SHIPPING_OPTION_WRITE.

Substituição completa dos campos

Todos os campos obrigatórios devem ser enviados integralmente na requisição — mesmo os que não foram alterados.

O backend realiza uma substituição completa dos dados, não uma atualização parcial.

Vínculos com tabelas de frete preservados

A atualização de um ponto de retirada não altera os vínculos existentes com tabelas de frete.

O campo linkedShippingTables retornado na resposta reflete o estado atual dos vínculos, que só podem ser modificados pelo endpoint PUT /shipping/pickup-points/link.

Cache

Ao atualizar um ponto de retirada, o cache de cotação de frete (PRODUCT_QUOTE) é invalidado automaticamente.

📋 Parâmetros

🏷️ Headers Obrigatórios

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

🔗 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
pickupPointId	integer	✅	ID único do ponto de retirada a ser atualizado

📋 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
name	string	✅	Nome do ponto de retirada (máximo 100 caracteres)
phone	string	✅	Telefone com código de país (ex: `+5511999999999`)
countryCode	string	✅	Código do país ISO alpha-3 (ex: `BRA`)
stateCode	string	✅	Código do estado (ex: `BR-SP`, máximo 10 caracteres)
city	string	✅	Cidade (máximo 50 caracteres)
district	string	✅	Bairro (máximo 50 caracteres)
address	string	✅	Logradouro (máximo 100 caracteres)
number	string	✅	Número do endereço (máximo 10 caracteres)
zipCode	string	✅	CEP (máximo 15 caracteres)
complement	string	✅ presente	Complemento — pode ser string vazia (máximo 255 caracteres)
latitude	numeric	✅	Latitude do ponto geográfico
longitude	numeric	✅	Longitude do ponto geográfico
openingHours	string	✅	Horário de funcionamento (texto livre ou JSON serializado)
active	boolean	✅	Define se o ponto está disponível no checkout

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/shipping/pickup-points/74 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "Loja Centro - SP (atualizado)",
7    "phone": "+5511999990001",
8    "countryCode": "BRA",
9    "stateCode": "BR-SP",
10    "city": "São Paulo",
11    "district": "Centro",
12    "address": "Rua das Flores",
13    "number": "200",
14    "zipCode": "01310100",
15    "complement": "Sala 5",
16    "latitude": -23.55052,
17    "longitude": -46.633308,
18    "openingHours": "Segunda a Sábado: 09:00 às 17:00",
19    "active": false
20  }'
curl --request PUT \
  --url {{MAIN_URL}}/shipping/pickup-points/74 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Loja Centro - SP (atualizado)",
    "phone": "+5511999990001",
    "countryCode": "BRA",
    "stateCode": "BR-SP",
    "city": "São Paulo",
    "district": "Centro",
    "address": "Rua das Flores",
    "number": "200",
    "zipCode": "01310100",
    "complement": "Sala 5",
    "latitude": -23.55052,
    "longitude": -46.633308,
    "openingHours": "Segunda a Sábado: 09:00 às 17:00",
    "active": false
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 74,
5    "name": "Loja Centro - SP (atualizado)",
6    "phone": "+5511999990001",
7    "address": "Rua das Flores",
8    "number": "200",
9    "district": "Centro",
10    "city": "São Paulo",
11    "countryCode": "BRA",
12    "stateCode": "BR-SP",
13    "zipCode": "01310100",
14    "complement": "Sala 5",
15    "latitude": "-23.55052",
16    "longitude": "-46.633308",
17    "openingHours": "Segunda a Sábado: 09:00 às 17:00",
18    "active": false,
19    "linkedShippingTables": []
20  }
21}
{
  "status": true,
  "data": {
    "id": 74,
    "name": "Loja Centro - SP (atualizado)",
    "phone": "+5511999990001",
    "address": "Rua das Flores",
    "number": "200",
    "district": "Centro",
    "city": "São Paulo",
    "countryCode": "BRA",
    "stateCode": "BR-SP",
    "zipCode": "01310100",
    "complement": "Sala 5",
    "latitude": "-23.55052",
    "longitude": "-46.633308",
    "openingHours": "Segunda a Sábado: 09:00 às 17:00",
    "active": false,
    "linkedShippingTables": []
  }
}

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

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_OPTION_WRITE`.
UAPPI_AUTH_NOT_FOUND	404	❌ Nenhum ponto de retirada encontrado com o ID informado.
UAPPI_VALIDATION_ERROR	422	❌ Um ou mais campos obrigatórios estão ausentes, inválidos ou no formato incorreto.

🗑️ Remover Ponto de Retirada

DELETE /shipping/pickup-points/{pickupPointId}

Remove permanentemente um ponto de retirada e todos os seus vínculos com tabelas de frete

📄 Descrição

Endpoint responsável por remover permanentemente um ponto de retirada da loja.

Requer o escopo SHIPPING_OPTION_WRITE.

Remoção em cascata

Ao remover um ponto de retirada, todos os seus vínculos com tabelas de frete são excluídos automaticamente.

A operação não é reversível — o ponto precisará ser recriado e revinculado caso necessário.

ID não encontrado

Este endpoint retorna um erro 404 quando o ID informado não existe — não silencia a falha.

Cache

Ao remover o ponto, o cache de cotação de frete (PRODUCT_QUOTE) é invalidado automaticamente.

📋 Parâmetros

🏷️ Headers Obrigatórios

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

🔗 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
pickupPointId	integer	✅	ID único do ponto de retirada a ser removido

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/shipping/pickup-points/74 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"
curl --request DELETE \
  --url {{MAIN_URL}}/shipping/pickup-points/74 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

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

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_OPTION_WRITE`.
UAPPI_INTEGRATION_SHIPPING_PICKUP_POINT_NOT_FOUND	404	❌ Nenhum ponto de retirada encontrado com o ID informado.

🔗 Vincular Pontos de Retirada a Tabelas de Frete

PUT /shipping/pickup-points/link

Adiciona ou remove vínculos entre pontos de retirada e tabelas de frete em lote

📄 Descrição

Endpoint responsável por gerenciar os vínculos entre pontos de retirada e tabelas de frete — permitindo adicionar (add) ou remover (remove) múltiplos vínculos em uma única requisição.

Requer o escopo SHIPPING_OPTION_WRITE.

Operação em lote

O corpo da requisição é um array direto de operações, onde cada item define uma combinação de shippingTableId, shippingPickupPointId e a action desejada.

Cada item é processado individualmente — falhas em um não interrompem os demais.

Campo error

A resposta espelha o array enviado, acrescido do campo error em cada item.

Quando o vínculo é processado com sucesso, error retorna como string vazia (""). Em caso de falha, o campo traz o código de erro referente ao item específico — como UAPPI_INTEGRATION_SHIPPING_TABLE_NOT_FOUND quando a tabela não existe.

O HTTP permanece 200 mesmo que haja erros parciais — verifique o campo error de cada item para garantir que todas as operações foram bem-sucedidas.

Limite por requisição

O array aceita no máximo 200 operações por requisição.

Cache

Ao realizar vínculos, o cache de cotação de frete (PRODUCT_QUOTE) é invalidado automaticamente.

📋 Parâmetros

🏷️ Headers Obrigatórios

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

📋 Parâmetros do Corpo

O corpo da requisição é um array de objetos. Cada objeto representa uma operação de vínculo.

Parâmetro	Tipo	Obrigatório	Descrição
shippingTableId	integer	✅	ID da tabela de frete
shippingPickupPointId	integer	✅	ID do ponto de retirada
action	string	✅	Ação a executar: `add` para vincular ou `remove` para desvincular

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/shipping/pickup-points/link \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '[
6    { "shippingTableId": 3, "shippingPickupPointId": 1, "action": "add" },
7    { "shippingTableId": 7, "shippingPickupPointId": 1, "action": "remove" }
8  ]'
curl --request PUT \
  --url {{MAIN_URL}}/shipping/pickup-points/link \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '[
    { "shippingTableId": 3, "shippingPickupPointId": 1, "action": "add" },
    { "shippingTableId": 7, "shippingPickupPointId": 1, "action": "remove" }
  ]'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "shippingTableId": 3,
6      "shippingPickupPointId": 1,
7      "action": "add",
8      "error": ""
9    },
10    {
11      "shippingTableId": 7,
12      "shippingPickupPointId": 1,
13      "action": "remove",
14      "error": ""
15    }
16  ]
17}
{
  "status": true,
  "data": [
    {
      "shippingTableId": 3,
      "shippingPickupPointId": 1,
      "action": "add",
      "error": ""
    },
    {
      "shippingTableId": 7,
      "shippingPickupPointId": 1,
      "action": "remove",
      "error": ""
    }
  ]
}

⚠️ Resposta com erro parcial

Quando uma ou mais operações falham, o HTTP continua 200 — verifique o campo error de cada item individualmente.

1{
2  "status": true,
3  "data": [
4    {
5      "shippingTableId": 99999,
6      "shippingPickupPointId": 99999,
7      "action": "add",
8      "error": "UAPPI_INTEGRATION_SHIPPING_TABLE_NOT_FOUND"
9    }
10  ]
11}
{
  "status": true,
  "data": [
    {
      "shippingTableId": 99999,
      "shippingPickupPointId": 99999,
      "action": "add",
      "error": "UAPPI_INTEGRATION_SHIPPING_TABLE_NOT_FOUND"
    }
  ]
}

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

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `SHIPPING_OPTION_WRITE`.
UAPPI_VALIDATION_ERROR	422	❌ Um ou mais itens do array estão com campos ausentes ou `action` inválida.

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 Pontos de Retirada

📋 Visão Geral

🔄 Entidades Envolvidas

📌 Notas e Considerações

📋 Listagem de Pontos de Retirada

📄 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

⚠️ Possíveis Erros

🗺️ Listagem Simplificada de Pontos de Retirada

📄 Descrição

📋 Parâmetros

🏷️ Headers Obrigatórios

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

🔍 Detalhe de Ponto de Retirada

📄 Descrição

📋 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

➕ Criar Ponto de Retirada

📄 Descrição