Contrasync Docs

Appearance

API de Assinaturas do Contrato - Contrato para Backend ​

Visão Geral ​

Endpoints para gerenciar o fluxo de assinaturas de um contrato, incluindo grupos de assinantes internos (colaboradores da empresa) e externos (prestadores/partes do contrato).

Autenticação padrão via Authorization: Bearer {token} + x-company-id.

Tipos de Dados ​

SignatureGroup ​

typescript
type SignatureGroupType = 'parts' | 'internal' | 'custom'

type SignerMember = {
  id: string
  userId?: string           // ID do usuário interno (quando type != 'parts')
  name: string
  email: string
  avatar?: string
  order: number             // Ordem de assinatura dentro do grupo
  status?: SignatureStatus  // Status da assinatura (apenas no retorno)
  signedAt?: Date           // Data da assinatura (quando status = 'signed')
}

type SignatureGroup = {
  id: string
  name: string
  type: SignatureGroupType
  order: number             // Ordem do grupo no fluxo
  isFixed: boolean          // Grupos fixos não podem ser removidos
  members: SignerMember[]
}

type SignatureOrder = 'internal_first' | 'parts_first' | 'custom'

type SignatureStepConfig = {
  groups: SignatureGroup[]
  signatureOrder: SignatureOrder
}

SignatureStatus ​

typescript
type SignatureStatus = 'pending' | 'signed' | 'rejected'

Endpoints ​

1. GET /contracts/:contractId/signatures ​

Retorna a configuração de assinaturas do contrato com status atualizado de cada assinante.

Response 200:

json
{
  "data": {
    "signatureOrder": "internal_first",
    "groups": [
      {
        "id": "group-internal",
        "name": "Internal",
        "type": "internal",
        "order": 1,
        "isFixed": true,
        "members": [
          {
            "id": "signer-1",
            "userId": "user-uuid-1",
            "name": "João Silva",
            "email": "[email protected]",
            "avatar": "https://...",
            "order": 1,
            "status": "signed",
            "signedAt": "2024-07-20T10:00:00Z"
          },
          {
            "id": "signer-2",
            "userId": "user-uuid-2",
            "name": "Maria Santos",
            "email": "[email protected]",
            "avatar": null,
            "order": 2,
            "status": "pending",
            "signedAt": null
          }
        ]
      },
      {
        "id": "group-managers",
        "name": "Gestores",
        "type": "custom",
        "order": 2,
        "isFixed": false,
        "members": [
          {
            "id": "signer-3",
            "userId": "user-uuid-3",
            "name": "Pedro Oliveira",
            "email": "[email protected]",
            "avatar": null,
            "order": 1,
            "status": "pending",
            "signedAt": null
          }
        ]
      },
      {
        "id": "group-parts",
        "name": "Partes",
        "type": "parts",
        "order": 3,
        "isFixed": true,
        "members": [
          {
            "id": "part-uuid-1",
            "name": "Empresa Prestadora LTDA",
            "email": "[email protected]",
            "avatar": null,
            "order": 1,
            "status": "pending",
            "signedAt": null
          }
        ]
      }
    ],
    "summary": {
      "totalSigners": 4,
      "signedCount": 1,
      "pendingCount": 3,
      "rejectedCount": 0,
      "allSigned": false
    }
  }
}

Notas:

  • type: 'parts' = partes do contrato (prestadores) - membros são carregados automaticamente das partes do contrato
  • type: 'internal' = colaboradores internos da empresa
  • type: 'custom' = grupos customizados criados pelo usuário
  • signatureOrder define a ordem geral: primeiro internos, primeiro partes, ou ordem customizada por grupo

2. PUT /contracts/:contractId/signatures ​

Atualiza a configuração de assinaturas do contrato. Usado para adicionar/remover membros dos grupos internos ou criar/remover grupos customizados.

Nota: O grupo type: 'parts' não pode ter membros alterados diretamente - os membros são sincronizados automaticamente com as partes do contrato.

Body:

json
{
  "signatureOrder": "internal_first",
  "groups": [
    {
      "id": "group-internal",
      "name": "Internal",
      "type": "internal",
      "order": 1,
      "isFixed": true,
      "members": [
        {
          "id": "signer-1",
          "userId": "user-uuid-1",
          "name": "João Silva",
          "email": "[email protected]",
          "order": 1
        },
        {
          "id": "signer-new",
          "userId": "user-uuid-4",
          "name": "Ana Costa",
          "email": "[email protected]",
          "order": 2
        }
      ]
    },
    {
      "id": "group-managers",
      "name": "Gestores",
      "type": "custom",
      "order": 2,
      "isFixed": false,
      "members": []
    }
  ]
}

Response 200: Retorna a configuração atualizada (mesmo formato do GET).

Validações:

  • Não é permitido alterar membros de grupos type: 'parts'
  • Não é permitido remover grupos com isFixed: true
  • userId deve ser de um usuário ativo da empresa
  • signatureOrder deve ser um valor válido

3. POST /contracts/:contractId/signatures/start ​

Inicia o fluxo de assinaturas. Envia notificações para os primeiros assinantes de acordo com signatureOrder.

Response 200:

json
{
  "data": {
    "message": "Fluxo de assinaturas iniciado",
    "notifiedSigners": [
      {
        "id": "signer-1",
        "name": "João Silva",
        "email": "[email protected]"
      }
    ]
  }
}

Validações:

  • Contrato deve estar no status signature
  • Deve haver pelo menos um assinante configurado
  • Não pode iniciar se já estiver em andamento

4. POST /contracts/:contractId/signatures/:signerId/sign ​

Registra a assinatura de um assinante. Pode incluir assinatura eletrônica ou digital.

Body:

json
{
  "signatureData": "base64-encoded-signature-image",
  "signatureType": "electronic",
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0..."
}

Response 200:

json
{
  "data": {
    "id": "signer-1",
    "status": "signed",
    "signedAt": "2024-07-20T10:00:00Z",
    "nextSigners": [
      {
        "id": "signer-2",
        "name": "Maria Santos",
        "email": "[email protected]"
      }
    ]
  }
}

Notas:

  • Após assinatura, notifica os próximos assinantes de acordo com a ordem configurada
  • Se todos assinaram, atualiza o status do contrato para completed

5. POST /contracts/:contractId/signatures/:signerId/reject ​

Rejeita a assinatura (recusa assinar).

Body:

json
{
  "reason": "Discordo das cláusulas do contrato"
}

Response 200:

json
{
  "data": {
    "id": "signer-1",
    "status": "rejected",
    "rejectionReason": "Discordo das cláusulas do contrato",
    "rejectedAt": "2024-07-20T10:00:00Z"
  }
}

Notas:

  • Rejeição notifica o responsável pelo contrato
  • Contrato pode ser editado e reenviado após rejeição

6. POST /contracts/:contractId/signatures/:signerId/reminder ​

Envia lembrete por email para um assinante pendente.

Response 200:

json
{
  "data": {
    "message": "Lembrete enviado com sucesso",
    "sentTo": "[email protected]"
  }
}

Validações:

  • Assinante deve ter status pending
  • Limite de 3 lembretes por dia por assinante

Fluxo de Assinaturas ​

  1. Configuração: Contrato carrega signatureConfig do workflow ou permite configuração manual
  2. Partes automáticas: Prestadores adicionados ao contrato são automaticamente incluídos no grupo type: 'parts'
  3. Internos editáveis: Grupos internos podem ter membros adicionados/removidos
  4. Início: Ao iniciar, notifica primeiro(s) assinante(s) de acordo com signatureOrder
  5. Sequência: Após cada assinatura, notifica o próximo na ordem
  6. Conclusão: Quando todos assinam, contrato vai para completed

Webhook Events ​

O backend pode emitir os seguintes eventos para sistemas externos:

json
{
  "event": "signature.signed",
  "contractId": "uuid",
  "signerId": "signer-1",
  "signerName": "João Silva",
  "signedAt": "2024-07-20T10:00:00Z"
}
json
{
  "event": "signature.rejected",
  "contractId": "uuid",
  "signerId": "signer-1",
  "signerName": "João Silva",
  "reason": "Motivo da rejeição"
}
json
{
  "event": "contract.completed",
  "contractId": "uuid",
  "completedAt": "2024-07-20T15:00:00Z",
  "totalSigners": 4
}