Altas

Alta de documento

El uso más simple es simplemente enviar el documento a Acertia sin especificar firmantes ni ninguna otra opción. A esta opción se le van agregando las demás como código QR, stickers, flujo, etc.

Para subir el documento puedes:

Enviar la URL directamente

Si tu documento puede ser accedido públicamente a través de una URL, puedes simplemente mandarnos esa URL

// puedes mandar el nombre junto con la url
const response = await services.request({
    url_doc : {
        url: 'https://www.dropbox.com/s/sxvgq1uhb4k3s4w/contrato.pdf?dl=0',
        name: 'contrato.pdf'
    },        
})

// o en este caso el nombre del documento se extraerá del parámetro "filename"
// del header "Content-Disposition". De no encontrarse, el documento 
// se guardará con el nombre de "default.pdf"
const response = await services.request({
    url_doc : 'https://www.dropbox.com/s/sxvgq1uhb4k3s4w/contrato.pdf?dl=0'        
})

Enviar el documento en base64

Si tu documento no es accesible por una URL, puedes mandarlo a Acertia codificado en base64

const response = await services.request({
    b64_doc: {
        // documento codificado en base64
        data: 'documento codificado en base64',
        // nombre con el que se guardará el documento
        name: 'ejemplo.pdf'
    }
})

Utilizar un template

Si estarás usando el mismo documento sólo cambiando unos datos. Puedes darlo de alta como un template HTML y sólo estar mandando los datos que quieres que inyectemos. Nosotros inyectamos los datos y generamos el documento PDF.

Para dar de alta el template, el primer paso es definir el HTML con su CSS inline.

El HTML puede contener campos y tablas dinámicos para inyectar los datos mas adelante.

Un campo puede ser cualquier elemento HTML que contenga texto. Para declarar un campo en tu página HTML agrega la clase "signmage-template-field" y un id único al elemento:

<p style="text-align:justify;">
    <span class="signmage-template-field" id="full-name"></span>
    is the owner of this document.
</p>

Cuando generes el documento, el valor que especifiques será insertado en el campo:

<p style="text-align:justify;">
    <span class="signmage-template-field" id="full-name">John Doe</span>
    is the owner of this document.
</p>

Las tablas son tablas HTML con la clase "signmage-template-table" y un id único:

<table 
    class="signmage-template-table" 
    id="directory" 
    style="border: 1px solid black;">

    <theader>
        <tr style="height: 31px;">
            <th>
                <strong>NAME</strong>
            </th>
            <th>
                <strong>PHONE</strong>
            </th>
            <th>
                <strong>ADDRESS</strong>
            </th>
        </tr>
    </theader>
    <tbody>

    </tbody>

</table>

De igual manera que con los campos, cuando el documento sea generado, los valores que especifiques serán insertados en su lugar correspondiente:

<table 
    class="signmage-template-table" 
    id="directory" 
    style="border: 1px solid black; width:100%;">

    <theader>
        <tr style="height: 31px;">
            <th>
                <strong>NAME</strong>
            </th>
            <th>
                <strong>PHONE</strong>
            </th>
            <th>
                <strong>ADDRESS</strong>
            </th>
        </tr>
    </theader>
    <tbody>
        <tr>
            <td>
                <p>John Doe</p>
            </td>
            <td>
                <p>843 James Lane 
                    Lake Mary, FL 32746</p>
            </td>
            <td>
                <p>202-555-0141</p>
            </td>
        </tr>
                <tr>
            <td>
                <p>Amy Rose</p>
            </td>
            <td>
                <p>7189 East Acacia St. 
                    Dundalk, MD 21222</p>
            </td>
            <td>
                <p>202-555-0141</p>
            </td>
        </tr>
    </tbody>

</table>

Una vez que ya tienes el template definido en HTML, el siguiente paso es darlo de alta en Acertia:

const templateData = 'html del documento';

const response = await services.saveTemplate({
        template_type:'html',
                    // el template tiene que mandarse codificado en base64
        template_data: Buffer.from(templateData).toString('base64'),
                 // nombre con el que se guardará el template
        template_name: 'ejemplo1'
    })

Acertia contestará con los campos dinámicos que encontró en tu template:

{
  tables: [ { id: 'directory', rows: [] } ],
  template_title: 'ejemplo1',
  fields: [
    { id: 'full-name', value: '' }
  ]
}

Y de ahí en adelante, cada vez que quieras utilizarlo, sólo es necesario que mandes los datos correspondientes:

const response = await services.request({
        template_title: 'ejemplo1',
        fields: [
            {"id":"full-name","value":"John Doe"}
        ],
        tables: [{
            id: 'directory',
            rows: [
                ['John Doe', 
                                    '843 James Lane Lake Mary, FL 32746', 
                                    '202-555-0141'],
            ]
        }]
    })

Stickers

Los stickers te permiten especificar quién puede firmar el documento y dónde puede hacerlo. Sólo los usuarios que se especifiquen en los stickers podrán firmar el documento, y sólo pueden firmar en la posición del sticker que hayas definido.

Hay tres maneras diferentes de colocar un sticker:

1. A través del API:

    const response = await services.request({
        //La URL, base64 o template de tu documento
        url_doc: 'https://acertia.com/assets/files/signmage.pdf',
        //stickers es un arreglo de firmantes
        stickers: [
            {
                //el emisor del certificado que puede firmar 
                //este sticker
                //(el default es SAT)
                //las opciones son:
                //'SAT' para certificados del SAT
                //'Vinculada a Correo Electronico'
                //'Vinculada a SMS'
                //'Vincualda a Correo Electronico por Liga'
                authority: 'SAT',
                //el tipo de sticker
                //puede ser 'line': la firma se coloca en el sticker de 
                //manera relativa al fondo de la posición proporcionada
                //o 'rect': centra la firma en la posición dada
                stickerType: 'line',
                //tipo de dato
                //el tipo de dato con el cual se validará al firmante
                //actualmente, el sticker se puede validar a través
                //de: correo, teléfono o RFC
                //(email, phone, rfc)
                dataType: 'rfc',
                //el dato a utilizar para validar al firmante
                data: 'ARCX9012226P8',        
                //tipo de imagen
                //opcional
                //puedes especificar el tipo de imagen que el usuario 
                //usará para firmar este sticker
                //las opciones disponibles son:
                //'desc': una imagen con el texto: "Firma realizada con 
                //certificado emitido por [emisor] para: [nombre]"
                //'name': nombre del firmante tal como se encuentra en 
                //su certificado escrito con una fuente de 
                //escritura a mano
                //'hash': el base64 del sha256 del documento antes 
                //de ser firmado 
                //seguido por el nombre del firmante
                //'stroke': la firma dibujada dentro del app
                imageType: 'hash',
                //el correo del firmante
                //si quieres que Acertia maneje el flujo de firma,
                //este campo
                //es mandatorio
                email: '[email protected]',
                //página donde se debe encontrar la firma (comenzando 
                //desde 0)
                page: 0,
                //posición de la firma dentro de la página
                //ESTAS SON COORDENADAS PDF. 
                //EL (0,0) ES LA ESQUINA INFERIOR IZQUIERDA
                rect: {
                    //x inferior izquierda
                    lx:388,
                    //y inferior izquierda
                    ly:400,
                    //x superior derecha
                    tx: 496,
                    //y superior derecha
                    ty: 480
                }
            }
        ]
    })

2. Colocando un recuadro de firma en tu PDF

   Cuando se recibe un PDF, Acertia analiza el documento en busca de áreas de firma. Un área de firma es cualquier rectángulo que dentro tenga la palabra "Acertia" seguida de un RFC o un correo electrónico. Acertia elimina estos rectángulos y coloca un sticker en su lugar de manera automática.

   Además del RFC o correo del firmante, también puedes especificar los otros parámetros del sticker. Por ejemplo:

   Acertia GOCF9002226A7

   Acertia GOCF9002226A7 [email protected]

   Acertia GOCF9002226A7 [email protected] centrada hash

   Todas se refieren a la firma amparada con certificado del SAT para GOCF9002226A7. El correo es opcional a menos que se desee usar el flujo de Acertia, en cuyo caso es obligatorio.

   Se puede incluir la palabra "Linea" o "Centrada", para alinear la firma a la línea inferior o para centrarla al sticker.

   También se pueden incluir las palabras: "Cualquiera", "Descriptiva", "Nombre", o "Hash", para definir la imagen que se asocia a la firma.

   Si se omite un parámetro se aplica el default establecido en su configuración.

3. Colocando un recuadro de firma en tu template HTML

   Puedes colocar un recuadro en tu template HTML en la posición donde quieres que aparezca la firma. Al momento de solicitar tu documento, inyectas en este recuadro los datos del sticker como se pueden ver en el punto anterior (Colocando un recuadro de firma en tu PDF). Por ejemplo:

Defines el recuadro como parte del template en HTML:

<div 
    style="
    border:1px solid black; 
    float:right; 
    width:200px; 
    height:120px; 
    margin:auto; 
    color:white; 
    word-break:break-all; 
    font-size:2px;
">
        <span class="signmage-template-field" id="signer1"></span>
    </div>

Y al momento de utilizarlo inyectas en ese campo los valores del sticker:

const response = await services.request({
        template_title: 'ejemploSticker',
        fields: [
            {"id":"signer1","value":"Acertia GOCF9002226A7 dibujo"},
        ],
        tables: []
    })

4. Líneas de firma

Si estás generando tu PDF a través de Microsoft Word, puedes colocar una línea horizontal con un ALT text siguiendo las mismas reglas que se utilizan para colocar recuadros de firma. Acertia detectará esta línea y colocará un sticker en su lugar.

Flujos

Un flujo de firmas toma un documento con stickers, lo manda a todos los firmantes y te notifica cuando todos lo han firmado.

const response = services.await({
    //URL, base64 o template de tu documento
    url_doc: 'https://acertia.mx/assets/files/signmage.pdf',
    //para iniciar un flujo de firmas el documento debe contener al
    //menos un sticker
    stickers: [
        {
            email: '[email protected]',
            dataType: 'rfc',
            data: 'ARCX9012226P8',
            stickerType: 'line',
            page: 0,
            rect: {
                lx:388,
                ly:400,
                tx: 496,
                ty: 480
            }
        }
    ],
    //flujo de firma
    workflow: {
        //opcional
        //especifica la fecha de expiración del flujo de firma. El
        //flujo será cancelado si no se ha completado antes de esta
        //fecha. Por default se fijan 3 meses desde la fecha en la 
        //que el flujo fue creado
        //formato de la fecha: dd/MM/yyyy
        expiration_date: '12/11/2016',
        //opcional
        //define que tan seguido debe recordar a los firmantes que
        //firmen este documento
        //los valores permitidos son:
        //12h, 1d, 2d, 3d, 4d, 5d, 6d or 7d
        remind_every: '1d',
        //opcional
        //lenguaje en el que los firmantes recibiarán la invitación
        //en sus correos
        //por default es 'es'
        //los valores permitidos son: 'es' (Español), 'en' (Inglés)
        language: 'es',
        //opcional
        //si se encuentra presente, define el orden en el que las firmas
        //serán solicitadas
        //DEBE SER DEL MISMO TAMAÑO QUE EL NÚMERO DE STICKERS EN EL DOCUMENTO
        ordered: [
            {
                //dato del firmante (debe corresponder a un sticker)
                data: 'ARCX9012226P8'
            }
        ]
    }
})

Código QR

Puedes agregar un código QR al documento que apunta a la versión firmada del mismo en nuestros servidores. De tal manera que si alguien recibe el documento por cualquier medio, incluso impreso, podrá validarlo usando la liga incrustada en el código QR.

Para agregar un código QR manda en la solicitud la página y posición en donde quieres que aparezca:

const response = await services.request({
        //URL, base64 o template de tu documento
        url_doc: 'https://acertia.mx/assets/files/signmage.pdf',
        //posición del código QR
        //esto agregará un código QR en la esquina
        //inferior izquierda de la primera página
        qr: {
            width:    150,
            height: 150,
            x: 0,
            y: 0,
            page: 1
        }
    })

Descripción de la respuesta de solicitud de un documento

Cada vez que subas un documento, Acertia contestará con la información básica del documento que se dio de alta. Por ejemplo:

{
    // el ticket es el id del documento en Acertia. Te será
    // util cuando recibas notificaciones sobre las firmas del 
    // documento o para realizar acciones sobre el mismo
  document_ticket: '6c46b879-42e1-4b3e-a1c4-dcf959178821',
    // indica si se inicio o no un flujo de firmas para el documento
  document_flow: false,
    // indica la cantidad de stickers que se dieron de alta con el documento
  sticker_count: 1,
    // muestra los detalles de los stickers que se dieron de alta
  stickers: [
    {
      sticker_index: 0,
      sticker_email: null,
      sticker_data: 'GOCF9002226A711',
      sticker_page: 0,
      sticker_coordinates: [Object],
      sticker_type: 'RFC',
      sticker_image_type: 'desc',
      sticker_authorities: [Array]
    }
  ],
    // URL del documento listo para ser firmado
  document_url: 'https://acertia.mx/pdf/6c46b879-42e1-4b3e-a1c4-dcf959178821/?child=true&inv=true'
}

Descargar documento

Una vez que ya diste de alta el documento, puedes descargarlo en cualquier momento utilizando su id e indicando si quieres descargar el documento "original" o el "universal".

// response contendrá el base64 del documento correspondiente
const response = await services.getDocument(
    'original', 
    '04c0c65d-a06c-4f43-9a17-63b375b0106b')

Información del documento

Puedes consultar en cualquier momento el estatus de un documento (además de las notificaciones que recibirás cuando se firme un documento).

const response = await services.getReport(
    '5b31583e ac48-4bb3-8066-5a84c648bdad')

Esto devolverá como respuesta:

{
  InkSignatures: [],
  firmas: [],
  certificationLevel: 0,
  metaData: {},
  ticket: '5b31583e-ac48-4bb3-8066-5a84c648bdad',
  fileDigest: '/zUDQrKJkdXhtjgP5TTZUhcjEEqe3U4pPa3Wjiut3Qk=',
  originalName: 'contrato',
  signable: true,
  haveForm: false,
  withQR: false,
  boxes: [
    {
      fromDocumentBox: false,
      lx: 355,
      ly: 102,
      width: 200,
      line: true,
      height: 100,
      data: 'GOCF9002226A711',
      email: null,
      customData: null,
      simple: false,
      authority: [Object],
      page: 0,
      signed: false,
      imageType: 'desc',
      authorities: []
    }
  ],
  allSigned: false
}

Eliminar documento

Endpoint: https://acertia.mx/developers/docs

Puedes eliminar documentos que tu hayas subido y que no hayan sido firmados. Para hacer esto, envía el id del documento (Acertia_id) y la acción "delete":

const response = await services.docs({
    ticket: '7481782e-391a-445d-995c-5e759290ad54',
    action: 'delete'
});

Restaurar documento

Endpoint: https://acertia.mx/developers/docs

Puedes restaurar documentos que hayas eliminado. Para hacerlo, envía el id del documento (Acertia_id) y la acción "restore":

const response = await services.docs({
    ticket: '7481782e-391a-445d-995c-5e759290ad54',
    action: 'restore'
});