Albaranes

Conjunto de llamadas que permiten realizar acciones sobre los albaranes/notas de entrega de una cuenta de FacturaDirecta.

Recurso Descripción
GET /api/deliveryNotes.xml Devuelve un listado de albaranes permitiendo el filtrado por múltiples atributos
GET /api/deliveryNotes/#{id}.xml Devuelve un albarán con identificador #{id}
GET /api/deliveryNotes/#{id}.pdf Devuelve un albarán con identificador #{id} en formato PDF
PUT /api/deliveryNotes/#{id}.xml Modifica los datos de un albarán existente identificado por el identificador #{id}
POST /api/deliveryNotes.xml Permite crear un nuevo albarán
DELETE /api/deliveryNotes/#{id}.xml Elimina un albarán existente identificado por el identificador #{id}
GET /api/deliveryNotes/send/#{id}.xml Envía por email el albarán con identificador #{id} al cliente
PUT /api/deliveryNotes.xml Devuelve una plantilla de la estructura en xml para poder utilizarla para crear un nuevo albarán

Trabajando con campos personalizados

Si el objeto tiene definidos campos personalizados estos se recibirán en un elemento XML de la siguiente forma:

<customAttributes>
 <customAttribute>
 <label><![CDATA[Campo 1]]></label>
 <value><![CDATA[Valor 1]]></value>
 </customAttribute>
 <customAttribute>
 <label><![CDATA[Campo 2]]></label>
 <value><![CDATA[Valor 2]]></value>
 </customAttribute>
</customAttributes>

El ejemplo anterior se corresponde con un objeto que tiene definidos dos campos personalizados con nombres “Campo 1” y “Campo 2”.

Los valores pueden tanto consultarse como modificarse.

Si se recibe un elemento con un campo personalizado con un nombre que no existe la llamada a la API fallará con el siguiente error:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
 <httpStatus>400</httpStatus>
 <errorCode>INVALID_INPUT_DATA</errorCode>
 <errorMessage><![CDATA[Se ha recibido un atributo personalizado que no existe en el objeto]]></errorMessage>
</xml>

Cuando se está actualizando un objeto solo se actualizarán aquellos campos personalizados incluidos en el XML. Si no existe el elemento customAttribute el campo personalizado no se actualiza, si existe se actualiza su valor, y su no se recibe un valor dentro del elemento customAttribute se elimina el contenido del campo personalizado.

Si consideramos el elemento customAttributes indicado arriba y en una actualización se recibe el siguiente fragmento:

<customAttributes>
 <customAttribute>
 <label><![CDATA[Campo 1]]></label>
 <value><![CDATA[Valor 1b]]></value>
 </customAttribute>
</customAttributes>

Se actualiza el valor del campo “Campo 1” a “Valor 1b” y “Campo 2” se mantiene.

Sin embargo si recibimos esto:

<customAttributes>
 <customAttribute>
 <label><![CDATA[Campo 1]]></label>
 <value><![CDATA[Valor 1]]></value>
 </customAttribute>
 <customAttribute>
 <label><![CDATA[Campo 2]]></label>
 </customAttribute>
</customAttributes>

Se actualiza el valor del campo “Campo 1” a “Valor 1b” y “Campo 2” se elimina.

Se ha definido este comportamiento para poder trabajar con la API sin perder valores de campos personalizados que son añadidos posteriormente a la integración con la API de FacturaDirecta.

GET /api/deliveryNotes.xml

Devuelve un listado de albaranes permitiendo el filtrado por múltiples atributos.

Obtener la lista de albaranes

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

Opciones de paginación de lista y límites de elementos

Por defecto la llamada devuelve los 100 primeros elementos. Para obtener la lista de más elementos o bien paginar las llamadas deben utilizarse los siguientes parámetros:

Parámetro Descripción
limit Indica el número de entradas que devolverá la llamada (por defecto son 100 y se pueden listar hasta un máximo de 250 entradas en una sola llamda)
start Indica la posición del primer elemento que se devolverá en la llamada (por defecto es el elemento de la posición 0)

Opciones de filtrado de albaranes

Para focalizar más la consulta de albaranes, puedes utilizar las siguientes opciones de filtrado:

Parámetro Descripción
client Permite obtener solo los albaranes de un cliente (especificado por su ID)
fromDate Permite obtener los albaranes desde la fecha indicada (en formato AAAAMMDD)
toDate Permite obtener los albarante hasta la fecha indicada (en formato AAAAMMDD)
documentSerial Permite obtener los albaranes de una única serie
documentNumber Permite obtener los albaranes con un determinado número (se refiere al número de albarán dentro de una serie, para buscar por número de albarán incluyendo serie debe utilizarse el parámetro documentNumberFormatted)
documentNumberFormatted Permite obtener los albaranes con un determinado número y serie tal y como se representan en el documento en formato PDF
subject Permite obtener las facturas donde su título contenga el valor indicado
tag Permite obtener los albaranes que tengan asignada la etiqueta con texto indicado (Se puede incluir más de un parámetro tag en la petición)
tagCond Cuando la consulta contiene más de un parámetro tag indica si la consulta mostrará los albaranes que tengan todas las etiquetas indicadas (valor and del parámetro) o cualquiera de ellas (valor or del parámetro)
documentStatus Permite obtener los albaranes que tengan asignado el estado con el texto indicado. Para obtener albaranes sin estado se debe indicar el parámetro documentStatus vacío
ownerEmail Permite obtener sólo los albaranes propiedad del usuario con el email indicado

Ejemplos

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes.xml?client=52\&fromDate=20110101\&toDate=20110331

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes.xml?client=52\&fromDate=20110101\&toDate=20110331\&tag=Etiqueta 1\&tag=Etiqueta 2\&tagCond=and

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes.xml?client=52\&fromDate=20110101\&toDate=20110331\&tag=Etiqueta 1\&tag=Etiqueta 2\&tagCond=or

GET /api/deliveryNotes/#{id}.xml

Obtener un albarán existente

Ejemplo para obtener un albarán con id=175

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

RESPUESTA SATISFACTORIA

<?xml version="1.0" encoding="UTF-8"?>
<deliveryNote>
 <id>1646</id>
 <updateDate>20130129105221.081</updateDate>
 <client>
 <id><![CDATA[86]]></id>
 <legalType><![CDATA[J]]></legalType>
 <name><![CDATA[CLIENTE, SL]]></name>
 <tradeName><![CDATA[Web International Solutions]]></tradeName>
 <taxCode><![CDATA[B12345674]]></taxCode>
 <address1><![CDATA[AVDA. PUBLICIDAD, 123]]></address1>
 <address2><![CDATA[]]></address2>
 <city><![CDATA[MADRID]]></city>
 <province><![CDATA[MADRID]]></province>
 <zipcode><![CDATA[28012]]></zipcode>
 <country><![CDATA[ES]]></country>
 <website><![CDATA[www.cliente-web.com]]></website>
 </client>
 <documentDate>20130121</documentDate>
 <documentSerial></documentSerial>
 <documentNumber>2</documentNumber>
 <documentNumberFormatted><![CDATA[0002]]></documentNumberFormatted>
 <currency>EUR</currency>
 <netTotal>33.06</netTotal>
 <tax1>
 <name>IVA</name>
 <base>33.06</base>
 <rate>21.00</rate>
 <total>6.94</total>
 </tax1>
 <grossTotal>40.00</grossTotal>
 <notes><![CDATA[Notas albarán creado desde la API]]></notes>
 <linePricesIncludeTaxes>true</linePricesIncludeTaxes>
 <hideTotals>false</hideTotals>
 <hidePrices>true</hidePrices>
 <documentLines>
 <documentLine>
 <productCode><![CDATA[HARD01]]></productCode>
 <description><![CDATA[Instalación 1 componente hardware en cliente]]></description>
 <quantity>1.00</quantity>
 <unitPrice>40.00</unitPrice>
 <totalPrice>40.00</totalPrice>
 <applyTax1>true</applyTax1>
 <applyTax2>false</applyTax2>
 <applyTax3>false</applyTax3>
 <applyTax4>false</applyTax4>
 </documentLine>
 </documentLines>
</deliveryNote>

Cosas a tener en cuenta al obtener la información de un albarán

La estructura que devuelve el sistema con información de albaranes es mucho más completa que la estructura que se requiere enviar en la creación o edición de albarán. El motivo principal es que el sistema devuelve información que se calcula automáticamente para el albarán. Los campos que pueden calcularse automáticamente son:

Campo Comentarios
documentDate si no se indica en la creación se asume la fecha actual de creación
documentNumber si no se indica en la creación se asume el número correlativo para la serie definida
netTotal siempre se calcula automáticamente siendo la suma de los totales (totalPrice) en documentLines
taxN/base siempre se calcula automáticamente a partir de los totales (totalPrice) de los documentLines que tenga el invoiceLine/applyTaxN a true
taxN/total siempre se calcula automáticamente a partir del taxN/base multiplicado por el taxN/rate y dividido por 100.
grossTotal siempre se calcula automáticamente siendo la suma de netTotal + taxN/total …

GET /api/deliveryNotes/#{id}.pdf

Descargar un albarán en PDF

Genera la descarga de un PDF con el albarán identificado por el id: #{id}

Ejemplo para descargar un albarán en PDF con id=175

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes/175.pdf

Modo seguro de descarga de PDF

Para asegurar que nunca se transfiere el token se acceso en la url de descarga, la llamada permite pasar como parámetro resultType=url. La respuesta de una llamda con este parámetro devolverá directamente una url temporal que puede ser utilizada para obtener el PDF de manera segura sin tener que introducir el token de acceso primario.

Ejemplo para descargar un albarán en PDF con id=175 en modo seguro

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes/175.pdf?resultType=url

La respuesta a esta llamada no será directamente el PDF sino otra URL temporal del estilo:

https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes/175/print?temporaryKey=b134af657d23b3e21f657d23b3e21&u=1

Es esta última URL la que descargará el documento PDF generado.

POST /api/deliveryNotes.xml

Crea un nuevo albarán

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml'
-d "<?xml version='1.0' encoding='UTF-8'?>
<deliveryNote>
 <client>
 <id><![CDATA[86]]></id>
 </client>
 <documentDate>20130121</documentDate>
 <currency>EUR</currency>
 <tax1>
 <name>IVA</name>
 <rate>21.00</rate>
 </tax1>
 <notes><![CDATA[Notas albarán creado desde la API]]></notes>
 <linePricesIncludeTaxes>false</linePricesIncludeTaxes>
 <hideTotals>false</hideTotals>
 <hidePrices>false</hidePrices>
 <documentLines>
 <documentLine>
 <productCode><![CDATA[HARD01]]></productCode>
 <description><![CDATA[Instalación 1 componente hardware en cliente]]></description>
 <quantity>1.00</quantity>
 <unitPrice>40.00</unitPrice>
 <applyTax1>true</applyTax1>
 </documentLine>
 </documentLines>
</deliveryNote>
"
https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes.xml

Cosas a tener en cuenta en la creación de un albarán

La estructura de creación de albarán dispone de muchos campos pero muchos de ellos son opcionales. El campo cliente (deliveryNote/client) es siempre obligatorio y debe indicarse el ID del cliente (deliveryNote/client/id). El cliente debe existir previamente a la llamada de creación de albarán, con lo que si el cliente es nuevo debe utilizarse primero la llamada de creación de cliente antes de continuar con la llamada de creación de albarán. Si no se indica la fecha del albarán (documentDate), el sistema asignará automáticamente la fecha actual. Si no se indica el número de albarán (documentNumber), el sistema asignará automáticamente un número correlativo teniendo en cuenta la serie del albarán (documentSerial) En los atributos tax1, tax2, tax3 y tax4 a nivel de deliveryNote, tan solo deben indicarse: - El nombre (deliveryNote/tax1/name): IRPF, IVA, etc.. - El porcentaje aplicado (deliveryNote/tax1/rate): 18, -15

PUT /api/deliveryNotes/#{id}.xml

Modifica un albarán existente

Ejemplo para actualizar un albarán con id=175. Prácticamente todos los elementos son opcionales, y solo aquellos que estén presentes en el xml serán actualizados.

Si algún elemento es obligatorio y no existe en el xml, el sistema devolverá un mensaje de error con una pequeña descripción indicando el motivo del error.

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X PUT -H 'Accept: application/xml' -H 'Content-Type: application/xml'
-d "<?xml version='1.0' encoding='UTF-8'?>
<deliveryNote>
 <id>175</id>
 <client>
 <id><![CDATA[86]]></id>
 </client>
 <documentDate>20130121</documentDate>
 <documentSerial></documentSerial>
 <documentNumber>2</documentNumber>
 <currency>EUR</currency>
 <tax1>
 <name>IVA</name>
 <rate>21.00</rate>
 </tax1>
 <notes><![CDATA[Notas albarán creado desde la API]]></notes>
 <linePricesIncludeTaxes>true</linePricesIncludeTaxes>
 <hideTotals>false</hideTotals>
 <hidePrices>false</hidePrices>
 <documentLines>
 <documentLine>
 <productCode><![CDATA[HARD01]]></productCode>
 <description><![CDATA[Instalación 1 componente hardware en cliente]]></description>
 <quantity>1.00</quantity>
 <unitPrice>40.00</unitPrice>
 <applyTax1>true</applyTax1>
 </documentLine>
 </documentLines>
</deliveryNote>"
https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes/175.xml

Cosas a tener en cuenta al modificar un albarán

En una modificación de albarán la mayoría de campos son OPCIONALES.

Si se desean modificar lineas de albarán (documentLines), siempre es necesario enviar toda la información de todos los documentLines del albarán. (Ya que la llamada para realizar modificaciones en estos datos regenera completamente la estructura).

POST /api/deliveryNotes/send/#{id}.xml

Permite enviar un albarán por correo electrónico en formato PDF

Hacer un envío de un albarán

Para hacer el envío del albarán con id=175 personalizando todos los valores:

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml'
-d "<?xml version='1.0' encoding='UTF-8'?>
<send>
        <subject><![CDATA[Título del mensaje]]></subject>
        <body><![CDATA[<p>Estimado cliente,</p> ...]]></body>
        <contentType>text/html</contentType>
        <from>usuario@miempresa.com</from>
        <toRecipients>
                <address>contacto1@micliente.com</address>
                <address>contacto2@micliente.com</address>
                <contact>12</contact>
        </toRecipients>
        <ccRecipients>
                <address>usuario1@miempresa.com</address>
        </ccRecipients>
        <bccRecipients>
                <address>usuario2@miempresa.com</address>
        </bccRecipients>
</send>" https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes/send/175.xml

Se puede enviar el mismo albarán sin indicar ningún dato del envío y el albarán se enviará con el texto por defecto al primer destinatario del cliente con el siguiente comando:

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml' https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes/send/175.xml

Si el mensaje puede enviarse correctamente se obtiene una respuesta con código de estado 200:

<?xml version="1.0" encoding="UTF-8"?>
<xml>
 <httpStatus>200</httpStatus>
</xml>

Formato del XML de entrada

Todos los elementos del XML de entrada son opcionales.

Campo Descripción
subject Título del mensaje. (Si no se indica se genera uno por defecto).
body Contenido del mensaje. (Si no se indica se genera uno por defecto).
contenType Se pueden indicar los valores text/plain o text/html. El contenido indicado en el elemento body debe tener el formato indicado en este elemento.
from Dirección de correo electrónico del remitente del mensaje. (Sólo se aceptan las siguiente direcciones para realizar el envío: la de la propia empresa o la de cualquier usuario de la cuenta).
toRecipients Lista de destinatarios del mensaje. Si no se indica se buscará entre las direcciones del cliente, primero la de la empresa y luego la de cualquier contacto para realizar el envío (Ver formato más adelante).
ccRecipients Lista de destinatarios en copia del mensaje (Ver formato más adelante).

bccRecipients: Lista de destinatarios en copia oculta del mensaje. (Ver formato más adelante).

Formato de las listas de destinatarios

Cada una de las listas de destinatarios (toRecipients, ccRecipients, bccRecipients) puede tener dos tipos de elementos:

Campo Descripción
address Dirección de correo electrónico
contact ID del contacto (El mensaje se enviará a su dirección de correo electrónico)

El programa validará que las direcciones introducidas en elementos address correspondan a alguna dirección permitida para el envío de mensajes. Para los elementos contact se validará que el contacto pertenece al cliente indicado en el documento que se está enviando.

Las direcciones de correo permitidas para el envío son: - La del cliente, - la de cualquier contacto del cliente, - la de tu propia empresa - y la de cualquiera de los usuarios de tu cuenta.

DELETE /api/deliveryNotes/#{id}.xml

Eliminar un albarán existente

Ejemplo para eliminar un albarán con id=175

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X DELETE https://[ACCOUNT_NAME].facturadirecta.com/api/deliveryNotes/175.xml

PUT /api/deliveryNotes.xml

Devuelve la plantilla xml del nuevo albarán

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