Introdução Última atualização: 09/02/2023

Essa área é destinada para os desenvolvedores que desejam integrar o sDoc em seus sistemas.
Aqui você vai encontrar toda a referência técnica que precisa para realizar uma integração completa.

Exemplos

  • Postman
    Baixe aqui a nossa Collection feita no Postman.

Histórico de atualizações

  • Versão 1.2 beta
    • Tipos de Assinatura (Digital e Eletrônica)
    • Posicionamento de Carimbo
    • Buscar Participante
    09/03/2022
  • Versão 1.0.2
    • Correção de bugs
    17/09/2021
  • Versão 1.0.1
    • Editar Solicitação
    31/08/2021
  • Versão 1.0
    • Lançamento da API de integração
    16/07/2021
  • sDoc Integration 2020
    Compatibilidade encerrada.

Tecnologias

  • .NET 5
    Nossa API de integração foi feita inteiramente com .NET 5 usando C#.
  • SQL Server
    Nossa base de dados é 100% Microsoft com SQL Server.
  • Windows Server (IIS)
    A API está hospedada nos servidores seguros da Safeweb com Windows.

Recursos e Funcionalidades

Criar Solicitações

Criar fluxos de coletas de assinatura no sDoc via integração.
A API não realiza qualquer tipo de assinatura, esse processo é feito inteiramente dentro do portal.

Contas

Gerencie as solicitações de sua empresa com o módulo de contas.
Válido somente para empresas que criaram a conta no portal.

Baixar Arquivo

Tenha acesso aos arquivos salvos em nuvem do sDoc.
Disponível somente para solicitações criadas via integração.

Callbacks

Seja notificado sempre que houver uma assinatura no arquivo.
Outros tipos de callbacks ainda não estão disponíveis.

Recursos não contemplados

  • QR Code
    O compartilhamento rápido de arquivos usando o QR Code não está disponível na Integração.
  • Gestão da Conta
    Nenhum recurso de gestão (ex. crias pastas / gerenciar usuários) é contemplado na integração.
  • Consultar Solicitações
    A Integração não suporta consultar a lista de solicitações criadas via portal ou integração.
    Consultas são exclusivamente feitas pelo identificador único de cada uma.

Autenticação

Autenticação é feito pelo Header da requisição.
Como no exemplo abaixo, envie o Token no Header pela chave Authorization.

Segurança do Token

  • O Token é exclusivo e intransferível.
    Você fica inteiramente responsável pela guarda do token.
  • O Token fica criptografado na nossa base de dados.
    Somente você tem a versão original.
  • A Safeweb não se responsabiliza pela perda ou vazamento do Token.
    Caso ocorra essa adversidade, entre no portal do sDoc, no menu Integração e clique em Gerar Token.
    Esse processo revoga o Token e a SecretKey geradas anteriormente.

Callbacks

Sempre que houver alguma notificação, o sDoc vai notificar seu sistema via callback cadastrado da plataforma ou vinculado a uma solicitação.

Notificações disponíveis

  • Assinatura realizada Vamos notificar sempre que houver uma nova assinatura na sua solicitação.

SecretKey

Para garantir a segurança de sua API de callback, vamos enviar um SecretKey, que somente seu sistema e o sDoc conhecem, junto com a notificação.
Assim seu sistema sabe que é o sDoc chamando e notificando a atualização de uma solicitação.

  • Guarde a SecretKey dentro do seu código no back-end.
    Assim você evita a exposição da SecretKey.
  • A Safeweb não se responsabiliza pela perda ou vazamento da SecretKey.
    Caso ocorra essa adversidade, entre no portal do sDoc, no menu Integração e clique em Gerar Token.
    Esse processo revoga o Token e a SecretKey geradas anteriormente.
Estrutura do conteúdo de resposta:
Atributo Tipo Descrição Tamanho
identifier string Identificador da solicitação. Identificador da solicitação que ocorreu uma alteração. 30
type int Tipo de notificação. Tipo de ação que ocorreu dentro da solicitação. Consulte a lista de enums para mais detalhes. -
secretKey string SecretKey da plataforma. Chave para que sua aplicação saiba que é o sDoc chamando. 130
Modelo JSON:
																	
{
	"identifier": "AAA000BBB111CCC222DDD333",
	"type": 0,
	"secretKey": "E35C7BE29087A8907136D9A0994CA96AF578C7A6F5CB94EF2D11D1BB83C1EDB3"					
}

Erros

Nossa API de Integração conta com um formato padronizado para retornar os erros.
Alguns erros estão mapeados em nossa base de dados, caso você esbarre por um deles, você vai receber o código de identificação do erro na resposta da API.
Assim, você pode tratar o problema, de acordo com o tipo de erro.

Resposta

Sempre vamos retornar a API como um HttpStatus 200 (OK). Caso você receba outro status na resquisição, pode ter ocorrido algum erro genérico na aplicação ou um erro inesperado no nosso servidor.

Código Mensagem
Sistema da API
INTEGRATION_API_OFF A API de Integração está inoperante no momento. Por favor, tente novamente mais tarde. Observações: Essa mensagem indica que desligamos a API temporariamente para realizar uma manutenção.
Empresa
INTEGRATION_ENTERPRISE_5C8C Dados da empresa não cadastrados. Favor, contatar a Safeweb para realizar o cadastro. Observações: Essa mensagem indica que provavelmente algum dado da empresa ficou faltando no cadastro.
INTEGRATION_ENTERPRISE_D0AW Empresa não é usuário do sDoc. Favor, entrar no sistema com seu certificado digital (e-CNPJ) para realizar o cadastro. Observações: Essa mensagem indica que a empresa precisa entrar no sDoc para se tornar usuário.
As solicitações no sDoc são vinculadas ao CNPJ da empresa, por isso precisamos desse cadastro antes.
Arquivo
INTEGRATION_FILE_A2FC Não foi possível localizar o arquivo pelo identificador recebido.
INTEGRATION_FILE_B425 O arquivo pertence a uma solicitação que foi excluída do sistema.
INTEGRATION_FILE_HW2A O arquivo pertence a uma solicitação que não foi criada via integração.
INTEGRATION_FILE_K2Q7 O arquivo pertence a uma solicitação que não foi criada por essa plataforma.
Plataforma
INTEGRATION_PLATFORM_54F9 Esta plataforma não está ativada para realizar operações.
INTEGRATION_PLATFORM_7F86 Plataforma não cadastrada para realizar operações na integração do sDoc.
INTEGRATION_PLATFORM_F52Q Token de identificação da plataforma não foi informado na conexão.
INTEGRATION_PLATFORM_W1SY Token de identificação da plataforma é inválido.
INTEGRATION_PLATFORM_H6D1 A plataforma não está ativa.
Solicitação
INTEGRATION_SOLICITATION_41A7 Link de callback não cadastrado ou recebido por parâmetro para criar solicitação.
INTEGRATION_SOLICITATION_7D5B Solicitação requisitada não pertence a essa plataforma.
INTEGRATION_SOLICITATION_8D12 Solicitação não encontrada.
INTEGRATION_SOLICITATION_B425 Essa solicitação foi excluída do sistema.
INTEGRATION_SOLICITATION_D6F2 Solicitação não foi criada via API de Integração.
Participante
INTEGRATION_PARTICIPANT_23AA Participante não encontrado. Observações: Essa mensagem indica que o participante não foi encontrado no banco de dados.
INTEGRATION_PARTICIPANT_AEC3 Não é possível definir o posicionamento de um carimbo para um participante que não está com o status de 'Pendente' da assinatura. Observações: Essa mensagem indica que o participante já assinou ou rejeitou o arquivo, não sendo mais possível definir um carimbo para o mesmo.
INTEGRATION_PARTICIPANT_B12A Não é possível remover o posicionamento de carimbo de um participante que não tem carimbo posicionado. Observações: Essa mensagem indica que você tentou remover o carimbo de um participante que não tinha um carimbo posicionado.
INTEGRATION_PARTICIPANT_4C3F Não foi encontrado o vinculo (assinatura) entre o participante (assinante) e o arquivo (documento). Favor, consulte o time de desenvolvimento do sDoc. Observações: Essa mensagem indica que o vinculo entre participante e arquivo não foi encontrado.
Isso pode afetar o fluxo de coleta de assinaturas.
Nesse caso, contate o suporte técnico da Safeweb para solucionar esse problema junto ao time técnico.
INTEGRATION_PARTICIPANT_45D3 Esse participante não pertence a nenhuma solicitação criada por essa plataforma. Observações: Essa mensagem indica que você tentou acessar um participante de uma solicitação criada por outra plataforma/aplicação.
Os identificadores dos participantes são públicos, mas são impedidos de serem acessados por terceiros graças a Autenticação da API.
Conta
INTEGRATION_ORGANIZATION_47C6 Essa conta foi excluída do sDoc.
INTEGRATION_ORGANIZATION_49D0 Nenhuma pasta foi encontrada com o identificador informado.
INTEGRATION_ORGANIZATION_A33A A pasta informada não pertence à conta.
INTEGRATION_ORGANIZATION_BB8C Nenhuma conta encontrada com o identificador recebido.

Enums

Status da Assinatura
nº Descrição
1 Pendente
2 Assinado
3 Rejeitado
4 Aprovado
Tipo de Assinatura
nº Descrição
1 Assinatura Digital.
2 Assinatura Eletrônica.
3 Aprovador.
4 Visualizador.
Tipo de Notificação
nº Descrição
1 Assinatura realizada.
2 Assinatura rejeitada. [ Não implementado ]
3 Solicitação editada no portal. [ Não implementado ]
4 Solicitação excluida via portal. [ Não implementado ]
5 Download de arquivo via portal. [ Não implementado ]

Solicitação

Crie fluxos de solicitações de assinaturas dentro do sDoc.

Limitações

  • Não é possível gerenciar solicitações criadas via portal.
  • Não é possível incluir novos participantes em solicitações criadas via API.
  • Não é possível adicionar novos arquivos em solicitações criadas via API.
  • Máximo de 10 arquivos por solicitação.
  • Máximo de 50 participantes por solicitação.
  • Assinatura do tipo 'eletrônica' deve ter seu carimbo posicionado após a criação da solicitação.

Envio de E-mail

Para utilizar o novo serviço de envio de e-mail ao criar uma solicitação via integração, será necessário realizar a inserção dos parâmetros de acordo com a estrutura do corpo de envio da requisição.

Conforme as instruções, você deverá adicionar os parâmetros de Settings conforme descrito na lista de parametros abaixo, além disso esta configuração é totalmente opcional.

caso você não queira realizar o envio de e-mails ao criar a solicitação, basta não adicionar os parâmetros ao corpo da requisição.

Criar

Método responsável por criar solicitações de assinatura dentro do portal do sDoc.

POST https://sdocs.safeweb.com.br/api/integration/v1/solicitation

(*) Atributos obrigatórios.

Estrutura do conteúdo de envio:
Atributo Tipo Descrição Tamanho ( min / max )
title* string Título da solicitação 5/200
description string Descrição da solicitação 5/400
callback string Link de callback para notificações 5/200
organization {
identifier string Identificador da conta 20
folder string Identificador da pasta 10
}
files [
{
name* string Nome do arquivo + extensão 5/200
type* string MimeType do arquivo 5/150
tempIdentifier* string Identificador temporário do arquivo 20
}
]
participants [
{
name* string Nome completo do participante 10/250
email* string E-mail para contato do participante 1/150
cpf* string CPF / CNPJ do participante 11 ou 14
signatureType* int Tipo de Assinatura Indica se esse participante deve assinar utilizando um certificado digital ou não. -
}
]
Settings {
SendEmail bool true/false Variável para ativar ou desativar o envio de e-mail ao criar solicitação, por padrão o envio de e-mail vem desativado.
}
JSON:
																	
                                        {
                                            "title": "título da solicitação",
                                            "description": "descrição da solicitação",
                                            "callback": "link de callback exclusivo para essa solicitação",
                                            "organization": {
                                                "identifier": "identificador da conta.",
                                                "folder": "identificador da pasta onde a solicitação vai ser vinculada."
                                            },
                                            "files": [
                                            {
                                                "name": "nome do arquivo + extensão",
                                                "type": "mimeType do arquivo",
                                                "tempIdentifier" : "identificador temporário do arquivo."
                                            }
                                            ],	
                                            "participants": [
                                            {
                                                "name": "nome completo do participante",
                                                "email": "e-mail de contato do participante",
                                                "cpf" : "cpf/cnpj do participante",
                                                "signatureType" : 1,
                                            }
                                            ],
                                            "Settings":{
                                                "SendEmail": true
                                            }					
                                        }
Estrutura do conteúdo de resposta:
Atributo Tipo Descrição Tamanho
identifier string Identificador da solicitação. Esse identificador é exclusivo para essa solicitação vinculado a plataforma. 30
title string Título da solicitação. O título passa por uma formatação antes de ser salvo em nossa base de dados. -
description string Descrição da solicitação. A descrição passa por uma formatação antes de ser salvo em nossa base de dados. -
callback string Link de callback para notificações. Caso não tenha sido informado no ato da criação, o link retornado será o que foi informado no cadastro da plataforma. -
createdDate datetime Data de criação da solicitação. A data é gerada pelo nosso banco de dados. -
organization {
identifier string Identificador da conta. Identificador da conta escolhida para atribuir a solicitação. -
folder string Identificador da pasta. Identificador da pasta da conta escolhida para atribuir a solicitação. -
}
files [
{
identifier string Identificador do arquivo. Identificador gerado exclusivamente para o arquivo dessa solicitação. 15
name string Nome do arquivo. O nome do arquivo passa por algumas validações e formatações antes de ser salvo na nossa base de dados. -
type string MimeType do arquivo. -
}
]
participants [
{
identifier string Identificador do participante. Identificador gerado para o participante. 8
fileIdentifier string Identificador do arquivo vinculado ao participante. Identificador para vincular essa participante (assinatura) ao arquivo. 15
name string Nome completo do participante. O nome passa por uma formatação antes de ser salvo na nossa base de dados. -
email string E-mail para contato do participante. -
cpf string CPF / CNPJ do participante. -
status int Status da assinatura para o participante vinculado ao arquivo. Como a solicitação acabou de ser criada, por padrão esse valor sempre retorna 1. -
signatureType int Tipo de assinatura definido para o participante. Consulte a lista de enums para obter mais detalhes. -
}
]
Resposta:
																	
{
	"error": false,
	"message": "Solicitação criada com êxito.",
	"result": {
		"identifier": "identificador gerado para a solicitação (30 CARACTERES)",
		"title": "título da solicitação formatado",
		"description": "descrição da solicitação formatado",
		"callback": "link de callback que o sistema vai chamar para notificações",
		"createdDate": "2021-06-06T22:09:21", // data de criação da solicitação (gerada pelo nosso banco de dados)
		"organization": {
			"identifier": "identificador da conta.",
			"folder": "identificador da pasta onde a solicitação está."
		},
		"files": [
			{
			   "identifier": "identificação do arquivo",
			   "name": "nome do arquivo formatado",
			   "type": "tipo do arquivo"
			}
		],
		"participants": [
			{
			   "identifier": "identificador do participante",
			   "fileIdentifier": "identificação do arquivo vinculado ao participante",
			   "name": "nome do participante formatado",
			   "email": "e-mail formatado",
			   "cpf": "cpf/cnpj do participante",
			   "status": 1,         // status da assinatura
			   "signatureType": 1   // tipo de assinatura
			}
		]
	}

Editar

Método responsável por editar uma solicitação específica.

PUT https://sdocs.safeweb.com.br/api/integration/v1/solicitation?identifier=IDENTIFICADOR_DA_SOLICITAÇÃO

(*) Atributos obrigatórios.

Estrutura do conteúdo de envio:
Atributo Tipo Descrição Tamanho ( min / max )
title* string Título da solicitação Esse parâmetro sempre precisa ser enviado, mesmo que não seja modificado. 5/200
description string Descrição da solicitação Caso sua solicitação tenha uma descrição, e a API não receber esse parâmetro, o mesmo será removido. 5/400
callback string Link de callback para notificações Caso esse parâmetro não seja enviado, o callback atual não será substituido. 5/200
organization {
identifier string Identificador da conta Se sua solicitação estiver em uma conta, você pode move-lá para outra, mas não poderá mais retorna-lá para a Conta Pessoal. 20
folder string Identificador da pasta Parametro obrigatório, caso enviado o identificador da conta. 10
}
JSON:
																	
{
	"title": "novo título da solicitação",
	"description": "nova descrição da solicitação",
	"callback": "novo link de callback",
	"organization": {
		"identifier": "identificador da conta.",
		"folder": "identificador da pasta onde a solicitação vai ser vinculada."
	}			
}
Resposta:
																	
{
	"error": false,
	"message": "Solicitação editada com êxito."
}

Buscar

Método responsável por buscar uma solicitação específica.

GET https://sdocs.safeweb.com.br/api/integration/v1/solicitation?identifier=IDENTIFICADOR_DA_SOLICITAÇÃO

Resposta:
																	
{
	"error": false,
	"message": "Solicitação 'IDENTIFICADOR_DA_SOLICITAÇÃO' buscada com êxito.",
	"result": {
		"identifier": "IDENTIFICADOR_DA_SOLICITAÇÃO",
		"title": "título da solicitação",
		"description": "descrição da solicitação",
		"callback": "link de callback que o sistema vai chamar para notificações",
		"createdDate": "2021-06-06T22:09:21", // data de criação da solicitação
		"organization": {
			"identifier": "identificador da conta.",
			"folder": "identificador da pasta onde a solicitação está."
		},
		"files": [
			{
			   "identifier": "identificação do arquivo",
			   "name": "nome do arquivo",
			   "type": "tipo do arquivo"
			}
		],
		"participants": [
			{
			   "identifier": "identificador do participante",
			   "fileIdentifier": "identificação do arquivo vinculado ao participante",
			   "name": "nome do participante",
			   "email": "e-mail do participante",
			   "cpf": "cpf/cnpj do participante",
			   "status": 1 // status da assinatura
			}
		]
	}

Excluir

Método responsável por excluir uma solicitação criada via integração.

DELETE https://sdocs.safeweb.com.br/api/integration/v1/solicitation?identifier=IDENTIFICADOR_DA_SOLICITAÇÃO

Resposta:
																	
{
	"error": false,
	"message": "Solicitação excluída com êxito."	
}

Contas

Listagem de contas e suas respectivas pastas.

Limitações:

  • Não é possível gerenciar contas.
  • Não é possível gerenciar pastas.
  • Não é possível gerenciar usuários.
  • Não é possível mover solicitações criadas.

Recurso Descontinuado

O Módulo de contas está sendo descontinuado do sDoc. Quando isso de fato occorrer, você será notificado com antecedência para migrar as solicitações e adaptar sua aplicação.

Listar

Método responsável por listar contas que a plataforma faça parte.

GET https://sdocs.safeweb.com.br/api/integration/v1/organizations

Resposta:
                            									
{
    "error": false,
    "result": [
        {
            "identifier": "identificador da conta",
            "name": "nome da conta",
            "description": "descrição da conta",
            "folders": 00, // Total de pastas na conta.
            "users": 00 // Total de usuários vinculados na conta.
        },
        ...
    ]
}

Pastas

Método responsável por listar hierarquia de pastas de uma conta específica.

GET https://sdocs.safeweb.com.br/api/integration/v1/organization/{IDENTIFICADOR_DA_CONTA}/folders

Resposta:
                            									
{
    "error": false,
    "result": [
        {
            "identifier": "identificador da pasta",
            "name": "nome da pasta",
            "description": "descrição da pasta",
            "subFolders": [
                {
                    "identifier": "identificador da sub-pasta",
                    "name": "nome da sub-pasta",
                    "description": "descrição da sub-pasta",
                    "subFolders": [
                        ...
                    ]
                }
            ],
            ...
        }
}

Arquivo

Localizar e realizar upload de arquivos.

Limitações:

  • Somente um arquivo por chamada.
  • Somente arquivos de até 10MB.
  • Somente arquivos adicionados via integração.
  • Não é possível desenhar QR Code no arquivo PDF.

Upload

Método responsável por enviar um arquivo temporariamente ao servidor do sDoc.

POST https://sdocs.safeweb.com.br/api/integration/v1/file

Estrutura do conteúdo de envio:
Atributo Tipo Descrição Tamanho ( min / max )
base64* string Base64 do arquivo -

(*) Atributos obrigatórios.

JSON:
                            									
{
    "base64": "base64 válido",				
}
Resposta:
                            									
{
    "error": false,
    "result": {
        "tempIdentifier": "identificador temporário do arquivo (após criar a solicitação esse identificador é descartado)"
    }
}

Buscar

Método responsável por buscar um arquivo de uma solicitação pelo seu identificador.

GET https://sdocs.safeweb.com.br/api/integration/v1/file?identifier=IDENTIFICADOR_DO_ARQUIVO

Resposta:
                            									
{
    "error": false,
    "result": {
        "identifier": "IDENTIFICADOR_DO_ARQUIVO",
        "name": "nome do arquivo",
        "type": "tipo do arquivo",
        "base64": "base64 do arquivo no servidor (com ou sem assinaturas, dependendo do status dos participantes)."
    }
}

Participante

Buscar, editar e posicionar carimbos para os participantes das solicitações.

Limitações:

  • Não é possível adicionar novos participantes ao fluxo.
  • Não é possível remover participantes inseridos no fluxo.
  • Somente participantes adicionados via integração.
  • Assinatura do tipo 'eletrônica' deve ter seu carimbo posicionado após a criação da solicitação.

Buscar

Método responsável por buscar um participante de uma solicitação pelo seu identificador.

GET https://sdocs.safeweb.com.br/api/integration/v1/participant?identifier=IDENTIFICADOR_DO_PARTICIPANTE

Estrutura do conteúdo de resposta:
Atributo Tipo Descrição Tamanho
identifier string Identificador do participante. 8
name string Nome completo do participante. -
email string E-mail para contato do participante. -
cpf string CPF / CNPJ do participante. -
status int Status da assinatura para o participante vinculado ao arquivo. Consulte a lista de enums para obter mais detalhes. -
signatureType int Tipo de assinatura definido para o participante. Consulte a lista de enums para obter mais detalhes. -
stamp {
page* string Página Número da página onde o carimbo deve ser posicionado no PDF. -
size {
width float Largura do Carimbo -
height float Altura do Carimbo -
}
position {
ury float URY -
urx float URX -
lly float LLY -
llx float LLX -
}
}
Resposta:
                            									
{
    "error": false,
    "result": {
        "identifier": "identificador do participante",
        "name": "nome do participante",
        "email": "e-mail do participante",
        "cpf": "cpf/cnpj do participante",
        "signatureType": 1,     // tipo de assinatura definido para o participante.
        "status": 1,            // status da assinatura
        "stamp": {              // Posição do carimbo ( se vinculado ao participante )
            "page": 1,
            "size": {
                "width": 180.57,
                "height": 60.94
            },
            "position": {
                "ury": 0.0,
                "urx": 0.0,
                "lly": 0.0,
                "llx": 0.0
            }	
        }
    }
}

Posicionar Carimbo

Método responsável por definir o posicionamento do carimbo para um participante.

POST https://sdocs.safeweb.com.br/api/integration/v1/participant/IDENTIFICADOR_DO_PARTICIPANTE/stamp

(*) Atributos obrigatórios.

Estrutura do conteúdo de envio:
Atributo Tipo Descrição Tamanho ( min / max )
page* string Página Número da página onde o carimbo deve ser posicionado no PDF. -
size {
width float Largura do Carimbo -
height float Altura do Carimbo -
}
position {
ury float URY -
urx float URX -
lly float LLY -
llx float LLX -
}
JSON:
																	
    {
        "page": 1,
        "size": {
            "width": 180.57,
            "height": 60.94
        },
        "position": {
            "ury": 0.0,
            "urx": 0.0,
            "lly": 0.0,
            "llx": 0.0
        }				
    }
Resposta:
                            									
    {
        "error": false,
        "message": "Carimbo posicionado com êxito."
    }

Remover Carimbo

Método responsável por buscar um arquivo de uma solicitação pelo seu identificador.

DELETE https://sdocs.safeweb.com.br/api/integration/v1/participant/IDENTIFICADOR_DO_PARTICIPANTE/stamp

Resposta:
                            									
    {
        "error": false,
        "message": "Carimbo removido com êxito."
    }