Clientes

Conjunto de llamadas que permiten realizar acciones sobre los clientes de una cuenta de FacturaDirecta.

Recurso Descripción
GET /api/clients.xml Devuelve un listado de clientes permitiendo el filtrado por múltiples atributos del clientes
GET /api/clients/#{id}.xml Devuelve información de un cliente existente identificado por el identificador #{id}
POST /api/clients.xml Permite crear un nuevo cliente
PUT /api/clients/#{id}.xml Modifica los datos de un cliente existente identificado por el identificador #{id}
DELETE /api/clients/#{id}.xml Elimina un cliente existente identificado por el identificador #{id}
PUT /api/clients.xml Devuelve una plantilla de la estructura en xml para poder utilizarla para crear un nuevo cliente

Cosas a tener en cuenta

Persona física vs Persona jurídica

Para poder definir un cliente correctamente es necesario indicar el tipo legal de la empresa. Actualmente, existen dos tipos legales (legalType):

  • F Para personas físicas (personas con nombre y apellidos)
  • J Para personas jurídicas (empresas tipo sociedades, etc..)

En el caso de personas físicas (F) será necesario especificar en la creación (de forma obligatoria) o en la modificación (de forma opcional) los campos: personName y personSurname que definirán el nombre de la persona.

En el caso de personas jurídicas (J) será necesario especificar en la creación (de forma obligatoria) o en la modificación (de forma opcional) el campo: name que definirá el nombre de la empresa.

Algunos ejemplos

Persona física

<legalType><![CDATA[F]]></legalType><!-- Person física F -->
<personName><![CDATA[Nombre Cliente]]></personName>
<personSurname><![CDATA[Apellidos Cliente]]></personSurname>

Persona jurídica

<legalType><![CDATA[J]]></legalType>
<name><![CDATA[Nombre Cliente]]></name>

Definición de impuestos

Cuando se crea un nuevo cliente, si no se indican los elementos de impuestos billing/tax1 y billing/tax2, se usaran los configurados por defecto en la cuenta, en caso de que cualquier de ellos esté presente se usará la configuración indicada ignoran la que haya por defecto en la cuenta.

Notas de factura

NOTA: Esta es una función obsoleta que sólo disponible en aquellas cuentas que las tenían en uso antes del 1 de diciembre de 2014.

El elemento customInvoiceNotes es de tipo boolean e indica si las notas para las facturas de este cliente deben ser las indicadas en la configuración de la cuenta para el resto de clientes (valor false) o se van a indicar unas notas personalizadas para este cliente (valor true).

En caso de indicarse el valor true se usarán como notas las indicadas en el elemento invoiceNotes. (Es posible indicar un elemento invoiceNotes vacío y customInvoiceNotes true para que las facturas de este cliente no tengan notas, mientras que por defecto sí tengan para otros clientes las configuradas en la cuenta)

Configuración de vencimientos

Se pueden configurar hasta cuatro vencimientos distintos indicando el número de días desde la fecha de factura y el porcentaje sobre el importe total de la factura para cada uno de ellos. En caso de indicarse deben los valores en dueDates/dueDate/rate deben sumar 100.

Configuración días de pago

Se pueden configurar hasta un máximo de dos días del mes en los que el cliente realiza los pagos, utilizando los elementos payableDayInMonth1 y payableDayInMonth2.

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

Devuelve un listado de clientes permitiendo el filtrado por algunos atributos del cliente.

El listado por defecto devuelve los 100 primeros clientes de la cuenta. Para listar los clientes siguientes es necesario indicarlo por parámetro.

Obtener la lista de los 100 primeros clientes

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

Obtener la lista de los 100 siguientes clientes

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml?start=100

Obtener la lista de los 50 primeros clientes

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml?limit=50

Obtener la lista de los 50 siguientes clientes

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml?limit=50&start=50

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

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

Parámetro Descripción
taxCode Permite obtener solo los clientes con el número de NIF indicado.
code Permite obtener solo los clientes con el código de cliente indicado.
term Permite obtener una lista de los clientes para los que el valor de term coincide en una parte del nombre fiscal (name), nombre comercial (tradeName), código fiscal (taxCode)
email Permite obtener una lista de los clientes cuyo email coincide exactamente con el email indicado
emailMatch Permite indicar si la coincidencia en la búsqueda por email es exacta o parcial. El valor por defecto es búsqueda exacta, si no se indica o se indica cualquier valor incorrecto se realizará una búsqueda exacta. Valores posibles: equals, contains.
ownerEmail Permite obtener sólo los clientes propiedad del usuario con el email indicado
customAttributeName:name Permite obtener una lista de clientes filtrando por el valor del campo personalizado de nombre name. Puede realizarse un filtrado por hasta un máximo de 3 campos personalizados diferentes (no se puede repetir el mismo campo en la búsqueda en más de un parámetro)

Llamadas de ejemplo

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml?taxCode=B12341234

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml?code=430000021

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml?customAttributeName:ID_CRM=735

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

Obtener un cliente existente

Ejemplo para obtener un cliente con id=80

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

RESPUESTA SATISFACTORIA

<?xml version="1.0" encoding="UTF-8"?>
<client>
        <id>80</id>
        <legalType><![CDATA[J]]></legalType>
<name><![CDATA[Nombre Cliente]]></name>
        <taxCode><![CDATA[NIF o Código fiscal]]></taxCode>
        <tradeName><![CDATA[Nombre comercial]]></tradeName>
        <noEInvoice>false</noEInvoice>
        <address>
                <line1><![CDATA[primera linea de dirección]]></line1>
                <line2><![CDATA[segunda linea de dirección]]></line2>
                <city><![CDATA[Vic]]></city>
                <province><![CDATA[Barcelona]]></province>
                <zipcode><![CDATA[08500]]></zipcode>
                <country><![CDATA[ES]]></country>
        </address>
        <website>www.facturadirecta.com</website>
        <language>es</language>
        <email>email@facturadirecta.com</email>
        <phone><![CDATA[555020202]]></phone>
        <mobilePhone></mobilePhone>
        <notes><![CDATA[Notas para esta empresa]]></notes>
        <companyCode><![CDATA[Código empresa 1]]></companyCode>
        <billing>
                <currency>EUR</currency>
                <tax1>
                        <name>IVA</name>
                        <rate>18.00</rate>
                </tax1>
                <tax2>
                        <name>IRPF</name>
                        <rate>-15.00</rate>
                </tax2>
                <bank>
                        <country>ES</country>
                        <name><![CDATA[La Caixa]]></name>
                        <accountNumber><![CDATA[ES6121002100300000000000]]></accountNumber>
                        <swift><![CDATA[CAIXESBBXXX]]></swift>
                </bank>
                <paymentMean>02</paymentMean>
                <payableDayInMonth1>7</payableDayInMonth1>
                <payableDayInMonth2>27</payableDayInMonth2>
                <dueDates>
                        <dueDate>
                                <delayInDays>30</delayInDays>
                                <rate>50.00</rate>
                        </dueDate>
                        <dueDate>
                                <delayInDays>60</delayInDays>
                                <rate>50.00</rate>
                        </dueDate>
                </dueDates>
                <customInvoiceNotes>true</customInvoiceNotes>
                <invoiceNotes><![CDATA[Notas de factura personalizadas para este cliente]]></invoiceNotes>
        </billing>
</client>

RESPUESTA DE ERROR (no encontrado)

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

POST /api/clients.xml

Crear un nuevo cliente

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml'
-d "<?xml version='1.0' encoding='UTF-8'?>
<client>
<legalType><![CDATA[J]]></legalType> <!-- Persona jurídica J -->
<name><![CDATA[Nombre Cliente]]></name>
        <taxCode><![CDATA[NIF o Código fiscal]]></taxCode>
        <tradeName><![CDATA[Nombre comercial]]></tradeName>
        <noEInvoice>false</noEInvoice>
        <address>
                <line1><![CDATA[primera linea de dirección]]></line1>
                <line2><![CDATA[segunda linea de dirección]]></line2>
                <city><![CDATA[Vic]]></city>
                <province><![CDATA[Barcelona]]></province>
                <zipcode><![CDATA[08500]]></zipcode>
                <country><![CDATA[ES]]></country>
        </address>
        <website>www.facturadirecta.com</website>
        <language>es</language>
        <email>email@facturadirecta.com</email>
        <phone><![CDATA[555020202]]></phone>
        <mobilePhone></mobilePhone>
        <notes><![CDATA[Notas para esta empresa]]></notes>
        <companyCode><![CDATA[Código empresa 1]]></companyCode>
<billing>
                <currency>EUR</currency>
                <tax1>
                        <name>IVA</name>
                        <rate>18.00</rate>
                </tax1>
                <tax2>
                        <name>IRPF</name>
                        <rate>-15.00</rate>
                </tax2>
                <bank>
                        <country>ES</country>
                        <name><![CDATA[La Caixa]]></name>
                        <accountNumber><![CDATA[ES6121002100300000000000]]></accountNumber>
                        <swift><![CDATA[CAIXESBBXXX]]></swift>
                </bank>
                <paymentMean>01</paymentMean>
                <dueDates>
                        <dueDate>
                                <delayInDays>30</delayInDays>
                                <rate>30</rate>
                        </dueDate>
                        <dueDate>
                                <delayInDays>90</delayInDays>
                                <rate>70</rate>
                        </dueDate>
                </dueDates>
                <customInvoiceNotes>false</customInvoiceNotes>
                <invoiceNotes><![CDATA[]]></invoiceNotes>
        </billing>
</client>"
https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml

Se puede solicitar que se autogenere el código de cliente indicando el parámetro autoCreateCompanyCode=true en la URL de llamada. Si el código de cliente resultante después de procesar la petición está vacío y todos los códigos de cliente de la cuenta son numéricos se asignará automáticamente como código de cliente el valor del del último cliente más uno.

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

Modificar un cliente existente

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

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X PUT -H 'Accept: application/xml' -H 'Content-Type: application/xml'
-d "<?xml version='1.0' encoding='UTF-8'?>
<client>
        <id>80</id>
        <legalType><![CDATA[F]]></legalType><!-- Person física F -->
<personName><![CDATA[Nombre Cliente]]></personName>
<personSurname><![CDATA[Apellidos Cliente]]></personSurname>
        <taxCode><![CDATA[NIF o Código fiscal]]></taxCode>
        <tradeName><![CDATA[Nombre comercial]]></tradeName>
        <noEInvoice>false</noEInvoice>
        <address>
                <line1><![CDATA[primera linea de dirección]]></line1>
                <line2><![CDATA[segunda linea de dirección]]></line2>
                <city><![CDATA[Vic]]></city>
                <province><![CDATA[Barcelona]]></province>
                <zipcode><![CDATA[08500]]></zipcode>
                <country><![CDATA[ES]]></country>
        </address>
        <website>www.facturadirecta.com</website>
        <language>es</language>
        <email>email@facturadirecta.com</email>
        <phone><![CDATA[555020202]]></phone>
        <mobilePhone></mobilePhone>
        <notes><![CDATA[Notas para esta empresa]]></notes>
        <companyCode><![CDATA[Código empresa 1]]></companyCode>
        <billing>
                <currency>EUR</currency>
                <bank>
                        <country>ES</country>
                        <name><![CDATA[CatalunyaCaixa]]></name>
                        <accountNumber><![CDATA[ES6121002100300000000000]]></accountNumber>
                        <swift><![CDATA[CAIXESBBXXX]]></swift>
                </bank>
                <paymentMean>02</paymentMean>
                <payableDayInMonth1>7</payableDayInMonth1>
                <payableDayInMonth2>27</payableDayInMonth2>
                <dueDates>
                        <dueDate>
                                <delayInDays>30</delayInDays>
                                <rate>50.00</rate>
                        </dueDate>
                        <dueDate>
                                <delayInDays>60</delayInDays>
                                <rate>50.00</rate>
                        </dueDate>
                </dueDates>
        </billing>
</client>"
https://[ACCOUNT_NAME].facturadirecta.com/api/clients/80.xml

Se puede solicitar que se autogenere el código de cliente indicando el parámetro autoCreateCompanyCode=true en la URL de llamada. Si el código de cliente resultante después de procesar la petición está vacío y todos los códigos de cliente de la cuenta son numéricos se asignará automáticamente como código de cliente el valor del del último cliente más uno.

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

Elimina un cliente existente identificado por el identificador #{id}

Ejemplo para eliminar un cliente con id=80

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

RESPUESTA SATISFACTORIA

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

RESPUESTA DE ERROR (no encontrado)

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

PUT /api/clients.xml

Obtener la plantilla xml de nuevo cliente

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