Provider Configs

Gerenciamento de configurações de provedores de assinatura eletrônica.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/api/v1/esignature/provider-configs`	Criar configuração	`ESIGNATURE_ADMIN`
GET	`/api/v1/esignature/provider-configs`	Listar configurações	`ESIGNATURE_READ`
GET	`/api/v1/esignature/provider-configs/:id`	Obter configuração	`ESIGNATURE_READ`
PATCH	`/api/v1/esignature/provider-configs/:id`	Atualizar configuração	`ESIGNATURE_ADMIN`
DELETE	`/api/v1/esignature/provider-configs/:id`	Excluir configuração	`ESIGNATURE_ADMIN`
POST	`/api/v1/esignature/provider-configs/:id/test`	Testar conexão	`ESIGNATURE_ADMIN`
POST	`/api/v1/esignature/provider-configs/:id/set-default`	Definir como padrão	`ESIGNATURE_ADMIN`

Atributos

Campo	Tipo	Descrição
`name`	string	Nome identificador da configuração
`providerType`	enum	Tipo do provedor: `OPENSIGN`, `DOCUSIGN`, `ADOBESIGN`, `ZAPSIGN`
`credentials`	object	Credenciais do provedor (criptografadas)
`isDefault`	boolean	Se é a configuração padrão da organização
`isActive`	boolean	Se a configuração está ativa
`settings`	object	Configurações adicionais do provedor
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data da última atualização
`createdBy`	string	ID do usuário que criou
`updatedBy`	string	ID do usuário que atualizou

Credenciais por Provedor

Segurança

As credenciais são criptografadas antes de serem armazenadas no banco de dados usando AES-256-GCM. Elas nunca são retornadas nas respostas da API.

OpenSign

O OpenSign suporta dois modos de autenticação:

Modo 1: Master Key (Self-hosted / Desenvolvimento)

Para instâncias self-hosted ou desenvolvimento local, use a Master Key do Parse Server:

Campo	Descrição	Obrigatório
`baseUrl`	URL base da instância OpenSign	Sim
`masterKey`	Master Key do Parse Server	Sim
`appId`	Application ID (padrão: `opensign`)	Não
`apiPrefix`	Prefixo da API: `/api/app` (Caddy) ou `/app` (direto)	Não

{
  "baseUrl": "https://opensign.suaempresa.com",
  "masterKey": "sua_master_key_aqui",
  "appId": "opensign",
  "apiPrefix": "/api/app"
}

Modo 2: Session Token (Usuário autenticado)

Para operações em nome de um usuário específico:

Campo	Descrição	Obrigatório
`baseUrl`	URL base da instância OpenSign	Sim
`sessionToken`	Token de sessão do usuário	Sim
`extUserId`	ID do usuário em `contracts_Users`	Sim
`appId`	Application ID (padrão: `opensign`)	Não
`apiPrefix`	Prefixo da API	Não

{
  "baseUrl": "https://opensign.suaempresa.com",
  "sessionToken": "r:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "extUserId": "AbCdEfGhIj",
  "appId": "opensign"
}

Self-hosted

Para instâncias self-hosted do OpenSign, o modo Master Key é recomendado pois não requer a geração de API tokens (funcionalidade disponível apenas em planos pagos do OpenSign Cloud).

DocuSign

Campo	Descrição	Obrigatório
`integrationKey`	Integration Key (Client ID)	Sim
`userId`	User ID (GUID do usuário)	Sim
`accountId`	Account ID	Sim
`rsaPrivateKey`	Chave RSA privada (PEM)	Sim
`environment`	`production` ou `demo`	Não

{
  "integrationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "rsaPrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIE...",
  "environment": "production"
}

Adobe Sign

Campo	Descrição	Obrigatório
`clientId`	Client ID da aplicação	Sim
`clientSecret`	Client Secret	Sim
`refreshToken`	Refresh Token OAuth	Sim

{
  "clientId": "xxxxxxxxxxxx",
  "clientSecret": "xxxxxxxxxxxx",
  "refreshToken": "xxxxxxxxxxxx"
}

ZapSign

Campo	Descrição	Obrigatório
`apiToken`	Token de API do ZapSign	Sim
`sandbox`	Se deve usar ambiente sandbox	Não

{
  "apiToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sandbox": false
}

Criar Configuração

POST /api/v1/esignature/provider-configs

Cria uma nova configuração de provedor de assinatura.

Atributos

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da configuração (max 100 caracteres)
`providerType`	enum	Sim	`OPENSIGN`, `DOCUSIGN`, `ADOBESIGN`, `ZAPSIGN`
`credentials`	object	Sim	Credenciais do provedor
`isDefault`	boolean	Não	Definir como padrão (default: false)
`isActive`	boolean	Não	Se está ativa (default: true)
`settings`	object	Não	Configurações adicionais

cURL
JavaScript

curl -X POST 'https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "esignature-provider-config",
      "attributes": {
        "name": "OpenSign Produção",
        "providerType": "OPENSIGN",
        "credentials": {
          "baseUrl": "https://opensign.suaempresa.com",
          "masterKey": "sua_master_key_aqui",
          "appId": "opensign",
          "apiPrefix": "/api/app"
        },
        "isDefault": true,
        "isActive": true,
        "settings": {
          "defaultExpirationDays": 30
        }
      }
    }
  }'

const response = await fetch('https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'esignature-provider-config',
      attributes: {
        name: 'OpenSign Produção',
        providerType: 'OPENSIGN',
        credentials: {
          baseUrl: 'https://opensign.suaempresa.com',
          masterKey: 'sua_master_key_aqui',
          appId: 'opensign',
          apiPrefix: '/api/app',
        },
        isDefault: true,
        isActive: true,
        settings: {
          defaultExpirationDays: 30,
        },
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Config criada: ${data.id}`);

Resposta

{
  "data": {
    "type": "esignature-provider-config",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "links": {
      "self": "/api/v1/esignature/provider-configs/550e8400-e29b-41d4-a716-446655440000"
    },
    "attributes": {
      "name": "OpenSign Produção",
      "providerType": "OPENSIGN",
      "isDefault": true,
      "isActive": true,
      "settings": {
        "defaultExpirationDays": 30
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "createdBy": "550e8400-e29b-41d4-a716-446655440001"
    }
  },
  "links": {
    "self": "/api/v1/esignature/provider-configs/550e8400-e29b-41d4-a716-446655440000"
  }
}

Listar Configurações

GET /api/v1/esignature/provider-configs

Lista todas as configurações de provedor da organização.

cURL
JavaScript

curl -X GET 'https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs' \
  -H 'Authorization: Bearer SEU_TOKEN'

const response = await fetch('https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
data.forEach(config => {
  console.log(`${config.attributes.name} (${config.attributes.providerType}) - Default: ${config.attributes.isDefault}`);
});

Resposta

{
  "data": [
    {
      "type": "esignature-provider-config",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "links": {
        "self": "/api/v1/esignature/provider-configs/550e8400-e29b-41d4-a716-446655440000"
      },
      "attributes": {
        "name": "OpenSign Produção",
        "providerType": "OPENSIGN",
        "isDefault": true,
        "isActive": true,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    },
    {
      "type": "esignature-provider-config",
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "links": {
        "self": "/api/v1/esignature/provider-configs/550e8400-e29b-41d4-a716-446655440002"
      },
      "attributes": {
        "name": "DocuSign Backup",
        "providerType": "DOCUSIGN",
        "isDefault": false,
        "isActive": true,
        "createdAt": "2024-01-16T14:00:00Z",
        "updatedAt": "2024-01-16T14:00:00Z"
      }
    }
  ]
}

Obter Configuração

GET /api/v1/esignature/provider-configs/:id

Obtém uma configuração específica por ID.

cURL
JavaScript

curl -X GET 'https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN'

const configId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs/${configId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Provedor: ${data.attributes.providerType}`);
console.log(`Padrão: ${data.attributes.isDefault}`);

Atualizar Configuração

PATCH /api/v1/esignature/provider-configs/:id

Atualiza uma configuração existente.

Atributos

Campo	Tipo	Descrição
`name`	string	Nome da configuração
`credentials`	object	Novas credenciais (substitui as existentes)
`isDefault`	boolean	Definir como padrão
`isActive`	boolean	Ativar/desativar
`settings`	object	Configurações adicionais

Nota

Não é possível alterar o providerType de uma configuração existente. Para mudar de provedor, crie uma nova configuração.

cURL
JavaScript

curl -X PATCH 'https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "esignature-provider-config",
      "attributes": {
        "name": "OpenSign Produção - Atualizado",
        "credentials": {
          "baseUrl": "https://opensign.suaempresa.com",
          "masterKey": "nova_master_key"
        },
        "settings": {
          "defaultExpirationDays": 15
        }
      }
    }
  }'

const configId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs/${configId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'esignature-provider-config',
      attributes: {
        name: 'OpenSign Produção - Atualizado',
        credentials: {
          baseUrl: 'https://opensign.suaempresa.com',
          masterKey: 'nova_master_key',
        },
        settings: {
          defaultExpirationDays: 15,
        },
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Config atualizada: ${data.attributes.updatedAt}`);

Excluir Configuração

DELETE /api/v1/esignature/provider-configs/:id

Exclui uma configuração de provedor.

Atenção

Não é possível excluir uma configuração que possui requisições de assinatura associadas. Primeiro, exclua ou cancele as requisições pendentes.

cURL
JavaScript

curl -X DELETE 'https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN'

const configId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs/${configId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

if (response.status === 204) {
  console.log('Config excluída com sucesso');
}

Resposta

Status 204 No Content em caso de sucesso.

Testar Conexão

POST /api/v1/esignature/provider-configs/:id/test

Testa a conexão com o provedor usando as credenciais configuradas.

cURL
JavaScript

curl -X POST 'https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs/550e8400-e29b-41d4-a716-446655440000/test' \
  -H 'Authorization: Bearer SEU_TOKEN'

const configId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs/${configId}/test`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const result = await response.json();

if (result.success) {
  console.log('Conexão OK!');
} else {
  console.error(`Falha na conexão: ${result.message}`);
}

Resposta de Sucesso

{
  "success": true,
  "message": "Connection successful"
}

Resposta de Falha

{
  "success": false,
  "message": "Invalid API key"
}

Definir como Padrão

POST /api/v1/esignature/provider-configs/:id/set-default

Define uma configuração como padrão da organização. A configuração padrão anterior será automaticamente desmarcada.

cURL
JavaScript

curl -X POST 'https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs/550e8400-e29b-41d4-a716-446655440000/set-default' \
  -H 'Authorization: Bearer SEU_TOKEN'

const configId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://e-signature.stg.catalisa.app/api/v1/esignature/provider-configs/${configId}/set-default`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`${data.attributes.name} agora é o provedor padrão`);

Resposta

Retorna a configuração atualizada com isDefault: true.

{
  "data": {
    "type": "esignature-provider-config",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "OpenSign Produção",
      "providerType": "OPENSIGN",
      "isDefault": true,
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T12:00:00Z"
    }
  }
}

Boas Práticas

Mantenha apenas uma configuração padrão - Facilita a integração
Teste antes de usar - Use /test após criar ou atualizar credenciais
Rotacione credenciais - Atualize as chaves periodicamente
Use nomes descritivos - Ex: "OpenSign Produção", "DocuSign Sandbox"
Configure webhooks - Após criar a config, configure o webhook no provedor

Endpoints​

Atributos​

Credenciais por Provedor​

OpenSign​

Modo 1: Master Key (Self-hosted / Desenvolvimento)​

Modo 2: Session Token (Usuário autenticado)​

DocuSign​

Adobe Sign​

ZapSign​

Criar Configuração​

Atributos​

Resposta​

Listar Configurações​

Resposta​

Obter Configuração​

Atualizar Configuração​

Atributos​

Excluir Configuração​

Resposta​

Testar Conexão​

Resposta de Sucesso​

Resposta de Falha​

Definir como Padrão​

Resposta​

Boas Práticas​

Endpoints

Atributos

Credenciais por Provedor

OpenSign

Modo 1: Master Key (Self-hosted / Desenvolvimento)

Modo 2: Session Token (Usuário autenticado)

DocuSign

Adobe Sign

ZapSign

Criar Configuração

Atributos

Resposta

Listar Configurações

Resposta

Obter Configuração

Atualizar Configuração

Atributos

Excluir Configuração

Resposta

Testar Conexão

Resposta de Sucesso

Resposta de Falha

Definir como Padrão

Resposta

Boas Práticas