Guia de integração

Visão geral

O Hipervist, da Sentra Tecnologia, audita veículos com inteligência artificial. A partir dos dados do veículo e das mídias da vistoria, a plataforma confere os dados com a fonte oficial, analisa fotos, selfies e vídeo, e devolve o resultado da auditoria com scores, conferências e alertas, junto com um laudo em PDF assinado com Carimbo Digital ICP-Brasil, verificável por qualquer pessoa.

Esta API REST é assíncrona e atende automóveis, caminhões, motos e semirreboques. Ela é consumida por instituições financeiras, seguradoras, administradoras de consórcio, órgãos de trânsito e empresas de vistoria, cada uma como um contratante isolado dos demais.

Todos os endereços desta documentação partem de https://api.hipervist.sentratecnologia.com.br/v1.

Fluxo de uma auditoria

[POST /auditorias]                            → cria o pedido e devolve ref_auditoria
     ↓
[ envio das mídias ]                          → ver Envio de mídias, abaixo
     ↓
[GET  /auditorias/{ref_auditoria}/status]     → acompanha o processamento (ou webhook)
     ↓
[GET  /auditorias/{ref_auditoria}/resultado]  → resultado completo, com os scores
     ↓
[GET  /auditorias/{ref_auditoria}/laudo]      → link de download do laudo em PDF

O laudo é produzido no fim do processamento. O resultado e o laudo ficam disponíveis quando o status indica processamento concluído.

Envio de mídias

Uma única família de operações atende imagem, selfie e vídeo, sempre do mesmo jeito: a abertura do envio devolve uma URL de envio, temporária, para cada parte do arquivo.

[POST /auditorias/{ref_auditoria}/midias]     → abre o envio e devolve as URLs de envio
[PUT  <url de envio>]                         → bytes de cada parte
[POST .../midias/{ref_midia}/concluir]        → avisa que o envio terminou

A plataforma calcula as partes a partir do tamanho_bytes declarado. O cliente não escolhe tamanho de parte nem calcula deslocamento: uma imagem normalmente sai em uma parte, um vídeo em várias, e a sequência é a mesma nos dois casos. Cada parte é um PUT HTTPS comum, e basta uma biblioteca HTTP. Não há envio de mídia em Base64 no corpo JSON.

Autenticação

Toda requisição autenticada exige Bearer Token (OAuth 2.0, JWT), obtido em POST /auth/token pelo fluxo client_credentials.

O contratante é identificado pelo claim ref_contratante do token, que carrega o identificador público do contratante: um código opaco emitido pela Sentra, sem significado de negócio. O claim sub não é usado para autorização.

O prazo do token vem em expires_in. Ele é configurado na plataforma, hoje na ordem de minutos, e pode mudar. Leia expires_in da resposta e não fixe o valor em código.

Não há refresh token. No fluxo client_credentials o cliente já detém o client_secret, então renovar é pedir outro token, como define a RFC 6749, seção 4.4.3.

Limites de requisição

Os limites valem por contratante, numa janela deslizante de 60 segundos. Ao excedê-los, a API responde 429 com Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.

  • POST /auth/token — 60 req/min por client_id

  • POST /auth/revoke — 60 req/min por client_id

  • POST /auditorias — 1.000 req/min

  • POST .../midias — 10.000 req/min

  • POST .../midias/lote — 2.000 req/min

  • POST .../midias/{ref_midia}/concluir — 10.000 req/min, em limite próprio, separado do da abertura

  • GET .../status — 20.000 req/min

  • GET .../resultado — 1.000 req/min

  • POST .../contestacao — 100 req/min

  • GET .../laudo — 1.000 req/min

  • GET /verificacao/carimbo/{ref_carimbo} — 600 req/min por endereço IP de origem, porque é pública e sem autenticação

  • GET /webhooks/eventos — 600 req/min

Rajada. Cada limite aceita rajada de até 20% do valor numa janela de 10 segundos, para que o paralelismo legítimo não seja penalizado pela distribuição desigual dentro do minuto.

Estes são os valores padrão. O limite de cada contratante pode ser acordado em contrato e diferir dos valores acima. Use X-RateLimit-Limit em vez de fixar o valor em código.

Prefira webhook a consulta periódica. Consultar GET .../status a cada poucos segundos, em grande volume de pedidos, gera mais requisições que todo o resto da integração somado. O limite alto dessa operação existe para não travar quem faz isso, e não como recomendação. Com webhook, o mesmo volume cabe em duas ordens de grandeza menos chamadas.

Desempenho

  • Abra os envios em lote, com POST .../midias/lote, até 20 mídias por chamada. Use a abertura unitária para mídia única, reabertura e nova tentativa da mídia recusada no lote.

  • A abertura e a conclusão de envio respondem em até 200 ms. A resposta confirma o recebimento, não o processamento.

  • As partes de uma mesma mídia podem ser enviadas em paralelo e fora de ordem.

  • O processamento é assíncrono. Acompanhe por GET /auditorias/{ref_auditoria}/status ou por webhook.

Webhook

A cada evento do pedido, o Hipervist faz um POST na URL de webhook informada na criação do pedido. A referência completa — a requisição com exemplo, a verificação da assinatura com vetor de teste e a política de entrega — está na operação Catálogo de eventos de webhook.

Suporte

Dúvidas sobre a integração: produto@sentratecnologia.com.br.