Órdenes de compra
Conjunto de llamadas que permiten realizar acciones sobre las órdenes de compra de una cuenta de FacturaDirecta.
| Recurso | Descripción |
|---|---|
| GET /api/purchaseOrders.xml | Devuelve un listado de órdenes de compra permitiendo el filtrado por múltiples atributos |
| GET /api/purchaseOrders/#{id}.xml | Devuelve una orden de compra con identificador #{id} |
| GET /api/purchaseOrders/#{id}.pdf | Devuelve una orden de compra con identificador #{id} en formato PDF |
| PUT /api/purchaseOrders/#{id}.xml | Modifica los datos de una orden de compra existente identificado por el identificador #{id} |
| POST /api/purchaseOrders.xml | Permite crear una nueva orden de compra |
| DELETE /api/purchaseOrders/#{id}.xml | Elimina una orden de compra existente identificado por el identificador #{id} |
| GET /api/purchaseOrders/send/#{id}.xml | Envía por email la orden de compra con identificador #{id} al proveedor |
| PUT /api/purchaseOrders.xml | Devuelve una plantilla de la estructura en xml para poder utilizarla para crear una nueva orden de compra |
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/purchaseOrders.xml
Devuelve un listado de órdenes de compra permitiendo el filtrado por múltiples atributos.
Obtener la lista de órdenes de compra
curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/purchaseOrders.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 órdenes de compra
Para focalizar más la consulta de órdenes de compra, puedes utilizar las siguientes opciones de filtrado:
| Parámetro | Descripción |
|---|---|
| provider | Permite obtener solo las órdenes de compra de un proveedor (especificado por su ID) |
| status (múltiple) | Permite obtener las órdenes de compra que se encuentren en cualquier estado indicado en este parámetro. Opciones: draft (Provisional), unavailable (No disponible), readyToDeliver (Listo para entregar), delivered (Entregado), canceled (Cancelado) |
| fromDate | Permite obtener las órdenes de compra desde la fecha indicada (en formato AAAAMMDD) |
| toDate | Permite obtener las órdenes de compra hasta la fecha indicada (en formato AAAAMMDD) |
| documentSerial (múltiple) | Permite obtener las órdenes de compra de una única serie |
| documentNumber | Permite obtener las órdenes con un determinado número (se refiere al número de orden dentro de una serie, para buscar por número de orden incluyendo serie debe utilizarse el parámetro documentNumberFormatted) |
| documentNumberFormatted | Permite obtener las órdenes de compra 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 las órdenes de compra 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 órdenes de compra que tengan todas las etiquetas indicadas (valor and del parámetro) o cualquiera de ellas (valor or del parámetro) |
| sent | Permite obtener las órdenes de compra según su estado de envío. Opciones: false (órdenes no enviadas), true (órdenes no enviadas), cualquier otro valor es ignorado |
| ownerEmail | Permite obtener sólo las órdenes de compra propiedad del usuario con el email indicado |
| client | Permite obtener sólo las órdenes de compra que contienen algún producto para el cliente indicado (especificado por su ID) |
Ejemplos
curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/purchaseOrders.xml?provider=52\&fromDate=20110101\&toDate=20110331 curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/purchaseOrders.xml?provider=52\&fromDate=20110101\&toDate=20110331\&tag=Etiqueta 1\&tag=Etiqueta 2\&tagCond=and curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/purchaseOrders.xml?provider=52\&fromDate=20110101\&toDate=20110331\&tag=Etiqueta 1\&tag=Etiqueta 2\&tagCond=or
GET /api/purchaseOrders/#{id}.xml
Obtener una orden de compra existente
Ejemplo para obtener una orden de compra con id=111
curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/purchaseOrders/111.xml
RESPUESTA SATISFACTORIA
<?xml version="1.0" encoding="UTF-8"?> <purchaseOrder> <id>111</id> <owner> <id>1</id> <email><![CDATA[me@mycompany.com]]></email> </owner> <updateDate>20150917173620.695</updateDate> <provider> <id><![CDATA[386]]></id> <legalType><![CDATA[J]]></legalType> <name><![CDATA[Muebles Arturo, SL]]></name> <tradeName><![CDATA[]]></tradeName> <taxCode><![CDATA[B44441111]]></taxCode> <address1><![CDATA[]]></address1> <address2><![CDATA[]]></address2> <city><![CDATA[]]></city> <province><![CDATA[]]></province> <zipcode><![CDATA[]]></zipcode> <country><![CDATA[ES]]></country> <website><![CDATA[]]></website> <timezone><![CDATA[]]></timezone> <defaultLanguage><![CDATA[es]]></defaultLanguage> </provider> <documentDate>20150917</documentDate> <documentSerial></documentSerial> <documentNumber>33</documentNumber> <documentNumberFormatted><![CDATA[0033]]></documentNumberFormatted> <documentStatus>pendingToReceive</documentStatus> <currency>EUR</currency> <netTotal>545.00</netTotal> <tax1> <name>IVA</name> <base>545.00</base> <rate>21.00</rate> <total>114.45</total> </tax1> <grossTotal>659.45</grossTotal> <notes><![CDATA[Entregar en delegación sur]]></notes> <linePricesIncludeTaxes>false</linePricesIncludeTaxes> <hidePrices>false</hidePrices> <lineTotalDecimals>2</lineTotalDecimals> <documentLines> <documentLine> <id>178</id> <productId>911</productId> <productCode><![CDATA[M3PV01]]></productCode> <description><![CDATA[Mesa auxiliar 3 patas serie Victoria]]></description> <quantity>1</quantity> <unitPrice>450.00</unitPrice> <totalPrice>450.00</totalPrice> <applyTax1>true</applyTax1> <applyTax2>false</applyTax2> <applyTax3>false</applyTax3> <applyTax4>false</applyTax4> <applyTax5>false</applyTax5> <applyTax6>false</applyTax6> <lineStatus>pendingToReceive</lineStatus> </documentLine> <documentLine> <id>179</id> <productId>1006</productId> <productCode><![CDATA[S89K09]]></productCode> <description><![CDATA[Silla marfil]]></description> <quantity>1</quantity> <unitPrice>95.00</unitPrice> <totalPrice>95.00</totalPrice> <applyTax1>true</applyTax1> <applyTax2>false</applyTax2> <applyTax3>false</applyTax3> <applyTax4>false</applyTax4> <applyTax5>false</applyTax5> <applyTax6>false</applyTax6> <lineStatus>pendingToReceive</lineStatus> </documentLine> </documentLines> </purchaseOrder>
Cosas a tener en cuenta al obtener la información de una orden de compra
La estructura que devuelve el sistema con información de órdenes de compra es mucho más completa que la estructura que se requiere enviar en la creación o edición de una orden de compra. El motivo principal es que el sistema devuelve información que se calcula automáticamente para la orden de compra. 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/purchaseOrders/#{id}.pdf
Descargar una orden de compra en PDF
Genera la descarga de un PDF con la orden de compra identificado por el id: #{id}
Ejemplo para descargar una orden de compra en PDF con id=111
curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/purchaseOrders/111.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 una orden de compra en PDF con id=111 en modo seguro
curl -u 03334b0a261a2c355ae2db022a963d8e:x https://[ACCOUNT_NAME].facturadirecta.com/api/purchaseOrders/111.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/purchaseOrders/111/print?temporaryKey=b134af657d23b3e21f657d23b3e21&u=1
Es esta última URL la que descargará el documento PDF generado.
POST /api/purchaseOrders.xml
Crea una nueva orden de compra
curl -u 03334b0a261a2c355ae2db022a963d8e:x -X POST -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d "<?xml version="1.0" encoding="UTF-8"?> <purchaseOrder> <provider> <id><![CDATA[386]]></id> </provider> <documentStatus>pendingToReceive</documentStatus> <currency>EUR</currency> <tax1> <name>IVA</name> <rate>21.00</rate> </tax1> <notes><![CDATA[Entregar en la delegación Sur]]></notes> <documentLines> <documentLine> <productId>911</productId> <productCode><![CDATA[M3PV01]]></productCode> <description><![CDATA[Mesa auxiliar 3 patas serie Victoria]]></description> <quantity>1</quantity> <unitPrice>450.00</unitPrice> <applyTax1>true</applyTax1> <lineStatus>pendingToReceive</lineStatus> </documentLine> <documentLine> <productId>1006</productId> <productCode><![CDATA[S89K09]]></productCode> <description><![CDATA[Silla marfil]]></description> <quantity>3</quantity> <unitPrice>95.00</unitPrice> <applyTax1>true</applyTax1> <lineStatus>pendingToReceive</lineStatus> </documentLine> </documentLines> </purchaseOrder> " https://[ACCOUNT_NAME].facturadirecta.com/api/purchaseOrders.xml
Cosas a tener en cuenta en la creación de una orden de compra
La estructura de creación de orden de compra dispone de muchos campos pero muchos de ellos son opcionales. El campo proveedor (purchaseOrder/provider) es siempre obligatorio y debe indicarse el ID del proveedor (purchaseOrder/provider/id). El proveedor debe existir previamente a la llamada de creación de orden de compra, con lo que si el proveedor es nuevo debe utilizarse primero la llamada de creación de proveedor antes de continuar con la llamada de creación de orden de compra. Si no se indica la fecha de la orden de compra (documentDate), el sistema asignará automáticamente la fecha actual. Si no se indica el número de orden de compra (documentNumber), el sistema asignará automáticamente un número correlativo teniendo en cuenta la serie de la orden de compra (documentSerial) En los atributos tax1, tax2, tax3 y tax4 a nivel de deliveryNote, tan solo deben indicarse: - El nombre (purchaseOrder/tax1/name): IRPF, IVA, etc.. - El porcentaje aplicado (purchaseOrder/tax1/rate): 18, -15
PUT /api/purchaseOrders/#{id}.xml
Modifica una orden de compra existente
Ejemplo para actualizar una orden de compra con id=111. 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"?> <purchaseOrder> <id>111</id> <provider> <id><![CDATA[386]]></id> </provider> <tax1> <name>IVA</name> <rate>21.00</rate> </tax1> <notes><![CDATA[Entregar en delegación sur. Retrasar entrega hasta segunda quincena de noviembre]]></notes> <linePricesIncludeTaxes>false</linePricesIncludeTaxes> <hidePrices>false</hidePrices> <lineTotalDecimals>2</lineTotalDecimals> <documentLines> <documentLine> <id>178</id> <productId>911</productId> <productCode><![CDATA[M3PV01]]></productCode> <description><![CDATA[Mesa auxiliar 3 patas serie Victoria]]></description> <quantity>1</quantity> <unitPrice>450.00</unitPrice> <totalPrice>450.00</totalPrice> <applyTax1>true</applyTax1> <lineStatus>pendingToReceive</lineStatus> </documentLine> <documentLine> <id>179</id> <productId>1006</productId> <productCode><![CDATA[S89K09]]></productCode> <description><![CDATA[Silla marfil]]></description> <quantity>1</quantity> <unitPrice>95.00</unitPrice> <totalPrice>95.00</totalPrice> <applyTax1>true</applyTax1> <lineStatus>pendingToReceive</lineStatus> </documentLine> </documentLines> </purchaseOrder>" https://[ACCOUNT_NAME].facturadirecta.com/api/purchaseOrders/166.xml
Cosas a tener en cuenta al modificar una orden de compra
En una modificación de una orden de compra la mayoría de campos son OPCIONALES.
Si se desean modificar líneas de la orden de compra (documentLines), siempre es necesario enviar toda la información de todos los documentLines de la orden. (Ya que la llamada para realizar modificaciones en estos datos regenera completamente la estructura).
POST /api/purchaseOrders/send/#{id}.xml
Permite enviar una orden de compra por correo electrónico en formato PDF
Hacer un envío de una orden de compra
Para hacer el envío de la orden de compra con id=111 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 proveedor,</p> ...]]></body>
<contentType>text/html</contentType>
<from>usuario@miempresa.com</from>
<toRecipients>
<address>contacto1@miproveedor.com</address>
<address>contacto2@miproveedor.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/purchaseOrders/send/111.xml
Se puede enviar la misma orden de compra sin indicar ningún dato del envío y la orden de compra se enviará con el texto por defecto al primer destinatario del proveedor 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/purchaseOrders/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 proveedor, 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 proveedor indicado en el documento que se está enviando.
Las direcciones de correo permitidas para el envío son: - La del proveedor, - la de cualquier contacto del proveedor, - la de tu propia empresa - y la de cualquiera de los usuarios de tu cuenta.