Documentos
A tela Documentos lista os documentos enviados para assinatura da empresa. Cada documento tem uma página de detalhe, em Detalhe do documento, de onde são cadastrados os destinatários, os campos, os observadores e as etiquetas. Esses recursos estão nas páginas ao lado.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /digital-signature/documents | Lista os documentos da empresa |
| POST | /digital-signature/documents | Cadastra um documento em Aguardando envio |
| GET | /digital-signature/documents/counts | Totais por status e por etiqueta |
| GET | /digital-signature/documents/{uuid} | Consulta um documento |
| POST | /digital-signature/documents/{uuid} | Altera título e arquivo |
| DELETE | /digital-signature/documents/{uuid} | Exclui um documento |
| GET | /digital-signature/documents/{uuid}/file | Baixa o arquivo do documento |
| GET | /digital-signature/documents/{uuid}/get-signed-document | Obtém a cópia assinada do provedor |
| PUT | /digital-signature/documents/{uuid}/parameters | Altera os parâmetros de assinatura |
| PATCH | /digital-signature/documents/{uuid}/send-to-sign | Envia o documento para assinatura |
| PATCH | /digital-signature/documents/{uuid}/check-status | Consulta o status no provedor |
| POST | /digital-signature/documents/{uuid}/cancel | Cancela o documento |
| PATCH | /digital-signature/documents/{uuid}/resend-link/{recipient_id} | Reenvia o link a um destinatário |
Para a consulta de status de vários documentos de uma vez, veja Consulta de status em lote.
Consultar e listar
GET /digital-signature/documents
Lista os documentos da empresa, ordenados por título, em ordem crescente. Documentos excluídos não aparecem.
Parâmetros de URL
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
| search | Não | Texto buscado no título e nos nomes das etiquetas |
| status_id | Não | Id do status. Para vários status, repita o parâmetro (status_id[]=1&status_id[]=2) |
| tags | Não | Nome de etiqueta. Traz os documentos que tenham uma das etiquetas informadas. Repita o parâmetro para várias |
| start_date | Não | Data inicial do cadastro |
| end_date | Não | Data final do cadastro |
| per_page | Não | Quantidade de registros por página. Sem ele, a resposta é a lista simples |
| page | Não | Número da página, quando per_page é informado |
Resposta (200): cada item traz os dados do documento (uuid, title,
status_id, status, message, expiration_date, created_at), e tags como
lista de nomes de etiqueta.
curl "https://api.pedagogo.app/digital-signature/documents?status_id=1&per_page=20" \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>"
GET /digital-signature/documents/counts
Totais usados nos chips de filtro da listagem. Os totais consideram todos os documentos da empresa, sem filtro.
Resposta (200):
{
"by_status": { "1": 4, "2": 10 },
"by_tag": [ { "tag": "Contratos", "total": 7 } ]
}
by_status tem o id do status como chave e a quantidade como valor.
by_tag traz uma linha por etiqueta, com a quantidade de documentos.
GET /digital-signature/documents/{uuid}
Consulta um documento com os seus dados, o status, os destinatários, os observadores, os campos de assinatura, os nomes das etiquetas e os usuários que criaram e alteraram o registro.
Resposta (200): o objeto do documento.
Cadastrar e alterar
POST /digital-signature/documents
Cadastra um documento em Aguardando envio. O envio é feito em
multipart/form-data.
Os parâmetros de assinatura do documento começam com os padrões de assinatura configurados pela empresa, em Configurações, no momento do cadastro. Depois do cadastro, esses valores pertencem ao documento: alterar as configurações da empresa não muda os documentos já cadastrados.
O cadastro registra a ação Documento criado no histórico.
Para o cadastro, a cota de documentos do pacote é conferida. Entram na conta os documentos da empresa em qualquer status, exceto os excluídos. No pacote mensal, só contam os documentos cadastrados no mês corrente.
Corpo (multipart/form-data)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| file | Sim | Arquivo | Arquivo do documento. Use PDF: somente PDF recebe campos de assinatura |
| title | Sim | Texto | Nome do documento |
| message | Não | Texto | Mensagem que acompanha o convite de assinatura |
| expiration_date | Não | Data | Data limite para a assinatura |
Resposta (201): o objeto do documento, com status 1 (Aguardando envio).
Erros
| Status | Mensagem | Quando acontece |
|---|---|---|
| 403 | Sua empresa não possui um plano de assinatura digital. | A empresa não tem o pacote Assinatura digital |
| 403 | Espaço insuficiente | A cota de documentos do pacote foi atingida |
Esses erros têm o formato {"message": "..."}.
curl -X POST https://api.pedagogo.app/digital-signature/documents \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>" \
-F "title=Contrato exemplo" \
-F "file=@./contrato-exemplo.pdf"
O curl define o Content-Type com o limite do envio ao usar -F. Não
informe esse cabeçalho manualmente.
POST /digital-signature/documents/{uuid}
Altera o título e o arquivo do documento. O envio é feito em
multipart/form-data.
Corpo (multipart/form-data)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| title | Sim | Texto | Nome do documento |
| file | Sim | Arquivo | Arquivo do documento. Substitui o PDF guardado |
Resposta (200): o objeto do documento alterado.
PUT /digital-signature/documents/{uuid}/parameters
Altera os parâmetros de assinatura do documento. Os valores valem para o envio do documento. Os nomes dos campos correspondem aos parâmetros da tela Detalhe do documento.
Corpo (JSON)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| requires_taxpayer_number | Não | Booleano | Exige a confirmação do CPF do destinatário |
| requires_two_factor | Não | Booleano | Envia um código de confirmação por e-mail, separado do convite |
| requires_selfie | Não | Booleano | Pede foto do documento e selfie antes da assinatura |
| validity_months | Não | Inteiro | Prazo de monitoramento, de 1 a 120 meses |
| qr_code_position | Não | Texto | Posição do QR code de validação: none (não inserir), top_left, top_right, bottom_left ou bottom_right |
| appends_certificate_to_signed_file | Não | Booleano | Inclui o comprovante de assinatura ao final do documento |
Resposta (200): o objeto do documento, com os parâmetros atualizados.
{
"requires_taxpayer_number": true,
"requires_two_factor": false,
"requires_selfie": false,
"validity_months": 12,
"qr_code_position": "bottom_right",
"appends_certificate_to_signed_file": true
}
DELETE /digital-signature/documents/{uuid}
Exclui o documento. A exclusão é lógica: o documento sai das listagens. O arquivo guardado é apagado do armazenamento. Se o documento ainda estiver ativo no provedor, o sistema tenta cancelá-lo lá. Uma falha no provedor não impede a exclusão local.
Resposta (200), sem dados úteis no corpo.
Arquivo e cópia assinada
GET /digital-signature/documents/{uuid}/file
Baixa o arquivo do documento. Antes da conclusão, é o PDF enviado. Depois da conclusão, é a cópia assinada.
Resposta (200): o arquivo para download. Sem arquivo guardado, a resposta é 204, sem corpo.
GET /digital-signature/documents/{uuid}/get-signed-document
Busca no provedor o PDF assinado, grava o arquivo no documento e dispara o envio da cópia aos observadores com notificação pelo sistema. A consulta de status também faz isso quando encontra o documento concluído.
Resposta (200), sem corpo.
Envio e acompanhamento
PATCH /digital-signature/documents/{uuid}/send-to-sign
Envia o documento para assinatura. O envio só acontece se:
- o documento estiver em Aguardando envio (senão, 400 com a mensagem
Documento não pode ser enviado para assinatura); - houver pelo menos um destinatário (senão, 400 com a mensagem
Documento deve ter pelo menos um destinatário para ser enviado para assinatura); - se o documento tiver campos de assinatura posicionados, cada destinatário
tiver pelo menos um campo de assinatura (senão, 422 com a lista dos
destinatários sem campo, em
Destinatário(s) sem campo de assinatura: ...).
Ao enviar, o PDF é gerado com os campos posicionados, e o documento segue ao provedor com título, mensagem, destinatários, parâmetros, etiquetas, data de expiração e campos. Cada destinatário recebe o link pelos canais cadastrados: por e-mail, se tiver e-mail, e por SMS e WhatsApp, se tiver celular. O documento passa para Aguardando assinatura, e o envio é registrado no histórico.
Se o provedor recusar o envio, a resposta de erro traz o motivo informado pelo provedor, e o documento continua em Aguardando envio.
Resposta (200), sem corpo.
PATCH /digital-signature/documents/{uuid}/check-status
Consulta o provedor sobre o documento. Atualiza o status, as datas de abertura e de assinatura de cada destinatário e registra a consulta no histórico.
Resposta (200): o retorno do provedor para o documento. Se o documento não
estiver vinculado ao provedor, a resposta é {"message": "Documento não encontrado"}.
Se o provedor não encontrar o documento, a resposta é
{"message": "Documento não encontrado na integração"}.
POST /digital-signature/documents/{uuid}/cancel
Cancela o documento no provedor e marca o documento como Cancelado. A justificativa, quando informada, fica registrada no histórico.
Corpo (JSON)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| justification | Não | Texto | Motivo do cancelamento, registrado no histórico |
Resposta (200): {"message": "Documento cancelado com sucesso"}.
Se o provedor não aceitar o cancelamento, a resposta de erro traz o motivo, e o status do documento não muda.
PATCH /digital-signature/documents/{uuid}/resend-link/{recipient_id}
Reenvia o link de assinatura para um destinatário, pelos canais cadastrados. O destinatário precisa ter o link gerado pelo envio do documento. O documento precisa estar em Aguardando assinatura, Aberto ou Assinatura parcial.
Parâmetros de URL
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
| recipient_id | Sim | Id do destinatário, como devolvido em GET /digital-signature/documents/{document_uuid}/recipients |
Resposta (200): {"message": "Links reenviados com sucesso"}.
Se o documento não estiver em um status que permita o reenvio, a resposta é 400
com a mensagem Documento não está em um status válido para reenvio do link.