Pular para o conteúdo
AssinaJá

Criar um documento a partir do seu PDF pela API

Isto é matéria para quem integra o AssinaJá com outro programa. Explica como criar um documento a partir de um PDF seu, sem modelo. Precisa de uma chave API; a referência completa está em Abrir documentação da API, em Definições → Desenvolvedores.

Os três passos

Seção intitulada “Os três passos”
  1. Peça um endereço de carregamento: GET /api/public/v1/Document/GenerateSignedUploadUrl. A resposta traz uploadUrl e documentPublicId; o endereço vale 1 hora.
  2. Carregue o PDF para o uploadUrl com um PUT, com os cabeçalhos x-ms-blob-type: BlockBlob e Content-Type: application/pdf.
  3. Crie o documento: POST /api/public/v1/Document/CreateDocument, com o documentPublicId do passo 1. A resposta traz o documentId.

O documento é montado em segundo plano. Envie um cabeçalho Idempotency-Key com um valor seu (um UUID, por exemplo): se o mesmo pedido chegar outra vez nas 24 horas seguintes com a mesma chave, recebe o mesmo documentId e não é criado um segundo documento.

Um corpo válido

Seção intitulada “Um corpo válido”
{
  "documentPublicId": "<documentPublicId do passo 1>",
  "emailSubject": "Por favor assine o contrato",
  "emailMessage": "Segue o contrato de que falámos.",
  "signerRecipients": [
    {
      "name": "Maria Silva",
      "email": "maria@example.pt",
      "phoneNumber": "+351912345678",
      "signatureType": "OTPSMS",
      "protectionMode": "None",
      "order": 1,
      "documentRecipientSignatureLocations": [
        { "pageNumber": 2, "x": 10, "y": 80, "width": 30, "height": 8 }
      ]
    }
  ]
}

O signatureType aceita Simple, SimpleInitials, OTPSMS, IdConfirmation, CMD, CMDSCAP ou LDC.

Onde vão as zonas de assinatura

Seção intitulada “Onde vão as zonas de assinatura”

As zonas de cada signatário vão em signerRecipients[].documentRecipientSignatureLocations.

Não use signatureLocations. Esse campo existe no signatário, mas é o que os detalhes do documento devolvem quando os lê (GET /Document/{id}). Num pedido de criação é recusado com SIGNATURE_LOCATIONS_WRONG_FIELD.

Cada zona tem:

  • pageNumber — 1 para a primeira página;
  • x, y, width e height — todos obrigatórios, em percentagem da página (0 a 100), medidos a partir do canto superior esquerdo;
  • x + width no máximo 100, e y + height no máximo 100.

Um signatário sem zonas não é convidado a assinar.

Seção intitulada “Erros que o pedido devolve logo”

Vêm como 400 com { code, message, detail }, e não é criado documento nenhum. O detail diz qual é o campo, por exemplo signerRecipients[1].phoneNumber.

code Quando O que fazer
NO_SIGNER_RECIPIENTS signerRecipients vem vazio. Junte pelo menos um signatário.
SIGNATURE_LOCATIONS_WRONG_FIELD As zonas vieram em signatureLocations e documentRecipientSignatureLocations vem vazio. Passe-as para documentRecipientSignatureLocations.
INVALID_SIGNATURE_LOCATION Uma zona está incompleta ou sai da página. Confira a zona indicada no detail com as regras acima.
SIGNER_PHONE_REQUIRED Um signatário com signatureType OTPSMS não tem phoneNumber. Junte o telemóvel, ou escolha outro tipo de assinatura.
NO_SIGNATURE_LOCATIONS Nenhum signatário tem zonas. Dê uma zona a pelo menos um signatário.

Os dois últimos só se aplicam quando o documento vai ser enviado. Se a organização tiver ligada a política Documentos criados fora do browser começam como rascunho, o documento fica em rascunho para uma pessoa o completar, e o telemóvel e as zonas são verificados quando for enviado.

Acompanhar o documento depois de criado

Seção intitulada “Acompanhar o documento depois de criado”

Enquanto o documento está a ser montado, o GET /api/public/v1/Document/{id} responde 409 com o code document_processing. Volte a perguntar daí a pouco.

Há problemas que só se descobrem com o PDF aberto — uma zona numa página que o PDF não tem, por exemplo. Nesse caso, GET /Document/{id}, PATCH /Document/{id}/Publish, GET /Document/{id}/SignUrl e GET /Document/{id}/SignUrls respondem todos 400 com:

  • code: DOCUMENT_CREATION_FAILED;
  • message: “The creation of the document with id N failed: …”, seguido do motivo;
  • detail: o código original — por exemplo SIGNER_PHONE_REQUIRED, VALIDATION_ERROR ou INTERNAL_ERROR.

Um erro interno aparece só como INTERNAL_ERROR, sem mais pormenores. Um documento mais antigo pode responder sem motivo depois da mensagem e sem detail.

Esse documento é final — perguntar outra vez não muda a resposta. Para tentar de novo, recomece no passo 1: um novo GenerateSignedUploadUrl, um novo carregamento (o documentPublicId usado fica gasto) e uma nova Idempotency-Key.

Enviar um rascunho

Seção intitulada “Enviar um rascunho”

Um documento que começou como rascunho envia-se com PATCH /api/public/v1/Document/{id}/Publish — o método é PATCH, não POST. Publicar envia o documento aos signatários.

Relacionado

Seção intitulada “Relacionado”