AddEnvelopeSessionRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/signdocs-com-br/json-schema/signdocs-com-br-add-envelope-session-request-schema.json",
  "title": "AddEnvelopeSessionRequest",
  "description": "Requisição para adicionar uma sessão de signatário ao envelope.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/signdocs-com-br-openapi.yaml#/components/schemas/AddEnvelopeSessionRequest",
  "type": "object",
  "required": [
    "signer",
    "policy",
    "signerIndex"
  ],
  "properties": {
    "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."
        },
        "userExternalId": {
          "type": "string",
          "description": "Identificador externo do usuário no sistema do integrador."
        },
        "cpf": {
          "type": "string",
          "description": "CPF do signatário (11 dígitos, sem pontuação).",
          "pattern": "^\\d{11}$"
        },
        "cnpj": {
          "type": "string",
          "description": "CNPJ do signatário (14 dígitos, sem pontuação).",
          "pattern": "^\\d{14}$"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "E-mail do signatário (obrigatório para etapas OTP)."
        },
        "phone": {
          "type": "string",
          "description": "Telefone do signatário em formato E.164.",
          "pattern": "^\\+[1-9]\\d{7,14}$"
        },
        "birthDate": {
          "type": "string",
          "format": "date",
          "description": "Data de nascimento do signatário (YYYY-MM-DD)."
        },
        "otpChannel": {
          "$ref": "#/$defs/OtpChannel"
        }
      }
    },
    "policy": {
      "type": "object",
      "description": "Política de verificação de identidade da sessão.",
      "required": [
        "profile"
      ],
      "properties": {
        "profile": {
          "type": "string",
          "description": "Perfil de verificação de identidade."
        }
      }
    },
    "purpose": {
      "type": "string",
      "description": "Finalidade da sessão.",
      "enum": [
        "DOCUMENT_SIGNATURE",
        "ACTION_AUTHENTICATION"
      ],
      "default": "DOCUMENT_SIGNATURE"
    },
    "signerIndex": {
      "type": "integer",
      "description": "Índice do signatário no envelope (mínimo 1). Define a ordem em modo SEQUENTIAL.",
      "minimum": 1
    },
    "returnUrl": {
      "type": "string",
      "format": "uri",
      "description": "URL de retorno após conclusão desta sessão. Sobrescreve a URL do envelope."
    },
    "cancelUrl": {
      "type": "string",
      "format": "uri",
      "description": "URL de retorno em caso de cancelamento. Sobrescreve a URL do envelope."
    },
    "metadata": {
      "type": "object",
      "description": "Metadados livres específicos desta sessão.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "deliverVia": {
      "type": "array",
      "description": "Canais pelos quais a SignDocs entrega o link de assinatura a este\nsignatário; cada signatário escolhe os seus. Omita para manter o\ncomportamento anterior: apenas o e-mail de convite.\n\nNum envelope `SEQUENTIAL`, o signatário posterior não recebe link antes da\nsua vez; quando ela chega, recebe pelos canais escolhidos aqui. O envio é\nadmitido nesta chamada, com a verificação de cota, porque depois não há a\nquem devolver um 429. Provisionamento e kill switch são conferidos de novo\nno momento do envio. Se nenhum canal pedido conseguir entregar, o signatário\nrecebe o convite por e-mail quando tem endereço e o envelope tem `owner`.\n\nWhatsApp e Telegram são habilitados **sob demanda**: o tenant pede ao time\ncomercial, e não é algo que se liga pelo painel. Pedir um canal que o tenant\nnão tem retorna **403** antes de qualquer gravação.\n\n`whatsapp` exige `signer.phone` em E.164. `whatsappInviteSent: true`\nsignifica que a Meta **aceitou** a mensagem, não que ela foi entregue ou\nlida; em qualquer outro caso o campo é omitido da resposta. Se a Meta\nreportar falha depois e o signatário tiver e-mail, a SignDocs reenvia o\nconvite por e-mail automaticamente, com um link novo, diferente do que veio\nnesta resposta; nenhum webhook, campo ou endpoint informa esse reenvio. Um\nnúmero que respondeu \"parar\", \"sair\" ou \"stop\" deixa de receber mensagens da\nSignDocs por WhatsApp.\n\n`telegram` exige `signer.cpf` e só alcança signatários que já registraram o\npróprio CPF no bot da SignDocs. `telegramInviteSent` vem na resposta sempre\nque o convite por Telegram é tentado nesta chamada, `false` quando não chegou.\n\nCada envio por WhatsApp ou Telegram consome a cota de mensagens do tenant.\nEsgotada a cota, a requisição é recusada com **429** antes de qualquer\ngravação; com o canal suspenso por kill switch, com **503**. Credenciais de\nsandbox também enviam mensagens reais por WhatsApp e consomem a cota de\nmensagens de sandbox.\n",
      "items": {
        "type": "string",
        "enum": [
          "email",
          "whatsapp",
          "telegram"
        ]
      }
    }
  },
  "$defs": {
    "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"
    }
  }
}