Ações em lote

Desativa ou reativa muitos usuários de uma vez, por critério, com simulação e confirmação obrigatórias.

Use o lote quando a mesma ação vale para muitos cadastros: desativar quem não compra há dois anos, reativar um grupo que foi desativado por engano. Em vez de uma chamada por usuário, você descreve o recorte (um filtro) e a plataforma resolve a lista no servidor.

Há duas ações: deactivate (status D) e activate (volta para A). Excluir cadastros em massa não é oferecido. activate reativa somente quem está desativado; cadastro pendente é aprovado um a um (Alterar cliente).

O fluxo em dois passos

O lote nunca executa de primeira. Ele exige que você simule, olhe a contagem e a amostra, e só então confirme:

Simule
Chame a rota com o seu filter e "simulate": true. A resposta traz total (quantos usuários o recorte alcança), sample (até 10 exemplos, com o status de antes e de depois) e um confirm_token.
Confira o recorte
Mostre o total e a amostra a quem decide. Se o número não é o esperado, ajuste o filtro e simule de novo.
Confirme
Repita o mesmo corpo, sem simulate, com o confirm_token recebido. Se o recorte mudou desde a simulação (cresceu), o token é recusado e você precisa simular de novo. O token tem validade: o campo expires_at da simulação diz até quando.

POST/api/v1/admin/users/bulkAdmin

Desativa ou reativa usuários em lote

Exige manage_users. Sem simulação prévia, a resposta é 428.

Corpo da requisição

actionstringobrigatório

deactivateactivate

deactivate desativa quem o filtro alcança (e ainda não está desativado). activate reativa só os desativados que o filtro alcança.

filterobject

O recorte. Todas as chaves são opcionais e se combinam (E lógico), mas é preciso informar pelo menos uma (ou ids).

user_typestring

customervendoradmin

Tipo de usuário.

current_statusstring

activedisabledpendingADP

Status atual. status é sinônimo. Com activate, só disabled (ou nada) é aceito.

without_orders_for_daysinteger

Sem pedido nos últimos N dias. Quem nunca comprou também entra.

never_orderedboolean

true: nunca fez pedido.

person_typestring

PFPJ

Tipo de pessoa.

has_cnpjboolean

true: com CNPJ.

email_containsstring

Parte do e-mail.

name_containsstring

Parte do nome.

last_login_beforestring

Sem login desde esta data (AAAA-MM-DD). Quem nunca entrou é medido pela data de cadastro.

email_verifiedboolean

E-mail verificado ou não.

has_limitboolean

true: já tem limite de crédito.

created_afterstring

Criado a partir de (AAAA-MM-DD).

created_beforestring

Criado antes de (AAAA-MM-DD).

idsarray

Lista de ids (UUID) a incluir.

exclude_idsarray

Ids a deixar de fora.

allboolean

true: a base inteira. Use só quando a pessoa pediu "todos" de forma explícita.

idsarray

Atalho: lista de ids no lugar do filter. Também passa por simulação e confirmação.

simulateboolean

true: só simula, não altera nada.

confirm_tokenstring

Token devolvido pela simulação. Obrigatório para executar.

Exemplo de requisição

Simulação seguida de execução:

bash

# 1. Simular
curl -X POST "$BASE_URL/api/v1/admin/users/bulk" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "action": "deactivate",
    "filter": {"user_type": "customer", "current_status": "active", "without_orders_for_days": 730},
    "simulate": true
  }'

# 2. Executar, com o confirm_token da resposta anterior
curl -X POST "$BASE_URL/api/v1/admin/users/bulk" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "action": "deactivate",
    "filter": {"user_type": "customer", "current_status": "active", "without_orders_for_days": 730},
    "confirm_token": "eyJ0IjoiZGZl..."
  }'

Resposta

200Simulação

json

{
  "simulate": true,
  "action": "deactivate",
  "description": "Desativar cadastros",
  "total": 1,
  "sample": [
    { "id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f", "name": "Padaria Pão Doce Ltda", "before": "A", "after": "D" }
  ],
  "confirm_token": "eyJ0IjoiZGZlMjU1NWUtYmZkMC00MWE4...",
  "expires_at": "2026-10-11T22:07:16.652274129Z",
  "async": false,
  "by": "filter"
}

200Execução concluída na hora

json

{
  "action": "deactivate",
  "by": "filter",
  "status": "done",
  "total_requested": 1,
  "affected": 1,
  "failed": []
}

202Execução virou uma tarefa

json

{
  "action": "deactivate",
  "by": "filter",
  "status": "running",
  "total_requested": 1200,
  "async": true,
  "job": { "id": "b1f0...", "status": "running", "total": 1200, "processed": 0, "affected": 0, "failed": 0, "percent": 0 }
}

Campos da resposta

totalinteger

(simulação) Quantos usuários o recorte alcança.

samplearray

(simulação) Até 10 exemplos com id, name, before (status atual) e after (status depois do lote).

confirm_tokenstring

(simulação) Token que autoriza a execução deste recorte, desta ação e deste usuário.

expires_atstring

(simulação) Até quando o token vale.

asyncboolean

true quando a execução vai rodar como tarefa em segundo plano. Recortes de 50 usuários ou mais, ou uma fila ocupada, viram tarefa.

affectedinteger

(execução) Usuários alterados.

failedarray

(execução) Falhas, cada uma com id e error. Lista vazia quando tudo deu certo. Se houver falhas, a resposta traz também partial_failure: true e message.

jobobject

(202) A tarefa: id, status, total, processed, affected, failed, percent. Acompanhe com GET /api/v1/admin/bulk-jobs/{id} até o status terminar.

Erros

Status	Quando	Corpo
400	`action` diferente de `deactivate` e `activate`	`{"error":"action must be deactivate or activate","detail":"action aceita deactivate ... Excluir cadastro em massa por filtro não é oferecido"}`
400	Sem `filter` e sem `ids`	`{"error":"filter is required","detail":"diga o recorte: user_type, current_status, without_orders_for_days (ou ids)"}`
400	Chave desconhecida no filtro	`{"error":"invalid_filter","detail":"filtro de lote inválido: chave \"foo\" não existe no filtro de usuários. Chaves aceitas: ..."}` (a lista de chaves vem na mensagem)
400	`activate` com `current_status` diferente de `disabled`	`{"error":"invalid_filter","detail":"com action activate, current_status só pode ser disabled ..."}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_users`	`{"error":"insufficient privileges","required":"manage_users"}`
409	`confirm_token` de outro pedido, ou o recorte cresceu desde a simulação	`{"error":"confirm_token_invalid","detail":"..."}`
428	Executou sem simular antes	`{"error":"simulate_required","detail":"lote por filtro exige simulação: chame a mesma rota com o mesmo corpo e \"simulate\": true, ..."}`

Mensagens de detail em português voltam como a API devolve.

Veja também

Ações em lote

Desativa ou reativa muitos usuários de uma vez, por critério, com simulação e confirmação obrigatórias.

O fluxo em dois passos

O lote nunca executa de primeira. Ele exige que você simule, olhe a contagem e a amostra, e só então confirme:

Simule
Chame a rota com o seu filter e "simulate": true. A resposta traz total (quantos usuários o recorte alcança), sample (até 10 exemplos, com o status de antes e de depois) e um confirm_token.
Confira o recorte
Mostre o total e a amostra a quem decide. Se o número não é o esperado, ajuste o filtro e simule de novo.
Confirme
Repita o mesmo corpo, sem simulate, com o confirm_token recebido. Se o recorte mudou desde a simulação (cresceu), o token é recusado e você precisa simular de novo. O token tem validade: o campo expires_at da simulação diz até quando.

POST/api/v1/admin/users/bulkAdmin

Desativa ou reativa usuários em lote

Exige manage_users. Sem simulação prévia, a resposta é 428.

Corpo da requisição

actionstringobrigatório

deactivateactivate

deactivate desativa quem o filtro alcança (e ainda não está desativado). activate reativa só os desativados que o filtro alcança.

filterobject

O recorte. Todas as chaves são opcionais e se combinam (E lógico), mas é preciso informar pelo menos uma (ou ids).

user_typestring

customervendoradmin

Tipo de usuário.

current_statusstring

activedisabledpendingADP

Status atual. status é sinônimo. Com activate, só disabled (ou nada) é aceito.

without_orders_for_daysinteger

Sem pedido nos últimos N dias. Quem nunca comprou também entra.

never_orderedboolean

true: nunca fez pedido.

person_typestring

PFPJ

Tipo de pessoa.

has_cnpjboolean

true: com CNPJ.

email_containsstring

Parte do e-mail.

name_containsstring

Parte do nome.

last_login_beforestring

Sem login desde esta data (AAAA-MM-DD). Quem nunca entrou é medido pela data de cadastro.

email_verifiedboolean

E-mail verificado ou não.

has_limitboolean

true: já tem limite de crédito.

created_afterstring

Criado a partir de (AAAA-MM-DD).

created_beforestring

Criado antes de (AAAA-MM-DD).

idsarray

Lista de ids (UUID) a incluir.

exclude_idsarray

Ids a deixar de fora.

allboolean

true: a base inteira. Use só quando a pessoa pediu "todos" de forma explícita.

idsarray

Atalho: lista de ids no lugar do filter. Também passa por simulação e confirmação.

simulateboolean

true: só simula, não altera nada.

confirm_tokenstring

Token devolvido pela simulação. Obrigatório para executar.

Exemplo de requisição

Simulação seguida de execução:

bash

# 1. Simular
curl -X POST "$BASE_URL/api/v1/admin/users/bulk" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "action": "deactivate",
    "filter": {"user_type": "customer", "current_status": "active", "without_orders_for_days": 730},
    "simulate": true
  }'

# 2. Executar, com o confirm_token da resposta anterior
curl -X POST "$BASE_URL/api/v1/admin/users/bulk" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "action": "deactivate",
    "filter": {"user_type": "customer", "current_status": "active", "without_orders_for_days": 730},
    "confirm_token": "eyJ0IjoiZGZl..."
  }'

Resposta

200Simulação

json

{
  "simulate": true,
  "action": "deactivate",
  "description": "Desativar cadastros",
  "total": 1,
  "sample": [
    { "id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f", "name": "Padaria Pão Doce Ltda", "before": "A", "after": "D" }
  ],
  "confirm_token": "eyJ0IjoiZGZlMjU1NWUtYmZkMC00MWE4...",
  "expires_at": "2026-10-11T22:07:16.652274129Z",
  "async": false,
  "by": "filter"
}

200Execução concluída na hora

json

{
  "action": "deactivate",
  "by": "filter",
  "status": "done",
  "total_requested": 1,
  "affected": 1,
  "failed": []
}

202Execução virou uma tarefa

json

{
  "action": "deactivate",
  "by": "filter",
  "status": "running",
  "total_requested": 1200,
  "async": true,
  "job": { "id": "b1f0...", "status": "running", "total": 1200, "processed": 0, "affected": 0, "failed": 0, "percent": 0 }
}

Campos da resposta

totalinteger

(simulação) Quantos usuários o recorte alcança.

samplearray

(simulação) Até 10 exemplos com id, name, before (status atual) e after (status depois do lote).

confirm_tokenstring

(simulação) Token que autoriza a execução deste recorte, desta ação e deste usuário.

expires_atstring

(simulação) Até quando o token vale.

asyncboolean

true quando a execução vai rodar como tarefa em segundo plano. Recortes de 50 usuários ou mais, ou uma fila ocupada, viram tarefa.

affectedinteger

(execução) Usuários alterados.

failedarray

(execução) Falhas, cada uma com id e error. Lista vazia quando tudo deu certo. Se houver falhas, a resposta traz também partial_failure: true e message.

jobobject

(202) A tarefa: id, status, total, processed, affected, failed, percent. Acompanhe com GET /api/v1/admin/bulk-jobs/{id} até o status terminar.

Erros

Status	Quando	Corpo
400	`action` diferente de `deactivate` e `activate`	`{"error":"action must be deactivate or activate","detail":"action aceita deactivate ... Excluir cadastro em massa por filtro não é oferecido"}`
400	Sem `filter` e sem `ids`	`{"error":"filter is required","detail":"diga o recorte: user_type, current_status, without_orders_for_days (ou ids)"}`
400	Chave desconhecida no filtro	`{"error":"invalid_filter","detail":"filtro de lote inválido: chave \"foo\" não existe no filtro de usuários. Chaves aceitas: ..."}` (a lista de chaves vem na mensagem)
400	`activate` com `current_status` diferente de `disabled`	`{"error":"invalid_filter","detail":"com action activate, current_status só pode ser disabled ..."}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_users`	`{"error":"insufficient privileges","required":"manage_users"}`
409	`confirm_token` de outro pedido, ou o recorte cresceu desde a simulação	`{"error":"confirm_token_invalid","detail":"..."}`
428	Executou sem simular antes	`{"error":"simulate_required","detail":"lote por filtro exige simulação: chame a mesma rota com o mesmo corpo e \"simulate\": true, ..."}`

Mensagens de detail em português voltam como a API devolve.