Crear un documento a partir de su PDF mediante la API

Esta página es para quien integra AssinaJá con otro programa. Explica cómo crear un documento a partir de un PDF propio, sin plantilla. Necesita una clave de API; la referencia completa está en Abrir la documentación de la API, en Configuración → Desarrolladores.

Los tres pasos

Pida una dirección de subida: GET /api/public/v1/Document/GenerateSignedUploadUrl. La respuesta incluye uploadUrl y documentPublicId; la dirección es válida durante 1 hora.
Suba el PDF al uploadUrl con un PUT, con las cabeceras x-ms-blob-type: BlockBlob y Content-Type: application/pdf.
Cree el documento: POST /api/public/v1/Document/CreateDocument, con el documentPublicId del paso 1. La respuesta incluye el documentId.

El documento se monta en segundo plano. Envíe una cabecera Idempotency-Key con un valor propio (un UUID, por ejemplo): si la misma petición vuelve a llegar en las 24 horas siguientes con la misma clave, recibe el mismo documentId y no se crea un segundo documento.

Un cuerpo 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 }
      ]
    }
  ]
}

El signatureType acepta Simple, SimpleInitials, OTPSMS, IdConfirmation, CMD, CMDSCAP o LDC.

Dónde van las zonas de firma

Las zonas de cada firmante van en signerRecipients[].documentRecipientSignatureLocations.

No use signatureLocations. Ese campo existe en el firmante, pero es el que devuelven los detalles del documento al leerlos (GET /Document/{id}). En una petición de creación se rechaza con SIGNATURE_LOCATIONS_WRONG_FIELD.

Cada zona tiene:

pageNumber: 1 para la primera página;
x, y, width y height: todos obligatorios, en porcentaje de la página (de 0 a 100), medidos desde la esquina superior izquierda;
x + width como máximo 100, e y + height como máximo 100.

A un firmante sin zonas no se le invita a firmar.

Errores que la petición devuelve de inmediato

Llegan como 400 con { code, message, detail }, y no se crea ningún documento. El detail indica el campo, por ejemplo signerRecipients[1].phoneNumber.

`code`	Cuándo	Qué hacer
`NO_SIGNER_RECIPIENTS`	`signerRecipients` llega vacío.	Añada al menos un firmante.
`SIGNATURE_LOCATIONS_WRONG_FIELD`	Las zonas llegaron en `signatureLocations` y `documentRecipientSignatureLocations` llega vacío.	Muévalas a `documentRecipientSignatureLocations`.
`INVALID_SIGNATURE_LOCATION`	Una zona está incompleta o se sale de la página.	Compruebe la zona indicada en el `detail` con las reglas anteriores.
`SIGNER_PHONE_REQUIRED`	Un firmante con `signatureType` `OTPSMS` no tiene `phoneNumber`.	Añada el móvil o elija otro tipo de firma.
`NO_SIGNATURE_LOCATIONS`	Ningún firmante tiene zonas.	Asigne una zona al menos a un firmante.

Los dos últimos solo se aplican cuando el documento se va a enviar. Si la organización tiene activada la política Los documentos creados fuera del navegador empiezan como borrador, el documento queda como borrador para que una persona lo complete, y el móvil y las zonas se comprueban cuando se envía.

Seguir el documento después de crearlo

Mientras el documento se está montando, GET /api/public/v1/Document/{id} responde 409 con el code document_processing. Vuelva a consultar al cabo de un rato.

Hay problemas que solo se descubren con el PDF abierto: una zona en una página que el PDF no tiene, por ejemplo. En ese caso, GET /Document/{id}, PATCH /Document/{id}/Publish, GET /Document/{id}/SignUrl y GET /Document/{id}/SignUrls responden todos 400 con:

code: DOCUMENT_CREATION_FAILED;
message: “The creation of the document with id N failed: …”, seguido del motivo;
detail: el código original, por ejemplo SIGNER_PHONE_REQUIRED, VALIDATION_ERROR o INTERNAL_ERROR.

Un error interno aparece solo como INTERNAL_ERROR, sin más detalles. Un documento más antiguo puede responder sin motivo después del mensaje y sin detail.

Ese documento es definitivo: volver a consultar no cambia la respuesta. Para intentarlo de nuevo, empiece otra vez por el paso 1: un nuevo GenerateSignedUploadUrl, una nueva subida (el documentPublicId usado queda consumido) y una nueva Idempotency-Key.

Enviar un borrador

Un documento que empezó como borrador se envía con PATCH /api/public/v1/Document/{id}/Publish: el método es PATCH, no POST. Publicar envía el documento a los firmantes.