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 |
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 |
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: |
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 |
write |
(true /false )
Especifica si el participante tendrá permisos para editar el contrato. El valor por defecto es |
invited |
(true /false )
Especifica si el participante necesitará iniciar sesión en Tractis para acceder al contrato. Cuando el valor es |
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 |
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 |
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