Hosted Flow

Captura autenticada via redirect para capture.provvi.com.br. A forma mais simples de integração — não requer instalação de SDK.

Como funciona

1. Seu backend cria uma sessão via API e recebe um token
2. Seu frontend redireciona o usuário para a URL de captura
3. O usuário captura as fotos na interface Provvi
4. Após concluir, o usuário é redirecionado de volta para o seu redirect_uri
5. Seu backend consulta os resultados ou recebe via webhook

Integrador                         Provvi
─────────                         ──────
Backend → POST /web/sessions ──→  token
Frontend → redirect ──────────→  capture.provvi.com.br?token=xxx
                                  (câmera → GPS → captura → assinatura)
Frontend ← redirect ──────────←  redirect_uri?provvi_session_token=xxx
Backend → GET /session-results →  fotos assinadas

URL de captura

https://capture.provvi.com.br?token=TOKEN_DA_SESSAO

Parâmetros de URL

Parâmetro	Obrigatório	Descrição
token	Sim	Token de sessão retornado por POST /web/sessions
license_key	Não	License Key do SDK. Se omitido, usa a chave embutida no deploy

Na maioria das integrações, o license_key já está configurado no deploy da página de captura. Basta passar o token.

Redirect de retorno

Quando todas as fotos da sessão são capturadas, o Hosted Flow redireciona o usuário para o redirect_uri configurado na criação da sessão, adicionando parâmetros de query:

https://seusite.com/captura/retorno?provvi_session_token=TOKEN&provvi_session_id=SESS_ID

Parâmetro	Descrição
provvi_session_token	Token original da sessão
provvi_session_id	ID da sessão para consulta de resultados

Exemplo de tratamento no retorno

// Página de retorno do integrador
const params = new URLSearchParams(window.location.search);
const sessionToken = params.get('provvi_session_token');

if (sessionToken) {
  // Consultar resultados no seu backend
  const results = await fetch(`/api/provvi/resultados/${sessionToken}`);
  const data = await results.json();
  // Exibir confirmação, redirecionar para próxima etapa, etc.
}

Perfis e enquadramento

O perfil definido na criação da sessão determina a interface de captura:

Perfil	Fotos	Enquadramento	Instruções
vehicle_inspection	3	Paisagem (retângulo horizontal)	“Enquadre o veículo inteiro na moldura”
real_estate	3	Retrato (retângulo vertical)	“Enquadre o ambiente inteiro na moldura”
high_value_item	3	Quadrado	”Enquadre o item centralizado na moldura”
demo	1	Quadrado	”Enquadre o objeto na moldura”

A interface mostra:

• Overlay semi-transparente com moldura de enquadramento
• Label da foto atual (ex: “Frente do veículo”)
• Indicadores de progresso (pontos para cada foto)
• Bússola (quando disponível)
• Instruções do perfil

Sessões multi-foto

Para perfis com mais de uma foto:

1. Cada captura é enviada individualmente para assinatura
2. Após assinatura, a interface avança automaticamente para a próxima foto
3. O progresso é mostrado com indicadores visuais
4. O redirect só ocorre quando todas as fotos forem capturadas

Validação de licença

O Hosted Flow valida a licença antes de iniciar a captura:

• Se o license_key for passado na URL, usa esse
• Caso contrário, usa a chave embutida no deploy (LICENSE_KEY)
• Se a licença for inválida, exibe mensagem de erro com o motivo

Motivos de rejeição:

Reason	Mensagem
INVALID_KEY	Chave de licença não reconhecida
REVOKED	Licença revogada
EXPIRED	Contrato expirado
VOLUME_EXCEEDED	Volume de capturas excedido
CLIENT_SUSPENDED	Cliente suspenso

Integração backend-a-backend

Criar sessão

# Python — exemplo
import requests

response = requests.post(
    'https://API_BASE/web/sessions',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'SUA_API_KEY',        # segredo do backend
    },
    json={
        'reference_id': 'VIN-9BWZZZ377VT004251',
        'redirect_uri': 'https://seusite.com/captura/retorno',
        'webhook_url': 'https://seusite.com/api/provvi/webhook',
        'profile': 'vehicle_inspection',
    }
)

data = response.json()
token = data['token']
capture_url = f'https://capture.provvi.com.br?token={token}'

Receber webhook

@app.route('/api/provvi/webhook', methods=['POST'])
def provvi_webhook():
    payload = request.json
    session_id = payload['session_id']
    reference_id = payload['reference_id']
    jpeg_url = payload['authenticated_jpeg_url']

    # Armazenar URLs, atualizar status no seu banco, etc.
    db.update_capture(reference_id, session_id=session_id, jpeg_url=jpeg_url)

    return '', 200

Consultar resultados

response = requests.get(f'https://API_BASE/web/session-results/{token}')
data = response.json()

for photo in data['photos']:
    print(f"Foto {photo['order']}: {photo['label']}")
    print(f"  JPEG: {photo['authenticated_jpeg_url']}")
    print(f"  GPS: {photo['gps_lat']}, {photo['gps_lon']}")
    print(f"  Hash: {photo['frame_hash_hex']}")

Vantagens do Hosted Flow

• Zero dependência no frontend — não instala SDK, não importa módulos
• Sempre atualizado — melhorias na interface refletem automaticamente
• Mobile-first — otimizado para câmeras de celular
• Cross-platform — funciona em qualquer browser moderno

Limitações

• Interface não é customizável (cores, layout, textos são do Provvi)
• Requer redirect — o usuário sai temporariamente do seu site/app
• Para controle total da UX, use o Web SDK ou os SDKs nativos