📍 Endereços do Grupo de Pedido

📋 Visão Geral

O módulo de Endereços do Grupo de Pedido permite atualizar os endereços de entrega e cobrança vinculados a um grupo de pedido, sem alterar o cadastro global de endereços do cliente na plataforma.

Cada grupo de pedido suporta até dois endereços: o endereço de entrega (delivery) — para onde os produtos serão enviados — e o endereço de cobrança (billing) — utilizado para fins fiscais e financeiros. Quando os dois são idênticos, é possível enviá-los juntos com o tipo both.

🔄 Entidades Envolvidas

Os endereços do grupo de pedido (OrderGroupAddress) representam um snapshot dos dados de entrega e cobrança no momento da compra. Esse registro é independente do cadastro global de endereços do cliente — alterações aqui afetam apenas o pedido em questão.

A atualização aplica uma estratégia de substituição completa: os endereços anteriores são removidos e os novos são inseridos em seguida. Isso garante consistência mas exige o envio de todos os campos obrigatórios a cada chamada.

Cada atualização gera automaticamente uma entrada no histórico do grupo de pedido (OrderGroupHistory), registrando os endereços anteriores e os novos para fins de rastreabilidade e auditoria.

📌 Notas e Considerações

A requisição aceita 1 ou 2 endereços no array addresses, com regras estritas de combinação de tipos:

1 endereço

both

2 endereços

delivery

billing

Não é possível atualizar apenas delivery ou apenas billing isoladamente — sempre é necessário substituir os dois endereços do grupo.
Os endereços atuais do grupo podem ser consultados no endpoint de detalhe (GET /orders/groups/{orderGroupId}) incluindo addresses na seleção de campos.

📍 Atualização de Endereços do Grupo de Pedido

PUT /orders/groups/{orderGroupId}/address

Atualiza os endereços de entrega e/ou cobrança de um grupo de pedido

📋 Descrição

Endpoint responsável por atualizar os endereços vinculados a um grupo de pedido, permitindo corrigir ou substituir o endereço de entrega, o de cobrança, ou ambos simultaneamente — sem alterar o cadastro global de endereços do cliente na plataforma.

A atualização utiliza uma estratégia de substituição completa: os endereços existentes do grupo são removidos e os novos são inseridos em seguida. Por isso, todos os campos obrigatórios de cada endereço devem ser enviados a cada chamada.

A cada atualização, o sistema registra automaticamente um histórico no grupo de pedido com os endereços anteriores e os novos, garantindo rastreabilidade completa das alterações.

O campo customerAddressType define o propósito de cada endereço e determina as regras de combinação aceitas:

both — atualiza entrega e cobrança com os mesmos dados; deve ser enviado sozinho (1 item no array)
delivery + billing — atualiza os dois endereços com dados distintos; devem ser enviados juntos (2 itens no array)

Não é possível enviar apenas delivery ou apenas billing isoladamente — a substituição sempre afeta os dois endereços do grupo.

🔐 Permissão

UserAuth — autenticação do usuário administrativo
ORDER_WRITE — escopo de permissão para operações de escrita em pedidos

📝 Parâmetros

🏷️ Headers Obrigatórios

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

🔗 Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`orderGroupId`	integer	✅ Sim	ID do grupo de pedido

📦 Parâmetros do Corpo

Campo	Tipo	Obrigatório	Descrição
`addresses`	array	✅ Sim	Array de endereços a atualizar — 1 item (`both`) ou 2 itens (`delivery` + `billing`)
`addresses[].customerAddressType`	string	✅ Sim	Tipo do endereço — `delivery`, `billing` ou `both`
`addresses[].addressZipCode`	string	✅ Sim	CEP — máximo 15 caracteres
`addresses[].addressRecipient`	string	✅ Sim	Nome do destinatário — máximo 100 caracteres
`addresses[].addressCountryCode`	string	✅ Sim	Código do país no formato alpha-3 — ex: `BRA`
`addresses[].addressStateCode`	string	✅ Sim	Código do estado — ex: `BR-SP`
`addresses[].addressState`	string	✅ Sim	Nome completo do estado
`addresses[].addressCity`	string	✅ Sim	Cidade
`addresses[].addressDistrict`	string	✅ Sim	Bairro
`addresses[].addressStreet`	string	✅ Sim	Logradouro
`addresses[].addressNumber`	string	✅ Sim	Número
`addresses[].addressComplement`	string	❌ Não	Complemento

1{
2  "addresses": [
3    {
4      "customerAddressType": "both",
5      "addressZipCode": "16201155",
6      "addressRecipient": "João Silva",
7      "addressStreet": "Rua José Masson",
8      "addressNumber": "100",
9      "addressDistrict": "Jardim Recanto",
10      "addressCity": "Birigui",
11      "addressState": "São Paulo",
12      "addressStateCode": "BR-SP",
13      "addressCountryCode": "BRA",
14      "addressComplement": "Apto 12"
15    }
16  ]
17}
{
  "addresses": [
    {
      "customerAddressType": "both",
      "addressZipCode": "16201155",
      "addressRecipient": "João Silva",
      "addressStreet": "Rua José Masson",
      "addressNumber": "100",
      "addressDistrict": "Jardim Recanto",
      "addressCity": "Birigui",
      "addressState": "São Paulo",
      "addressStateCode": "BR-SP",
      "addressCountryCode": "BRA",
      "addressComplement": "Apto 12"
    }
  ]
}

Exemplo com entrega e cobrança diferentes

1{
2  "addresses": [
3    {
4      "customerAddressType": "delivery",
5      "addressZipCode": "01310100",
6      "addressRecipient": "João Silva",
7      "addressStreet": "Av. Paulista",
8      "addressNumber": "1000",
9      "addressDistrict": "Bela Vista",
10      "addressCity": "São Paulo",
11      "addressState": "São Paulo",
12      "addressStateCode": "BR-SP",
13      "addressCountryCode": "BRA",
14      "addressComplement": ""
15    },
16    {
17      "customerAddressType": "billing",
18      "addressZipCode": "04922150",
19      "addressRecipient": "João Silva",
20      "addressStreet": "Travessa Fidelcina",
21      "addressNumber": "42",
22      "addressDistrict": "Centro",
23      "addressCity": "São Paulo",
24      "addressState": "São Paulo",
25      "addressStateCode": "BR-SP",
26      "addressCountryCode": "BRA",
27      "addressComplement": ""
28    }
29  ]
30}
{
  "addresses": [
    {
      "customerAddressType": "delivery",
      "addressZipCode": "01310100",
      "addressRecipient": "João Silva",
      "addressStreet": "Av. Paulista",
      "addressNumber": "1000",
      "addressDistrict": "Bela Vista",
      "addressCity": "São Paulo",
      "addressState": "São Paulo",
      "addressStateCode": "BR-SP",
      "addressCountryCode": "BRA",
      "addressComplement": ""
    },
    {
      "customerAddressType": "billing",
      "addressZipCode": "04922150",
      "addressRecipient": "João Silva",
      "addressStreet": "Travessa Fidelcina",
      "addressNumber": "42",
      "addressDistrict": "Centro",
      "addressCity": "São Paulo",
      "addressState": "São Paulo",
      "addressStateCode": "BR-SP",
      "addressCountryCode": "BRA",
      "addressComplement": ""
    }
  ]
}

💡 Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/orders/groups/3710/address' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "addresses": [
7      {
8        "customerAddressType": "both",
9        "addressZipCode": "01310100",
10        "addressRecipient": "João Silva",
11        "addressStreet": "Av. Paulista",
12        "addressNumber": "1000",
13        "addressDistrict": "Bela Vista",
14        "addressCity": "São Paulo",
15        "addressState": "São Paulo",
16        "addressStateCode": "BR-SP",
17        "addressCountryCode": "BRA",
18        "addressComplement": ""
19      }
20    ]
21  }'
curl --request PUT \
  --url '{{MAIN_URL}}/orders/groups/3710/address' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "addresses": [
      {
        "customerAddressType": "both",
        "addressZipCode": "01310100",
        "addressRecipient": "João Silva",
        "addressStreet": "Av. Paulista",
        "addressNumber": "1000",
        "addressDistrict": "Bela Vista",
        "addressCity": "São Paulo",
        "addressState": "São Paulo",
        "addressStateCode": "BR-SP",
        "addressCountryCode": "BRA",
        "addressComplement": ""
      }
    ]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "orderGroupId": 3710,
6      "customerAddressType": "both",
7      "customerAddressId": null,
8      "addressZipCode": "01310100",
9      "addressRecipient": "João Silva",
10      "addressStreet": "Av. Paulista",
11      "addressNumber": "1000",
12      "addressDistrict": "Bela Vista",
13      "addressCity": "São Paulo",
14      "addressState": "São Paulo",
15      "addressStateCode": "BR-SP",
16      "addressCountryCode": "BRA",
17      "addressComplement": ""
18    }
19  ]
20}
{
  "status": true,
  "data": [
    {
      "orderGroupId": 3710,
      "customerAddressType": "both",
      "customerAddressId": null,
      "addressZipCode": "01310100",
      "addressRecipient": "João Silva",
      "addressStreet": "Av. Paulista",
      "addressNumber": "1000",
      "addressDistrict": "Bela Vista",
      "addressCity": "São Paulo",
      "addressState": "São Paulo",
      "addressStateCode": "BR-SP",
      "addressCountryCode": "BRA",
      "addressComplement": ""
    }
  ]
}

Campos da Resposta

Campo	Tipo	Nullable	Descrição
`orderGroupId`	integer	Não	ID do grupo de pedido
`customerAddressType`	string	Não	Tipo do endereço atualizado — `delivery`, `billing` ou `both`
`customerAddressId`	integer	Sim	ID do endereço de cadastro do cliente na plataforma; `null` quando não vinculado a um cadastro
`addressZipCode`	string	Não	CEP do endereço
`addressRecipient`	string	Não	Nome do destinatário
`addressStreet`	string	Não	Logradouro
`addressNumber`	string	Não	Número
`addressDistrict`	string	Não	Bairro
`addressCity`	string	Não	Cidade
`addressState`	string	Não	Nome completo do estado
`addressStateCode`	string	Não	Código do estado — ex: `BR-SP`
`addressCountryCode`	string	Não	Código do país no formato alpha-3 — ex: `BRA`
`addressComplement`	string	Não	Complemento do endereço

⚠️ 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 do Erro	HTTP	Descrição
`UAPPI_STORE_ORDER_GROUP_NOT_FOUND`	404	Grupo de pedido não encontrado com o ID informado
`UAPPI_STORE_ORDER_GROUP_ADDRESS_TYPE_BOTH_IS_REQUIRED`	422	Tipo `both` obrigatório quando apenas 1 endereço é enviado no array
`UAPPI_STORE_ORDER_GROUP_ADDRESS_TYPE_PAIR_IS_REQUIRED`	422	Par `delivery` + `billing` obrigatório quando 2 endereços são enviados no array
`UAPPI_STORE_ORDER_INVALID_ADDRESS`	422	Endereço inválido — campos obrigatórios ausentes ou inválidos
`UAPPI_STORE_CUSTOMER_ADDRESS_COUNTRY_NOT_FOUND`	422	Código do país não encontrado
`UAPPI_STORE_CUSTOMER_ADDRESS_STATE_NOT_FOUND`	422	Código do estado não encontrado para o país informado

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

📍 Endereços do Grupo de Pedido

📋 Visão Geral

🔄 Entidades Envolvidas

📌 Notas e Considerações

📍 Atualização de Endereços do Grupo de Pedido

📋 Descrição

🔐 Permissão

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

📦 Parâmetros do Corpo

Exemplo com entrega e cobrança diferentes

💡 Exemplo de Requisição

✅ Resposta de Sucesso

Campos da Resposta

⚠️ Possíveis Erros

Nesta página

Institucional