---
title: "Listar transações"
method: GET
path: "/v1/transactions"
tags: ["Transactions"]
---

# Listar transações

`GET /v1/transactions`

## Request

- Base URL: `https://api.signdocs.com.br`
- URL: `https://api.signdocs.com.br/v1/transactions`
- Auth: HTTP bearer

Retorna uma lista paginada de transações do tenant autenticado.
Suporta filtros por status, usuário, grupo de documentos e intervalo de datas.

Requer scope `transactions:read`.

## Query parameters

- `status` 'CREATED' | 'DOCUMENT_UPLOADED' | 'IN_PROGRESS' | 'COMPLETED' | 'CANCELLED' | 'EXPIRED' | 'FAILED': Status possíveis de uma transação.
- `userExternalId` string
- `documentGroupId` string
- `startDate` string, date-time
- `endDate` string, date-time
- `limit` integer
- `nextToken` string

## Response `200`

Lista de transações retornada com sucesso.

- TransactionListResponse: Resposta de listagem de transações.
  - `transactions` object[], required
    - `transactionId` string, required
    - `status` 'CREATED' | 'DOCUMENT_UPLOADED' | 'IN_PROGRESS' | 'COMPLETED' | 'CANCELLED' | 'EXPIRED' | 'FAILED', required: Status possíveis de uma transação.
    - `purpose` 'DOCUMENT_SIGNATURE' | 'ACTION_AUTHENTICATION', required: Finalidade da transação.
    - `policy` Policy, required: Política de verificação de identidade da transação.
      - `profile` 'CLICK_ONLY' | 'CLICK_PLUS_OTP' | 'BIOMETRIC' | 'BIOMETRIC_PLUS_OTP' | 'DIGITAL_CERTIFICATE' | 'BIOMETRIC_SERPRO' | 'BIOMETRIC_SERPRO_AUTO_FALLBACK' | 'BIOMETRIC_DOCUMENT_FALLBACK' | 'CUSTOM', required: Perfis de política de verificação pré-definidos. Cada perfil resolve para uma lista ordenada de etapas (`StepType`): - `CLICK_ONLY`: CLICK_ACCEPT - `CLICK_PLUS_OTP`: CLICK_ACCEPT, OTP_CHALLENGE, OTP_VERIFY - `BIOMETRIC`: BIOMETRIC_LIVENESS, BIOMETRIC_MATCH - `BIOMETRIC_PLUS_OTP`: BIOMETRIC_LIVENESS, BIOMETRIC_MATCH, OTP_CHALLENGE, OTP_VERIFY - `DIGITAL_CERTIFICATE`: CLICK_ACCEPT, DIGITAL_SIGN_A1 - `BIOMETRIC_SERPRO`: BIOMETRIC_LIVENESS, BIOMETRIC_MATCH, SERPRO_IDENTITY_CHECK - `BIOMETRIC_SERPRO_AUTO_FALLBACK`: as mesmas etapas de `BIOMETRIC_SERPRO`, mais uma etapa DOCUMENT_PHOTO_MATCH criada em estado `DORMANT`. Se a base governamental estiver indisponível, a etapa SERPRO passa a `SKIPPED` e a dormente é ativada, sem derrubar a assinatura em andamento. - `BIOMETRIC_DOCUMENT_FALLBACK`: BIOMETRIC_LIVENESS, DOCUMENT_PHOTO_MATCH — para signatários sem cadastro biométrico prévio, comparando a prova de vida com a foto de um documento oficial. - `CUSTOM`: etapas definidas em `policy.customSteps`. `BIOMETRIC`, `BIOMETRIC_PLUS_OTP`, `BIOMETRIC_SERPRO`, `BIOMETRIC_SERPRO_AUTO_FALLBACK` e `BIOMETRIC_DOCUMENT_FALLBACK` exigem cota biométrica provisionada para o tenant.
      - `customSteps` StepType[]: Etapas customizadas (apenas quando `profile` = `CUSTOM`).
      - `minSimilarity` number, double: Limiar mínimo de similaridade facial exigido desta transação, para as etapas `BIOMETRIC_MATCH` e `DOCUMENT_PHOTO_MATCH`. **Só aperta, nunca afrouxa.** O valor precisa ser maior ou igual ao limiar configurado para o tenant; um valor abaixo dele retorna 400 informando o mínimo vigente, em vez de ser ignorado em silêncio — afrouxar a verificação de identidade é decisão do tenant, não da requisição. Documentos de maior risco podem assim exigir mais confiança que o padrão da conta, sem reconfigurar o tenant. Aceita tanto percentual (`95`) quanto fração (`0.95`).
      - `minLivenessConfidence` number, double: Limiar mínimo de confiança de vivacidade (`BIOMETRIC_LIVENESS`) exigido desta transação. Mesmo enquadramento do `minSimilarity`: só aperta, e um valor abaixo do mínimo do tenant retorna 400. Quando o tenant não define limiar de vivacidade próprio, qualquer valor válido é aceito.
    - `userExternalId` string, required
    - `documentHash` string
    - `documentGroupId` string
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `nextToken` string: Token para buscar a próxima página de resultados.
  - `count` integer, required: Número de transações retornadas nesta página.

## Other responses

- `400`: Requisição inválida — parâmetros ausentes ou malformados.
- `401`: Autenticação ausente ou inválida.
- `403`: Permissões insuficientes para a operação solicitada. Inclui `purpose: "ACTION_AUTHENTICATION"` sem `featureFlags.trustSessionsEnabled`. A verificação é pelo `purpose`, não pela rota: vale em `/v1/transactions`, `/v1/signing-sessions` e `/v1/envelopes/{envelopeId}/sessions`, além de `/v1/trust-sessions`. O remédio é habilitar a flag para o tenant e provisionar a cota `monthlyTrustSessions`.
- `500`: Erro interno do servidor.

---

[API](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api.md) · [All operations](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api/revisions/2d3805aed161?raw)