Proveedores

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

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

Cosas a tener en cuenta en la api de proveedores

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 del proveedor]]></personName>
<personSurname><![CDATA[Apellidos del proveedor]]></personSurname>

Persona jurídica

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

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

Obtener la lista de proveedores

curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/providers.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 proveedores

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

Parámetro Descripción
taxCode Permite obtener solo los proveedores con el número de NIF indicado.
code Permite obtener solo los proveedores con el código de proveedor indicado.
term Permite obtener una lista de los proveedores 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 proveedores 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 proveedores 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)

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

Obtener un proveedor existente

Ejemplo para obtener un proveedor con id=77

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

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

RESPUESTA SATISFACTORIA

<?xml version="1.0" encoding="UTF-8"?>
<provider>
    <id>77</id>
    <legalType><![CDATA[J]]></legalType>
    <name><![CDATA[Nombre Proveedor]]></name>
    <taxCode><![CDATA[NIF o Código fiscal]]></taxCode>
    <tradeName><![CDATA[Nombre comercial]]></tradeName>
    <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>
</provider>

RESPUESTA DE ERROR (no encontrado)

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

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

Modificar un proveedor existente

Ejemplo para actualizar un proveedor con id=77. 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'?>
<provider>
    <id>77</id>
    <legalType><![CDATA[F]]></legalType><!-- Persona física -->
    <personName><![CDATA[Nom proveedor]]></personName>
    <personSurname><![CDATA[Apellidos proveedor]]></personSurname>
    <taxCode><![CDATA[NIF o Código fiscal]]></taxCode>
    <tradeName><![CDATA[Nombre comercial]]></tradeName>
    <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>
</provider>"
https://[ACCOUNT_NAME].facturadirecta.com/api/providers/77.xml

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

POST /api/providers.xml

Crear un nuevo proveedor

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml'
-d "<?xml version='1.0' encoding='UTF-8'?>
<provider>
    <legalType><![CDATA[J]]></legalType><!-- Person jurídica -->
    <name><![CDATA[Nombre Proveedor]]></name>
    <taxCode><![CDATA[NIF o Código fiscal]]></taxCode>
    <tradeName><![CDATA[Nombre comercial]]></tradeName>
    <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>
</provider>"
https://[ACCOUNT_NAME].facturadirecta.com/api/providers.xml

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

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

Eliminar un proveedor existente

Ejemplo para eliminar un proveedor con id=77

curl -u 03334b0a261a2c355ae2db022a963d8e:x -X DELETE https://[ACCOUNT_NAME].facturadirecta.com/api/providers/77.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/providers.xml

Obtener la plantilla xml de nuevo proveedor

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