Ayuda

Requisitos de la API REST de Tractis

En esta página repasamos los requisitos que hay que tener en cuenta para integrarse con la API REST de Tractis.

Protocolo de comunicación

Al tratarse de una API REST todas las invocaciones de la API se realizan mediante HTTP. Las acciones de la API se invocan empleando dos datos: la operación HTTP (POST, GET, PUT o DELETE) y la URL.

Algunos ejemplos de acciones de la API de Tractis son:

  • Crear contrato: POST /contracts
  • Listar contratos: GET /contracts
  • Listar templates: GET /templates

Debido a la naturaleza de los datos manejados en Tractis. Todas las invocaciones a la API han de realizarse mediante HTTPS de forma que la comunicación entre Tractis y el cliente vaya siempre cifrada.

Formato de comunicación

Tractis emplea las mismas URLs para servir la interfaz web HTML y para ofrecer la API XML. Es por esto que cuando invocamos una acción hemos de especificar siempre que estamos empleando la API y por tanto esperamos una respuesta XML.

Por tanto, para indicarle a Tractis que estamos invocando la API hemos de incluir siempre en las peticiones la cabecera HTTP Accept: application/xml

Además, cuando vayamos a pasarle a la API parámetros empleando un XML en el cuerpo de la petición hemos de hacérselo saber empleando la cabecera HTTP Content-Type: application/xml

Autenticación

Para utilizar la API de Tractis es necesario indicar el e-mail y la contraseña de la cuenta de usuario con la que se va a operar utilizando autenticación HTTP Básica.

Codificación de caracteres

Tractis trabaja con UTF-8 para facilitar el trabajo en distintos idiomas.

Códigos de estado

Tractis emplea los códigos de estado HTTP para dar información sobre el resultado de la acción invocada. Algunos de los códigos empleados por Tractis son:

  • 200 OK: La petición se ha procesado correctamente.
  • 201 Created: Se ha creado un recurso (por ejemplo, una petición post para crear un contrato).
  • 401 Unauthorized: Las credenciales de autenticación son incorrectas.

Puedes consultar la lista completa de códigos de estado en el RFC2616 “Hypertext Transfer Protocol — HTTP/1.1″.

Ejemplo de invocación

A continuación se muestra un par de ejemplos de invocación de la API mediante el programa cURL:


  $ curl -u demo@tractis.com:demouser \
         -H 'Accept: application/xml' \
         -i -X GET https://www.tractis.com/contracts
  HTTP/1.1 200 OK
  Status: 200 OK
  Content-Type: application/xml; charset=utf-8

  <?xml version="1.0" encoding="UTF-8"?>
  <contracts total_items="1" pages="1" page="1" per_page="25">
    <contract>
      [...]
    </contract>
  </contracts>


  $ 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