API Pública v1.0

Documentação da API

Integre o Provador Virtual VesteGO ao seu e-commerce. API REST com autenticação via API Key, processamento assíncrono e resposta em JSON.

Swagger UI Interativo Criar Conta Grátis

Visão Geral

Base URL	`https://api.vestego.app`
Formato	JSON (`Content-Type: application/json`)
Autenticação	Header `X-API-Key`
Protocolo	HTTPS obrigatório
Docs Interativos	/api/v1/docs

Autenticação

Como obter sua API Key

Acesse o Dashboard do VesteGO
Vá em Configurações → API Keys
Clique em Criar chave e dê um nome (ex: "Integração Shopify")
Copie a chave imediatamente — ela só é exibida uma vez

Segurança: Nunca exponha sua API key em código client-side (JavaScript no navegador). Use sempre no backend do seu e-commerce.

Formato da chave: vgo_xxxxxxxxxxxxxxxx (prefixo vgo_ + string aleatória)

Inclua o header em todas as requisições:

curl -H "X-API-Key: vgo_sua_chave_aqui" \
  https://api.vestego.app/api/v1/garments

Endpoints

GET/api/v1/garmentsAPI Key

Listar peças do catálogo

Retorna as peças de roupa cadastradas na sua loja. Use os parâmetros para filtrar por categoria e paginar os resultados.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`category`	string	Não	Filtrar por categoria (ex: camiseta, calca). Máximo 50 caracteres, alfanumérico.
`limit`	int	Não	Máximo de itens retornados (1–100, padrão 20)
`offset`	int	Não	Offset para paginação (0–10000)

Exemplo cURL

curl -H "X-API-Key: vgo_sua_chave_aqui" \
  "https://api.vestego.app/api/v1/garments?category=camisa&limit=10"

Resposta 200

[
  {
    "id": 1,
    "name": "Camisa Social Azul",
    "category": "camisa",
    "image_url": "garments/uuid.jpg"
  }
]

Respostas possíveis

200 — Lista de peças retornada com sucesso400 — Parâmetro category inválido401 — API key ausente ou inválida429 — Rate limit excedido

GET/api/v1/garments/{garment_id}API Key

Obter peça por ID

Retorna detalhes de uma peça específica. Retorna 404 se a peça não existir ou não pertencer à sua loja.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`garment_id`	int	Sim	ID da peça (path parameter)

Exemplo cURL

curl -H "X-API-Key: vgo_sua_chave_aqui" \
  "https://api.vestego.app/api/v1/garments/1"

Resposta 200

{
  "id": 1,
  "name": "Camisa Social Azul",
  "category": "camisa",
  "image_url": "garments/uuid.jpg"
}

Respostas possíveis

200 — Peça encontrada401 — API key ausente ou inválida404 — Peça não encontrada

POST/api/v1/tryonAPI Key

Criar try-on

Cria um job de try-on assíncrono. Consome 1 crédito. O processamento leva em média 60–120 segundos. Consulte o status com GET /api/v1/tryon/{job_id}.

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
`garment_id`	int	Sim	ID da peça do seu catálogo
`model_image_url`	string	Não	URL HTTPS da foto do cliente (corpo inteiro). Máximo 2048 caracteres. IPs privados e localhost são bloqueados.

Exemplo cURL

curl -X POST -H "X-API-Key: vgo_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"garment_id": 1, "model_image_url": "https://exemplo.com/foto.jpg"}' \
  "https://api.vestego.app/api/v1/tryon"

Resposta 200

{
  "job_id": 42,
  "status": "pending",
  "message": "Try-on criado com sucesso. Use GET /api/v1/tryon/42 para verificar status."
}

Respostas possíveis

200 — Try-on criado com sucesso (status: pending)402 — Créditos insuficientes404 — Peça não encontrada429 — Rate limit ou limite de jobs simultâneos excedido503 — Serviço temporariamente indisponível

GET/api/v1/tryon/{job_id}API Key

Consultar status do try-on

Retorna o status atual de um job de try-on. Use polling a cada 2–3 segundos até o status ser 'completed' ou 'failed'.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`job_id`	int	Sim	ID do job retornado no POST /api/v1/tryon

Exemplo cURL

curl -H "X-API-Key: vgo_sua_chave_aqui" \
  "https://api.vestego.app/api/v1/tryon/42"

Resposta 200

{
  "job_id": 42,
  "status": "completed",
  "result_url": "https://storage.vestego.app/tryon/uuid.jpg",
  "error_message": null,
  "processing_time_sec": 12.5,
  "created_at": "2026-02-15T14:30:00",
  "completed_at": "2026-02-15T14:30:12"
}

Respostas possíveis

200 — Status retornado (pending / processing / completed / failed)401 — API key ausente ou inválida404 — Job não encontrado

GET/api/v1/creditsAPI Key

Consultar créditos restantes

Retorna os créditos restantes e o plano atual da sua conta.

Exemplo cURL

curl -H "X-API-Key: vgo_sua_chave_aqui" \
  "https://api.vestego.app/api/v1/credits"

Resposta 200

{
  "credits_remaining": 45.5,
  "plan": "pro"
}

Respostas possíveis

200 — Créditos e plano retornados401 — API key ausente ou inválida404 — Assinatura não encontrada

Códigos de Erro

Código	Significado
`400`	Requisição inválida (parâmetros ou body incorretos)
`401`	API key ausente, inválida ou desativada
`402`	Créditos insuficientes para a operação
`404`	Recurso não encontrado ou não pertence à sua loja
`429`	Rate limit excedido — aguarde e tente novamente
`503`	Serviço temporariamente indisponível

Formato de erro padrão:

{
  "detail": "Créditos insuficientes"
}

Rate Limits

Os limites abaixo se aplicam aos endpoints de try-on. Cada API key também tem um limite global de 60 requisições por minuto.

Plano	Try-on / min	Jobs simultâneos
Basic	10	1
Plus	10	2
Pro	15	5
Business	50	10
Enterprise	250	50

Ao exceder o limite, a API retorna 429 com header Retry-After: 60 (segundos).

Fluxo Recomendado

Listar peças

GET /api/v1/garments

Busque as peças do seu catálogo

Criar try-on

POST /api/v1/tryon

Envie garment_id e receba job_id

Polling

GET /api/v1/tryon/{id}

A cada 2–3s até status = completed

Exibir resultado

result_url

Mostre a imagem ao seu cliente

Dica: Tempo médio de processamento é de 60–120 segundos. Faça polling a cada 2–3 segundos. Verifique os créditos restantes com GET /api/v1/credits antes de criar jobs em lote.

Em Breve

Estamos trabalhando nestas funcionalidades para simplificar ainda mais a integração.

Em Breve

Widget JS Embeddable

Integre o provador virtual ao seu site com uma única linha de HTML.

Em Breve

SDK JavaScript / TypeScript

Biblioteca oficial para integração simplificada no frontend e backend Node.js.

Em Breve

SDK Python

Biblioteca oficial para integração em backends Python (Django, Flask, FastAPI).

Em Breve

Webhooks

Receba notificações automáticas quando um try-on for concluído, sem precisar de polling.

Em Breve

Plugin Shopify

Instalação em 1 clique diretamente da App Store do Shopify.

Em Breve

Plugin WooCommerce

Plugin oficial WordPress para integração nativa com WooCommerce.

Precisa de ajuda com a integração?

Nossa equipe técnica está disponível para ajudar na integração com seu e-commerce.

Falar com Suporte Central de Ajuda