API atual/Referência completa/Formas de envio

Endereço de retirada

Lê e grava o endereço onde o cliente retira o pedido numa forma de envio do tipo retirada na loja.

Numa forma de retirada na loja o cliente não recebe nada em casa: ele busca o pedido num endereço do seller. Esse endereço é um ponto de retirada. Quando o seller ainda não tem um, o GET devolve uma sugestão montada com o endereço do cadastro do seller, que você pode confirmar com um PUT. Depois que o pedido fica pronto, a retirada é conduzida em Retiradas.

Ler o endereço

GET/api/v1/vendor/shipping-methods/{id}/pickup-pointSeller

Lê o endereço de retirada do seller

Parâmetros de caminho

iduuidobrigatório

Id da forma de envio.

Exemplo de requisição: ler

bash

curl "$BASE_URL/api/v1/vendor/shipping-methods/3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21/pickup-point" \
  -H "Authorization: Bearer $TOKEN"

Resposta: ler

200Ponto de retirada

json

{
  "pickup_point": {
    "id": "d3b07384-d9a0-4c1b-8d0e-7a1b2c3d4e5f",
    "name": "Loja Centro",
    "code": "PICKUP",
    "address": "Rua das Flores, 120, Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01310-100",
    "country": "BR",
    "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "status": "active",
    "is_default": false,
    "position": 0,
    "type": "store",
    "serves_kind": "both",
    "is_pickup_point": true,
    "pickup_instructions": "Retire no balcão com o código de 6 dígitos.",
    "pickup_expires_days": 7,
    "created_at": "2026-10-01T14:20:11Z",
    "updated_at": "2026-10-01T14:20:11Z"
  }
}

Campos da resposta

pickup_pointobject

O ponto de retirada.

iduuid

Id do ponto. Ausente na pré-visualização que ainda não foi salva.

namestring

Nome do ponto.

codestring

Sempre PICKUP.

addressstring

Logradouro, número e bairro.

citystring

Cidade.

statestring

UF, 2 letras.

zipcodestring

CEP.

pickup_instructionsstring

Instruções mostradas ao cliente.

pickup_expires_daysinteger

Dias que o pedido fica à espera da retirada antes de expirar.

is_pickup_pointboolean

Sempre true.

(demais)various

country, vendor_id, status, type, serves_kind, is_default, position, created_at, updated_at: dados do depósito que guarda o ponto.

Erros: ler

Status	Quando	Corpo de exemplo
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
400	A forma não é de retirada (nome e código sem "retirada", "retirar" ou "pickup").	`{"error":"shipping method is not an in-store pickup method"}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	A forma existe, mas pertence a outro seller ou à loja inteira.	`{"error":"forbidden","detail":"shipping method does not belong to this vendor"}`
404	Não existe forma com esse id.	`{"error":"shipping method not found"}`
500	Cadastro do seller sem dados para a sugestão, ou serviço indisponível.	`{"error":"failed to load seller address"}`

Gravar o endereço

Cria o ponto na primeira vez e atualiza nas seguintes. Se você não enviar id, a plataforma reaproveita o ponto de retirada que o seller já tem, em vez de criar outro.

PUT/api/v1/vendor/shipping-methods/{id}/pickup-pointSeller

Grava o endereço de retirada do seller

Parâmetros de caminho

iduuidobrigatório

Id da forma de envio.

Corpo da requisição

iduuid

Id do ponto já salvo. Opcional; se enviado, precisa ser um ponto de retirada seu.

namestringobrigatório

Nome do ponto.

addressstringobrigatório

Logradouro, número e bairro.

citystringobrigatório

Cidade.

statestringobrigatório

UF. Convertida para maiúsculas.

zipcodestringobrigatório

CEP.

pickup_instructionsstring

Instruções mostradas ao cliente.

pickup_expires_daysintegerpadrão: 7

Dias de espera antes de a retirada expirar. Zero ou negativo vira 7.

Exemplo de requisição: gravar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/shipping-methods/3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21/pickup-point" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loja Centro",
    "address": "Rua das Flores, 120, Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01310-100",
    "pickup_instructions": "Retire no balcão com o código de 6 dígitos.",
    "pickup_expires_days": 7
  }'

Resposta: gravar

200Ponto gravado

json

{
  "pickup_point": {
    "id": "d3b07384-d9a0-4c1b-8d0e-7a1b2c3d4e5f",
    "name": "Loja Centro",
    "code": "PICKUP",
    "address": "Rua das Flores, 120, Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01310-100",
    "country": "BR",
    "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "status": "active",
    "is_default": false,
    "position": 0,
    "type": "store",
    "serves_kind": "both",
    "is_pickup_point": true,
    "pickup_instructions": "Retire no balcão com o código de 6 dígitos.",
    "pickup_expires_days": 7,
    "created_at": "2026-10-01T14:20:11Z",
    "updated_at": "2026-10-01T14:20:11Z"
  }
}

Campos da resposta

pickup_pointobject

O ponto de retirada.

iduuid

Id do ponto. Ausente na pré-visualização que ainda não foi salva.

namestring

Nome do ponto.

codestring

Sempre PICKUP.

addressstring

Logradouro, número e bairro.

citystring

Cidade.

statestring

UF, 2 letras.

zipcodestring

CEP.

pickup_instructionsstring

Instruções mostradas ao cliente.

pickup_expires_daysinteger

Dias que o pedido fica à espera da retirada antes de expirar.

is_pickup_pointboolean

Sempre true.

(demais)various

country, vendor_id, status, type, serves_kind, is_default, position, created_at, updated_at: dados do depósito que guarda o ponto.

Erros: gravar

Status	Quando	Corpo de exemplo
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	Falta nome, endereço, cidade, UF ou CEP.	`{"error":"pickup name, address, city, state and ZIP code are required"}`
400	A forma não é de retirada (nome e código sem "retirada", "retirar" ou "pickup").	`{"error":"shipping method is not an in-store pickup method"}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	A forma é de outro seller, ou o `id` do ponto não é um ponto de retirada seu.	`{"error":"pickup point does not belong to this seller"}`
404	Não existe forma com esse id.	`{"error":"shipping method not found"}`
500	Falha ao gravar.	`{"error":"failed to update pickup address"}`

Veja também

API atual/Referência completa/Formas de envio

Endereço de retirada

Lê e grava o endereço onde o cliente retira o pedido numa forma de envio do tipo retirada na loja.

Ler o endereço

GET/api/v1/vendor/shipping-methods/{id}/pickup-pointSeller

Lê o endereço de retirada do seller

Parâmetros de caminho

iduuidobrigatório

Id da forma de envio.

Exemplo de requisição: ler

bash

curl "$BASE_URL/api/v1/vendor/shipping-methods/3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21/pickup-point" \
  -H "Authorization: Bearer $TOKEN"

Resposta: ler

200Ponto de retirada

json

{
  "pickup_point": {
    "id": "d3b07384-d9a0-4c1b-8d0e-7a1b2c3d4e5f",
    "name": "Loja Centro",
    "code": "PICKUP",
    "address": "Rua das Flores, 120, Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01310-100",
    "country": "BR",
    "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "status": "active",
    "is_default": false,
    "position": 0,
    "type": "store",
    "serves_kind": "both",
    "is_pickup_point": true,
    "pickup_instructions": "Retire no balcão com o código de 6 dígitos.",
    "pickup_expires_days": 7,
    "created_at": "2026-10-01T14:20:11Z",
    "updated_at": "2026-10-01T14:20:11Z"
  }
}

Campos da resposta

pickup_pointobject

O ponto de retirada.

iduuid

Id do ponto. Ausente na pré-visualização que ainda não foi salva.

namestring

Nome do ponto.

codestring

Sempre PICKUP.

addressstring

Logradouro, número e bairro.

citystring

Cidade.

statestring

UF, 2 letras.

zipcodestring

CEP.

pickup_instructionsstring

Instruções mostradas ao cliente.

pickup_expires_daysinteger

Dias que o pedido fica à espera da retirada antes de expirar.

is_pickup_pointboolean

Sempre true.

(demais)various

country, vendor_id, status, type, serves_kind, is_default, position, created_at, updated_at: dados do depósito que guarda o ponto.

Erros: ler

Status	Quando	Corpo de exemplo
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
400	A forma não é de retirada (nome e código sem "retirada", "retirar" ou "pickup").	`{"error":"shipping method is not an in-store pickup method"}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	A forma existe, mas pertence a outro seller ou à loja inteira.	`{"error":"forbidden","detail":"shipping method does not belong to this vendor"}`
404	Não existe forma com esse id.	`{"error":"shipping method not found"}`
500	Cadastro do seller sem dados para a sugestão, ou serviço indisponível.	`{"error":"failed to load seller address"}`

Gravar o endereço

Cria o ponto na primeira vez e atualiza nas seguintes. Se você não enviar id, a plataforma reaproveita o ponto de retirada que o seller já tem, em vez de criar outro.

PUT/api/v1/vendor/shipping-methods/{id}/pickup-pointSeller

Grava o endereço de retirada do seller

Parâmetros de caminho

iduuidobrigatório

Id da forma de envio.

Corpo da requisição

iduuid

Id do ponto já salvo. Opcional; se enviado, precisa ser um ponto de retirada seu.

namestringobrigatório

Nome do ponto.

addressstringobrigatório

Logradouro, número e bairro.

citystringobrigatório

Cidade.

statestringobrigatório

UF. Convertida para maiúsculas.

zipcodestringobrigatório

CEP.

pickup_instructionsstring

Instruções mostradas ao cliente.

pickup_expires_daysintegerpadrão: 7

Dias de espera antes de a retirada expirar. Zero ou negativo vira 7.

Exemplo de requisição: gravar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/shipping-methods/3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21/pickup-point" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loja Centro",
    "address": "Rua das Flores, 120, Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01310-100",
    "pickup_instructions": "Retire no balcão com o código de 6 dígitos.",
    "pickup_expires_days": 7
  }'

Resposta: gravar

200Ponto gravado

json

{
  "pickup_point": {
    "id": "d3b07384-d9a0-4c1b-8d0e-7a1b2c3d4e5f",
    "name": "Loja Centro",
    "code": "PICKUP",
    "address": "Rua das Flores, 120, Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01310-100",
    "country": "BR",
    "vendor_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "status": "active",
    "is_default": false,
    "position": 0,
    "type": "store",
    "serves_kind": "both",
    "is_pickup_point": true,
    "pickup_instructions": "Retire no balcão com o código de 6 dígitos.",
    "pickup_expires_days": 7,
    "created_at": "2026-10-01T14:20:11Z",
    "updated_at": "2026-10-01T14:20:11Z"
  }
}

Campos da resposta

pickup_pointobject

O ponto de retirada.

iduuid

Id do ponto. Ausente na pré-visualização que ainda não foi salva.

namestring

Nome do ponto.

codestring

Sempre PICKUP.

addressstring

Logradouro, número e bairro.

citystring

Cidade.

statestring

UF, 2 letras.

zipcodestring

CEP.

pickup_instructionsstring

Instruções mostradas ao cliente.

pickup_expires_daysinteger

Dias que o pedido fica à espera da retirada antes de expirar.

is_pickup_pointboolean

Sempre true.

(demais)various

country, vendor_id, status, type, serves_kind, is_default, position, created_at, updated_at: dados do depósito que guarda o ponto.

Erros: gravar

Status	Quando	Corpo de exemplo
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	Falta nome, endereço, cidade, UF ou CEP.	`{"error":"pickup name, address, city, state and ZIP code are required"}`
400	A forma não é de retirada (nome e código sem "retirada", "retirar" ou "pickup").	`{"error":"shipping method is not an in-store pickup method"}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	A forma é de outro seller, ou o `id` do ponto não é um ponto de retirada seu.	`{"error":"pickup point does not belong to this seller"}`
404	Não existe forma com esse id.	`{"error":"shipping method not found"}`
500	Falha ao gravar.	`{"error":"failed to update pickup address"}`