> Crie uma sessão de captura da TruthScan, receba um webhook da foto assinada e leia os resultados com sua chave de API.

Source: https://truthscan.com/pt-br/truthscan-ai-capture-api-documentation
Documentation index: https://truthscan.com/llms.txt
Plans and pricing: https://truthscan.com/pricing

For AI agents: the documentation index is at <https://truthscan.com/llms.txt> and a Markdown version of this page is at <https://truthscan.com/pt-br/truthscan-ai-capture-api-documentation.md>.

API de Captura

[![ISO 27001](https://truthscan.com/_next/image?url=%2Fimages%2Fcertifications%2Fiso-27001.webp&w=256&q=75&dpl=dpl_2eizWT8MUuujb4NWFLnyVZj6rK4e)](https://trust.truthscan.com/?lang=en)

[![Certificado SOC 2](https://truthscan.com/_next/image?url=%2Fimages%2Fcertifications%2Fsoc2.webp&w=256&q=75&dpl=dpl_2eizWT8MUuujb4NWFLnyVZj6rK4e)](https://trust.truthscan.com/?lang=en)

[![Conforme GDPR](https://truthscan.com/_next/image?url=%2Fimages%2Fcertifications%2Fgdpr.webp&w=256&q=75&dpl=dpl_2eizWT8MUuujb4NWFLnyVZj6rK4e)](https://trust.truthscan.com/?lang=en)

[![Parceiro GASA](https://truthscan.com/_next/image?url=%2Fimages%2Fcertifications%2Fgasa.png&w=256&q=75&dpl=dpl_2eizWT8MUuujb4NWFLnyVZj6rK4e)](https://gasa.org/knowledge-base/blog/global-anti-scam-alliance-partners-with-truthscan-to-integrate-deepfake-detection-on-scam.org)

# API de Captura TruthScan

Crie um link de captura para o telefone, receba uma foto assinada e leia o resultado com sua chave de API.

## Autenticação

Crie uma chave secreta na sua [conta](https://truthscan.com/pt-br/account).

Envie-a em toda chamada no cabeçalho x-api-key ou em Authorization: Bearer. A chave precisa pertencer a uma organização com acesso à API. O link aberto no telefone não usa essa chave.

Substitua YOUR\_API\_KEY pela sua chave secreta.

## Criar uma sessão

Devolve um link de captura. inviteeEmail é obrigatório. expiresInSeconds padrão é 15 minutos e não passa de 7 dias. maxCaptures padrão é 20 e não passa de 20\. webhookUrl é opcional. Quando enviado, precisa ser https e resolver para um endereço público. webhookSecret aparece só nesta resposta. instructions é opcional: uma nota de boas-vindas e pedidos, cada um marcado como obrigatório ou não. O telefone os lista. Tocar em um abre a câmera para essa foto. Um pedido obrigatório precisa de uma foto enviada. Um opcional pode ser ignorado. instructions.success é opcional e aparece depois de Concluir. Modelos de passos ficam em /api/capture/templates com a mesma chave. Esta chamada não recebe um template id; envie esses passos em instructions.

```bash
POST /api/capture/session/create
```

Defina sendEmail como true para a TruthScan enviar o link por e-mail. Aí subject e message são obrigatórios. Coloque {link} na mensagem onde a URL de captura deve aparecer. emailSent é true só quando esse e-mail foi enviado. Caso contrário, envie captureLink você mesmo.

Guarde webhookSecret. Ele é a chave HMAC de capture.completed.

Exemplo de pedido

```bash
curl -X POST https://truthscan.com/api/capture/session/create \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "inviteeEmail": "person@example.com",
    "expiresInSeconds": 900,
    "maxCaptures": 1,
    "webhookUrl": "https://example.com/hooks/capture"
  }'
```

Exemplo de resposta

```json
{
  "sessionId": "11111111-1111-4111-8111-111111111111",
  "captureToken": "…",
  "captureUrl": "/capture/11111111-1111-4111-8111-111111111111?token=…",
  "captureLink": "https://truthscan.com/capture/11111111-1111-4111-8111-111111111111?token=…",
  "expiresAt": "2026-10-07T16:00:00.000Z",
  "expiresInSeconds": 900,
  "maxCaptures": 1,
  "challenge": "other_side",
  "webhookSecret": "…",
  "emailSent": false
}
```

## Ler resultados

Consulte a sessão até capturesUsed aumentar, ou espere o webhook. As URLs de download expiram em uma hora.

### Status da sessão

Validade, capturas usadas e a URL de webhook que você registrou.

```bash
GET /api/capture/sessions/{sessionId}
```

Exemplo de pedido

```bash
curl https://truthscan.com/api/capture/sessions/SESSION_ID \
  -H 'x-api-key: YOUR_API_KEY'
```

Exemplo de resposta

```json
{
  "sessionId": "11111111-1111-4111-8111-111111111111",
  "expiresAt": "2026-10-07T16:00:00.000Z",
  "maxCaptures": 1,
  "capturesUsed": 1,
  "inviteeEmail": "person@example.com",
  "webhookUrl": "https://example.com/hooks/capture",
  "createdAt": "2026-10-07T15:45:00.000Z"
}
```

### Listar fotos

Fotos de uma sessão, da mais nova para a mais antiga. Use page e limit (máximo 50). Cada item é um resumo mais downloadUrl. A localização da lista só inclui latitude, longitude e altitude. Busque o arquivo para precisão, direção e velocidade.

```bash
GET /api/capture/sessions/{sessionId}/assets
```

Exemplo de pedido

```bash
curl 'https://truthscan.com/api/capture/sessions/SESSION_ID/assets?page=1&limit=20' \
  -H 'x-api-key: YOUR_API_KEY'
```

Exemplo de resposta

```json
{
  "assets": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "verificationState": "trusted",
      "trustTier": "standard",
      "decision": "passed",
      "decisionFlags": [],
      "risk": { "score": 0.95, "flags": ["geolocation_low_accuracy"] },
      "capturedAtUtc": "2026-10-07T15:50:00.000Z",
      "submittedAtUtc": "2026-10-07T15:50:01.200Z",
      "signedAtUtc": "2026-10-07T15:50:03.000Z",
      "captureToSubmitMs": 1200,
      "geolocation": {
        "latitude": 37.7749,
        "longitude": -122.4194,
        "altitude": 15,
        "altitudeAccuracyMeters": null,
        "accuracyMeters": null,
        "headingDegrees": null,
        "speedMetersPerSecond": null
      },
      "deviceModel": "iPhone",
      "devicePlatform": "iOS",
      "inviteeEmail": "person@example.com",
      "thumbnailUrl": "https://…",
      "downloadUrl": "https://…"
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 1,
    "total": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}
```

### Obter uma foto

O mesmo registro da página de detalhe da captura, mais assetUrl do JPEG assinado. O exemplo mostra os campos em que você decide o fluxo. device também inclui tela, lista de câmeras, GPU e entrada. sensors.geolocation repete o objeto de localização.

```bash
GET /api/capture/assets/{assetId}
```

Exemplo de pedido

```bash
curl https://truthscan.com/api/capture/assets/ASSET_ID \
  -H 'x-api-key: YOUR_API_KEY'
```

Exemplo de resposta

```json
{
  "id": "22222222-2222-4222-8222-222222222222",
  "sessionId": "11111111-1111-4111-8111-111111111111",
  "verificationState": "trusted",
  "trustTier": "standard",
  "decision": "review",
  "decisionFlags": [{ "code": "device_clock_skew", "class": "contextual" }, { "code": "gps_ip_distance_yellow", "class": "informational" }],
  "duplicateOf": null,
  "reviewReason": null,
  "imageAnalysis": {
    "status": "ready",
    "verdict": "real",
    "labelConfidence": 98.4,
    "agreement": "strong",
    "screenRecapture": false,
    "qualityWarnings": [],
    "indicators": [],
    "description": "A person holding a driver's license in a doorway.",
    "imageTags": ["person", "license", "doorway", "indoor", "document"],
    "requestedPhoto": "Front of the driver's license",
    "requestCompliance": "pass",
    "detectorVersion": null
  },
  "risk": { "score": 0.95, "flags": ["geolocation_low_accuracy"] },
  "inviteeEmail": "person@example.com",
  "mimeType": "image/jpeg",
  "assetUrl": "https://…",
  "thumbnailUrl": null,
  "capturedAtUtc": "2026-10-07T15:50:00.000Z",
  "submittedAtUtc": "2026-10-07T15:50:01.200Z",
  "serverReceivedAtUtc": "2026-10-07T15:50:02.000Z",
  "signedAtUtc": "2026-10-07T15:50:03.000Z",
  "createdAtUtc": "2026-10-07T15:50:03.100Z",
  "captureToSubmitMs": 1200,
  "timing": {
    "capturedAtUtc": "2026-10-07T15:50:00.000Z",
    "submittedAtUtc": "2026-10-07T15:50:01.200Z",
    "serverReceivedAtUtc": "2026-10-07T15:50:02.000Z",
    "signedAtUtc": "2026-10-07T15:50:03.000Z",
    "captureToSubmitMs": 1200
  },
  "geolocation": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": 15,
    "altitudeAccuracyMeters": 10,
    "accuracyMeters": 12,
    "headingDegrees": null,
    "speedMetersPerSecond": null
  },
  "deviceModel": "iPhone",
  "devicePlatform": "iOS",
  "device": {
    "browserName": "Mobile Safari",
    "platform": "iOS",
    "timezone": "America/Los_Angeles",
    "screenWidth": 390,
    "screenHeight": 844,
    "camera": { "width": 1920, "height": 1080, "facingMode": "environment" },
    "connection": { "effectiveType": "4g", "downlinkMbps": 10, "rttMs": 50 },
    "network": {
      "publicIp": "203.0.113.10",
      "publicIpv4": "203.0.113.10",
      "ipSource": "cloudflare_visitor",
      "browserReportedIpv4": "203.0.113.10",
      "ipObservations": [
        { "address": "203.0.113.10", "source": "cloudflare_visitor", "trusted": true },
        { "address": "203.0.113.10", "source": "browser_stun", "trusted": false }
      ],
      "privacy": { "status": "not_detected", "reasons": [] },
      "country": "US",
      "city": "San Francisco"
    }
  },
  "sensors": {
    "gyroVariance": 0.02,
    "accelVariance": 0.11,
    "motionSampleCount": 24,
    "gyroSampleCount": 12,
    "accelSampleCount": 12,
    "permissionDenied": {
      "camera": false,
      "geolocation": false,
      "motion": false
    }
  }
}
```

### Campos do resultado

Decida com decision. verificationState só diz se a assinatura é válida. assetUrl e downloadUrl expiram depois de uma hora.

| Campo             | Significado                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| verificationState | Só a assinatura: trusted, valid\_untrusted, invalid ou none. trusted significa que a TruthScan assinou o arquivo.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| decision          | passed, review, unable\_to\_verify ou rejected                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| decisionFlags     | Por que a decisão foi essa. hard rejeita, contextual pede revisão, unavailable indica que a verificação não rodou e informational registra evidência sem mudar o resultado. A distância GPS/IP é verde abaixo de 50 km, amarela entre 50 e 150 km e vermelha acima disso. Amarelo e vermelho aparecem como alerta, mas sozinhos não pedem revisão. Uma combinação de plataforma e GPU fora do catálogo também pede revisão. Desfoque, escuridão ou baixa qualidade pedem revisão. Um relógio de celular a mais de 5 minutos do servidor ao enviar a foto para assinatura pede revisão.                                                                                                                                                                           |
| imageAnalysis     | Evidência consultiva do detector de imagem. description traz uma ou duas frases sobre o que há na foto, ou null quando essa etapa não termina. imageTags traz até cinco tags curtas da mesma foto e fica vazio quando essa etapa não termina. requestedPhoto é o passo da foto para o qual esta imagem foi tirada, ou null quando o link não tinha passos. requestCompliance é pass, fail ou review para esse passo, ou null quando não havia passo ou a conferência não terminou. fail ou review define decision como review, salvo quando decision já é rejected. screenRecapture true exige revisão e uma nova captura ao vivo. verdict e labelConfidence não mudam decision no modo de observação; a confiança é do modelo, não uma probabilidade de fraude. |
| trustTier         | standard ou high. Não é um veredito de autenticidade.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| risk.score        | Completude dos sensores, de 0 a 1\. Não é uma pontuação de autenticidade.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| risk.flags        | camera\_permission\_denied, geolocation\_permission\_denied, geolocation\_missing, geolocation\_low\_accuracy, motion\_permission\_denied, motion\_samples\_missing, gyro\_missing, zero\_gyro\_variance, accel\_missing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| geolocation       | latitude, longitude, altitude, altitudeAccuracyMeters, accuracyMeters, headingDegrees, speedMetersPerSecond                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| device            | Navegador, plataforma, user agent, fuso, tela, câmera, conexão e rede. network inclui o IP público selecionado, sua origem, cada observação IP validada do servidor, cabeçalhos e navegador, proprietário ASN, localização aproximada e avaliação de VPN/proxy. Um sinal de privacidade indica revisão, não é prova.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| sensors           | Contagens combinada, do giroscópio e do acelerômetro; gyroVariance; accelVariance e permissionDenied de câmera, geolocalização e movimento                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| timing            | Horários do obturador, do envio, do recebimento no servidor e da assinatura, mais captureToSubmitMs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

## Webhook

Depois de uma captura confiável, a TruthScan envia POST capture.completed para webhookUrl. Redirecionamentos não são seguidos. O corpo não inclui a localização precisa. Busque o arquivo para o registro completo.

Leia X-TruthScan-Signature. O formato é t=<segundos unix>,v1=<hex>. Calcule HMAC-SHA256 de t + "." + o corpo bruto com webhookSecret e rejeite timestamps com mais de cinco minutos de diferença.

Exemplo de corpo

```json
{
  "id": "…",
  "type": "capture.completed",
  "data": {
    "sessionId": "11111111-1111-4111-8111-111111111111",
    "assetId": "22222222-2222-4222-8222-222222222222",
    "verificationState": "trusted",
    "trustTier": "standard",
    "decision": "review",
    "flags": ["device_clock_skew", "gps_ip_distance_yellow"],
    "imageAnalysis": {
      "status": "ready",
      "verdict": "real",
      "labelConfidence": 98.4,
      "agreement": "strong",
      "screenRecapture": false,
      "qualityWarnings": [],
      "indicators": [],
      "description": "A person holding a driver's license in a doorway.",
      "imageTags": ["person", "license", "doorway", "indoor", "document"],
      "requestedPhoto": "Front of the driver's license",
      "requestCompliance": "pass",
      "detectorVersion": null
    },
    "capturedAtUtc": "2026-10-07T15:50:00.000Z"
  }
}
```

## Limites de taxa

Os limites são compartilhados entre instâncias. Um 429 inclui Retry-After em segundos.

### Limites

Cada chamada conta como um pedido contra o IP e contra a organização.

| Caminho             | Balde       | Limite         |
| ------------------- | ----------- | -------------- |
| Criar e ler         | IP          | 600 / minuto   |
| Criar e ler         | Organização | 2.000 / minuto |
| Captura no telefone | IP          | 60 / minuto    |
| Captura no telefone | Organização | 2.000 / minuto |

Criar e ler cobre POST /api/capture/session/create e as três rotas GET de resultado. A captura no telefone cobre nonce, upload-url e assinatura. O telefone não envia sua chave de API. Organizações no teste grátis têm limites menores: 120 pedidos de criar e ler por minuto por IP e 300 por organização, e 60 pedidos do telefone por minuto por IP e 300 por organização. E-mails de convite ficam em 30 por hora e 150 por dia. Esse limite responde 429 com o código INVITE\_EMAIL\_LIMIT.

### Resposta limitada

Espere Retry-After e envie o pedido de novo.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 12
}
```

O que ler

- Retry-After: segundos até a janela reiniciar
- retryAfter: o mesmo valor no corpo JSON

Boas práticas

- Consulte o status da sessão em vez de listar arquivos em um loop curto.
- Prefira o webhook quando puder receber callbacks HTTPS.

## Erros

Chamadas com falha devolvem JSON com error e code.

401 e 403 significam que a chave não pode ser usada. 404 significa que a sessão ou o arquivo não está na sua organização.

| Código                    | Significado                                                                                           |
| ------------------------- | ----------------------------------------------------------------------------------------------------- |
| MISSING\_API\_KEY         | Sem x-api-key nem token Bearer                                                                        |
| INVALID\_API\_KEY         | Chave desconhecida, inativa ou sem organização                                                        |
| ORG\_NO\_API\_ACCESS      | O acesso à API da organização está desligado                                                          |
| INVITEE\_EMAIL\_REQUIRED  | inviteeEmail estava ausente                                                                           |
| INVITEE\_EMAIL\_INVALID   | inviteeEmail não é um endereço válido                                                                 |
| INVITE\_MESSAGE\_REQUIRED | sendEmail é true e message está ausente ou longo demais                                               |
| INVITE\_SUBJECT\_REQUIRED | sendEmail é true e subject está ausente                                                               |
| WEBHOOK\_URL\_REJECTED    | webhookUrl não é https público                                                                        |
| SESSION\_NOT\_FOUND       | Nenhuma sessão com esse id na sua organização                                                         |
| ASSET\_NOT\_FOUND         | Nenhum arquivo com esse id na sua organização                                                         |
| RATE\_LIMIT\_EXCEEDED     | Pedidos demais na janela atual                                                                        |
| INVITE\_EMAIL\_LIMIT      | Limite de e-mails de convite do teste grátis. O corpo inclui limit, window (hour ou day) e retryAfter |

## Perguntas frequentes

Como a API de Captura entra no seu backend.

Não. O telefone envia o JPEG direto para o armazenamento e a TruthScan assina. Você recebe metadados e uma URL de download.

Registre webhookUrl ao criar a sessão, ou consulte GET /api/capture/sessions/{sessionId} até capturesUsed aumentar.

Precisa ser https, não pode incluir credenciais e precisa resolver só para um endereço público. Hosts privados, de loopback e link-local são rejeitados.

### Meu servidor envia a foto?

### Como sei que a captura terminou?

### Posso escolher qualquer URL de webhook?
