API atual/Referência completa/Conta do seller

Saúde do seller

Indicadores de despacho, qualidade dos anúncios e recálculo de nota do seller.

O painel de saúde do seller mostra dois lados da operação: o despacho (a loja está enviando dentro do prazo prometido?) e a qualidade dos anúncios (fotos, atributos, descrição, título, estoque). Os dados são calculados pela plataforma a partir dos pedidos dos últimos 30 dias e dos produtos do seller.

GET/api/v1/vendor/health/summarySeller

Indicadores de despacho

Devolve os indicadores de despacho dos últimos 30 dias, a faixa de cor resultante e os pedidos que estão perto de estourar o prazo.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/health/summary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Indicadores

json

{
  "late_dispatch_rate": 0.08,
  "band": "yellow",
  "avg_handling_hours": 30.5,
  "p90_handling_hours": 61.2,
  "promised_days": 2,
  "stockout_rate": 0.03,
  "at_risk_orders": [
    {
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "order_number": "PEDIDO-20261010-0004",
      "hours_left": 6.5
    }
  ]
}

Campos da resposta

late_dispatch_ratenumber

Fração (0 a 1) dos pedidos despachados no período que passaram do prazo prometido.

bandstring

greenyellowred

Faixa derivada da taxa de atraso: green até 5%, yellow até 15%, red acima disso.

avg_handling_hoursnumber

Média, em horas, entre o pedido e o despacho.

p90_handling_hoursnumber

Percentil 90 dessas horas: 9 em cada 10 pedidos saem em até esse tempo.

promised_daysinteger

Prazo prometido de despacho, em dias, configurado no seller (padrão 2).

stockout_ratenumber

Fração (0 a 1) dos pedidos do período que foram cancelados.

at_risk_ordersobject[]

Até 50 pedidos ainda não despachados cujo prazo vence em menos de 24 horas.

at_risk_orders[].order_iduuid

Id do pedido.

at_risk_orders[].order_numberstring

Número do pedido mostrado ao cliente.

at_risk_orders[].hours_leftnumber

Horas até o prazo. Negativo quando já estourou.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O token não pertence a um seller vinculado a uma loja.	`{"error":"no vendor account associated with this user"}`
500	Falha ao calcular.	`{"error":"failed to compute summary","detail":"..."}`

GET/api/v1/vendor/health/listingsSeller

Qualidade dos anúncios

Lista a nota de qualidade de cada produto do seller, dos piores para os melhores, com os problemas encontrados. A nota vai de 0 a 100: good a partir de 80, improve de 50 a 79, critical abaixo de 50.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Parâmetros de consulta

bandstring

goodimprovecritical

Filtra por faixa de qualidade.

pageintegerpadrão: 1

Página, a partir de 1. O tamanho da página é fixo em 20.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/health/listings?band=critical&page=1" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Anúncios

json

{
  "items": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Camiseta Algodão Preta",
      "score": 42,
      "band": "critical",
      "issues": [
        "missing_photos",
        "short_description"
      ]
    }
  ],
  "total": 1
}

Campos da resposta

itemsobject[]

Anúncios da página.

items[].product_iduuid

Id do produto.

items[].namestring

Nome do produto.

items[].scoreinteger

Nota de 0 a 100.

items[].bandstring

goodimprovecritical

Faixa da nota.

items[].issuesstring[]

missing_photoslow_attributesshort_descriptionbad_titleout_of_stock

Problemas encontrados.

totalinteger

Total de anúncios que atendem ao filtro, todas as páginas.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O token não pertence a um seller vinculado a uma loja.	`{"error":"no vendor account associated with this user"}`
500	Falha ao listar.	`{"error":"failed to list listings","detail":"..."}`

POST/api/v1/vendor/health/listings/{productId}/ai-fixSeller

Pedir proposta de correção do anúncio

Recalcula a nota do produto e devolve a estrutura de uma proposta de correção (título, descrição, atributos e imagens). Não recebe corpo.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Parâmetros de caminho

productIduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/health/listings/c3f92551-9dda-4fc7-b518-353d1c4e4035/ai-fix" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Proposta

json

{
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "title": "",
  "description": "",
  "attributes": [],
  "images": [],
  "note": "ai_fill_available"
}

Campos da resposta

product_iduuid

O produto.

titlestring

Título sugerido.

descriptionstring

Descrição sugerida.

attributesobject[]

Atributos sugeridos.

imagesobject[]

Imagens sugeridas.

notestring

Indicador do estado do recurso.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O token não pertence a um seller vinculado a uma loja.	`{"error":"no vendor account associated with this user"}`
500	Falha ao montar a proposta.	`{"error":"failed to build proposal","detail":"..."}`

POST/api/v1/vendor/health/listings/{productId}/ai-fix/applySeller

Aplicar a correção e recalcular

Recalcula e grava a nota de qualidade do produto com os dados atuais. Não recebe corpo e não altera o produto. Chame depois de corrigir um anúncio para ver a nota nova em health/listings.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Parâmetros de caminho

productIduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/health/listings/c3f92551-9dda-4fc7-b518-353d1c4e4035/ai-fix/apply" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nota recalculada

json

{
  "applied": true
}

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O token não pertence a um seller vinculado a uma loja.	`{"error":"no vendor account associated with this user"}`
500	Produto inexistente ou falha ao recalcular.	`{"error":"failed to apply","detail":"..."}`

Veja também

Saúde do seller

Indicadores de despacho, qualidade dos anúncios e recálculo de nota do seller.

GET/api/v1/vendor/health/summarySeller

Indicadores de despacho

Devolve os indicadores de despacho dos últimos 30 dias, a faixa de cor resultante e os pedidos que estão perto de estourar o prazo.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/health/summary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Indicadores

json

{
  "late_dispatch_rate": 0.08,
  "band": "yellow",
  "avg_handling_hours": 30.5,
  "p90_handling_hours": 61.2,
  "promised_days": 2,
  "stockout_rate": 0.03,
  "at_risk_orders": [
    {
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "order_number": "PEDIDO-20261010-0004",
      "hours_left": 6.5
    }
  ]
}

Campos da resposta

late_dispatch_ratenumber

Fração (0 a 1) dos pedidos despachados no período que passaram do prazo prometido.

bandstring

greenyellowred

Faixa derivada da taxa de atraso: green até 5%, yellow até 15%, red acima disso.

avg_handling_hoursnumber

Média, em horas, entre o pedido e o despacho.

p90_handling_hoursnumber

Percentil 90 dessas horas: 9 em cada 10 pedidos saem em até esse tempo.

promised_daysinteger

Prazo prometido de despacho, em dias, configurado no seller (padrão 2).

stockout_ratenumber

Fração (0 a 1) dos pedidos do período que foram cancelados.

at_risk_ordersobject[]

Até 50 pedidos ainda não despachados cujo prazo vence em menos de 24 horas.

at_risk_orders[].order_iduuid

Id do pedido.

at_risk_orders[].order_numberstring

Número do pedido mostrado ao cliente.

at_risk_orders[].hours_leftnumber

Horas até o prazo. Negativo quando já estourou.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O token não pertence a um seller vinculado a uma loja.	`{"error":"no vendor account associated with this user"}`
500	Falha ao calcular.	`{"error":"failed to compute summary","detail":"..."}`

GET/api/v1/vendor/health/listingsSeller

Qualidade dos anúncios

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Parâmetros de consulta

bandstring

goodimprovecritical

Filtra por faixa de qualidade.

pageintegerpadrão: 1

Página, a partir de 1. O tamanho da página é fixo em 20.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/health/listings?band=critical&page=1" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Anúncios

json

{
  "items": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Camiseta Algodão Preta",
      "score": 42,
      "band": "critical",
      "issues": [
        "missing_photos",
        "short_description"
      ]
    }
  ],
  "total": 1
}

Campos da resposta

itemsobject[]

Anúncios da página.

items[].product_iduuid

Id do produto.

items[].namestring

Nome do produto.

items[].scoreinteger

Nota de 0 a 100.

items[].bandstring

goodimprovecritical

Faixa da nota.

items[].issuesstring[]

missing_photoslow_attributesshort_descriptionbad_titleout_of_stock

Problemas encontrados.

totalinteger

Total de anúncios que atendem ao filtro, todas as páginas.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O token não pertence a um seller vinculado a uma loja.	`{"error":"no vendor account associated with this user"}`
500	Falha ao listar.	`{"error":"failed to list listings","detail":"..."}`

POST/api/v1/vendor/health/listings/{productId}/ai-fixSeller

Pedir proposta de correção do anúncio

Recalcula a nota do produto e devolve a estrutura de uma proposta de correção (título, descrição, atributos e imagens). Não recebe corpo.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Parâmetros de caminho

productIduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/health/listings/c3f92551-9dda-4fc7-b518-353d1c4e4035/ai-fix" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Proposta

json

{
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "title": "",
  "description": "",
  "attributes": [],
  "images": [],
  "note": "ai_fill_available"
}

Campos da resposta

product_iduuid

O produto.

titlestring

Título sugerido.

descriptionstring

Descrição sugerida.

attributesobject[]

Atributos sugeridos.

imagesobject[]

Imagens sugeridas.

notestring

Indicador do estado do recurso.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O token não pertence a um seller vinculado a uma loja.	`{"error":"no vendor account associated with this user"}`
500	Falha ao montar a proposta.	`{"error":"failed to build proposal","detail":"..."}`

POST/api/v1/vendor/health/listings/{productId}/ai-fix/applySeller

Aplicar a correção e recalcular

Recalcula e grava a nota de qualidade do produto com os dados atuais. Não recebe corpo e não altera o produto. Chame depois de corrigir um anúncio para ver a nota nova em health/listings.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário (veja Tokens).

Parâmetros de caminho

productIduuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/health/listings/c3f92551-9dda-4fc7-b518-353d1c4e4035/ai-fix/apply" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nota recalculada

json

{
  "applied": true
}

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"invalid or expired token"}`
403	O token não pertence a um seller vinculado a uma loja.	`{"error":"no vendor account associated with this user"}`
500	Produto inexistente ou falha ao recalcular.	`{"error":"failed to apply","detail":"..."}`