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. |
JSON Schema
{
"$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.
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.