Ativar uma loja

Uma loja só vende quando cinco peças existem e estão ligadas entre si. Esta página é a ordem em que elas precisam ser criadas — a dependência é real: pular um passo faz o seguinte falhar ou, pior, gravar um registro órfão que não aparece na vitrine.

Quem cria o quê

Quatro das cinco entidades não são criadas pela API de integração. ContractAccount, CommercialPolicy, Seller e ShippingPolicy são criadas pelo time Grocers, no painel administrativo. As rotas correspondentes existem no serviço principal, mas exigem sessão de usuário com papel Admin ou Owner — não a credencial Basic de integração — e a de ShippingPolicy nem sequer tem verbo de criação direto.

A única das cinco que você cria é o Warehouse.

O diagrama responde: onde termina a Grocers e começa o seu time, e o que precisa existir antes do quê?

As setas são dependências reais de dado, não etapas de projeto: a ShippingPolicy precisa do id do seller e do da política comercial, e o warehouse precisa dos shippingPolicyId já existentes. O que atravessa a fronteira são identificadores — você recebe GUIDs e os usa no seu único POST.

Entidade	Quem cria	Como
ContractAccount	Grocers	provisionamento de contrato
CommercialPolicy	Grocers	painel administrativo
Seller	Grocers	painel administrativo
ShippingPolicy	Grocers	painel administrativo
Warehouse	você	`POST /v1/batch/Warehouses`
Marcas, categorias, produtos, SKUs	você	`/v1/batch/*`
Estoque e preço	você	`/v1/batch/*`
Webhook	você	`POST /v1/Webhooks`

O que você faz nos quatro primeiros passos é fornecer os dados ao time Grocers e receber os identificadores de volta. Os blocos JSON abaixo são a informação que a Grocers precisa de você, não corpos de requisição que você envia.

Conta contratante (ContractAccount) — Grocers

É o seu tenant: CNPJ, endereço e o usuário administrador inicial. Criada pelo time Grocers na abertura do contrato — você recebe o contractAccountId pronto.

A criação também provisiona automaticamente:

o usuário administrador com papel Admin;
os templates de e-mail transacional já com a identidade visual da marca (logo, cor primária, redes sociais e contatos de suporte).

Se a marca mudar depois, os templates não são regerados sozinhos — a atualização de branding é um passo à parte. Fale com o suporte.

Política comercial (CommercialPolicy) — Grocers

Define o conjunto de preços que vale para um público. O contrato começa com uma política padrão; peça novas se a operação tiver tabelas distintas (varejo e atacado, por exemplo). Antes de modelar, leia Multi-política em Tipos de preço: o desenho suportado é um produto por política.

O único dado necessário é o nome:


{ "name": "Varejo" }

Você recebe de volta o id — é ele que vai em commercialPolicyId no cadastro de produto e no de preço. Guarde-o.

Seller (a loja física) — Grocers

O seller é o endereço de onde a mercadoria sai. Os dados que a Grocers precisa:


{
  "name": "Loja Centro",
  "country": "Brasil",
  "state": "RJ",
  "city": "Rio de Janeiro",
  "neighborhood": "Centro",
  "zipCode": "20031170",
  "street": "Av. Rio Branco",
  "number": "156",
  "complement": "Loja A",
  "reference": "Em frente à praça",
  "phoneNumber": "2133334444",
  "description": "Loja âncora do centro"
}

Campo	Obrigatório	Regra
`name`	sim	3 a 60 caracteres
`state`	sim	exatamente 2 caracteres (`RJ`, `SP`)
`city`, `neighborhood`, `street`	sim	3 a 60 caracteres
`zipCode`	sim	exatamente 8 dígitos, sem hífen
`number`	sim	1 a 6 caracteres
`country`, `complement`, `reference`	não	3 a 60 caracteres quando presentes
`phoneNumber`	sim	telefone válido
`description`	não	3 a 160 caracteres

zipCode com hífen (20031-170) é reprovado: a validação exige exatamente 8 caracteres. Envie 20031170.

Você recebe de volta o id do seller.

Política de entrega (ShippingPolicy) — Grocers

Amarra seller + política comercial + uma modalidade de entrega. É por isso que ela vem depois dos dois: precisa dos dois id já existentes.

Uma política tem exatamente uma modalidade:

Modalidade	Bloco	O que a Grocers precisa saber
Agendada	`scheduledDelivery`	tempo de separação, quantidade mínima e máxima de itens, valor mínimo de compra, e as janelas de entrega (dia da semana, horário de início e fim, capacidade, valor adicional)
Expressa	`expressDelivery`	faixa de tempo máxima de entrega, quantidade mínima e máxima de itens, valor mínimo de compra, faixas de frete
Retirada	`pickupPoint`	endereço do ponto de retirada, tempo de separação, limite de horas, quantidade mínima e máxima de itens, valor mínimo

Se a loja opera agendada e retirada, são duas ShippingPolicies para o mesmo seller.

Você recebe de volta o id de cada política — é ele que vai em shippingPolicyIds no passo seguinte.

Warehouse (o estoque) — você

Este é o seu passo. O warehouse é a unidade de estoque que abastece as entregas, e ele se liga às políticas de entrega criadas no passo anterior:


curl -X POST $GROCERS_API/v1/batch/Warehouses \
  -H "Authorization: Basic $BASIC" \
  -H "x-contractAccountId: $TENANT" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "externalReference": "CD-CENTRO",
      "name": "CD Centro",
      "shippingPolicyIds": ["b3f1a2c4-5d6e-4f70-8a91-2b3c4d5e6f70"]
    }
  ]'

Veja Warehouses.

O warehouse é o último dos cinco, não o quarto. Ele referencia shippingPolicyIds, e o processador valida que todos os GUIDs enviados já existem: se algum não existir, a criação é recusada com conflito e volta como Warehouse_CreationFailed no seu webhook. Não dá para criar o warehouse “antes” e ligar as políticas depois pela API de integração — a ligação só é gravada no POST. Espere os id das políticas.

Checklist antes de abrir a loja

Antes de liberar a vitrine, confirme que cada item abaixo responde como esperado:

- contractAccountId + credencial Basic do ambiente
- commercialPolicyId (id em mãos)
- sellerId de cada loja
- shippingPolicyId de cada modalidade ativa
- Warehouse criado e ligado às ShippingPolicies
- Catálogo carregado (marcas → categorias → produtos)
- Estoque publicado por SKU
- Preço publicado por SKU + política
- Webhook registrado para eventos de pedido
- Endpoint do ERP persistindo o evento e respondendo 2xx
- Mapa shippingPolicyId → warehouse no seu ERP

O erro mais comum na ativação é o item existir no catálogo mas não aparecer na busca. Na prática são sempre as mesmas duas causas: sem estoque no warehouse ou sem preço na política comercial que a vitrine está usando.