signdocs-com-br · Schema

CreateTransactionRequest

Requisição de criação de transação.

CompanyDigital SignatureBrazilDocument Management

Properties

Name Type Description
purpose object
policy object
signer object
document object Documento em base64 (opcional — pode ser enviado posteriormente). Suporta PDF e outros formatos.
action object
digitalSignature object
fallbackDocument object Documento oficial enviado com antecedência para o caso de a base governamental estar indisponível. Aceito **apenas** com `policy.profile` = `BIOMETRIC_SERPRO_AUTO_FALLBACK`; em qualquer outro perfil r
documentGroupId string Identificador do grupo de documentos (para assinatura com múltiplos signatários).
signerIndex integer Índice do signatário no grupo (inicia em 0).
totalSigners integer Total de signatários no grupo (máximo 100).
metadata object Metadados customizados (chave-valor string).
expiresInMinutes integer Tempo de expiração da transação em minutos.
View JSON Schema on GitHub

JSON Schema

signdocs-com-br-create-transaction-request-schema.json Raw ↑
{
  "$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"
      ]
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/signdocs-com-br-create-transaction-request"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.