FacturaDirecta API (REST en XML)

La API de FacturaDirecta se encuentra implementada en XML sobre HTTP utilizando los cuatro verbos (GET/POST/PUT/DELETE). Cada recurso, como Factura, Cliente, Gasto, Proveedor, etc… tiene su propia URL y se manipula de forma aislada. En otras palabras, hemos intentado que la API siguiera los principios de REST tanto como ha sido posible.

Autenticación

La autenticación se puede gestionar de dos formas, puedes elegir la que mejor se adapte a tus circunstancias e incluso trabajar indistintamente de una u otra forma en el mismo proyecto.

Utilizando parámetros

La primera forma es indicar el API token como un parámetro más en la llamada de nombre api_token, así por ejemplo para obtener un listado de gastos puedes ejecutar: 

curl https://[ACCOUNT_NAME].facturadirecta.com/api/expenses.xml?api_token=03334b0a261a2c355ae2db022a963d8e

o incluso directamente accediendo a dicha URL en un navegador (aún no estando identificado en tu cuenta de FacturaDirecta)

https://[ACCOUNT_NAME].facturadirecta.com/api/expenses.xml?api_token=03334b0a261a2c355ae2db022a963d8e

Utilizando autenticación HTTP

También es posible utilizar la autenticación Básica de HTTP. En este caso cada petición tiene que incluir la cabecera de autorización HTTP. Debes utilizar tu API token como nombre de usuario y “x” (o cualquier otro texto) como la contraseña (sólo el API token se utilizará para autenticar las peticiones de la API). Ejemplo con Curl:

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/expenses.xml

Generación de tu API token

Puedes generar tu API token de dos formas:

1) Vía login REST

Utilizando una llamada de login. Por ejemplo:

curl -X POST -d "u=USERNAME&p=PASSWORD" https://[ACCOUNT_NAME].facturadirecta.com/api/login.xml

2) Vía menú web

Generando un API token desde el menú superior en tu cuenta de FacturaDirecta: Configuración > API y aplicaciones externas

Lanzando peticiones

Asegúrate de fijar las dos cabeceras http ‘Content-Type’ y ‘Accept’ al valor ‘application/xml’ para identificar el formato de petición (request) y respuesta (response). Ejemplo con Curl:

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d "<?xml version='1.0' encoding='UTF-8'?><provider><id></id><name>Proveedor API</name><taxCode>B22345678</taxCode></provider>" https://[ACCOUNT_NAME].facturadirecta.com/api/providers.xml

Límite de peticiones

Por defecto, todas las cuentas tienen un límite de 5.000 peticiones por API cada día y de un máximo de 60 peticiones por API por minuto. Si se superan estos límites, se recibirá una respuesta 503 para las peciciones siguientes.

Respuestas

Si una petición acaba satisfactoriamente, la API devolverá un código de estado en el rango de 200.

Si una petición falla, la API devolvera un código fuera del rango de 200 y posiblemente la información del error en formato XML como contenido de la respuesta. Por ejemplo, si el recurso solicitado no existe en la base de datos, la respuesta HTTP podría tener la siguiente formato:

HTTP/1.1 404 The record could not be found
Date: Thu, 16 Mar 2006 17:41:40 GMT
...

Propietarios de objetos

Todos los objetos susceptibles de tener un propietario (que no están anidados dentro de otros) muestran información de su propietario al descargarse. La información de propietario se muestra siempre dentro de un elemento owner que habitualmente contendrá dos elementos indicando el ID del usuario (id) y el correo electrónico del mismo (email).

<owner>
    <id>2</id>
    <email><![CDATA[user@company.com]]></email>
</owner>

Si el usuario propietario de un objeto ha sido eliminado del programa, el elemento owner únicamente contendrá el elemento id

<owner>
    <id>1</id>
</owner>

Archivos adjuntos

Todos aquellos objetos que puedan incluir algún documento adjunto, en caso de tenerlo, incluyen un elemento attachments con los detalles de los distintos archivos adjuntos disponibles, por ejemplo así:

<attachments>
    <attachment>
        <url>https://[ACCOUNT_NAME].facturadirecta.com/api/storage/179/Contrato.pdf</url>
        <size>36908</size>
        <mimeType>application/pdf</mimeType>
    </attachment>
    <attachment>
        <url>https://[ACCOUNT_NAME].facturadirecta.com/api/storage/180/plano.png</url>
        <description><![CDATA[Plano de la obra]]></description>
        <size>229856</size>
        <mimeType>image/png</mimeType>
    </attachment>
</attachments>

El elemento solo está presente cuando el objeto tiene algún archivo, y tendrá tantos elementos attachment como archivos adjuntos tenga.

Cada archivo adjunto puede descargarse llamando directamente a la URL indicada simpre que se incluya el token de autenticación, bien sea como cabecera o como parámetro. La llamada debe seguir redirecciones para poder descargar el archivo ya que el servidor devolverá una URL temporal de descarta en una redirección 302.

Ejemplo con curl:

curl -L -O -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/storage/179/Contrato.pdf

Ejemplo con wget: wget --user 03334b0a261a2c355ae2db022a963d8e --password x https://[ACCOUNT_NAME].facturadirecta.com/api/storage/179/Contrato.pdf

Una nota sobre SSL

Cualquier petición no-SSL lanzada contra la cuenta de FacturaDirecta devolverá una respuesta 301 Moved Permanently redireccionando a la petición SSL. La cabecera Location contendrá la URI correcta. Asegúrate de utilizar HTTPS.