REST API: Recuperar datos para sistemas de facturación
Rest API: Recepción de pedidos, albaranes y/o validación de facturas de compra en tspoonlab
tspoonlab es un entorno perfecto para generar los pedidos desde cocina a nuestros proveedores. Existen varias posibilidades para generarlos: en base a una planificación, en base a stock o mediante plantillas. En todos los casos se deja constancia en la aplicación de lo que vamos a pedir y se envía por Whatsapp, mail o teléfono al proveedor.
La recepción de pedidos equivale a la entrada de los albaranes y no solo tiene implicaciones de coste o control contable. Nos permite también anotar los puntos de control de recepción, los números de lote del pedido recibido, generar una entrada en el almacén y comprobar que la cantidad servida y los precios son similares a los solicitados. Por lo tanto recomendamos realizar la recepción/entrada de albarán desde tspoonlab.
Una vez recepcionados los pedidos éstos pueden ser enviados a sistemas externos de gestión y en ellos poder validar las facturas con los albaranes y arrancar todos los procesos contables.
Desde la pantalla de proveedores de tspoonlab también se puede realizar la validación de las facturas contra los albaranes recibidos. En ese proceso se crea una factura y se le asocian sus albaranes. A partir de aquí la factura, los impuestos y el pago deben ser gestionados por un sistema de facturación.
Por lo tanto para las compras podemos enviar los albaranes o las facturas. Para no repetir los envíos una vez procesados por el sistema externo se deben marcar en tspoonlab como procesados para que no se envíen de nuevo.
Rest API: Login
Para poder hacer llamadas a nuestras api's lo primero que necesitamos es identificarnos mediante una llamada de login.
Esa llamada nos retornará una token que después debemos asociar en cada llamada posterior.
Este shell script muestra como autenticarnos mediante curl:
[email protected]
password=XXXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
En las llamadas posteriores debemos añadir a nuestros headers el token recibido de la llamada de login
curl -X PUT -v -H "$(cat rememberme.txt)" $url/integration/llamada
Rest API: Seleccionar un centro de coste/restaurante
Las peticiones que se describen en los apartados siguientes hacen referencia a un centro de coste, en la mayoría de los casos se correspondería con un restaurante.
Para recuperar la lista de centros de costes y sus identificadores consulta el artículo Rest API: Centros de coste.
El identificador de centro de coste se corresponde al campo idOrderCenter de la clase UserOrderCenter.
Una vez tenemos el identificador este deberá añadirse a los headers para que sea utilizado en llamadas posteriores:
echo -n 'order:351583444167656299610202XXXXXXXXXXXX' >> rememberme.txt
Por tanto en nuestros request headers debemos especificar tanto el token devuelto por el login como el identificador del centro de coste:
rememberme:aGVucnkudXBzYWxsLmRAZXXXXXXXXXXXXXXXXXX
order:351583444167656299610202XXXXXXXXXXXX
Rest API: Recuperación de pedidos de compras no marcados como procesados
Para recuperar los pedidos de compras no marcados como procesados debemos realizar esta llamada :
GET: https://app.tspoonlab.com/recipes/api/integration/purchases/orders/pending?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&includeInternal=true&idVendor=XXXXX
Debemos pasar los siguientes request parameters:
startDate (String). Fecha a partir de la cuál se recuperarán los datos.
endDate (String). Fecha hasta la cuál se recuperarán los datos.
includeInternal (Boolean) Incluir también albaranes de proveedores marcados como internos. Opcional. Valor por defecto true.
idVendor (Id). Parámetro opcional donde se muestra el identificador del proveedor. Nos recuperará solo los datos asociados al proveedor. Para obtener el id del proveedor dirígete al artículo Rest API: Proveedores.
El formato de las fechas debe ser YYYY-MM-DD y es inclusivo en startDate y endDate. Es decir todos los datos con fecha igual a startDate o endDate son retornados.
Nos retornará un array de la clase PurchaseOrder y un código 200.
class PurchaseOrder {
String id; // Id del pedido
String numOrder; // Número de pedido
String idVendor; // Id del proveedor
String vendor; // Nombre del proveedor
String codeVendor; // Código del proveedor
String accountVendor; // Num cuenta contable del proveedor
String nif; // Nif del proveedor
Date date; // Fecha del pedido
String dateFormatted; // Fecha del pedido en YYYY/MM/DD
Date dateReception; // Fecha de recepción
String sentBy; // Enviado por
String dateReceptionFormatted; // Fecha de recepción en YYYY/MM/DD
Double total; // Importe total
List<PurchaseOrderLine> listOrders; // Detalle de líneas del pedido
}
Las líneas de detalle:
public class PurchaseOrderLine {
String id; // Identificador de la línea de detalle
int position; // Posición dentro del albarán
String codeComponent; // Código del producto
String idComponent; // Identificador Ingrediente, material
String codeVendorComponent; // Código del producto para el proveedor
String component; // Descripción del ingrediente, material
String comment; // Comentario
// Valores en la unidad base del ingrediente
Double quantity; // Cantidad
String idUnit; // Identificador de la unidad
String unit; // Unidad
Double cost; // Coste unitario
// En caso de haber comprado con un formato
boolean hasFormat; // true si tiene información de formato
Double quantityFormat; // Cantidad del formato
String idUnitFormat; // Identificador de la unidad del format
String unitFormat; // Unidad del formato
Double costFormat; // Coste unitario del formato
Double iva; // Tipo de iva aplicado a la línea
String idCostType; // Identificador de la cuenta de análisis
String costType; // Descripción de la cuenta de análisis
String codeCostType; // Código de la cuenta de análisis
String accountCostType; // Cuenta contable de la cuenta de análisis
String accountAuxCostType; // Cuenta contable de la cuenta de análisis
String idBusinessLine; // Identificador de la linea de negocio
String businessLine; // Descripción de la linea de negocio
String codeBusinessLine; // Código de la linea de negocio
List<LineType> listTypes; // Lista de tipos del componente.
}Para cada tipo de las lista de tipos/familias:
class LineType {
String id; // Identificador del impuesto para la factura
String descr; // Descripción del tipo
}
Este seria un ejemplo de la llamada:
[email protected]
password=XXXXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X GET -v -H "$(cat rememberme.txt)" $url/integration/purchases/orders/pending | python -m json.tool
Rest API: Marcar pedidos de compras como procesados
Una vez que hemos traspasado los albaranes de compras al sistema externo podemos marcarlas como procesados en tspoonlab de forma que ya no se reenviaran otra vez en peticiones posteriores.
PUT:
https://app.tspoonlab.com/recipes/api/integration/purchases/orders/processed
La petición retorna un código 200 en caso de que se haya ejecutado correctamente.
En el request body debemos pasar un esta estrucura la lista identificadores de facturas que queremos marcar como contabilizadas
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/purchases/orders/processed
Rest API: Recuperación de albaranes de compras no marcados como procesados
Para recuperar los albaranes de compras no marcados como contabilizados debemos realizar esta llamada:
GET: https://app.tspoonlab.com/recipes/api/integration/purchases/deliveries/pending?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&includeInternal=true&idVendor=XXXXX
Debemos pasar los siguientes request parameters:
startDate (String). Fecha a partir de la cuál se recuperarán los datos.
endDate (String). Fecha hasta la cuál se recuperarán los datos.
includeInternal (Boolean) Incluir también albaranes de proveedores marcados como internos. Opcional. Valor por defecto true.
idVendor (Id). Parámetro opcional donde se indica el identificador del proveedor. Nos recuperará solo los datos asociados al proveedor. Para obtener el id del proveedor dirígete al artículo Rest API: Proveedores.
El formato de las fechas debe ser YYYY-MM-DD y es inclusivo en startDate y endDate. Es decir todos los datos con fecha igual a startDate o endDate son retornados.
Nos retornará un array de la clase PurchaseDelivery y un código 200.
public class PurchaseDelivery {
private String id; // Id del albarán
private String idVendor; // Id del proveedor
private String vendor; // Nombre del proveedor
private String codeVendor; // Código del proveedor
private String accountVendor; // Num cuenta contable del proveedor
private String nif; // Nif del proveedor
private String deliveryNum ; // Número de albarán
private String deliveryFor;
// Para del albarán. Normalmente el número de pedido
private Date date; // Fecha del albarán en formato time_t
private String dateFormatted; // Fecha del albarán en
// formato YYYY/MM/DD
private Date dateSent; // Fecha envio del pedido
private String dateSentFormatted; // Fecha envio del
// pedido en YYYY/MM/DD
private String sentBy; // Enviado por
private String receivedBy; // Recibido por
private Double baseCalculated; // Importe base albarán
// con redondeo a 5 decimales
private Double base; // Importe base albarán
private Double taxes; // Importe impuestos
private Double total; // Importe total
private String idCostType; // Id de la cuenta de análisis
// (Si imputamos todo el albarán si no aparece puede
// ser que este imputado por línea de albarán)
private String costType; // Descripción de la cuenta de análisis
// (Si imputamos todo el albarán si no aparece puede
// ser que este imputado por línea de albarán)
private String codeCostType; // Código de la cuenta de análisis
// (Si imputamos todo el albarán si no aparece puede
// ser que este imputado por línea de albarán)
private String accountCostType; // Cuenta contable
// de la cuenta de análisis
// (Si imputamos todo el albarán si no aparece puede
// ser que este imputado por línea de albarán)
private String accountAuxCostType; // Cuenta contable
// de la cuenta de análisis
// (Si imputamos todo el albarán si no aparece puede
// ser que este imputado por línea de albarán)
private String idBusinessLine; // Identificador de la linea de negocio
private String businessLine; // Descripción de la linea de negocio
private String codeBusinessLine; // Código de la linea de negocio
private String vendorType; // tipo de proveedor
private String vendorTypeCode; // Código del tipo de proveedor
private boolean vendorTypeInternal;
// Indica si el proveedor es interno
private List<DeliveryTax> listTaxes; // Detalle de los impuestos
private List<PurchaseDeliveryLine> listDeliveries;
// Detalle de líneas del albarán
private List<PurchaseDeliverySentLine> listSent;
// Detalle de líneas del pedido
}
public class DeliveryTax {
private String id; // Identificador del impuesto para el albarán
private short type; // Tipo de impuesto
// (0:IVA, 1:Transportes, 2:Descuentos, 3: Otros, -1: Descuento s/base)
private Double base; // Base puede ser nulo
// para Transportes, Descuentos y otros
private Double percent; // Tipo/Porcentaje puede ser nulo
// para Transportes, Descuentos y otros
private Double total; // Total impuesto o transporte
//o descuento o otros
}
Las líneas de detalle:
public class PurchaseDeliveryLine {
private String id; // Identificador de la línea de detalle
private int position; // Posición dentro del albarán
private String idComponent; // Id producto
private String codeComponent; // Código del producto
private String component; // Nombre del producto
private String codeVendorComponent;
// Código del producto para el proveedor
private String comment; // Comentario
private boolean recibido; // Si se ha recibido o no
// Valores en la unidad base del ingrediente
private Double quantity; // Cantidad
private String idUnit; // Identificador de la unidad
private String unit; // Unidad
private Double cost; // Coste unitario
// En caso de haber comprado con un formato
private boolean hasFormat; // true si tiene información de formato private Double quantityFormat; // Cantidad del formato
private String idUnitFormat; // Identificador de la unidad del format
private String unitFormat; // Unidad del formato
private Double costFormat; // Coste unitario del formato
private Double iva; // Tipo de IVA aplicado a la línea
private String idCostType; // Identificador de la
// cuenta de análisis
private String costType; // Descripción de la
// cuenta de análisis
private String codeCostType; // Código de la
// cuenta de análisis
private String accountCostType; // Cuenta contable de la
// cuenta de análisis
private String accountAuxCostType; // Cuenta contable de la
// cuenta de análisis
private String idBusinessLine; // Identificador de la linea de negocio
private String businessLine; // Descripción de la linea de negocio
private String codeBusinessLine; // Código de la linea de negocio
private List<LineType> listTypes; // Lista de tipos del componente.
private String idStore; // Identificador del almacén
private String store; // Almacén
}
Para cada tipo de las lista de tipos/familias:
public class LineType {
private String id; // Identificador del impuesto para la factura
private String descr; // Descripción del tipo
}Las líneas del pedido:
public class PurchaseDeliverySentLine {
private String id; // Identificador de la línea de detalle
private int position; // Posición dentro del albarán
private String codeComponent; // Código del producto
private String idComponent; // Identificador Ingrediente, material
private String codeVendorComponent;
// Código del producto para el proveedor
private String component; // Descripción del ingrediente, material
private String comment; // Comentario
// Valores en la unidad base del ingrediente
private Double quantity; // Cantidad
private String idUnit; // Identificador de la unidad
private String unit; // Unidad
private Double cost; // Coste unitario
// En caso de haber comprado con un formato
private boolean hasFormat; // true si tiene información de formato
private Double quantityFormat; // Cantidad del formato
private String idUnitFormat; // Identificador de la unidad del format
private String unitFormat; // Unidad del formato
private Double costFormat; // Coste unitario del formato
}
Este sería un ejemplo de llamada:
[email protected]
password=XXXXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X GET -v -H "$(cat rememberme.txt)" $url/integration/purchases/deliveries/pending | python -m json.tool
Para recuperar todas las compras estén o no procesadas podemos hacer la siguiente llamada:
GET: https://app.tspoonlab.com/recipes/api/integration/purchases/deliveries/all?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&includeInternal=true&idVendor=XXXX
Rest API: Marcar albaranes de compras como procesados
Una vez hemos traspasado los albaranes de compras al sistema externo podemos marcarlas como procesados en tspoonlab de forma que ya no se reenviarán otra vez en peticiones posteriores:
PUT:
https://app.tspoonlab.com/recipes/api/integration/purchases/deliveries/processed?lock=true
El parámetro lock indica si además de marcar el albarán como procesado lo bloqueamos.
La petición retorna un código 200 en caso de que se haya ejecutado correctamente.
En el request body debemos pasar un esta estrucura la lista identificadores de facturas que queremos marcar como contabilizadas:
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/purchases/deliveries/processed
Rest API : Marcar albaranes de compras como bloqueados
Si queremos marcar albaranes en tspoonlab como bloqueados:
PUT:
https://app.tspoonlab.com/recipes/api/integration/purchases/deliveries/lock
La petición retorna un código 200 en caso de que se haya ejecutado correctamente.
En el request body debemos pasar un esta estructura la lista identificadores de facturas que queremos bloquear.
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/purchases/deliveries/lock
Rest API: Recuperación de facturas de compras no contabilizadas
Para recuperar las facturas de compras pendientes de contabilizar debemos realizar esta llamada:
GET: https://app.tspoonlab.com/recipes/api/integration/purchases/invoices/pending?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&includeInternal=true&onlyValidated=true&idVendor=XXXXX
Debemos pasar los siguientes request parameters:
startDate (String). Fecha a partir de la cuál se recuperarán los datos.
endDate (String). Fecha hasta la cuál se recuperarán los datos.
includeInternal (Boolean) Incluir también facturas de proveedores marcados como internos. Opcional. Valor por defecto true.
onlyValidated (Boolean) Incluir solo las facturas de proveedores marcados como validados. Opcional. Valor por defecto false.
idVendor (Id). Parámetro opcional donde se indica el identificador del proveedor. Nos recuperará solo los datos asociados al proveedor.
El formato de las fechas debe ser YYYY-MM-DD y es inclusivo en startDate y endDate. Es decir todos los datos con fecha igual a startDate o endDate son retornados.
Nos retornará un array de la clase PurchaseInvoice y un código 200.
public class PurchaseInvoice {
String id; // Id de la factura
String idVendor; // Id del proveedor
String vendor; // Nombre del proveedor
String codeVendor; // Código del proveedor
String accountVendor; // Num cuenta contable del proveedor
String nif; // Nif del proveedor
boolean inEuropeanUnion; // Si es proveedor intracomunitario
boolean inVies; // Si esta inscrito en el registro Vies
String country; // El pais del proveedor si esta establecido. ISO 3166-1 alfa-2
String documentNum; // Num de documento
String invoiceNum; // Num de factura
boolean paid; // Si está ya pagada
boolean validated; // Si está validada
String comment; // Comentario factura
Date date; // Fecha factura
Date dateAccounting; // Fecha contabilidad si nulla utilizar date
Date dateDue; // Fecha de vencimiento
String codePaymentType; // Código de la forma de pago
String idCostTypeVendor; // Identificador de la cuenta de análisis del proveedor
String costTypeVendor; // Descripción de la cuenta de análisis del proveedor
String codeCostTypeVendor; // Código de la cuenta de análisis del proveedor
String accountCostTypeVendor; // Cuenta contable de la cuenta de análisis del proveedor
String accountAuxCostTypeVendor; // Ora Cuenta contable de la cuenta de análisis del proveedor
String idDocument; // Id del documento asociado a la factura
String extDocument; // Extensión del documento asociado a la factura
String idBusinessLine; // Identificador de la linea de negocio
String businessLine; // Descripción de la linea de negocio
String codeBusinessLine; // Código de la linea de negocio
Double total; // Total factura
Double base; // Total base imponible
Double taxes; // Total impuestos
List<InvoiceTax> listTaxes; // Detalle de los impuestos
List<CostTypeTax> listCostTypeTaxes; // Detalle de los impuestos por cuenta de análisis
List<PurchaseDelivery> listDeliveries; // Detalle de albaranes
}
public class InvoiceTax {
private String id; // Identificador del impuesto para la factura
private short type; // Tipo de impuesto
// (0:IVA, 1:Transportes, 2:Descuentos, 3: Otros, -1: Descuento s/base)
private Double base; // Base puede ser nulo
// para Transportes, Descuentos y otros
private Double percent; // Tipo/Porcentaje
// puede ser nulo para Transportes, Descuentos y otros
private Double total; // Total impuesto o transporte o descuento o otros
}
El albarán está representado por la clase PurchaseDelivery tal como se ha documentado con anterioridad.
Este seria un ejemplo de la llamada:
[email protected]
password=XXXXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X GET -v -H "$(cat rememberme.txt)" $url/integration/purchases/invoices/pending | python -m json.tool
Para recuperar todas las facturas estén o no contabilizadas podemos hacer la siguiente llamada:
GET: https://app.tspoonlab.com/recipes/api/integration/purchases/invoices/all?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&includeInternal=true&onlyValidated=false&idVendor=XXXX
Para recuperar el documento asociado a la factura debemos realizar está llamada:
https://app.tspoonlab.com/recipes/api/exportFileBoundFile/{idDocument}.{extDocument}?id={idDocument}&rememberme={rememberme}
listCostTypeTaxes retorna el detalle de impuestos por cuenta de análisis para la factura:
class CostTypeTax {
String id; // Identificador de la cuenta de análisis
String descr; // Descripción de la cuenta de análisis
List<OrderVendorVat> listTaxes;
}
class OrderVendorVat {
Double base; // base imponible
Double percent; // Porcentaje de IVA
Double total; // Importe del iva
}
Rest API: Marcar facturas de compras como contabilizadas
Una vez hemos traspasado las facturas de compras a la contabilidad podemos marcarlas como contabilizadas en tspoonlab de forma que ya no se reenviarán otra vez en peticiones posteriores.
PUT:
https://app.tspoonlab.com/recipes/api/integration/purchases/invoices/accounted?lock=true
El parámetro lock indica si además de marcar la factura como contabilizada la bloqueamos.
La petición retorna un código 200 en caso de que se haya ejecutado correctamente.
En el request body debemos pasar esta estructura en la lista de identificadores de facturas que queremos marcar como contabilizadas.
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/purchases/invoices/accounted
Rest API: Marcar facturas de compras como no contabilizadas
Si queremos volver a marcar facturas en tspoonlab como no contabilizadas:
PUT:
https://app.tspoonlab.com/recipes/api/integration/purchases/invoices/not/accounted
La petición retorna un código 200 en caso de que se haya ejecutado correctamente.
En el request body debemos pasar un esta estructura la lista identificadores de facturas que queremos marcar como contabilizadas.
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/purchases/invoices/not/accounted
Rest API: Marcar facturas de compras como bloqueadas
Si queremos marcar facturas en tspoonlab como bloqueadas:
PUT:
https://app.tspoonlab.com/recipes/api/integration/purchases/invoices/lock
La petición retorna un código 200 en caso de que se haya ejecutado correctamente.
En el request body debemos pasar en esta estructura la lista de identificadores de facturas que queremos bloquear.
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/purchases/invoices/lock
Rest API: Ventas en tspoonlab
En los restaurantes tspoonlab puede integrarse con el sistema de TPV (Terminal Punto de Venta). Podemos recuperar las ventas de la TPV y utilizarlas en tspoonlab para la gestión de los almacenes y el cálculo del Food Cost teórico. Esta situación no es el objeto de este artículo ya que lo que aquí se describe es cómo enviar las ventas de tspoonlab hacia un sistema externo. En el caso de las TPV's lo que se produce es lo contrario.
Si tenemos una tienda online con Shopify lo que haríamos sería recuperar las peticiones de ventas y gestionar las producciones desde tspoonlab. Una vez realizamos el envío de la venta ésta se considera realizada y ya se podría enviar de vuelta a Shopify o a un sistema de gestión. Por lo tanto en este caso ya tiene ciertas ventajas integrarse con el módulo de ventas de tspoonlab.
Finalmente en caso de gestionar un centro de producción se generan peticiones y envío de productos. Desde los clientes (normalmente restaurantes del grupo) hacia el centro de producción y del centro de producción hacia los clientes. Aquí si que nos resultará especialmente útil integrarnos con el módulo de ventas.
Rest API: Login
Para poder hacer llamadas a nuestras API'S lo primero que necesitamos es identificarnos mediante una llamada de login.
Esa llamada nos retornará una token que después debemos asociar en cada llamada posterior.
Este shell script muestra como autenticarnos mediante curl:
[email protected]
password=XXXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
En las llamadas posteriores debemos añadir a nuestros headers el token recibido de la llamada de login:
curl -X PUT -v -H "$(cat rememberme.txt)" $url/integration/llamada
Rest API: Seleccionar un centro de coste/restaurante
Las peticiones que se describen en los apartados siguientes hacen referencia a un centro de coste, en la mayoría de los casos se correspondería con un restaurante
Para recuperar la lista de centros de costes y sus identificadores consulta el artículo Rest API: Centro de Coste.
El identificador de centro de coste se corresponde al campo idOrderCenter de la clase UserOrderCenter.
Una vez tenemos el identificador este deberá añadirse a los headers para que sea utilizado en llamadas posteriores.
echo -n 'order:351583444167656299610202XXXXXXXXXXXX' >> rememberme.txt
Por tanto en nuestros request headers debemos especificar tanto el token devuelto por el login como el identificador del centro de coste:
rememberme:aGVucnkudXBzYWxsLmRAZXXXXXXXXXXXXXXXXXX
order:351583444167656299610202XXXXXXXXXXXX
Rest API: Recuperación de albaranes de venta no contabilizadas
Para recuperar los albaranes de ventas pendientes de contabilizar debemos realizar esta llamada:
GET: https://app.tspoonlab.com/recipes/api/integration/sales/deliveries/pending?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&includeInternal=true
Debemos pasar los siguientes request parameters:
startDate (String). Fecha a partir de la cuál se recuperarán los datos
endDate (String). Fecha hasta la cuál se recuperarán los datos.
includeInternal (Boolean) Incluir también facturas de proveedores marcados como internos. Opcional. Valor por defecto true
El formato de las fechas debe ser YYYY-MM-DD y es inclusivo en startDate y endDate. Es decir todos los datos con fecha igual a startDate o endDate son retornados.
Nos retornará un array de la clase SalesDelivery y un código 200.
public class SalesDelivery {
private String id; // Id de la factura
private String idCustomer; // Id del client
private String customer; // Nombre del cliente
private String customerCode; // código cliente
private String address; // direccion
private String cp; // código postal
private String city; // ciudad
private String nif; // Nif del proveedor
private String contact; // nombre contacto
private String phone; // telf
private String contactAux; // otro nombre contacto
private String phoneAux; // otro telf
private String mail; // mail
private String mailAux; // otro mail
private String mailCC; // mail copia
private String web; // url del cliente
private String customerType; // tipo de cliente
private String customerTypeCode; // Código del tipo de cliente
private boolean customerTypeInternal;
// Indica si el cliente es interno
private String invoiceNum; // Num de factura
private Date date; // Fecha factura
private Double base; // Total base imponible
private List<SalesDeliveryLine> listLines;
private List<SalesDeliveryLine> listLinesPending;
}
Las líneas de detalle aparecen en listLines y listLinesPending. En listLines tenemos todas las enviadas y en listLinesPending las pendientes de enviar.
public class SalesDeliveryLine {
private String id; // Identificador de la línea de detalle
private int position; // Posición dentro del albarán
// Tendran valor si enviamos un producto. en caso contrario nulo
private String idComponent; // Identificador del producto
private String component; // Descripción del producto
private String codeComponent; // Código del product
// Tendran valor si enviamos un menu. en caso contrario nulo
private String idMenu; // Identificador del menu
private String menu; // Descripción del menu
private String codeMenu; // Código del menu
private String codeCustomerProduct;
// Código de venta del componente/menu
private String comment; // Comentario
private boolean sent; // Si se ha recibido o no
private Double quantity; // Cantidad
private String idUnit; // Identificador de la unidad
private String unit; // Unidad
private Double cost; // Precio venta unitario sin iva
private Double costRecipe; // Coste unitario de escandallo
private Double iva; // Tipo de IVA aplicado a la línea
private List<LineType> listTypes; // Lista de tipos del componente.
private String idCustomerGroup; // Grupo de productos del producto
private String customerGroup; // Nombre del grupo de producto
}
Este seria un ejemplo de la llamada:
[email protected]
password=XXXXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X GET -v -H "$(cat rememberme.txt)" $url/integration/sales/deliveries/pending | python -m json.tool
Para recuperar todos los albaranes de venta estén procesados o no:
GET: https://app.tspoonlab.com/recipes/api/integration/sales/deliveries/all?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&includeInternal=true
Rest API : Marcar albaranes de venta como contabilizadas
Una vez hemos traspasado los albaranes de venta a la contabilidad podemos marcarlas como contabilizadas en tspoonlab de forma que ya no se reenviaran otra vez en peticiones posteriores:
PUT:
https://app.tspoonlab.com/recipes/api/integration/sales/deliveries/accounted
La petición retorna un código 200 en caso de que se haya ejecutado correctamente
En el request body debemos pasar un esta estructura la lista identificadores de facturas que queremos marcar como contabilizadas.
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/sales/deliveries/accounted
Rest API : Marcar albaranes de venta como no contabilizadas
Si queremos volver a marcar como no contabilizadas albaranes de venta en tspoonlab:
PUT:
https://app.tspoonlab.com/recipes/api/integration/sales/deliveries/not/accounted
La petición retorna un código 200 en caso de que se haya ejecutado correctamente
En el request body debemos pasar un esta estructura la lista identificadores de facturas que queremos marcar como contabilizadas:
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/sales/deliveries/not/accounted
Rest API: Marcar albaranes de venta como bloqueados
Si queremos marcar albaranes en tspoonlab como bloqueadas:
PUT:
https://app.tspoonlab.com/recipes/api/integration/sales/deliveries/lock
La petición retorna un código 200 en caso de que se haya ejecutado correctamente.
En el request body debemos pasar un esta estructura la lista identificadores de facturas que queremos bloquear:
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/sales/deliveries/lock
Rest API : Recuperación de facturas de venta no contabilizadas
Para recuperar las facturas de ventas pendientes de contabilizar debemos realizar esta llamada:
GET: https://app.tspoonlab.com/recipes/api/integration/sales/invoices/pending?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&includeInternal=true
Debemos pasar los siguientes request parameters:
startDate (String). Fecha a partir de la cual se recuperarán los datos
endDate (String). Fecha hasta la cual se recuperarán los datos.
includeInternal (Boolean) Incluir también facturas de proveedores marcados como internos. Opcional. Valor por defecto true
El formato de las fechas debe ser YYYY-MM-DD y es inclusivo en startDate y endDate. Es decir todos los datos con fecha igual a startDate o endDate son retornados.
Nos retornará un array de la clase SalesInvoice y un código 200.
public class SalesInvoice {
private String id; // Id de la factura
private String idCustomer; // Id del client
private String customer; // Nombre del client
private String codeCustomer; // Código del client
private String accountCustomer; // Num cuenta contable del cliente
private String nif; // Nif del client
private String documentNum; // Num de documento
private String invoiceNum; // Num de factura
private boolean paid; // Si está ya pagada
private String comment; // Comentario factura
private Date date; // Fecha factura
private Date dateAccounting; // Fecha contabilidad si nulla utilizar date
private Date dateDue; // Fecha de vencimiento
private String codePaymentType; // Código de la forma de pago
private String idCostTypeVendor;
// Identificador de la cuenta de análisis del cliente
private String costTypeVendor;
// Descripción de la cuenta de análisis del cliente
private String codeCostTypeVendor;
// Código de la cuenta de análisis del cliente
private String accountCostTypeVendor;
// Cuenta contable de la cuenta de análisis del cliente
private String accountAuxCostTypeVendor;
// Cuenta contable de la cuenta de análisis del cliente private String idDocument;
// Id del documento asociado a la factura
private String extDocument; /
/ Extensión del documento asociado a la factura
private Double total; // Total factura
private Double base; // Total base imponible
private Double taxes; // Total impuestos
private List<InvoiceTax> listTaxes; // Detalle de los impuestos
private List<CostTypeTax> listCostTypeTaxes;
// Detalle de los impuestos por cuenta de análisis
private List<SalesDelivery> listDeliveries;
// Detalle de albaranes
}
Las clases InvoiceTax, CostTypeTax y SalesDelivery ya se han explicado en apartados anteriores.
Rest API : Marcar facturas de venta como contabilizadas
Una vez hemos traspasado las facturas de venta a la contabilidad podemos marcarlas como contabilizadas en tspoonlab de forma que ya no se reenviarán otra vez en peticiones posteriores.
PUT:
https://app.tspoonlab.com/recipes/api/integration/sales/invoices/accounted
La petición retorna un código 200 en caso de que se haya ejecutado correctamente
En el request body debemos pasar un esta estructura la lista identificadores de facturas que queremos marcar como contabilizadas:
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/sales/invoices/accounted
Rest API : Marcar facturas de venta como no contabilizadas
Si queremos volver a marcar como no contabilizadas facturas de venta en tspoonlab
PUT:
https://app.tspoonlab.com/recipes/api/integration/sales/invoices/not/accounted
La petición retorna un código 200 en caso de que se haya ejecutado correctamente.
En el request body debemos pasar un esta estructura la lista identificadores de facturas que queremos marcar como contabilizadas.
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/sales/invoices/not/accounted
Rest API : Marcar facturas de venta como bloqueadas
Si queremos marcar facturas de venta en tspoonlab como bloqueadas:
PUT:
https://app.tspoonlab.com/recipes/api/integration/sales/invoices/lock
La petición retorna un código 200 en caso de que se haya ejecutado correctamente.
En el request body debemos pasar un esta estructura la lista identificadores de facturas que queremos bloquear:
public class NewListIds {
private List<String> listIds;
}Aquí tenemos un ejemplo de llamada:
username= [email protected]
password=XXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
curl -X PUT -d '{"listIds":["idFactura1", "idFactura2"]}' -H "$(cat rememberme.txt)" -H 'Content-Type: application/json' $url/integration/sales/invoices/lock
Rest API: Creación de pedidos de compra en tspoonlab
Para crear pedidos en tspoonlab lo primero que debemos hacer es obtener un id de proveedor.
Rest API: Identificar el proveedor
Debemos llamar a la función:
GET:
https://app.tspoonlab.com/recipes/api/listVendorsPaged
Esta llamada está documentada en el artículo Rest API: Proveedores.
Si estamos en un entorno con un centro de producción donde nuestro proveedor está vinculado a un cliente del centro de producción el campo orderCenter tendrá el valor del centro de coste donde vayamos a pedir.
De la respuesta seleccionaremos el id del proveedor al que vamos a realizar el pedido:
Rest API: Crear pedido
Para crear un pedido debemos llamar a:
POST:
https://app.tspoonlab.com/recipes/api/integration/purchases/orders
En el body vamos a especificar toda la información relativa al pedido que queremos crear:
NewPurchaseOrder {
String idVendor; // Id del proveedor
String codeVendor; // Código del proveedor
Date dateSend; // Fecha de envio
Date dateReception; // Fecha de recepción
List<NewPurchaseOrderLine> listLines; // Detalle de líneas del pedido
}
NewPurchaseOrderLine {
String idComponent; // Identificador Ingrediente, material
String codeComponent; // Cógido del proveedor
double quantity; // Cantidad. No puede ser nula
String idUnit; // Identificador de unidad
String unit; // Nombre de la unidad
}
Rest API: Crear pedido desde identificadores
Donde:
idVendor es el identificador del proveedor conseguido del apartado anterior.
dateSend y dateReception son las fechas de envío del pedido y fecha prevista de recepción del mismo.
listLines es la lista de items que queremos comprar con el idComponent y la cantidad (quantity)
Para obtener el idComponent podemos consultar los productos a la venta del proveedor. Este campo aparece en la clase VendorComponent. Tal como se explica en el artículo Rest API: Proveedores.
Para obtener el idUnit podemos consultar la lista de unidades tal como se explica en el articulo Rest API: Unidades.
Los campos de códigos y unidad no son necesarios.
Rest API: Crear pedido desde códigos
Donde:
codeVendor es el código del proveedor y codeComponent es el código del artículo del proveedor. Unit es la descripción de la unidad.
En caso de que el component, unit no estén asociados al proveedor se generará un error ya que no se puede crear la compra.
Para validar si la unit es válida se verificará la del componente y la del formato.
Si el codeVendor no existiera en el centro de coste se generaría también un error.
Los campos de identificadores no son necesarios.
La respuesta de esta llamada es una estructura con el id del pedido:
IdWrapper {
String id; // Identificador del pedido
}
Rest API: Marcar el pedido como enviado
Una vez creado el pedido debemos enviarlo al proveedor y posteriormente marcarlo como enviado:
PUT:
https://app.tspoonlab.com/recipes/api/vendorOrder/{idProvCom}/sent
Donde:
idProvCom es el identificador del pedido obtenido en el apartado anterior.
No devuelve datos. Solo código 200 si se ha enviado correctamente.
Rest API: Marcar el pedido como recibido (Albarán)
Cuando llega la mercancía debemos marcar el pedido como recibido y generar un albarán:
PUT:
https://app.tspoonlab.com/recipes/api/vendorOrder/{idProvCom}/received/date
Donde:
idProvCom es el identificador del pedido obtenido en el apartado anterior.
En el body especificaremos la fecha de recepción y el número de albarán.
public class NewOrderReceiveParams {
Date date; // Fecha de recepción
String deliveryNum; // Número de albarán
}
No devuelve datos. Solo código 200 si se ha recibido correctamente.
Rest API: Creación de pedidos de venta en tspoonlab
Para crear pedidos de venta en tspoonlab lo primero que debemos hacer es obtener un id de cliente:
Rest API: Identificar el cliente
Debemos llamar a la función:
GET:
https://app.tspoonlab.com/recipes/api/listCustomersPaged
Esta llamada está documentada en el artículo Rest API: Clientes.
De la respuesta seleccionaremos el id del cliente al que vamos a realizar el pedido
Rest API: Crear pedido
Para crear un pedido debemos llamar a:
POST:
https://app.tspoonlab.com/recipes/api/integration/sales/orders
En el body vamos a especificar toda la información relativa al pedido que queremos crear:
NewSaleOrder {
String idCustomer; // Id del cliente
String codeCustomer; // Código del cliente
Date dateSend; // Fecha en que se ha generado el pedido
Date dateReception; // Fecha de envio/recepción del pedido
List<NewPurchaseSaleLine> listLines; // Detalle de líneas del pedido
}
NewPurchaseSaleLine {
String idComponent; // Identificador del producto a la venta
String codeComponent; // Cógido del producto en el cliente
double quantity; // Cantidad. No puede ser nula
String idUnit; // Identificador de unidad
String unit; // Nombre de la unidad
}
Rest API: Crear pedido desde identificadores
Donde:
idCustomer es el identificador del cliente conseguido del apartado anterior.
dateSend y dateReception son las fechas de generación del pedido y fecha prevista de envío/recepción del mismo.
listLines es la lista de items que queremos comprar con el idComponent y la cantidad (quantity).
Para obtener el idComponent podemos consultar los productos a la venta del cliente, puedes dirigirte al artículo Rest API: Clientes.
Para obtener el idUnit podemos consultar la lista de unidades tal como se explica en Rest API: Unidades.
Los campos de códigos no son necesarios.
Rest API: Crear pedido desde códigos
Donde codeCustomer es el código del cliente y codeComponent es el código del producto del cliente.
unit es la descripción de la unidad
Los campos de identificadores no son necesarios.
La respuesta de esta llamada es una estructura con el id del pedido:
IdWrapper {
String id; // Identificador del pedido
}
En caso de que el component, unit no estén asociados al cliente se generará un error ya que no se puede crear la venta.
Si el codeCustomer no existiera en el centro de coste se generaría también un error.
Rest API: Consultar totales de compras por estados
Para poder consultar las cantidades totales de las compras por estado en un período de tiempo debemos llamar a la función:
GET:
https://app.tspoonlab.com/recipes/api/integration/purchases/totals?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&type=0
Debemos pasar los siguientes request parameters:
startDate (String). Fecha a partir de la cuál se recuperarán los datos. Obligatorio.
endDate (String). Fecha hasta la cuál se recuperarán los datos. Obligatorio.
type (short). Tipo de total.
El formato de las fechas debe ser YYYY-MM-DD y es inclusivo en startDate y endDate. Es decir todos los datos con fecha igual a startDate o endDate son retornados.
Los tipos de total type de tipo numérico puede tomar estos valores:
0 - vendorOrderTypeNotSent - Pedidos no enviados.
1 - vendorOrderTypeNotReceived = Pedidos no recibidos.
2 - vendorOrderTypeReceivedNotInvoice = Pedidos recibidos que no están en factura.
3 - vendorOrderTypeReceivedInvoice = Pedidos recibidos en factura.
4 - vendorOrderTypeReceivedInvoiceAccounted = Pedidos recibidos en factura y contabilizados.
5 - vendorOrderTypeReceivedInvoiceNotAccounted = Pedidos recibidos en factura y no contabilizados.
6 - vendorOrderTypePendingApproval = Pedidos pendientes de aprobación.
7 - vendorOrderTypePendingReview = Pedidos pendientes de revisión.
8 - vendorOrderTypeScanPendingValidate = Pedidos escaneados pendientes de validación.
9 - vendorOrderTypeReceived = Pedidos recibidos.
10 - vendorOrderTypeReceivedInvoiceValidated = Pedidos recibidos en facturas validadas.
11 - vendorOrderTypeReceivedInvoiceNotValidated = Pedidos recibidos en facturas no validadas.
Retorna el importe total:
class ValueWrapper {
Double value;
}
¿Te ha resultado útil este artículo?
Si necesitas más ayuda, contacta con soporte haciendo clic en el Chat de Soporte Integrado en la esquina inferior derecha de tu pantalla.