Ayuda

Crear contrato

Asegúrate de tener claros los requisitos de la API REST de Tractis antes de empezar la integración.

Descripción

Esta acción permite la creación de contratos en Tractis. La acción puede recibir parámetros para configurar:

  • El nombre del contrato.
  • Las etiquetas del contrato.
  • Las notas del contrato.
  • La plantilla que queremos usar.
  • En caso de cargar una plantilla con variables, los valores de las mismas.
  • La gente que tiene acceso al contrato así como sus permisos.
  • Los elementos visibles en la página del contrato.

El único parámetro obligatorio, como veremos a continuación, es el nombre. El resto de configuraciones son opcionales.

La acción se invoca con: POST /contracts

Crear de un contrato simple

La invocación más sencilla de esta acción es crear un contrato con un nombre únicamente. Como hemos dicho antes, el único parámetro obligatorio es el nombre del contrato. La invocación sería así (hemos dejado únicamente las cabeceras más relevantes):


  $ curl -u demo@tractis.com:password \
         -H 'Accept: application/xml' \
         -H 'Content-Type: application/xml' \
         -i -X POST https://www.tractis.com/contracts \
         -d \
'<contract>
  <name>Contrato de confidencialidad</name>
</contract>'
  HTTP/1.1 201 Created
  Status: 201 Created
  Location: https://www.tractis.com/contracts/949981041
  Content-Type: application/xml; charset=utf-8

En la respuesta podemos ver como Tractis devuelve el código HTTP 201 Created confirmando así que el contrato se ha creado correctamente. También vemos cómo emplea la cabecera Location para indicar la URL del contrato creado en la que podemos identificar la ID del contrato creado.

A continuación se listan algunos parámetros básicos de un contrato.

Parámetro Descripción
name
(obligatorio)
Nombre del contrato.
show-menu (true/false

Especifica si el menú principal de Tractis será utilizado en la presentación del contrato. El valor por defecto es true

notes Notas del contrato. Podemos emplear el parámetro sticky_notes para que las notas aparezcan sobre el contrato.
sticky-notes (true/false

Especifica si las notas se ven siempre en la página del contrato, sobre el contrato. El valor por defecto es false

tag-list Lista de etiquetas que serán aplicadas al contrato. Las etiquetas de la lista deben estar separadas por comas. 

Estas etiquetas son útiles para clasificar los contratos ya que luego podemos recuperar listados de contratos con determinadas etiquetas.

redirect-when-signed URL a la que será redirigido el usuario una vez haya firmado el contrato.

Crear un contrato a partir de una plantilla

Como ya hemos comentado, al crear un contrato podemos basarlo en una plantilla de Tractis. Al utilizar una plantilla el contrato se creará con el texto que hay en la plantilla y, si la plantilla tiene variables, podemos rellenarlas en la misma petición en la que creamos el contrato.

A continuación vemos un ejemplo de un contrato creado a partir de una plantilla donde rellenamos las variables de dicha plantilla:


  $ curl -u demo@tractis.com:password \
         -H 'Accept: application/xml' \
         -H 'Content-Type: application/xml' \
         -i -X POST https://www.tractis.com/contracts \
         -d \
 '<contract>
   <name>Escrituras de constitución de una SL</name>
   <template>249186096</template>
   <auto-complete>
     <compañía>
       <capital-social-en-euros>Valor del capital social</capital-social-en-euros>
       <valor-de-cada-participación>Valor de cada participación</valor-de-cada-participación>
       <denominación-social>Valor de la denominación social</denominación-social>
       <objeto-social>Valor de objeto social</objeto-social>
       <domicilio-social>Valor del domicilio social</domicilio-social>
     </compañía>
   </auto-complete>
 </contract>'
 HTTP/1.1 201 Created
 Status: 201 Created
 Location: https://www.tractis.com/contracts/723497093
 Content-Type: application/xml; charset=utf-8

Para esta prueba hemos usado una plantilla pública: https://www.tractis.com/templates/249186096. Así que podéis hacer la prueba vosotros mismos.

Tal y como hemos visto, los parámetros para la utilización de plantillas son:

Parámetro Descripción
template ID de la plantilla que será utilizada para crear el contrato. 

Se puede obtener fácilmente la ID de la plantilla mirando su URL:

https://www.tractis.com/templates/249186096

auto-complete Conjunto de variables de la plantilla así como los valores que serán asignados a cada variable. 

Podemos ver un XML con la lista de variables de una plantilla para tener una estructura base de ejemplo.

Hay que tener en cuenta que todos los parámetros que estamos viendo en las distintas secciones de esta página se pueden usar juntos. Por tanto, podemos crear un contrato a partir de una plantilla que tenga una serie de tags y unas notas.

Crear un contrato e invitar a un participante

Cuando creamos un contrato podemos enviar una invitación para participar en el contrato a otra persona y con qué permisos queremos que participe.


  $ curl -u demo@tractis.com:password \
         -H 'Accept: application/xml' \
         -H 'Content-Type: application/xml' \
         -i -X POST https://www.tractis.com/contracts \
         -d \
 '<contract>
    <name>Contrato de ejemplo con envío de invitación</name>
    <team>
      <member>
        <email>ernesto.jimenez@tractis.com</email>
        <sign>true</sign>
        <write>true</write>
      </member>
    </team>
  </contract>'
  HTTP/1.1 201 Created
  Status: 201 Created
  Location: https://www.tractis.com/contracts/139343253
  Content-Type: application/xml; charset=utf-8

A continuación podemos ver los parámetros que adepta <member>

Parámetro Descripción
Parámetros de <member>
email 

(obligatorio)

Especifica el mail al que será enviada la invitación o token.
sign (true/false

Especifica si el participante tendrá permisos de firma. El valor por defecto es false.

write (true/false

Especifica si el participante tendrá permisos para editar el contrato. El valor por defecto es false.

invited (true/false

Especifica si el participante necesitará iniciar sesión en Tractis para acceder al contrato. Cuando el valor es true, Tractis enviará una invitación a ese participante y está tendrá que iniciar sesión en Tractis. Si el valor es false, la persona recibirá una URL con un token aleatorio donde podrá leer y firmar el contrato sin tener que iniciar sesión en Tractis.

invitation_notify (true/false

Especifica si se desea enviar una notificación de invitación por email al participante (si no se indica el parámetro, el valor toma el valor true). Cuando el valor es true, Tractis enviará el email de notificación al participante.

validate_cert_dni_attribute (11111111X

Especifica si se desea comprobar que el número de electronic ID (p.ej: DNIe) alegado es igual al número de electronic ID contenido en el certificado utilizado para firmar. Si los números no coinciden, Tractis no permitirá realizar la firma e informará al usuario para que corrija el problema.

pin_enabled (true/false)  Default: false 

Especifica que se activa el forzado de nº de móvil para la firma con Clickwrap Avanzado.

pin_to (34607123456

Especifica el número de móvil para la firma con Clickwrap Avanzado. Se enviará el SMS durante la creación del contrato y fuerza al firmante a disponer de ese número.

El número debe tener el código de país, ej. para móvil de España: 34607123456

pin_first_name (Jose Luis

Si el firmante no dispone de cuenta en Tractis, se le creará una durante el proceso de firma, si se informa el parámetro pin_first_name se usará como “Nombre” durante el registro de cuenta en la pasarela de firma con Clickwrap Avanzado y se prepopulará automáticamente (el usuario resultante podrá cambiar estos datos en su perfil de usuario)

pin_last_name (Gordo Romero

Si el firmante no dispone de cuenta en Tractis, se le creará una durante el proceso de firma, si se informa el parámetro pin_first_name se usará como “Apellidos” durante el registro de cuenta en la pasarela de firma con Clickwrap Avanzado y se prepopulará automáticamente (el usuario resultante podrá cambiar estos datos en su perfil de usuario)

pin_text (Hola cliente, el PIN para poder firmar el contrato ##CONTRACT_ID## es este ##PIN##

Texto personalizado que se le enviará al usuario firmante durante la firma con Clickwrap avanzado, se deben especificar los placeholders siguientes: (1) ##CONTRACT_ID## que se traducirá al id del contrato al que corresponde el PIN y (2) ##PIN## que se traducirá al PIN que el usuario tendrá que introducir durante el proceso de firma con Clickwrap avanzado.

pin_sender (ACME INC) Default Tractis 

Texto o número personalizado que se usará como remitente en el envío del PIN durante el proceso de firma con Clickwrap avanzado. Máximo 11 caracteres.

Importante: Esta funcionalidad requiere aprobación previa de Tractis, por favor, enviar un email a info@tractis.com para su activación en tu cuenta.

access_control_enabled (true/false) Default false 

Habilita el control de acceso al contrato cuando se usa la pasarela de contratación (API /contracts/gateway) con firmante anónimo (no se require iniciar sesión para la firma).

access_control_method (pin

Especifica el método de control de acceso al contrato cuando se usa la pasarela de contratación (API /contracts/gateway) con firmante anónimo (no se require iniciar sesión para la firma). Actualmente sólo “pin”, necesita access_control_enabled = true y el parámetro pin_to informado.

Enviando contratos para firmar a tu cliente sin que se registre en Tractis

En la última tabla hemos visto que el parámetro invited permite especificar que no queremos enviar una invitación al contrato que requiera iniciar sesión en Tractis, sino que queremos que nuestro cliente reciba un e-mail con una URL aleatoria mediante la que podrá ver y firmar el contrato sin necesidad de ser usuario registrado en Tractis.

Además, como podemos ver en el siguiente ejemplo, cuando no vamos a enviar una invitación a Tractis tenemos la posibilidad de especificar el asunto y/o el cyerpo del e-mail que el usuario recibirá para indicarle la URL.


  $ curl -u demo@tractis.com:password \
         -H 'Accept: application/xml' \
         -H 'Content-Type: application/xml' \
         -i -X POST https://www.tractis.com/contracts \
         -d \
 '<contract>
   <name>Contrato de ejemplo con envío de invitación</name>
   <team>
     <member>
       <email>ernesto.jimenez@tractis.com</email>
       <sign>true</sign>
       <invited>false</invited>
       <message>
         <subject>Renting contract</subject>
         <body>
Hello Ernesto,
As we talked, here is the url with your contract to sign.
##URL##

Regards
John Doe
         </body>
       </message>
     </member>
   </team>
  </contract>'
  HTTP/1.1 201 Created
  Status: 201 Created
  Location: https://www.tractis.com/contracts/139343253
  Content-Type: application/xml; charset=utf-8

Los parámetros de <message> son:

Parámetro Descripción
Parámetros de <Message>
subject Texto del título del mensaje.
body Texto del cuerpo del mensaje en texto plano (no se soporta HTML). 

Si el cuerpo del mensaje incluye la cadena ##URL## Tractis sustituirá esta cadena por la URL aleatoria para que el usuario acceda al contrato. Si no incluímos esta cadena, Tractis incluirá la URL automáticamente al final del mensaje.

Ejemplo de creación de contrato completo

Como dijimos anteriormente, podemos combinar los distintos parámetros que hemos visto en las secciones de esta página. A continuación mostramos un ejemplo de creación de un contrato completo con:

  • Nombre y tags.
  • Texto de una plantilla con las variables rellenadas.
  • URL enviada a nuestro cliente en un e-mail personalizado para que lo firme sin necesidad de ser usuario de Tractis

  $ curl -u demo@tractis.com:password \
         -H 'Accept: application/xml' \
         -H 'Content-Type: application/xml' \
         -i -X POST https://www.tractis.com/contracts \
         -d \
 '<contract>
   <name>Escrituras de constitución de la SL de ernesto jiménez</name>
   <tag-list>escrituras sl, ernesto jiménez</tag-list>
   <template>249186096</template>
   <team>
     <member>
       <email>ernesto.jimenez@tractis.com</email>
       <sign>true</sign>
       <invited>false</invited>
       <message>
         <subject>Escrituras de la SL</subject>
         <body>
Hola Ernesto,

Aquí tienes las escrituras de constitución del la S.L. para que las firmes
##URL##

Comprueba que todo está en orden y firma con tu DNI electrónico cuando puedas.

Un saludo
Demo User
         </body>
       </message>
     </member>
   </team>
   <auto-complete>
     <compañía>
       <capital-social-en-euros>20.000.000 €</capital-social-en-euros>
       <valor-de-cada-participación>200 €</valor-de-cada-participación>
       <denominación-social>Super-Hiper-Mega-Empresa</denominación-social>
       <objeto-social>hacer cosas chulas</objeto-social>
       <domicilio-social>C/ El Quinto Pino</domicilio-social>
     </compañía>
   </auto-complete>
 </contract>'
  HTTP/1.1 201 Created
  Status: 201 Created
  Location: https://www.tractis.com/contracts/139343253
  Content-Type: application/xml; charset=utf-8