top of page

ProvAí Commerce — Documentação Técnica da API

​

1. Visão Geral

A API ProvAí Commerce permite que lojistas integrem a prova virtual de moda e acessórios (powered by IA) diretamente em seu site, e-commerce ou aplicativo, usando sua própria chave de API.

​

2. Autenticação

Toda requisição usa sua chave de API pessoal, enviada no corpo da requisição (não em header — ver Seção 4).

Gere e gerencie suas chaves na página Integrações do painel ProvAí Commerce. Cada chave é exibida apenas uma vez no momento da criação — guarde-a em local seguro.

​

3. URL Base

https://validar-chave-853701127308.us-central1.run.app

​

4. Endpoint: Prova Virtual

POST /validar-chave Content-Type: application/json

Corpo da requisição (JSON):

CampoTipoObrigatórioDescrição

chaveApistringSimSua chave de API

imagemPessoaBase64stringNão*Foto da pessoa, codificada em Base64 (sem prefixo data:image/...)

imagemProdutoUrlstringNão*URL pública da imagem do produto

*Se imagemPessoaBase64 e imagemProdutoUrl não forem enviados, o endpoint apenas valida a chave e debita 1 crédito, sem gerar imagem — útil para checagem de saldo/validação isolada.

Exemplo de requisição:

{ "chaveApi": "pv_live_xxxxxxxxxxxxxxxx", "imagemPessoaBase64": "/9j/4AAQSkZJRgABAQAAAQ...", "imagemProdutoUrl": "https://minhaloja.com/produtos/vestido-floral.jpg" }

Resposta de sucesso (200):

{ "valido": true, "lojistaId": "abc123", "creditosRestantes": 42, "resultado": { "b64": "iVBORw0KGgoAAAANSUhEUgAA..." } }

resultado.b64 é a imagem final (pessoa vestindo o produto), codificada em Base64 PNG.

​

5. Códigos de Erro

CódigoSignificadoCorpo de resposta

400chaveApi ausente ou inválida no formato{ "erro": "chaveApi obrigatoria" }

401Chave de API não encontrada/inválida{ "erro": "chave invalida" }

402Créditos insuficientes{ "erro": "creditos insuficientes" }

404Lojista não encontrado{ "erro": "lojista nao encontrado" }

500Erro interno, ou falha ao gerar a prova virtual{ "erro": "erro interno" } ou { "erro": "falha ao gerar prova virtual", "detalhe": {...} }

Importante: o crédito é debitado assim que a chave é validada, antes da geração da imagem. Se a geração falhar (erro 500 vindo do processamento de IA), o crédito já foi consumido — não há reembolso automático.

​

6. Créditos

  • Cada chamada bem-sucedida com geração de imagem consome 1 crédito.

  • Créditos não expiram enquanto a conta estiver ativa.

  • Consulte seu saldo (creditosRestantes) diretamente na resposta de cada chamada, ou no painel ProvAí Commerce.

 

7. Exemplo de Integração (JavaScript)

const response = await fetch('https://validar-chave-853701127308.us-central1.run.app/validar-chave', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ chaveApi: 'pv_live_xxxxxxxxxxxxxxxx', imagemPessoaBase64: fotoBase64, imagemProdutoUrl: 'https://minhaloja.com/produtos/vestido-floral.jpg' }) }); const data = await response.json(); if (data.resultado?.b64) { imgElement.src = 'data:image/png;base64,' + data.resultado.b64; }

​

8. Limites de Requisição (Rate Limiting)

Em definição — não implementado nesta versão da API. Nenhum limite de requisições por minuto/segundo é aplicado no momento. Esta seção será atualizada quando o rate limiting for implementado no backend.

​

9. Versionamento

Versão atual da API: v1. Mudanças que quebrem compatibilidade serão comunicadas com antecedência e disponibilizadas em uma nova versão de URL (ex: /v2/validar-chave).

​

10. Suporte

Em caso de dúvidas técnicas, entre em contato: inovaappmobileltda@gmail.com ou pelo Whastapp +5571 98952-6117

 

bottom of page