VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Dashboards

Classificação de status

Define quais status de pedido contam como receita e como venda concluída nos cards, e reaplica a regra aos cards existentes.

Os números de receita dos cards dependem de uma decisão de negócio: um pedido "Em espera" já é receita? "Enviado"? "Reembolsado"? Como cada loja tem seus próprios status, a plataforma sugere uma classificação e permite que você a ajuste. Cards de receita herdam essa classificação (status_scope.mode = store_default) e acompanham as mudanças; cards que você congelou (custom) não mudam.

Ver a classificação

GET/api/v1/admin/dashboards/status-classificationAdmin

Ver a classificação de cada status

Exemplo de requisição (ver)

bash
curl "$BASE_URL/api/v1/admin/dashboards/status-classification" \
  -H "Authorization: Bearer $TOKEN"

Resposta (ver)

200Classificação
json
{
  "statuses": [
    {
      "code": "failed",
      "name": "Failed",
      "name_pt": "Pagamento Recusado",
      "letter_code": "F",
      "type": "cancelled",
      "counts_as_revenue": false,
      "is_completed_sale": false,
      "classified": true,
      "source": "ladder",
      "reason": "admin.dashboards.statusClassification.reason.canonical_failed"
    },
    {
      "code": "shipped",
      "name": "Enviado",
      "name_pt": "Enviado",
      "letter_code": "S",
      "type": "shipped",
      "counts_as_revenue": true,
      "is_completed_sale": false,
      "classified": false,
      "source": "ladder",
      "reason": "admin.dashboards.statusClassification.reason.unclassified_fail_open"
    }
  ],
  "drift": []
}

Campos da resposta

statusesarray
Todos os status da loja, com a classificação vigente.
statuses[].codestring
Código do status.
statuses[].namestring
Nome.
statuses[].name_ptstring
Nome em português.
statuses[].letter_codestring
Letra guardada nos pedidos.
statuses[].typestring
Fase do ciclo de vida.
statuses[].counts_as_revenueboolean
Se pedidos neste status somam na receita.
statuses[].is_completed_saleboolean
Se contam como venda concluída.
statuses[].classifiedboolean
false quando nem a regra automática nem uma decisão sua cobrem o status. Nesse caso counts_as_revenue vem true (na dúvida, conta).
statuses[].sourcestring
ladderuser
ladder (regra automática) ou user (decisão sua).
statuses[].reasonstring
Chave de tradução do motivo.
statuses[].decided_atstring
Quando alguém decidiu. Só em source: user.
statuses[].decided_byuuid
Quem decidiu. Só em source: user.
driftarray
Status criados depois de cards terem sido gravados: code, store_default_card_ids e custom_card_ids. Lista vazia ou null quando está tudo em dia.

Erros (ver)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
500Falha inesperada no servidor.{"error":"failed to ..."}

Classificar um status

PUT/api/v1/admin/dashboards/status-classification/{code}Admin

Classificar um status

Parâmetros de caminho

codestringobrigatório
Código do status (shipped, Paid...).

Corpo da requisição

counts_as_revenuebooleanobrigatório
Se o status soma na receita.
is_completed_salebooleanobrigatório
Se conta como venda concluída.
reasonstring
Motivo (texto livre, para auditoria).

Exemplo de requisição (classificar)

bash
curl -X PUT "$BASE_URL/api/v1/admin/dashboards/status-classification/on_hold" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"counts_as_revenue": false, "is_completed_sale": false, "reason": "Em espera ainda não é venda"}'

Resposta (classificar)

200Classificação gravada
json
{
  "message": "classification updated",
  "cards_updated": 14
}

Campos da resposta

messagestring
Texto fixo, em inglês.
cards_updatedinteger
Cards de receita atualizados (os store_default). 0 se a reaplicação falhar.

Erros (classificar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_dashboards"}
400Corpo inválido: não é JSON, tem campo desconhecido (a leitura rejeita campos que a API não conhece) ou passa de 1 MB.{"error":"invalid request body","detail":"json: unknown field \"foo\""}
500Falha inesperada no servidor.{"error":"failed to ..."}

Reclassificar cards

POST/api/v1/admin/dashboards/status-classification/reclassifyAdmin

Reaplicar a classificação aos cards

Exemplo de requisição (reclassificar)

bash
curl -X POST "$BASE_URL/api/v1/admin/dashboards/status-classification/reclassify" \
  -H "Authorization: Bearer $TOKEN"

Resposta (reclassificar)

200Cards atualizados
json
{
  "cards_updated": 14
}

Campos da resposta

cards_updatedinteger
Quantos cards store_default foram reescritos com a lista atual de status.

Erros (reclassificar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"manage_dashboards"}
500Falha inesperada no servidor.{"error":"failed to ..."}
Mudar a classificação muda números existentes

Ao classificar um status, todos os cards store_default são reescritos na hora e passam a mostrar o novo total no próximo refresh. Cards custom não são tocados. Use reclassify depois de criar um status novo, para que os cards o incluam.

O código do status não é conferido

A rota não verifica se code existe no cadastro de status e grava o código em minúsculas. Um status cujo código tem maiúsculas (como Paid) fica registrado como paid; confira na resposta do GET se a decisão surtiu efeito.

Veja também

  • Especificação do card
  • Executar a aba
  • Status de pedido
Anterior
Compartilhar abas
Próxima
Alertas e assinaturas
Nesta página
  • Ver a classificação
  • Exemplo de requisição (ver)
  • Resposta (ver)
  • Erros (ver)
  • Classificar um status
  • Exemplo de requisição (classificar)
  • Resposta (classificar)
  • Erros (classificar)
  • Reclassificar cards
  • Exemplo de requisição (reclassificar)
  • Resposta (reclassificar)
  • Erros (reclassificar)
  • Veja também