Cada endpoint dispone de un formato de acceso genérico (para PUT,GET,POST,DELETE), y en algunos casos existen recursos especializados que, aunque intentamos que sigan el mismo patrón de acceso, puede variar en la forma de pasarle parámetros.
Por norma general dispondremos del siguiente formato para cada verbo HTTP:
PUT /EndpointREST/{format}
Los endpoint PUT nos permiten crear o insertar nuevos registros o actualizarlos. Para insertar un registro debemos añadir en formato JSON los campos y sus valores en el body de la petición, sin el campo “id”.
Si quisiéramos actualizar un registro, sería de la misma manera pero indicando el campo “id” y el valor del registro que se desea actualizar.
GET/POST /EndpointREST/{format}/{id}/{pag}/{tpag}
Los endpoint GET/POST nos permiten obtener registros. Se puede indicar solo {format} para obtener todos los registros. {format}/{id} para obtener un registro. O paginar los resultados con {format}//{pag}/{tpag}. Para que el paginador funcione correctamente debes indicar esa doble barra inclinada entre {format} y {pag} ({format}//{pag}). {pag} indica el número de la página a mostrar y {tpag} cuantos elementos por página se mostrarán.
La mayoría de endpoints son paginables, y en la respuesta aparecerá el siguiente elemento que podréis consultar sobre el total de elementos, el tamaño de página usado, etc.:
_pages":[
{
"totalRecords": 3116,
"records": 10,
"tampage": "10",
"page": "0",
"npages": 312,
"nextpage": 1
En el caso de endpoints con muchos registros o muchos campos siempre recomendamos paginar los resultados.
Si el endpoint consultado se envía por POST es posible filtrar los resultados enviando un formulario con el campo y el valor a buscar.
DELETE /Endpoint REST/{id}
Los endpoints para eliminar registros. Aunque tenemos disponible este verbo HTTP para borrar registros, lo habitual es desactivarlos indicando en el campo “status” el valor “0”, ya que muchos de los endpoints tienen este campo. En el caso de pedidos lo mejor es anularlos, pues hay varios procesos que se deben ejecutar (recálculo de stock, anulación de facturas, etc.).
Valores por defecto
En los endpoints será habitual que haya ciertos campos comunes que tendrán un valor por defecto, normalmente porque solo hay un registro (y por tanto un identificador), o porque se ha tomado la decisión que el valor indicado será el valor por defecto (aunque haya otros elementos de su tipo disponibles).
idMetagroup/idMetagrupo/customer: cw5fc79ea0d5dca. Se puede obtener accediendo a /MetaGroupREST/{format}
fkIva:
IVA 10%: cw58f868e7b05f4cw5fc79ea0d5dca
IVA 21%: cw58f868efd7febcw5fc79ea0d5dca
fkManufacturer: cw5fe2206f81d41
Artículos
PUT /ArticleREST/{format}/{id}
Ejemplo de respuesta:
"Article":{
"customer": "cw5d51549d49698", <-- Metagrupo
"name": "TEST", <-- Nombre del artículo
"reference": null,
"pubDate": null,
"weight": null,
"unitPrice": null,
"status": "1", <-- Por defecto se marca a 1 (Activo), 0 si se desactiva
"flags": "cw5e5cf0641a519", <-- Condición en el que se encuentra el artículo. Obligatorio. Ese identificador corresponde con "Nuevo"
"fkIva": "cw5d530f9722705", <-- Iva. Es obligatorio
Se puede crear un registro de stock indicando los siguientes campos
*idStore: Id del almacén
*created: Fecha de creación del registro
*idArticle: Id del artículo
*status: Por defecto a 1 (Activo). Si fuera a cero quedaría desactivado.
*basePrice: El precio que tiene el artículo
*cost: Coste real del artículo
*barCode: Código de barras
idMasterArticle: Si el artículo tiene un artículo padre.
*multiplier: Unidades
idArticleStock: Identificador del SSN (Número de serie) relacionado
idContainer: Identificador del contenedor
Se suele crear un registro por almacén con las unidades existentes en este indicadas en el campo “multiplier”. Si está activo el control por número de serie habría que crear un registro por cada número de serie, y por tanto siempre podría haber más de un registro por almacén.
Si además el stock está contenido en cajas, pales y/o lotes, también habría que indicarlo. Además de crear las entradas correspondientes en /ArticleContainersREST, /ContainersREST y /ContainerObjectsREST.
Por último, si las ubicaciones del almacén están activadas sería necesario indicar la ubicación donde se entrará el stock, o donde se encuentre en ese momento. Si todo el proceso de ubicaciones se realiza por la API sería necesario añadir las entradas correspondientes en /StoresLocationsREST, /StoresLocationsDefinitionsREST y /StoresLocationsStockREST.
Modificación de stock
El stock puede ser modificado usando el mismo servicio. Si existe una orden de compra se deberá gestionar también está.
Obtener el stock disponible
El stock disponible se puede obtener desde el endpoint /ArticleStockREST/availables/{format}/{idArticle}/{idStore}
Categorías
Aquí tenemos tres endpoints:
Categorías: Nos devuelve todas las categorías.
Relación de categorías con categorías: Las relaciones entre las categorías, la jerarquía la marca el campo nivel de la categoría.
Relaciones de categorías con artículos: Define la pertenencia de los artículos con las categorías.
GET|PUT /CategoryREST/{format}
Dónde {format} puede ser JSON o XML
Este endpoint devolvería todas las categorías, también es el usado para insertar con PUT.
GET /CategoryREST/{format}/{id}
Dónde {format} puede ser JSON o XML
Donde {id} es el identificador de la categoría
Este endpoint devolvería la categoría indicada con {id}.
GET|PUT /CategoriesRelCategoryREST/{format}
Dónde {format} puede ser JSON o XML
Este endpoint devolvería todas las relaciones entre categorías, también es el usado para insertar con PUT.
GET /CategoriesRelCategoryREST/{format}/{id}
Dónde {format} puede ser JSON o XML
Donde {id} es el identificador de la relación
Este endpoint devolvería los datos de la relación indicada con {id}.
GET /CategoriesRelCategoryREST/category/{format}/{id}
Dónde {format} puede ser JSON o XML
Donde {id} es el identificador de la categoría
Este endpoint devolvería todas las relaciones que tuviera la categoría indicada.
GET|PUT /CategoriesRelArticleREST/{format}
Dónde {format} puede ser JSON o XML
Este endpoint devolvería todas las relaciones entre categorías y artículos, también es el usado para insertar con PUT.
GET /CategoriesRelArticleREST/{format}/{id}
Dónde {format} puede ser JSON o XML
Donde {id} es el identificador de la relación
Este endpoint devolvería los datos de la relación indicada con {id}.
GET /CategoriesRelArticleREST/category/{format}/{id}
Dónde {format} puede ser JSON o XML
Donde {id} es el identificador de la categoría
Este endpoint devolvería los datos de relación en los que apareciera la categoría indicada en {id}.
GET /CategoriesRelArticleREST/article/{format}/{id}
Dónde {format} puede ser JSON o XML
Donde {id} es el identificador del artículo
Este endpoint devolvería los datos de relación del artículo indicado en {id}.
Ejemplos, hay que indicar las credenciales de autenticación siempre:
GET/CategoryREST/JSON
Esto devolverá el listado completo de categorías. Como el resultado es muy grande no os indico el resultado, pero dentro de “Category” habría un array con las categorías.
GET/CategoryREST/JSON/cw5d656bc93b3cd
Esto devuelve una categoría.
Salida truncada:
Inserción:
PUT/CategoryREST/{format}
Body:
Inserción:
PUT/CategoryREST/{format}
Body:
{
"fkFamily":"",
"fkInvoiceCat":"",
"fkInvoiceSubCat": "",
"fkInvoiceDepartment": "",
"fkInvoiceReceivedCat": "",
"fkInvoiceReceivedSubcat": "",
"customer": "cw5d656bc93b3cd", ← Obligatorio
"name": "Categoría 1", ← Obligatorio
"furl": "",
"level": "0", ← Obligatorio
"created": "2020-11-18", ← Obligatorio
"fkUser": "",
"fkMenu": "",
"position": "",
"fkInvSentCat": "",
"fkInvSentSubCat": ""
}
Response:
PUT/CategoriesRelCategoryREST/JSON
Body:
{
"fkCategoryParent":"123", ← Identificador de la categoría padre
"fkCategoryChild":"456" ← Identificador de la categoría hija
}
Response:
PUT/CategoriesRelArticleREST/JSON
Obtener los datos de las categorías hijas de una categoría padre dada:
Hay que llamar a GET /CategoriesRelCategoryREST/category/{format}/{id}, que al pasarle el id de la categoría padre os devolverá un listado de identificadores de categorías hijas.
Para obtener los datos de estas categorías tendríais que llamar a GET /CategoryREST/{format}/{id} con el {id} de la categoría hija, que correspondería al campo fkCategoryChild en la petición anterior.
Los campos reference, name y múltiple son lo mínimo que necesitaréis.
Las características pueden ser traducibles para mostrarlas en múltiples idiomas añadiendo un registro relacionado. Para ello:
Hay que realizar una petición de inserción en el servicio:/ECMTextREST, indicando en el campo idECMWebPage el identificador de la característica (campo id) y rellenar el campo Title.
Define los nombres de los valores de las características. Por ejemplo, para la característica “Color” aquí habría que indicar los valores correspondientes: rojo, verde, azul, etc.
Los nombres de los valores de las características pueden ser traducibles para mostrarlas en múltiples idiomas añadiendo un registro relacionado. Para ello:
Hay que realizar una petición de inserción en el servicio: /ECMTextREST, indicando en el campo idECMWebPage el identificador del nombre de la característica (campo id) y rellenar el campo Title.
En el artículo, bien al crearlo o modificarlo puedes indicar que los artículos que lo componen se desglosen:
articlesContainedToPurchase: Desglosar en compras con Artículos contenidos (1/0)
articlesContainedToPreparation: Desglosar artículo con artículos contenidos durante la preparación (1/0)
articlesContainedToEntry: Desglosar artículo comprado durante la entrada (1/0)
assemblyOnEntry: Fabricación del artículo continente en la entrada de los contenidos (1/0)
Empresas y contactos
Un pedido está vinculado con un contacto de un cliente. Para nosotros, un cliente es una empresa, y un contacto un empleado de esa empresa. En el caso de particulares tanto la empresa como el contacto serán el mismo. Por tanto, primero hay que crear el cliente, y después los posibles contactos que existan.
Servicio de clientes: /CrmCompanyREST, con el valor “|Cliente|” en el campo “category”. Si el cliente ya existiese, o tuviera un valor en “category” distinto (por ejemplo “|Proveedor|”) es necesario que se mantenga el valor existente, con lo que quedaría “|Proveedor|Cliente|”.
También es necesario rellenar los campos defaultAddressInvoice, defaultContactInvoice, defaultAddressInvoiceToSend y defaultContactInvoiceToSend. Los defaultAddress* deben tener el identificador de la dirección que se crea de facturación, los defaultContact el id del contacto. Son necesarios para la generación automática de la factura al crear el pedido.
El campo customerConsent del contacto debe tener el valor “1”, indica que consiente la gestión de la solicitud, para el ecommerce permitiría la gestión del pedido.
El campo prospectConsent permite el envío de información periódica si se le da el valor “1”.
Para ambos campos están los campos de fechas: customerConsentDate y prospectConsentDate.
Además, cada cliente tendrá sus propias direcciones que se añadirán al pedido:
Para conocer el tipo de dirección fiscal o de envío que existen, se puede utilizar /AddressTypeREST/ShipmentAddressType (envío), y /AddressTypeREST/FiscalAddressType (Fiscal)
Pedidos
Para la creación del pedido es necesario primero que esté creado el cliente /CrmCompanyREST), el contacto (/ContactsREST) y el carrito (/ShoppingCartREST) con sus artículos (/ShoppingCartsArticleREST).
A continuación hay que realizar una petición a /OrderREST/generate con los parámetros indicados en el endpoint (más abajo).
Carro de la compra
Un pedido está relacionado con un carro de la compra y sus conceptos.
Servicio de datos del carrito: /ShoppingCartREST
Servicio de conceptos del carrito: /ShoppingCartArticleREST
Tenéis las definiciones de campos en los enlaces indicados. Si tenéis alguna duda consultadnos. Las peticiones PUT funcionan igual a los ejemplos de las categorías. El campo “Id” solo se indica si es una actualización, si no, no debe aparecer en el Body de la petición.
PUT /ShoppingCartREST
Obtener todos los carritos
GET /ShoppingCartREST/{format}//{pag}/{tpag}
Obtener los datos de un carrito
GET /ShoppingCartREST/{format}/{id}
Insertar un artículo en un carrito
PUT /ShoppingCartsArticleREST
Explicación de campos
"inStock": "1", ← Indicar "1" si el artículo en el momento de insertarlo en el carrito tenía stock. En caso contrario indicar un "0"
"grossUnitStockPrice": "246.46", <-- Precio bruto unitario de stock
"unitStockBasePrice": "143.00", <-- Precio base unitario de stock
"unitStockPrice": "143.00", <-- Precio unitario de stock
"grossUnitNoStockPrice": "246.46", <-- Precio bruto unitario sin stock
"unitNoStockBasePrice": "143.00", <-- Precio base unitario sin stock
"unitNoStockPrice": "143.00", <-- Precio unitario sin stock
"rechargo": "-10.00", <-- Recargo de equivalencia sin símbolos de euro o porcentaje
"rechargoType": "0", <-- Tipo de recargo de equivalencia. Para indicar un tipo porcentual, el valor es "0", para indicar un tipo directo (euros), "1".
"totalStockBasePrice": "143.00", <-- Precio base total de stock
"totalStockPrice": "143.00", <-- Precio total de stock
"totalNoStockBasePrice": "0", <-- Precio base total sin stock
"totalNoStockPrice": "0" <-- Precio total sin stock
Nosotros trabajamos con dos precios: precios de stock y precios sin stock. Algunos de nuestros clientes trabajan con dos precios dependiendo del stock disponible de un artículo, si hay stock el artículo tiene un precio, si no hay stock tiene un precio diferente.
Si este no es vuestro caso los campos "unitStockPrice"/"unitNoStockPrice", "unitStockBasePrice"/"unitNoStockBasePrice" y "grossUnitStockPrice"/"grossUnitNoStockPrice" deberían coincidir en su valor. Por ejemplo, el valor de "unitStockPrice" debe ser igual al valor de "unitNoStockPrice".
Para los totales se pueden dar tres casos
Si el número de unidades vendidas están disponibles (hay stock), entonces los campos "totalNoStockPrice" y "totalNoStockBasePrice" tendrán el valor "0", los otros dos campos de total serán los que tengan el valor correcto.
Si el número de unidades vendidas no están disponibles (no hay stock), entonces los campos "totalStockPrice" y "totalStockBasePrice" tendrán el valor "0", los otros dos campos de total serán los que tengan el valor correcto.
Si disponemos de 5 unidades de stock pero se han vendido 7 unidades, entonces los campos "totalStockPrice" y "totalStockBasePrice" tendrán el valor de las cinco unidades que haya en stock, y "totalNoStockPrice" y "totalNoStockBasePrice" tendrán el valor de las restantes dos unidades de las que no hay stock.
Métodos de pago
Efectivo / Contrarreenbolso
0
Transferencia bancaria
1
Domiciliación
2
Tarjeta de crédito/debito
3
Pagaré
4
Talón
5
Confirming
6
Carta de cŕedito
7
Cheque
8
CESCE
9
American Express
A
Agente
B
RAndorra
C
Vale
D
Devolución del vale
T
Contrarreembolso
E
Leasing
L
Renting
R
Paypal
P
Paga Más tarde
F
Tarjeta regalo
G
Aplazame
H
Obtener los artículos de un carrito
GET /ShoppingCartsArticleREST/shoppingCart/{format}/{idCart}
Pedidos
La creación del pedido se basa en los datos existentes en el carrito. Por tanto es necesario crear primero el carrito y sus conceptos antes de generar el pedido
Una vez creado el carrito, a /OrderREST/generate se le pasan cuatro parámetros: cartId (identificador del carrito), userId (identificador del cliente), swlang (idioma (es,en, etc.)), metagroup (identificador del metagrupo), con lo que se generará el pedido, se reservará stock (o se creará una orden de compra si no hubiera stock), se generará las facturas correspondientes, etc.
El recurso /OrderREST/generate genera un pedido en estado “En proceso” o “Pendiente de mercancía”. Si se quiere otro estado es necesario generar el pedido sin usar este recurso.
POST /OrderREST/generate
Body Form:
cartId: “bc00019261a00fd” ← Obligatorio. Identificador del carrito (ShoppingCartsREST)
userId: “cw5ceeecf5cebd9” ← Obligatorio. Identificador del usuario (ContactREST)
swlang: “es” ← Obligatorio. Idioma de las notificaciones
metagroup: “cw5ced461c0d4af”. ← Obligatorio.
Si el artículo del carrito no tuviera los precios indicados, o se desea modificar los totales en vez de que el sistema los obtenga de los artículos del carrito habría que indicarlos con los siguientes parámetros:
orderTotalDiscount: “10” <-- Valor real del descuento total del pedido. Cero si no hay descuento.
orderBasePrice: “100” <-- Precio base total del pedido sin impuestos. Subtotal
orderTotalTax: “21” <-- Importe de los impuestos aplicables al pedido.
orderTotalSurcharge: “0” <-- Importe de recargo de equivalencia total
orderTotalPrice: “121” <-- Total con impuestos ya sumados.
orderType: “cw5f3a93ae273da” ← Opcional. Tipo de pedido. Si no se indica en la petición el sistema buscará el tipo de pedido “web”.
Si se está generando un pedido que corresponde al cliente de un cliente es necesario también indicar el identificador del cliente:
userId: “cw5ceeecf5cebd9” ← Obligatorio. Su valor corresponderá con el cliente.
idClientOfClient: “cw622208040b6ab” ← Será el identificador del cliente de userId
OrdersChangeStatus - Orders - Cambio de valor en campo status
PurchaseOrdersChangeStatus - PurchaseOrders - Cambio de valor en campo status
RMAChangeStatus - RMA - Cambio de valor en campo status
WorkOrdersChangeStatus - WorkOrders - Cambio de valor en campo status
TraceabilityInsert - Traceability - Inserción
Respuesta
La llamada al URL es de tipo POST y se incluyen los siguientes parámetros:
object: nombre del objeto que ha desencadenado la llamada
objectid: valor de la clave primaria para dicho objeto
event: evento que ha desencadenado la llamada. Valores: I para inserción, M para modificación, D para borrado, F para cambio de valor en campo
Sólo si el evento es de tipo F:
field: nombre del campo asociado al evento
fieldBefore: valor del campo antes de modificar
fieldAfter: valor del campo después de modificar
Proceso para obtener el stock disponible desde los webhooks
Webhook OrdersModify, OrdersChangeStatus:
Con el identificador que recibes haces una consulta a GET /OrdersArticleREST/byOrder/{format}/{idOrder} para obtener los artículos (también podrías hacer la misma consulta usando POST /OrdersArticleREST/{format} y {idOrder} y su valor en el body del formulario). Con los artículos haces una petición por artículo a GET /ArticleStockREST/availables/{format}/{idArticle}/{idStore} para obtener el stock disponible de esos artículos. El {idArticle} sería el campo {id}, y el {idStore} el campo {idStore} que te devuelve /OrdersArticleREST/byOrder.
Webhook TraceabilityInsert:
El identificador que recibes corresponde al endpoint /ecomTraceabilityREST, por tanto tendrás que llamar primero a este endpoint con el identificador recibido GET /ecomTraceabilityREST/{format}/{id} con lo que obtendrás el registro de la trazabilidad con el mensaje de qué a cambiado. Para obtener el artículo usamos el campo {idParent} devuelto en la petición anterior para consultar el registro de stock en el endpoint GET /ArticleStockREST/{format}/{id}, en el que tendrémos los campos {idArticle} e {idStore} para usarlos en el endpoint GET /ArticleStockREST/availables/{format}/{idArticle}/{idStore}.
Webhook WorkOrdersChangeStatus:
El identificador que recibes es el de una orden de trabajo de tipo entrada. Lo primero que hay que hacer es obtener los códigos de barras entrados a través de GET /WorkOrderSSNREST/workOrder/{format}/{id}. Con el valor del campo {fkSN} de cada registro obtenido consultamos el artículo y almacén al que corresponde a través de GET /ArticleStockREST/{format}/{id}, que nos devolverá el registro con el {idArticle} e {idStore} que podrás pasar a GET /ArticleStockREST/availables/{format}/{idArticle}/{idStore} para obtener los disponibles.
Conocer los movimientos de stock de un artículo
En cualquier momento puedes consultar /ecomTraceabilityREST para obtener el listado de cambios que se hayan realizado en el stock de un artículo a través de POST /ecomTraceabilityREST/{format} y en el body indicar la clave {idParent} con el valor del id del artículo a consultar.
Multicliente
De cara a trabajar con varios clientes dentro de Yunbit tenemos que tener en cuenta los siguientes factores.
IDs a crear
Categorías de empresas:
CLIENTETEAMTODAY_PROPIA
CLIENTETEAMTODAY
CLIENTETEAMTODAY_B2C
CLIENTETEAMTODAY_ECI
CLIENTETEAMTODAY_ECI_WEB
BYNIUMA
CORNERS BYNIUMA
MULTIMARCA TRUCCO Y NAELLE
Ya están creadas recuerda poner | al principio y al final.
Tipos de pedidos:
PROPIA_BYNIUMA = cw6155c7aeb0786
MULTIMARCA = Este ya existe y el ID es cw614459fa9a119
B2C_BYNIUMA = cw6155c7dc63a9a
ECI_BYNIUMA = cw6155c86b4027c
ECIWEB_BYNIUMA = cw6155c77f8e4d5
Compañías de transporte:
SEUR
DHL
Servicios de transporte:
SEUR Normal…
Empresas
Si tiene albarán personalizado indicar el siguiente ID en el campo idProposalTemplateAlbaran como se indica en la sección Albaranes de Empresas
Artículos
En la inserción de artículos comunicamos el cliente relacionado con el artículo en el campo fkClient, el campo debe estar relleno con el id de la empresa en Yunbit. En el endpoint de Artículos Maestros.
Los artículos actuales hay que vincularlos a GJB, dinos si lo haces tu o lo hacemos nosotros.
Pedidos
En la inserción de pedidos comunicamos el cliente relacionado con el pedido en el campo “idClientOfClient”
Para poder añadir etiquetas se tendra que una peticion PUT a https://cloud.yunbit.es/eCommerce/ShippingLabelREST/JSON con los siguientes parametros en el cuerpo:
'idOrder' : Identificador del pedido.
'type' : formato de la etiqueta (ZPL, PDF, TPL)
'documentum' : Fichero pasado a base64 de ( PDF, ZPL, TPL)
‘fileName’: Nombre de la etiqueta con su extensión.
Utilizamos cookies para optimizar nuestro sitio web y nuestro servicio.
Técnicas o necesarias / preferencias
Siempre activo
El almacenamiento o acceso técnico es estrictamente necesario para el propósito legítimo de permitir el uso de un servicio específico explícitamente solicitado por el abonado o usuario, o con el único propósito de llevar a cabo la transmisión de una comunicación a través de una red de comunicaciones electrónicas.
Preferencias
El almacenamiento o acceso técnico es necesario para la finalidad legítima de almacenar preferencias no solicitadas por el abonado o usuario.
Análisis o medición
El almacenamiento o acceso técnico que es utilizado exclusivamente con fines estadísticos. El almacenamiento o acceso técnico que se utiliza exclusivamente con fines estadísticos anónimos. Sin un requerimiento, el cumplimiento voluntario por parte de tu Proveedor de servicios de Internet, o los registros adicionales de un tercero, la información almacenada o recuperada sólo para este propósito no se puede utilizar para identificarte.
Publicidad comportamental
El almacenamiento o acceso técnico es necesario para crear perfiles de usuario para enviar publicidad, o para rastrear al usuario en una web o en varias web con fines de marketing similares.
