Facturas periódicas (recurring invoices)

Conjunto de llamadas que permiten realizar acciones sobre las facturas periódicas de una cuenta de FacturaDirecta.

Las facturas periódicas son “plantillas” de factura que se pueden configurar para poder generar automáticamente facturas reales de forma periódica (mensualmente, trimestralmente, anualmente,…)

Recurso	Descripción
GET /api/recurringInvoices.xml	Devuelve un listado de facturas periódicas permitiendo el filtrado por múltiples atributos
GET /api/recurringInvoices/#{id}.xml	Devuelve información de una factura periódica existente identificada por el identificador `#{id}`
PUT /api/recurringInvoices/#{id}.xml	Modifica los datos de una factura periódica existente identificada por el identificador `#{id}`
POST /api/recurringInvoices.xml	Permite crear una nueva factura periódica
DELETE /api/recurringInvoices/#{id}.xml	Elimina una factura periódica existente identificada por el identificador `#{id}`
PUT /api/recurringInvoices.xml	Devuelve una plantilla de la estructura en xml para poder utilizarla para crear una nueva factura periódica

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/recurringInvoices.xml

Obtener la lista de facturas periódicas

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/recurringInvoices.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 facturas periódicas

Para focalizar más la consulta de facturas periódicas, puedes utilizar las siguientes opciones de filtrado:

Parámetro	Descripción
client	Permite obtener solo las facturas periódicas de un cliente (especificado por su ID)
subject	Permite obtener las facturas donde su título contenga el valor indicado
tag	Permite obtener las facturas 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á las facturas que tengan todas las etiquetas indicadas (valor `and` del parámetro) o cualquiera de ellas (valor `or` del parámetro)
ownerEmail	Permite obtener sólo las facturas periódicas propiedad del usuario con el email indicado

Ejemplos

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/recurringInvoices.xml?client=52

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

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

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

Obtener una factura periódica existente

Ejemplo para obtener una factura periódica con id=210

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

RESPUESTA SATISFACTORIA

<?xml version="1.0" encoding="UTF-8"?>
<recurringInvoice>
        <id>210</id>
        <recurringConfiguration>
                <startDate>20110415</startDate>
                <endDate>20120415</endDate>
                <nextInvoiceDate>20110418</nextInvoiceDate>
                <periodicity>1 M</periodicity>
                <createAsDraft>true</createAsDraft>
                <mail>
                        <active>false</active>
                        <subject><![CDATA[This is the subject]]></subject>
                        <facturae>3.1</facturae>
                        <signFiles>true</signFiles>
                        <body><![CDATA[This is the body]]></body>
                        <clientRecipients>
                                <recipient>email1@cliente_ejemplo.com</recipient>
                                <recipient>email2@cliente_ejemplo.com</recipient>
                        </clientRecipients>
                </mail>
        </recurringConfiguration>
        <client>
                <id><![CDATA[57]]></id>
                <name><![CDATA[CLIENTE1, SL]]></name>
                <taxCode><![CDATA[33946562B]]></taxCode>
        </client>
        <invoiceSerial><![CDATA[T11]]></invoiceSerial>
        <currency>EUR</currency>
        <tags>
                <globalTag><![CDATA[Etiqueta global 1]]></globalTag>
                <localTag><![CDATA[Etiqueta local 1]]></localTag>
                <globalTag><![CDATA[Global 2]]></globalTag>
        </tags>
        <netTotal>29.36</netTotal>
        <tax1>
                <name>IVA</name>
                <base>29.36</base>
                <rate>18.00</rate>
                <total>5.28</total>
        </tax1>
        <tax2>
                <name>IRPF</name>
                <base>29.36</base>
                <rate>-15.00</rate>
                <total>-4.40</total>
        </tax2>
        <grossTotal>30.24</grossTotal>
        <notes></notes>
        <invoiceLines>
                <invoiceLine>
                        <productCode><![CDATA[U]]></productCode>
                        <description><![CDATA[Tarifa al uso]]></description>
                        <quantity>4.00</quantity>
                        <unitPrice>8.95</unitPrice>
                        <discountRate>18.00</discountRate>
                        <totalPrice>29.36</totalPrice>
                        <applyTax1>true</applyTax1>
                        <applyTax2>true</applyTax2>
                </invoiceLine>
        </invoiceLines>
        <payments>
                <payment>
                        <id>240</id>
                        <dueRate>50.00</dueRate>
                        <dueDelay>30</dueDelay>
                        <amount>15.12</amount>
                </payment>
                <payment>
                        <id>241</id>
                        <dueRate>50.00</dueRate>
                        <dueDelay>60</dueDelay>
                        <amount>15.12</amount>
                </payment>
        </payments>
</recurringInvoice>

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

Modificar una factura periódica existente

Ejemplo para actualizar una factura periódica con id=210. 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.

En algunos casos, es posible que solo interese modificar la periodicidad o los datos de configuración de la factura periódica. En otros, tal vez interese solo modificar las lineas de la factura o actualizar importes. Y en otros puede que solo interese modificar el contenido del plazo de los pagos.

En todos estos casos, es posible solamente indicar aquellos campos que deseamos cambiar.

Por ejemplo, si se deseara cambiar algunos datos de la periodicidad, activar el envío de email y modificar los vencimientos, bastaría con utilizar un código del estilo siguiente:

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X PUT -H 'Accept: application/xml' -H 'Content-Type: application/xml'
-d "<?xml version='1.0' encoding='UTF-8'?>
<recurringInvoice>
<id>210</id>
<recurringConfiguration>
<periodicity>1 Y</periodicity>
                 <nextInvoiceDate>20110518</nextInvoiceDate>
<mail>
<active>true</active>
</mail>
</recurringConfiguration>
<payments>
                    <payment>
<dueRate>50</dueRate>
<dueDelay>30</dueDelay>
</payment>
<payment>
<dueRate>50</dueRate>
<dueDelay>60</dueDelay>
</payment>
</payments>
</recurringInvoice>" $URL/api/recurringInvoices/210.xml

POST /api/recurringInvoices.xml

Crear una nueva factura periódica

La creación de una factura periódica funciona de forma similar a la creación de una factura normal.

En este caso, existen unos campos de configuración adicionales que definen la periodicidad de la factura:

Configuración de una factura periódica (recurringConfiguration)

El campo recurringConfiguration puede contener los siguientes subcampos:

Campo	Descripción
startDate	fecha de inicio en que la factura periódica empieza a ser válida.
endDate	fecha fin en que la factura periódica quedará desactivada.
nextInvoiceDate	fecha en la que se va a generar la próxima factura periódica.
periodicity	indica la periodicidad. El formato debe ser un número seguido de un espacio en blanco i de la unidad de periodo (`D`=día, `W`=semana, `M`=mes, `Y`=año). Ejemplos, `<periodicity>1 M</periodicity>`, `<periodicity>3 M</periodicity>`, `<periodicity>1 Y</periodicity>`.
createAsDraft	con valor true, la factura periódica se generará en estado provisional.
mail	Contiene la configuración del envío de factura automática por email.
active	true indica que la factura debe enviarse por email al generarse en cada periodo
subject	Título del mensaje de correo electrónico que se utilizará para el envío
facturae	Indica si se desea adjuntar el formato facturae de la factura (valores esperados en este campo: `3.2.1`, `3.2`, `3.1` o vacío. (vacío = no se incluirá facturae)
signFiles	`true` indica que la factura que se envíe por email se firmará digitalmente
clientRecipients	contiene la lista de direcciones de correo del cliente que recibirán el correo con la factura adjunta
recipient	indica una dirección de correo de recepción

IMPORTANTE: Los correos indicados en recipient deben estar previamente configurados en algún contacto del propio cliente o bien estar definidos en el campo ‘Correo’ del propio cliente. En caso contrario, el sistema no permitirá realizar la configuración del envío. (Esta validación se realiza para evitar que por error se puedan enviar facturas a direcciones de correo que no pertenecen al cliente seleccionado).

Ejemplo de llamada

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml'
-d "<?xml version='1.0' encoding='UTF-8'?>
<recurringInvoice>
        <id>189</id>
        <recurringConfiguration>
                <startDate>20110415</startDate>
                <endDate>20120415</endDate>
                <nextInvoiceDate>20110418</nextInvoiceDate>
                <periodicity>1 M</periodicity>
                <createAsDraft>false</createAsDraft>
                <mail>
                        <active>true</active>
                        <subject><![CDATA[Este es el titulo del mensaje]]></subject>
                        <facturae>3.2</facturae>
                        <signFiles>true</signFiles>
                        <body><![CDATA[Adjunta encontrara su factura. Gracias.]]></body>
                        <clientRecipients>
                            <recipient>email1@cliente_ejemplo.com</recipient>
                            <recipient>email2@cliente_ejemplo.com</recipient>
                        </clientRecipients>
                </mail>
        </recurringConfiguration>
        <client>
                <id>57</id>
        </client>
        <invoiceSerial>T11</invoiceSerial>
        <currency>EUR</currency>
        <tags>
                <globalTag><![CDATA[Etiqueta global 1]]></globalTag>
                <localTag><![CDATA[Etiqueta local 1]]></localTag>
                <globalTag><![CDATA[Global 2]]></globalTag>
        </tags>
        <tax1>
                <name>IVA</name>
                <rate>18.00</rate>
        </tax1>
        <tax2>
                <name>IRPF</name>
                <rate>-15.00</rate>
        </tax2>
        <subject></subject>
        <notes></notes>
        <invoiceLines>
                <invoiceLine>
                        <productCode><![CDATA[U]]></productCode>
                        <description><![CDATA[Tarifa al uso]]></description>
                        <quantity>4.00</quantity>
                        <unitPrice>8.95</unitPrice>
                        <discountRate>18.00</discountRate>
                        <applyTax1>true</applyTax1>
                        <applyTax2>true</applyTax2>
                </invoiceLine>
        </invoiceLines>
        <payments>
                <payment>
                        <dueDelay>30</dueDelay>
                        <dueRate>50</dueRate>
                </payment>
                <payment>
                        <dueDelay>60</dueDelay>
                        <dueRate>50</dueRate>
                </payment>
        </payments>
</recurringInvoice>
"
https://[ACCOUNT_NAME].facturadirecta.com/api/recurringInvoices.xml

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

Eliminar una factura periódica existente

Ejemplo para eliminar una factura periódica con id=210

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

PUT /api/recurringInvoices.xml

Obtener la plantilla xml de nueva factura periódica

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