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 |
Para poder definir un cliente correctamente es necesario indicar el tipo legal de la empresa. Actualmente, existen dos tipos legales (legalType):
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.
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.
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)
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.
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.
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.
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.
curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml
curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml?start=100
curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml?limit=50
curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/clients.xml?limit=50&start=50
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) |
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) |
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) |
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
Obtener un cliente existente
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>
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.
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.
Elimina un cliente existente identificado por el identificador #{id}
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>