API atual/Referência completa/Cadastro de clientes

Regras de grupo por estado

Liga um estado a um grupo de clientes para atribuir o grupo automaticamente conforme o endereço, e aplica a regra aos clientes existentes.

Um grupo de clientes (usergroup) reúne clientes que recebem o mesmo tratamento: uma tabela de preços, um benefício, um regime de imposto. Muitas lojas precisam de um grupo por estado, porque o ICMS e a política comercial mudam de uma unidade da federação para outra. A regra por estado automatiza isso: "cliente com endereço em MG entra no grupo Atacado MG".

Todas as rotas desta página exigem o módulo state-usergroup-rules ligado (403 module_disabled caso contrário). Ler pede view_vendors ou manage_vendors; criar, aplicar e excluir pedem manage_vendors. Estas são as regras do marketplace inteiro; sellers têm regras próprias, por outras rotas.

Listar regras

Devolve as regras do marketplace, ordenadas por sigla do estado e nome do grupo. Sem paginação.

GET/api/v1/admin/state-usergroup-rulesAdmin

Lista as regras de grupo por estado

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/state-usergroup-rules" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regras retornadas

json

{
  "rules": [
    {
      "id": "3d0c2a58-52c1-4c1c-9f11-9d0f5a1c7b10",
      "state_code": "MG",
      "state_name": "Minas Gerais",
      "usergroup_id": "01569276-9514-44f3-bdca-897942fae7f0",
      "auto_assign": true,
      "created_at": "2026-10-11T22:00:00Z",
      "usergroup_name": "Atacado"
    }
  ],
  "total": 1
}

Sem regras, rules vem [] e total vem 0.

Campos da resposta

rules[].iduuid

Id da regra.

rules[].state_codestring

Sigla do estado, como foi gravada.

rules[].state_namestring

Nome do estado. Pode ser vazio.

rules[].usergroup_iduuid

Grupo de clientes atribuído.

rules[].auto_assignboolean

Se a regra atribui o grupo automaticamente.

rules[].created_atstring

Criação, RFC 3339 em UTC.

rules[].usergroup_namestring

Nome do grupo. Ausente se o grupo não existir mais.

totalinteger

Quantidade de regras.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"state-usergroup-rules"}`
500	Falha interna	`{"error":"failed to list state usergroup rules","detail":"..."}`

Criar uma regra

Grava a regra e, se auto_assign estiver ligado, já coloca no grupo todos os clientes existentes cujo endereço padrão está no estado. A partir daí, cada endereço novo ou alterado nesse estado dispara a atribuição.

A chamada também atualiza: se já existe regra para o mesmo par estado e grupo, ela é regravada (nome do estado e auto_assign) e o id se mantém, sem erro de duplicidade.

POST/api/v1/admin/state-usergroup-rulesAdmin

Cria ou atualiza uma regra de grupo por estado

Corpo da requisição

state_codestringobrigatório

Sigla do estado, como MG. A comparação com o endereço ignora maiúsculas na aplicação retroativa; grave em maiúsculas.

usergroup_iduuidobrigatório

Grupo de clientes de destino. Precisa existir.

state_namestring

Nome do estado, só para exibição.

auto_assignbooleanpadrão: true

Se false, a regra fica cadastrada mas não atribui ninguém.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/state-usergroup-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "state_code": "MG",
    "state_name": "Minas Gerais",
    "usergroup_id": "01569276-9514-44f3-bdca-897942fae7f0",
    "auto_assign": true
  }'

Resposta

201Regra gravada

json

{
  "id": "3d0c2a58-52c1-4c1c-9f11-9d0f5a1c7b10",
  "state_code": "MG",
  "state_name": "Minas Gerais",
  "usergroup_id": "01569276-9514-44f3-bdca-897942fae7f0",
  "auto_assign": true,
  "created_at": "2026-10-11T22:00:00Z",
  "usergroup_name": "Atacado"
}

A resposta não diz quantos clientes foram atribuídos na varredura inicial; para saber, use a operação Aplicar uma regra aos clientes existentes, logo abaixo (ela devolve a contagem de novos vínculos), ou confira o grupo.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Falta `state_code`	`{"error":"state_code is required"}`
400	Falta `usergroup_id`	`{"error":"usergroup_id is required"}`
400	Grupo inexistente	`{"error":"usergroup 00000000-0000-0000-0000-000000000000 not found"}`
400	`usergroup_id` que não é UUID	`{"error":"o valor \"abc\" não é um uuid válido. ..."}`
401 / 403	Sem token, sem `manage_vendors`, ou módulo desligado	`{"error":"module_disabled","module":"state-usergroup-rules"}`

Aplicar uma regra aos clientes existentes

Coloca no grupo todo cliente (não excluído) cujo endereço padrão está no estado da regra. É idempotente: rodar de novo não duplica, e devolve só os vínculos novos criados. Útil se o grupo foi criado depois dos clientes, ou se você precisa refazer a varredura. Só age em regra com auto_assign ligado.

POST/api/v1/admin/state-usergroup-rules/{id}/applyAdmin

Aplica a regra aos clientes existentes

Parâmetros de caminho

iduuidobrigatório

Id da regra.

Sem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/state-usergroup-rules/3d0c2a58-52c1-4c1c-9f11-9d0f5a1c7b10/apply" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regra aplicada

json

{ "assigned": 124 }

Campos da resposta

assignedinteger

Vínculos novos criados. 0 quando todos já estavam no grupo, quando o estado não tem clientes ou quando a regra não existe.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem `manage_vendors`, ou módulo desligado	`{"error":"module_disabled","module":"state-usergroup-rules"}`
500	`id` que não é UUID, ou falha interna	`{"error":"failed to apply state usergroup rule","detail":"..."}`

Excluir uma regra

Remove a regra. Os clientes que já foram colocados no grupo continuam nele: a exclusão só impede novas atribuições. Para tirar clientes do grupo, use a gestão de grupos de clientes.

DELETE/api/v1/admin/state-usergroup-rules/{id}Admin

Exclui uma regra de grupo por estado

Parâmetros de caminho

iduuidobrigatório

Id da regra.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/state-usergroup-rules/3d0c2a58-52c1-4c1c-9f11-9d0f5a1c7b10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regra excluída

json

{ "message": "state usergroup rule deleted" }

Erros

Status	Quando	Corpo
500	Regra inexistente (deveria ser 404), `id` que não é UUID, ou falha interna	`{"error":"failed to delete state usergroup rule","detail":"state usergroup rule 0000... not found"}`
401 / 403	Sem token, sem `manage_vendors`, ou módulo desligado	`{"error":"module_disabled","module":"state-usergroup-rules"}`

Veja também

API atual/Referência completa/Cadastro de clientes

Regras de grupo por estado

Liga um estado a um grupo de clientes para atribuir o grupo automaticamente conforme o endereço, e aplica a regra aos clientes existentes.

Listar regras

Devolve as regras do marketplace, ordenadas por sigla do estado e nome do grupo. Sem paginação.

GET/api/v1/admin/state-usergroup-rulesAdmin

Lista as regras de grupo por estado

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/state-usergroup-rules" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regras retornadas

json

{
  "rules": [
    {
      "id": "3d0c2a58-52c1-4c1c-9f11-9d0f5a1c7b10",
      "state_code": "MG",
      "state_name": "Minas Gerais",
      "usergroup_id": "01569276-9514-44f3-bdca-897942fae7f0",
      "auto_assign": true,
      "created_at": "2026-10-11T22:00:00Z",
      "usergroup_name": "Atacado"
    }
  ],
  "total": 1
}

Sem regras, rules vem [] e total vem 0.

Campos da resposta

rules[].iduuid

Id da regra.

rules[].state_codestring

Sigla do estado, como foi gravada.

rules[].state_namestring

Nome do estado. Pode ser vazio.

rules[].usergroup_iduuid

Grupo de clientes atribuído.

rules[].auto_assignboolean

Se a regra atribui o grupo automaticamente.

rules[].created_atstring

Criação, RFC 3339 em UTC.

rules[].usergroup_namestring

Nome do grupo. Ausente se o grupo não existir mais.

totalinteger

Quantidade de regras.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo desligado	`{"error":"module_disabled","module":"state-usergroup-rules"}`
500	Falha interna	`{"error":"failed to list state usergroup rules","detail":"..."}`

Criar uma regra

A chamada também atualiza: se já existe regra para o mesmo par estado e grupo, ela é regravada (nome do estado e auto_assign) e o id se mantém, sem erro de duplicidade.

POST/api/v1/admin/state-usergroup-rulesAdmin

Cria ou atualiza uma regra de grupo por estado

Corpo da requisição

state_codestringobrigatório

Sigla do estado, como MG. A comparação com o endereço ignora maiúsculas na aplicação retroativa; grave em maiúsculas.

usergroup_iduuidobrigatório

Grupo de clientes de destino. Precisa existir.

state_namestring

Nome do estado, só para exibição.

auto_assignbooleanpadrão: true

Se false, a regra fica cadastrada mas não atribui ninguém.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/state-usergroup-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "state_code": "MG",
    "state_name": "Minas Gerais",
    "usergroup_id": "01569276-9514-44f3-bdca-897942fae7f0",
    "auto_assign": true
  }'

Resposta

201Regra gravada

json

{
  "id": "3d0c2a58-52c1-4c1c-9f11-9d0f5a1c7b10",
  "state_code": "MG",
  "state_name": "Minas Gerais",
  "usergroup_id": "01569276-9514-44f3-bdca-897942fae7f0",
  "auto_assign": true,
  "created_at": "2026-10-11T22:00:00Z",
  "usergroup_name": "Atacado"
}

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Falta `state_code`	`{"error":"state_code is required"}`
400	Falta `usergroup_id`	`{"error":"usergroup_id is required"}`
400	Grupo inexistente	`{"error":"usergroup 00000000-0000-0000-0000-000000000000 not found"}`
400	`usergroup_id` que não é UUID	`{"error":"o valor \"abc\" não é um uuid válido. ..."}`
401 / 403	Sem token, sem `manage_vendors`, ou módulo desligado	`{"error":"module_disabled","module":"state-usergroup-rules"}`

Aplicar uma regra aos clientes existentes

POST/api/v1/admin/state-usergroup-rules/{id}/applyAdmin

Aplica a regra aos clientes existentes

Parâmetros de caminho

iduuidobrigatório

Id da regra.

Sem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/state-usergroup-rules/3d0c2a58-52c1-4c1c-9f11-9d0f5a1c7b10/apply" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regra aplicada

json

{ "assigned": 124 }

Campos da resposta

assignedinteger

Vínculos novos criados. 0 quando todos já estavam no grupo, quando o estado não tem clientes ou quando a regra não existe.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem `manage_vendors`, ou módulo desligado	`{"error":"module_disabled","module":"state-usergroup-rules"}`
500	`id` que não é UUID, ou falha interna	`{"error":"failed to apply state usergroup rule","detail":"..."}`

Excluir uma regra

Remove a regra. Os clientes que já foram colocados no grupo continuam nele: a exclusão só impede novas atribuições. Para tirar clientes do grupo, use a gestão de grupos de clientes.

DELETE/api/v1/admin/state-usergroup-rules/{id}Admin

Exclui uma regra de grupo por estado

Parâmetros de caminho

iduuidobrigatório

Id da regra.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/state-usergroup-rules/3d0c2a58-52c1-4c1c-9f11-9d0f5a1c7b10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regra excluída

json

{ "message": "state usergroup rule deleted" }

Erros

Status	Quando	Corpo
500	Regra inexistente (deveria ser 404), `id` que não é UUID, ou falha interna	`{"error":"failed to delete state usergroup rule","detail":"state usergroup rule 0000... not found"}`
401 / 403	Sem token, sem `manage_vendors`, ou módulo desligado	`{"error":"module_disabled","module":"state-usergroup-rules"}`