Quando usar: você é administrador e quer conectar o sistema da sua empresa ao Sonarview Sign para enviar documentos para assinatura automaticamente, sem passar pela tela.
Onde fica
Abra Configurações → Integrações. Essa área é só para administradores da empresa.
Chave de API
É a credencial que o seu sistema usa para falar com o Sonarview Sign. Em Chaves de API → Criar chave, você gera uma chave que começa com sk_live_. Pontos importantes:
-
A chave aparece uma única vez. Copie e guarde em local seguro.
-
Você pode limitar o que cada chave faz (permissões: criar assinaturas, consultar status, webhook).
-
Pode revogar a chave a qualquer momento. Ela para de funcionar na hora.
O nome da chave diz o que ela pode: leia antes de manter
Na lista de Chaves de API aparecem duas origens de chave, e as duas são suas:
-
as que você criou nesta tela, com o nome que você escolheu;
-
as credenciais de máquina, emitidas pelo próprio sistema de quem integra (sem passar por aqui). Elas se chamam Credencial de máquina e existem para que um robô de consulta funcione sem depender de alguém estar logado.
Nas credenciais de máquina, o poder vem escrito entre parênteses no próprio nome:
| O que você lê | O que a chave pode fazer |
|---|---|
Credencial de máquina (somente leitura) | Só consulta: acompanha status, lista envelopes, baixa o documento assinado e o laudo. Não cria assinatura e não gera custo. |
Credencial de máquina (CRIA ASSINATURAS) | Cria assinaturas pela API, e elas são cobradas na sua conta, como qualquer envio. |
Credencial de máquina (DESTRÓI ARQUIVO) | Pode mandar destruir documentos guardados. É irreversível: o arquivo não volta (a prova de quem assinou permanece). |
O nome da credencial diz o poder dela. Uma credencial que cria assinaturas ou que destrói arquivos não se chama “(leitura)”: o nome na lista diz o que ela pode fazer, e é por ele que você decide o que revogar. Leia o nome antes de assumir que é só consulta.
Na dúvida, revogue. Se você não reconhece uma chave, ou ela pode mais do que a sua integração precisa, revogue-a. Quem integra emite outra em segundos, e nenhum documento já assinado é afetado. O contrário não é verdade: uma chave a mais, esquecida e viva, continua podendo o que o nome dela diz.
Uma credencial de máquina é substituída a cada nova emissão do mesmo sistema. Se o sistema de quem integra pede outra, a anterior dele deixa de valer no mesmo instante. Se uma integração parar de responder logo depois de alguém "pedir a chave de novo", é quase sempre isso, e a solução é usar a chave nova, não pedir uma terceira.
Cada sistema diz quem é ao pedir a credencial. A substituição olha o sistema que pediu (o campo origin), não a organização inteira: uma emissão só substitui as credenciais do mesmo sistema. Se você integra com mais de um sistema na mesma organização, envie esse campo: sem ele, os seus sistemas compartilham a mesma linha e um pedido de chave derruba a chave do outro. A documentação da API explica os valores aceitos.
Ambiente de testes (sandbox)
Antes de ir para valer, abra um Ambiente de testes e use uma chave sk_test_. Ele é isolado, não tem custo, permite até 10 envios e os e-mails saem marcados como teste. Quando terminar, clique em "Testes concluídos" para liberar a criação das chaves de produção (sk_live_).
Segredo do webhook
Se o seu sistema quiser ser avisado automaticamente quando um documento é assinado, ele recebe um aviso (webhook), e o Segredo do webhook serve para confirmar que o aviso veio mesmo do Sonarview Sign. Há duas regras que evitam a única falha grave desta integração: aceitar qualquer keyId da lista, e ler o signed_scope em vez de presumi-lo. O passo a passo completo está em Webhooks: como receber e conferir o aviso de documento assinado, e é lá que está também quantas vezes tentamos o aviso e até quando (~7 dias), mais a regra do 410, que é a única que o sistema da sua empresa pode acionar sem saber.
O que o seu sistema precisa arquivar
Quem envia documentos pela API deve guardar o resultado do próprio lado. São duas peças, e as duas importam:
-
O documento assinado: o PDF final. O seu sistema baixa pelo endereço que chega no aviso de conclusão ou, a qualquer momento, pelo endereço de retirada da API (o mesmo caminho, sem prazo).
-
O laudo: o relatório que diz quem assinou, quando, de que aparelho e de onde, assinado digitalmente pelo Sonarview Sign. Na assinatura simples o PDF final pode sair igual ao arquivo que você enviou: nesse caso a prova de quem assinou está no laudo, não no documento. Arquive os dois juntos.
O laudo não tem prazo: continua disponível mesmo depois que o documento sai do nosso armazenamento. Já o documento assinado tem prazo de guarda, conforme o seu plano: por isso a recomendação é o seu sistema baixar e arquivar assim que o documento é concluído. Quem contrata espaço de guarda (o Cofre Sonarview, vendido em pacotes de GB) mantém aqui, sem prazo, tudo o que couber no espaço contratado.
Se quiser conferir se ficou algo para trás, a API tem uma lista do que o seu sistema ainda não retirou. Um aviso honesto sobre essa lista: ela enxerga apenas a organização da credencial que você usou. Uma lista vazia pode significar "nada pendente" ou "a chave está apontando para outra organização". Confira a organização antes de comemorar o zero.
Como conferir se o arquivo que você guardou está íntegro
Depois de baixar o documento assinado, o seu sistema consegue provar que guardou o arquivo certo, inteiro, sem depender de palpite.
A consulta de status devolve, junto com os dados do documento, dois campos:
-
sha256: a impressão digital do PDF final. É calculada exatamente sobre os mesmos bytes que a API entrega no download. -
sizeBytes: o tamanho do PDF final, em bytes.
O seu sistema calcula o SHA-256 do arquivo que arquivou e compara com o sha256 que devolvemos. Igual = a cópia está correta. Diferente = alguma coisa se perdeu no caminho, e vale baixar de novo.
Não use o tamanho como régua. É a armadilha mais comum: um contrato legítimo pode ser um PDF pequeno, e um arquivo corrompido pode ter tamanho plausível. Tamanho é palpite; a impressão digital responde sim ou não.
Enquanto o documento não estiver concluído, os dois campos vêm vazios (null). Vazio quer dizer "ainda não há arquivo final", nunca "o arquivo está errado". Tratar vazio como falha faz o seu sistema rejeitar documentos bons.
Uma observação que evita confusão: o laudo é um arquivo separado e não entra nessa conta. A impressão digital é a do documento assinado.
O link que devolvemos na resposta É UMA CREDENCIAL
Quando o seu sistema cria uma solicitação, a nossa resposta traz um link de assinatura por signatário. Na assinatura simples, quem tiver esse link assina no lugar daquela pessoa: não há segundo fator. (Na avançada é exigido também o código de 6 dígitos; na qualificada, o certificado.)
Nós já enviamos esse link ao signatário por e-mail: o seu sistema não precisa entregá-lo a ninguém. Por isso, na simples: não o exiba em tela, não o grave em log e não o encaminhe a terceiros, inclusive ao próprio remetente.
Se você não usa esse link, peça para deixar de recebê-lo. Desde 16/08/2026 a credencial de máquina pode ser emitida com omitSignUrls: true: as respostas passam a vir sem os links, e o convite ao signatário continua sendo enviado normalmente. Um campo que a sua integração não usa é superfície que você está guardando sem precisar.
Credencial de máquina
Se a sua integração começar a receber “401” ou “403” do nada, leia o code da resposta. É ele que diz de que lado está o problema, e o que fazer a seguir:
code | O que quer dizer | O que fazer |
|---|---|---|
unauthorized | O valor enviado não corresponde a nenhuma chave nossa | Confira o cabeçalho, se não é chave de teste contra produção, e se não há espaço a mais na cópia. |
credential_revoked | A sua chave existe e nós a desativamos: revogada no painel, ou substituída por uma rotação | A sua configuração está certa. Emita outra credencial; reapresentar esta não volta a funcionar. |
token_app_mismatch (403) | Você usou Authorization: Bearer com um crachá do Sonarview que é válido, mas foi emitido para outro aplicativo. Por exemplo, o crachá do Hub usado para chamar a Sign. | Repetir a chamada não resolve, porque o crachá não está vencido nem inválido. Peça um crachá da Sign, ou use a X-API-Key desta organização, que é o caminho recomendado para integração entre sistemas. |
A nossa operação é avisada no instante em que uma credencial de máquina em uso é desativada, e outra vez se alguém continuar apresentando uma credencial já revogada, para o problema não ficar do seu lado esperando que você escreva.
Para o seu sistema consultar status sem depender de um login de pessoa, a API emite uma credencial de máquina da organização: uma chave durável, cujo poder depende do que foi pedido na emissão. A emissão mais comum é somente de leitura (consultar status, listar solicitações e ver a lista de pendências), mas ela também pode ser emitida para criar assinaturas ou para destruir arquivos guardados, e nesse caso o nome dela na tela diz isso, como na tabela acima. Leia o nome antes de assumir que é só consulta.
-
Ela aparece uma única vez. Guarde-a por organização.
-
Perdeu? Peça outra: a anterior é desativada e nasce uma nova, sem intervalo sem credencial.
-
Ela aparece nesta mesma tela de Integrações, e você pode revogá-la quando quiser.
Exigir um tipo mínimo de assinatura na credencial
Desde 17/08/2026, ao emitir uma credencial de máquina você pode exigir que todo documento criado por ela aceite, no mínimo, um determinado tipo de assinatura: simple, advanced ou qualified. Serve para o caso em que a sua área jurídica decidiu que aquela integração nunca pode gerar assinatura simples.
Quem tentar criar um documento abaixo do mínimo recebe uma recusa clara (403 signature_type_too_weak), e nenhum documento é criado.
A exigência vale pelo tipo mais fraco que o documento aceita, nunca pelo rótulo dele. É a parte que costuma surpreender: um envelope híbrido tem o nome mais forte, e ainda assim deixa o signatário escolher a assinatura simples. Por isso a regra olha a lista inteira de tipos aceitos, e não o nome do envelope. Pela mesma razão, hybrid não vale como mínimo.
Sem essa exigência, nada muda: a credencial continua aceitando qualquer tipo, como antes.
Como a API conta para cobrança: por assinatura concluída
Na tela, um envio pode ser cobrado como envelope (o pacote inteiro). Pela API não existe envelope: o que conta é a assinatura concluída, uma a uma, qualquer que seja o tipo.
Na prática: um documento com cinco signatários criado pela API conta cinco assinaturas quando as cinco forem concluídas, e nenhuma enquanto ninguém assinar. Documento criado e nunca assinado não gera cobrança.
Se a sua integração hoje envia o campo billingUnit com envelope ou document, ela continua funcionando, mas esses valores saem da API, e o recomendado é deixar de enviar o campo. Omitir tem exatamente o mesmo efeito que enviar signature.
Se a conta entrar em prazo de leitura, o que acontece com a sua integração
Quando o período de teste acaba ou a fatura fica em atraso, a conta entra em um prazo de leitura: continua vendo, baixando e exportando, e deixa de criar. A regra vale para a API assim como vale para a tela.
O que a sua integração vê, hoje: se ela entra com o token da conta Sonarview, os pedidos que criam passam a receber uma recusa dizendo que a conta está em leitura, e a mensagem diz, com todas as letras, que a restrição não é da sua integração, para o suporte do seu lado não ir procurar defeito onde não há. Consulta e download continuam respondendo normalmente.
Se ela entra com a chave de API desta página, esse bloqueio ainda não está ligado: um envio pode passar durante o prazo. Dizemos isso aqui porque quem integra merece saber o que o sistema faz, e não só o que ele deveria fazer. Quando ligar, atualizamos esta página com a data.
O que continua funcionando: quem já foi convidado a assinar continua conseguindo assinar, e os processos em andamento terminam. A pessoa do outro lado não tem culpa da fatura de quem enviou.
Os detalhes do prazo (quantos dias, o que fica aberto e quem decide) estão em Consumo, plano e cobrança: como acompanhar.
Para a sua equipe técnica
Quem vai programar a integração tem um Manual de Integração completo, com os endereços (endpoints), exemplos prontos (cURL, Node.js, Python) e a lista de erros. Ele acompanha o seu acesso e também fica no painel. Serviços do próprio ecossistema Sonarview podem se conectar por um token de serviço (M2M), descrito no mesmo manual.
A chave de API dá acesso aos documentos da sua empresa. Trate-a como uma senha: nunca a exponha no navegador, em apps de celular ou em repositórios públicos. Gere uma chave por sistema e revogue as que não usa mais.
De quem é o espaço que o documento ocupa
Ao criar um documento pela API, o seu sistema pode declarar de qual aplicativo ele veio (campos origin e originOrgId). Essa declaração decide em que plano o armazenamento é contado: documento criado por outro aplicativo Sonarview pesa no plano desse aplicativo, e não no plano da Assinatura Eletrônica. A intenção é que o mesmo arquivo pese em um plano só. Se vir o mesmo documento contado em dois medidores, fale com o suporte: é defeito nosso e nós corrigimos.
Documento criado pelo seu próprio sistema (sem declarar outro aplicativo) conta normalmente no plano da Assinatura Eletrônica, igual ao que é enviado pela tela.
Mandar apagar um documento pela API (ordem de destruição)
Dá para mandar destruir um documento guardado, e a ordem é irreversível: o arquivo não volta, e a prova de quem assinou permanece. O passo a passo completo está em Apagar um documento pela API: a ordem de destruição.
Ainda com dúvida?
Se a opção de criar chaves estiver bloqueada, verifique se há um ambiente de testes aberto (encerre-o em "Testes concluídos") e se você é administrador. Persistindo, fale com o suporte pelo chat de ajuda.