Originação com múltiplos assinantes

Visão Geral

Para emitir uma CCB com múltiplos assinantes, o fluxo é dividido em três etapas sequenciais:

1. Cadastro da pessoa (Person / Business)
   ↓
2. Associação como assinante.
   ↓
3. Criação da CCB com os papéis definidos

O sistema não exige um "cadastro de assinante" prévio isolado. O vínculo acontece no momento da criação da Application, onde cada entidade já cadastrada recebe um papel (role) que define sua responsabilidade na operação.

Etapa 1 — Cadastro da Pessoa

Antes de incluir qualquer assinante na CCB, a entidade deve existir no sistema como Person (Pessoa Física) ou Business (Pessoa Jurídica).

Pessoa Física

POST /banking/originator/persons

{
  "name": "Felipe Tavares",
  "taxpayer_id": "12345678900",
  "birth_date": "1990-01-15",
  "email": "[email protected]",
  "phone": "+5511999999999"
}

Pessoa Jurídica

POST /banking/originator/businesses

{
  "company_name": "Empresa Exemplo LTDA",
  "taxpayer_id": "12345678000100",
  "email": "[email protected]",
  "phone": "+5511999999999",
  "signers": [
    {
      "person_id": "uuid-do-representante"
    }
  ]
}

Quando o papel for desempenhado por uma Empresa, o sistema busca automaticamente os indivíduos configurados como signers vinculados a ela e os inclui na lista de assinantes da CCB. Por isso, os representantes da empresa devem estar cadastrados como Person previamente.

O retorno de ambos os endpoints inclui o id da entidade criada — esse ID é usado nos campos de assinantes no payload da Application.

Etapa 2 — Papéis de Assinantes Suportados

Cada entidade associada à Application recebe um papel que determina sua responsabilidade jurídica na operação.

Além dos envolvidos diretos, o sistema verifica automaticamente se o Produto ou o Fundo

Etapa 3 — Criação da CCB com Assinantes

Endpoint

POST /banking/originator/applications

Payload Completo

{
  "product": {
    "id": "d4f2f4a1-477e-4fa6-a3d0-0fa2628cbdc3"
  },
  "borrower": {
    "id": "0bd03cc0-9b62-42ad-b3fb-f3a3e3132729"
  },
  "funding": {
    "id": "ecc143f4-e1cc-499b-ae1f-be6a47004dca"
  },
  "simulation_id": "{{simulationId}}",
  "signature_provider": "ZAPSIGN",
  "signature_collect_method": "LINK",
  "signature_authentication_options": {
    "mode": "FACIAL_BIOMETRICS"
  },
  "signature_collect_options": {
    "require_self_photo": false,
    "require_selfie_validation": false
  },
  "guarantors": [
    {
      "guarantor_id": "53f390d5-b960-49a4-968c-56c8e7cbd4ab",
      "type": "PERSON"
    },
    {
      "guarantor_id": "b4d9eb62-14d2-4d28-8e98-c9d95c707a7b",
      "type": "PERSON"
    }
  ],
  "co_signers": [],
  "co_debtors": [
    {
      "co_debtor_id": "62218881-0e34-41d9-bf0c-c0cf4e6bda03",
      "type": "PERSON"
    }
  ],
  "collateral_providers": [
    {
      "collateral_provider_id": "0a7b6e06-82b1-4ebe-a380-ab64392be72f",
      "type": "PERSON"
    }
  ],
  "representatives": [
    {
      "representative_id": "6d6aafc6-41e2-45ce-aece-e588199867f8",
      "type": "PERSON"
    }
  ],
  "sureties": [
    {
      "surety_id": "ad277aa0-845b-41cf-8c6f-8009d0aa35e6",
      "type": "PERSON"
    }
  ],
  "investors": [],
  "custom_variables": {
    "variavel_exemplo_1": "valor 1",
    "variavel_exemplo_2": "valor 2"
  }
}

Referência de Campos

Campos raiz

Estrutura de cada assinante

Todos os arrays de assinantes seguem a mesma estrutura, variando apenas o nome do campo de ID:

Objeto signature_authentication_options

Objeto signature_collect_options

custom_variables

Objeto livre de chave-valor usado para injetar informações personalizadas no template do contrato. As chaves devem corresponder às variáveis configuradas no template do produto.

"custom_variables": {
  "nome_da_variavel": "valor",
  "outra_variavel": "outro valor"
}

Provedores de Assinatura

Fluxo Interno de Assinaturas

Após a criação da Application, o sistema processa os assinantes automaticamente:

Application criada
  → Renderização do contrato (PDF via template + custom_variables)
  → Validação de KYC de todos os signatários
       KYC APPROVED ou NOT_REQUIRED → avança
       KYC REJECTED → CANCELED
  → Status: PENDING_SIGNATURE
  → Notificações disparadas a cada signatário via provedor
  → Todos assinam
  → ISSUED

Para cada signatário identificado, o sistema cria um registro interno com status PENDING. A CCB só avança para ISSUED após todos os registros de assinatura serem concluídos.

Observações Importantes

Empresas como assinantes — ao informar type: BUSINESS, o sistema não inclui a empresa diretamente como assinante, mas sim os indivíduos cadastrados como signers vinculados a ela. Certifique-se de que os representantes da empresa estão cadastrados e vinculados antes de criar a Application.

Arrays vazios — campos como co_signers, investors podem ser enviados como []. O sistema os ignora sem retornar erro.

simulation_id — expira após um período configurado no produto. Sempre crie a Application logo após a simulação.

Erros Comuns