Assinatura Digital: o que dá para automatizar pela API do aplicativo

O QUE ESTA FONTE RESPONDE

A Assinatura Digital tem endereços de API próprios, dentro da API do ERP. Dá para criar documento, acompanhar quem assinou, reenviar o convite, cancelar, excluir e mexer em contatos, modelos e pastas sem ninguém abrir o aplicativo.

Aqui está só o que é específico da Assinatura Digital. Como se gera a chave, como ela viaja na chamada, como funciona a paginação, o formato do retorno e o que cada código de erro genérico significa é assunto das fontes da API do ERP. Não repita esse caminho: mande o cliente para lá.

Nunca peça, repita nem confira a chave de API no atendimento. Se o cliente colar a chave na conversa, oriente a gerar outra, porque a que foi exposta deve ser considerada perdida.

SÃO DOIS RECURSOS NO PLANO, NÃO UM

Esta é a causa número um de chamado. Ter a integração por API liberada NÃO libera a API da Assinatura Digital. A chamada valida dois recursos, nesta ordem: primeiro o de integração por API, depois o de assinatura digital.

Se o segundo estiver faltando ou vencido, a resposta é esta, com HTTP 402: "O seu plano atual não permite integrar com Assinatura Digital. Por favor, contrate outro plano!".

Ou seja: quem já consome a API para venda ou cadastro e recebe essa mensagem não está com a chave errada nem com o endereço errado. Falta o recurso da Assinatura Digital vigente. Isso é plano, não é configuração de integração.

DEPOIS DO PLANO VEM A PERMISSÃO DO USUÁRIO DA CHAVE

Passar no plano ainda não basta. Cada chamada é conferida contra a permissão do usuário dono da chave, nas mesmas permissões da Assinatura Digital que ficam no cadastro do usuário dentro do ERP.

Listar cobra a caixa de listagem, ver o detalhe cobra visualizar, criar cobra adicionar, alterar cobra editar, excluir cobra excluir e cancelar cobra cancelar. Duas que não são óbvias: reenviar o convite cobra a caixa de adicionar, e listar os documentos de uma pasta cobra a caixa de listagem de pastas.

Por isso, resposta de "sem permissão" na API não se resolve no código do cliente. Resolve-se no grupo do usuário, dentro do ERP.

Uma armadilha real: criar cobra DUAS caixas. Isso vale para documento, contato e pasta. Adicionar, para gravar; e visualizar, porque a resposta do cadastro é montada lendo o registro recém-criado. Se o usuário da chave tem adicionar e não tem visualizar, o registro é criado, o convite sai para os signatários e mesmo assim a chamada responde sem permissão. Quem não sabe disso repete a chamada e cria documentos duplicados. Antes de mandar tentar de novo, peça para conferir a listagem.

Cuidado para não confundir duas recusas diferentes. Uma é a da caixa de permissão, e fala em não ter permissão para acessar a funcionalidade. A outra fala em não ter permissão para acessar aquele registro: essa é o documento não estar ao alcance do usuário da chave, ou porque é de outro funcionário, ou porque é de outra loja.

O QUE A API FAZ COM DOCUMENTOS

Listar documentos, com filtro por nome do documento, por nome do signatário, por situação e por período de cadastro. Um aviso: o filtro por nome do signatário sozinho quebra a consulta e devolve erro. Ele só funciona junto com o filtro por nome do documento. Se o cliente relatar erro na listagem, pergunte por qual campo ele está filtrando.

Ver um documento, que volta com os signatários e a situação de cada um, o histórico, a pasta, o link do arquivo original e o link do arquivo assinado quando já existe. O campo de quantidade de assinaturas é a contagem de signatários do documento, não quantos já assinaram: quem assinou se lê na situação de cada signatário.

Listar os signatários de um documento.

Criar documento, enviando o arquivo em base64 junto com o nome e a lista de signatários. Cada signatário leva nome, e-mail, telefone, CPF, função, o canal de envio e o tipo de autenticação. No documento dá para já mandar pasta, data de expiração, permissão de recusar, lembrete e a mensagem que vai no convite.

Editar nome, pasta e data de expiração.

Excluir, cancelar e reenviar o convite.

Três coisas que o integrador não espera. Documento criado pela API já nasce Em andamento e o convite sai na hora: não existe, pela API, criar rascunho e enviar depois. O arquivo enviado em base64 é gravado como PDF, com limite de 10 MB por arquivo. E signatário marcado como WhatsApp ou SMS já é disparado por esse canal no próprio cadastro, consumindo saldo ali, antes de qualquer reenvio.

Data de expiração no passado é recusada: "A data de expiração deve ser maior ou igual à data de hoje!".

CONTATOS, MODELOS, PASTAS E USUÁRIOS

Contatos: listar com filtro por nome, e-mail, telefone, CPF e período, ver, criar, editar e excluir. Contatos é o cadastro próprio do aplicativo, não é o cadastro de clientes do ERP. Contato com CPF, telefone e e-mail iguais aos de um já cadastrado na mesma loja é recusado com "Contato já consta na base de dados.".

Modelos: listar, ver o modelo com os campos dele e excluir. Não existe criar nem editar modelo pela API. Existe ainda um endereço que gera documento a partir do modelo, devolvendo o link do modelo ou o link de um documento já preenchido com os campos que você mandar. O modo desse mesmo endereço que dispara por e-mail está com defeito e não devolve resposta válida: não indique esse modo, escale.

Pastas: listar, ver, ver quem tem acesso, criar, editar, excluir e listar os documentos de uma pasta. O acesso da pasta (liberado para todos ou restrito a usuários selecionados) é aplicado na EDIÇÃO. Na criação pela API a lista de usuários não é vinculada: crie a pasta e ajuste o acesso em seguida, pela edição ou pela tela. Na edição, ou você manda acesso liberado sem lista de usuários, ou manda a lista sem acesso liberado; as duas juntas, ou nenhuma das duas, são recusadas com a mensagem explicando. Pasta não é só organização: ela restringe quem enxerga.

Usuários: listar os usuários ativos da loja, para você saber a quem vincular uma pasta.

AS REGRAS DO APLICATIVO QUE A API HERDA

A API não é atalho para furar regra. Ela usa as mesmas rotinas da tela e devolve as mesmas recusas.

Documento assinado não é excluído nem cancelado. Nenhuma permissão libera isso.

E a recusa não explica por quê. Tanto excluir quanto cancelar devolvem sempre a mesma frase, "Falha ao excluir Documento.", com HTTP 400, seja qual for a causa — documento assinado, documento fora do alcance daquele usuário, qualquer outro impedimento da rotina. Não leia essa frase como se o problema fosse a exclusão: ela sai igual no cancelamento. Diante dela, confira a situação do documento antes de mexer em qualquer coisa da integração.

Documento assinado não é reenviado. A resposta é "Documento já está assinado e não pode ser enviado.".

Documento já cancelado responde "Documento já está cancelado." quando você tenta cancelar de novo.

Documento assinado, cancelado ou recusado não é editado. Essa lista é fechada: nos demais casos a edição passa.

Ao criar, o nome do documento é obrigatório e é obrigatório pelo menos um signatário. Se o nome do signatário vier vazio, a recusa fala em e-mail do contato mesmo assim: leia como falta de dado do signatário e confira o nome antes do e-mail.

O QUE COSTUMA DAR ERRADO

Recebo 402 mesmo já usando a API. É o recurso de assinatura digital que falta no plano, não a integração por API.

A API não devolve os documentos que eu vejo na tela. Três causas, nesta ordem. Primeira: a listagem sai da loja em que o usuário da chave está logado, e informar outra loja na consulta não muda isso. Segunda: se o usuário da chave não tem a permissão de enxergar documentos dos outros funcionários, a API devolve só os que ele mesmo criou. Terceira: a listagem geral traz os documentos que estão fora de pasta; documento guardado em pasta sai pela listagem de documentos daquela pasta.

Cancelei e a resposta falou em excluir. É o texto da resposta de sucesso do cancelamento, que veio errado no código. O documento foi cancelado, não excluído. Confirme pela situação do documento.

Reenviei pela API e o signatário diz que não recebeu. A resposta de sucesso do reenvio é fixa: ela confirma que a rotina rodou, não que a mensagem chegou. Investigue entrega pela fonte de link que não chega.

O reenvio pela API consumiu saldo. É esperado. No reenvio, quem está marcado como WhatsApp ou SMS é disparado de novo por esse canal, e esses canais consomem saldo por signatário. E-mail não consome. Saldo tem fonte própria.

Criei a pasta pela API e ninguém ficou com acesso. É assim que a criação funciona hoje: ela não vincula os usuários. Ajuste o acesso pela edição da pasta, na API ou na tela.

Editei um documento vencido e ele voltou para Em andamento. Também é esperado: a edição regrava a situação como Em andamento.

Recebi 404 falando de um controller que não existe. Isso foi um defeito de versão antiga no endereço da API, já corrigido. Não é erro de uso e não adianta mexer na chamada: atualize a versão ou escale para o time.

ONDE ESTÃO AS OUTRAS RESPOSTAS

Chave, autenticação, paginação, formato do retorno e mensagens de erro comuns a toda a API: fontes da integração API.

O que cada caixa de permissão libera, e quem enxerga o quê: fontes de permissões e de visibilidade da Assinatura Digital.

Situações do documento, situação por signatário, histórico, token, lembrete e o que acontece quando o signatário abre o link: cada uma tem a sua fonte.

Cliente, produto, venda, nota fiscal e usuário são do ERP e se respondem pelas fontes do ERP.