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.
Por parámetro
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. Utilizando una llamada de login. Por ejemplo:
curl -X POST -d "u=USERNAME&p=PASSWORD" https://[ACCOUNT_NAME].facturadirecta.com/api/login.xml
2. Generando un API token desde el menú superior en tu cuenta de FacturaDirecta (opció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
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
...
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.