---
title: "Consultar transação"
method: GET
path: "/v1/transactions/{transactionId}"
tags: ["Transactions"]
---

# Consultar transação

`GET /v1/transactions/{transactionId}`

## Request

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

Retorna os detalhes completos de uma transação, incluindo signatário, etapas e metadados.

Requer scope `transactions:read`.

## Path parameters

- `transactionId` string, required

## Response `200`

Detalhes da transação retornados com sucesso.

- TransactionDetailResponse: Resposta com detalhes completos da transação.
  - `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
  - `signer` union, required: Dados do signatário. É obrigatório informar pelo menos um entre `cpf` e `cnpj`.
    - object
      - `name` string, required: Nome completo do signatário.
      - `email` string, email: E-mail do signatário (obrigatório para etapas OTP).
      - `userExternalId` string, required: Identificador externo do usuário no sistema do integrador.
      - `displayName` string: Nome de exibição do signatário.
      - `cpf` string, required: CPF do signatário (11 dígitos, sem pontuação). Obrigatório se `cnpj` não for informado.
      - `cnpj` string: CNPJ do signatário (14 dígitos, sem pontuação). Obrigatório se `cpf` não for informado.
      - `phone` string: Telefone do signatário em formato E.164. Obrigatório quando `otpChannel` é `sms` ou `whatsapp`, ou quando `deliverVia` inclui `whatsapp`.
      - `otpChannel` 'email' | 'sms' | 'whatsapp' | 'telegram': Canal de entrega do OTP, escolhido por signatário. Independente do canal usado para entregar o link de assinatura: um convite por WhatsApp pode ter OTP por e-mail, e um convite por e-mail pode ter OTP por WhatsApp. `sms` e `whatsapp` exigem `signer.phone` e o canal habilitado para o tenant (`sms.enabled` / `whatsapp.enabled`); caso contrário o passo de OTP falha com **422**. No WhatsApp, um número que pediu para não receber mensagens também falha com 422, com uma mensagem que orienta a escolher outro canal. `telegram` exige `telegram.enabled` no tenant. O código chega pelo bot da SignDocs quando o signatário já registrou o próprio CPF nele; sem registro, é enviado por telefone (Telegram Gateway) se o tenant tiver essa opção habilitada, e caso contrário o passo falha com **422** de imediato. Ao criar a sessão, `otpChannel: telegram` ainda exige `signer.email` quando a política tem OTP. Um OTP por WhatsApp ou pelo Telegram Gateway consome a cota de mensagens do tenant; esgotada, o envio é recusado com **429**.
      - `otpChannelSelectable` boolean: Quando `true`, a tela de assinatura hospedada permite que o signatário escolha o canal (entre os de `availableOtpChannels`) que recebe o OTP no momento da assinatura e troque de canal durante o fluxo. Padrão `false` — integrações existentes mantêm um único canal fixo e o backend recusa um canal escolhido pelo signatário se este campo não estiver definido.
    - object
      - `name` string, required: Nome completo do signatário.
      - `email` string, email: E-mail do signatário (obrigatório para etapas OTP).
      - `userExternalId` string, required: Identificador externo do usuário no sistema do integrador.
      - `displayName` string: Nome de exibição do signatário.
      - `cpf` string: CPF do signatário (11 dígitos, sem pontuação). Obrigatório se `cnpj` não for informado.
      - `cnpj` string, required: CNPJ do signatário (14 dígitos, sem pontuação). Obrigatório se `cpf` não for informado.
      - `phone` string: Telefone do signatário em formato E.164. Obrigatório quando `otpChannel` é `sms` ou `whatsapp`, ou quando `deliverVia` inclui `whatsapp`.
      - `otpChannel` 'email' | 'sms' | 'whatsapp' | 'telegram': Canal de entrega do OTP, escolhido por signatário. Independente do canal usado para entregar o link de assinatura: um convite por WhatsApp pode ter OTP por e-mail, e um convite por e-mail pode ter OTP por WhatsApp. `sms` e `whatsapp` exigem `signer.phone` e o canal habilitado para o tenant (`sms.enabled` / `whatsapp.enabled`); caso contrário o passo de OTP falha com **422**. No WhatsApp, um número que pediu para não receber mensagens também falha com 422, com uma mensagem que orienta a escolher outro canal. `telegram` exige `telegram.enabled` no tenant. O código chega pelo bot da SignDocs quando o signatário já registrou o próprio CPF nele; sem registro, é enviado por telefone (Telegram Gateway) se o tenant tiver essa opção habilitada, e caso contrário o passo falha com **422** de imediato. Ao criar a sessão, `otpChannel: telegram` ainda exige `signer.email` quando a política tem OTP. Um OTP por WhatsApp ou pelo Telegram Gateway consome a cota de mensagens do tenant; esgotada, o envio é recusado com **429**.
      - `otpChannelSelectable` boolean: Quando `true`, a tela de assinatura hospedada permite que o signatário escolha o canal (entre os de `availableOtpChannels`) que recebe o OTP no momento da assinatura e troque de canal durante o fluxo. Padrão `false` — integrações existentes mantêm um único canal fixo e o backend recusa um canal escolhido pelo signatário se este campo não estiver definido.
  - `action` ActionMetadata: Metadados da ação autenticada (para `ACTION_AUTHENTICATION`).
    - `type` string, required: Tipo da ação.
    - `description` string, required: Descrição da ação.
    - `reference` string: Referência externa da ação.
  - `documentHash` string
  - `documentGroupId` string
  - `signerIndex` integer
  - `totalSigners` integer
  - `metadata` object
  - `steps` object[], required
    - `stepId` string, required
    - `type` 'CLICK_ACCEPT' | 'OTP_CHALLENGE' | 'OTP_VERIFY' | 'BIOMETRIC_LIVENESS' | 'BIOMETRIC_MATCH' | 'DOCUMENT_PHOTO_MATCH' | 'SERPRO_IDENTITY_CHECK' | 'DIGITAL_SIGN_A1' | 'PURPOSE_DISCLOSURE', required: Tipos de etapa de verificação de identidade. Em `policy.customSteps` a ordem é validada na criação: BIOMETRIC_MATCH, SERPRO_IDENTITY_CHECK e DOCUMENT_PHOTO_MATCH exigem BIOMETRIC_LIVENESS antes de si, OTP_CHALLENGE e OTP_VERIFY vêm sempre em par e nessa ordem, e DIGITAL_SIGN_A1 tem de ser a última etapa.
    - `status` 'PENDING' | 'STARTED' | 'COMPLETED' | 'FAILED' | 'SKIPPED' | 'DORMANT', required: Status possíveis de uma etapa. `SKIPPED` e `DORMANT` aparecem nos perfis com fallback: a etapa dormente é criada junto com a transação e só entra em `PENDING` se a etapa que ela substitui for pulada.
    - `order` integer, required
    - `attempts` integer, required
    - `startedAt` string, date-time
    - `completedAt` string, date-time
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `expiresAt` string, date-time

## Other responses

- `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`.
- `404`: Recurso não encontrado.
- `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)