{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/signdocs-com-br/json-schema/signdocs-com-br-create-transaction-request-schema.json",
  "title": "CreateTransactionRequest",
  "description": "Requisição de criação de transação.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/signdocs-com-br-transactions-api-openapi.yml#/components/schemas/CreateTransactionRequest",
  "type": "object",
  "required": [
    "purpose",
    "policy",
    "signer"
  ],
  "properties": {
    "purpose": {
      "$ref": "#/$defs/TransactionPurpose"
    },
    "policy": {
      "$ref": "#/$defs/Policy"
    },
    "signer": {
      "$ref": "#/$defs/Signer"
    },
    "document": {
      "type": "object",
      "description": "Documento em base64 (opcional — pode ser enviado posteriormente). Suporta PDF e outros formatos.",
      "properties": {
        "content": {
          "type": "string",
          "format": "byte",
          "description": "Conteúdo do documento codificado em base64."
        },
        "filename": {
          "type": "string",
          "description": "Nome do arquivo."
        }
      }
    },
    "action": {
      "$ref": "#/$defs/ActionMetadata"
    },
    "digitalSignature": {
      "$ref": "#/$defs/DigitalSignatureMetadata"
    },
    "fallbackDocument": {
      "type": "object",
      "description": "Documento oficial enviado com antecedência para o caso de a base governamental\nestar indisponível. Aceito **apenas** com `policy.profile` =\n`BIOMETRIC_SERPRO_AUTO_FALLBACK`; em qualquer outro perfil retorna 400.\n\nEnviá-lo na criação é o que permite que a etapa `DOCUMENT_PHOTO_MATCH` dormente\nseja executada sem interromper o signatário para pedir uma foto do documento no\nmeio da assinatura. Sem ele, o fallback ainda ocorre, mas exige a captura do\ndocumento naquele momento.\n",
      "required": [
        "image",
        "type"
      ],
      "properties": {
        "image": {
          "type": "string",
          "format": "byte",
          "description": "Imagem do documento em base64. Máximo de 5 MB."
        },
        "type": {
          "type": "string",
          "description": "Tipo do documento enviado.",
          "enum": [
            "RG",
            "CNH",
            "PASSPORT",
            "OTHER"
          ]
        }
      }
    },
    "documentGroupId": {
      "type": "string",
      "description": "Identificador do grupo de documentos (para assinatura com múltiplos signatários)."
    },
    "signerIndex": {
      "type": "integer",
      "description": "Índice do signatário no grupo (inicia em 0).",
      "minimum": 0
    },
    "totalSigners": {
      "type": "integer",
      "description": "Total de signatários no grupo (máximo 100).",
      "minimum": 1,
      "maximum": 100
    },
    "metadata": {
      "type": "object",
      "description": "Metadados customizados (chave-valor string).",
      "additionalProperties": {
        "type": "string"
      }
    },
    "expiresInMinutes": {
      "type": "integer",
      "description": "Tempo de expiração da transação em minutos.",
      "minimum": 1
    }
  },
  "$defs": {
    "ActionMetadata": {
      "type": "object",
      "description": "Metadados da ação autenticada (para `ACTION_AUTHENTICATION`).",
      "required": [
        "type",
        "description"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Tipo da ação."
        },
        "description": {
          "type": "string",
          "description": "Descrição da ação."
        },
        "reference": {
          "type": "string",
          "description": "Referência externa da ação."
        }
      }
    },
    "DigitalSignatureMetadata": {
      "type": "object",
      "description": "Metadados adicionais para assinatura digital ICP-Brasil.",
      "properties": {
        "reason": {
          "type": "string",
          "description": "Motivo da assinatura."
        },
        "location": {
          "type": "string",
          "description": "Local da assinatura."
        },
        "contactInfo": {
          "type": "string",
          "description": "Informação de contato do signatário."
        }
      }
    },
    "OtpChannel": {
      "type": "string",
      "description": "Canal de entrega do OTP, escolhido por signatário. Independente do canal\nusado para entregar o link de assinatura: um convite por WhatsApp pode ter\nOTP por e-mail, e um convite por e-mail pode ter OTP por WhatsApp.\n\n`sms` e `whatsapp` exigem `signer.phone` e o canal habilitado para o tenant\n(`sms.enabled` / `whatsapp.enabled`); caso contrário o passo de OTP falha com\n**422**. No WhatsApp, um número que pediu para não receber mensagens também\nfalha com 422, com uma mensagem que orienta a escolher outro canal.\n\n`telegram` exige `telegram.enabled` no tenant. O código chega pelo bot da\nSignDocs quando o signatário já registrou o próprio CPF nele; sem registro, é\nenviado por telefone (Telegram Gateway) se o tenant tiver essa opção\nhabilitada, e caso contrário o passo falha com **422** de imediato. Ao criar a\nsessão, `otpChannel: telegram` ainda exige `signer.email` quando a política\ntem OTP.\n\nUm OTP por WhatsApp ou pelo Telegram Gateway consome a cota de mensagens do\ntenant; esgotada, o envio é recusado com **429**.\n",
      "enum": [
        "email",
        "sms",
        "whatsapp",
        "telegram"
      ],
      "default": "email"
    },
    "Policy": {
      "type": "object",
      "description": "Política de verificação de identidade da transação.",
      "required": [
        "profile"
      ],
      "properties": {
        "profile": {
          "$ref": "#/$defs/PolicyProfile"
        },
        "customSteps": {
          "type": "array",
          "description": "Etapas customizadas (apenas quando `profile` = `CUSTOM`).",
          "items": {
            "$ref": "#/$defs/StepType"
          }
        },
        "minSimilarity": {
          "type": "number",
          "format": "double",
          "minimum": 0,
          "maximum": 100,
          "description": "Limiar mínimo de similaridade facial exigido desta transação, para as\netapas `BIOMETRIC_MATCH` e `DOCUMENT_PHOTO_MATCH`.\n\n**Só aperta, nunca afrouxa.** O valor precisa ser maior ou igual ao\nlimiar configurado para o tenant; um valor abaixo dele retorna 400\ninformando o mínimo vigente, em vez de ser ignorado em silêncio —\nafrouxar a verificação de identidade é decisão do tenant, não da\nrequisição. Documentos de maior risco podem assim exigir mais\nconfiança que o padrão da conta, sem reconfigurar o tenant.\n\nAceita tanto percentual (`95`) quanto fração (`0.95`).\n"
        },
        "minLivenessConfidence": {
          "type": "number",
          "format": "double",
          "minimum": 0,
          "maximum": 100,
          "description": "Limiar mínimo de confiança de vivacidade (`BIOMETRIC_LIVENESS`) exigido\ndesta transação. Mesmo enquadramento do `minSimilarity`: só aperta, e\num valor abaixo do mínimo do tenant retorna 400.\n\nQuando o tenant não define limiar de vivacidade próprio, qualquer valor\nválido é aceito.\n"
        }
      }
    },
    "PolicyProfile": {
      "type": "string",
      "description": "Perfis de política de verificação pré-definidos. Cada perfil resolve para uma\nlista ordenada de etapas (`StepType`):\n\n- `CLICK_ONLY`: CLICK_ACCEPT\n- `CLICK_PLUS_OTP`: CLICK_ACCEPT, OTP_CHALLENGE, OTP_VERIFY\n- `BIOMETRIC`: BIOMETRIC_LIVENESS, BIOMETRIC_MATCH\n- `BIOMETRIC_PLUS_OTP`: BIOMETRIC_LIVENESS, BIOMETRIC_MATCH, OTP_CHALLENGE, OTP_VERIFY\n- `DIGITAL_CERTIFICATE`: CLICK_ACCEPT, DIGITAL_SIGN_A1\n- `BIOMETRIC_SERPRO`: BIOMETRIC_LIVENESS, BIOMETRIC_MATCH, SERPRO_IDENTITY_CHECK\n- `BIOMETRIC_SERPRO_AUTO_FALLBACK`: as mesmas etapas de `BIOMETRIC_SERPRO`, mais uma\n  etapa DOCUMENT_PHOTO_MATCH criada em estado `DORMANT`. Se a base governamental\n  estiver indisponível, a etapa SERPRO passa a `SKIPPED` e a dormente é ativada,\n  sem derrubar a assinatura em andamento.\n- `BIOMETRIC_DOCUMENT_FALLBACK`: BIOMETRIC_LIVENESS, DOCUMENT_PHOTO_MATCH — para\n  signatários sem cadastro biométrico prévio, comparando a prova de vida com a foto\n  de um documento oficial.\n- `CUSTOM`: etapas definidas em `policy.customSteps`.\n\n`BIOMETRIC`, `BIOMETRIC_PLUS_OTP`, `BIOMETRIC_SERPRO`, `BIOMETRIC_SERPRO_AUTO_FALLBACK`\ne `BIOMETRIC_DOCUMENT_FALLBACK` exigem cota biométrica provisionada para o tenant.\n",
      "enum": [
        "CLICK_ONLY",
        "CLICK_PLUS_OTP",
        "BIOMETRIC",
        "BIOMETRIC_PLUS_OTP",
        "DIGITAL_CERTIFICATE",
        "BIOMETRIC_SERPRO",
        "BIOMETRIC_SERPRO_AUTO_FALLBACK",
        "BIOMETRIC_DOCUMENT_FALLBACK",
        "CUSTOM"
      ]
    },
    "Signer": {
      "type": "object",
      "description": "Dados do signatário.\nÉ obrigatório informar pelo menos um entre `cpf` e `cnpj`.\n",
      "required": [
        "name",
        "userExternalId"
      ],
      "anyOf": [
        {
          "required": [
            "cpf"
          ]
        },
        {
          "required": [
            "cnpj"
          ]
        }
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Nome completo do signatário."
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "E-mail do signatário (obrigatório para etapas OTP)."
        },
        "userExternalId": {
          "type": "string",
          "description": "Identificador externo do usuário no sistema do integrador."
        },
        "displayName": {
          "type": "string",
          "description": "Nome de exibição do signatário."
        },
        "cpf": {
          "type": "string",
          "description": "CPF do signatário (11 dígitos, sem pontuação). Obrigatório se `cnpj` não for informado.",
          "pattern": "^\\d{11}$"
        },
        "cnpj": {
          "type": "string",
          "description": "CNPJ do signatário (14 dígitos, sem pontuação). Obrigatório se `cpf` não for informado.",
          "pattern": "^\\d{14}$"
        },
        "phone": {
          "type": "string",
          "description": "Telefone do signatário em formato E.164. Obrigatório quando `otpChannel` é `sms` ou `whatsapp`, ou quando `deliverVia` inclui `whatsapp`.",
          "pattern": "^\\+[1-9]\\d{7,14}$"
        },
        "otpChannel": {
          "$ref": "#/$defs/OtpChannel"
        },
        "otpChannelSelectable": {
          "type": "boolean",
          "description": "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.",
          "default": false
        }
      }
    },
    "StepType": {
      "type": "string",
      "description": "Tipos de etapa de verificação de identidade. Em `policy.customSteps` a ordem é\nvalidada na criação: BIOMETRIC_MATCH, SERPRO_IDENTITY_CHECK e DOCUMENT_PHOTO_MATCH\nexigem BIOMETRIC_LIVENESS antes de si, OTP_CHALLENGE e OTP_VERIFY vêm sempre em par\ne nessa ordem, e DIGITAL_SIGN_A1 tem de ser a última etapa.\n",
      "enum": [
        "CLICK_ACCEPT",
        "OTP_CHALLENGE",
        "OTP_VERIFY",
        "BIOMETRIC_LIVENESS",
        "BIOMETRIC_MATCH",
        "DOCUMENT_PHOTO_MATCH",
        "SERPRO_IDENTITY_CHECK",
        "DIGITAL_SIGN_A1",
        "PURPOSE_DISCLOSURE"
      ]
    },
    "TransactionPurpose": {
      "type": "string",
      "description": "Finalidade da transação.",
      "enum": [
        "DOCUMENT_SIGNATURE",
        "ACTION_AUTHENTICATION"
      ]
    }
  }
}