calculate-order
Este método se utiliza para calcular y obtener la información de una orden de venta antes de ser creada, este método es meramente informativo ya que no se genera ninguna orden de venta al momento de ejecutarse.
Este método se utiliza para revisar una orden de venta antes de crearse, es útil para confirmar la información antes de enviarla al método add-order y posteriormente ya crear la orden de venta, utiliza la misma estructura que add-order por lo que los mensajes de error serán los mismo, esto también es útil para saber si existe algún error en la petición antes de enviar los datos al método add-order.
Es especialmente útil cuando se utiliza la opción de calcular el total de la orden utilizando el precio en MXN (Peso mexicano) de los productos y/o servicios que se ingresen en el carrito de compras, para así poder obtener el total de la orden ya en la criptomoneda con la que se va a pagar.
Cuando el total de la orden se ingresa manualmente ya en la criptomoneda con la que se va a pagar no es tan necesario hacer uso de calculate-order, sin embargo, cuando el total de la orden se ingresa manualmente en MXN (Peso mexicano), es decir, que no se utiliza el precio de los productos y/o servicios, pero si se ingresa el total en MXN como ya se mencionó, si recomendamos utilizar calculate-order, para revisar los datos finales de la orden de venta antes de crearla.
Path del método
calculate-order
Endpoint final
PRODUCCION
https://aceptabits.com/api/thirdparty/v1/calculate-order
SANDBOX DE PRUEBAS
https://sandbox.aceptabits.com/api/thirdparty/v1/calculate-order
Método de petición HTTP
POST
Lista de parámetros
| Parámetro | Obligatorio | Descripción | valor |
|---|---|---|---|
| code_customer | Si | Es el código del cliente a la que se asignara la orden | ejemplo: pgbcus52768928368489799 Este código es único de cada cliente, se obtiene al consultar el listado de clientes o al generar un cliente nuevo, consulte los métodos: get-customers, add-customer o show-customer para más detalles Así mismo en estos mismos métodos puedes encontrar la tienda a la que pertenece el cliente con los campos code_shop y name_shop |
| code_currency | Si | Es el código de moneda con el que se pagara la orden | ejemplo: PBT o BTC Este código es único para cada moneda soportada en la plataforma, para consultar el listado de monedas soportadas en la plataforma consulta el método: get-currencies |
| type_order | Si | Es el tipo de orden de venta Indica si el total de la orden se ingresara de manera manual o si se utilizara el carrito de compras para calcular el total de la orden | Se aceptan dos valores el 1 y el 2: 1 = se debe de ingresar el total de la orden manualmente, ya sea en moneda FIAT, es decir en MXN (Peso mexicano) o en la la CRIPTOMONEDA con la que se pagara la orden 2 = se calculara el total de la orden utilizando el precio y cantidad de los productos y/o servicios agregados en el carrito de compras Si alguno de los elementos del carrito de compras (productos y/o servicios agregados) no tiene precio, es decir que tenga $0.00, forzosamente se deberá de utilizar el valor 1 para este parámetro, si se ingresa el valor 2 retornara el error 1361 |
| type_total | Únicamente obligatorio cuando type_order se envié con valor 1 | Es el tipo de total Indica si el total de la orden ingresado manualmente está en moneda FIAT (es decir en MXN) o en la CRIPTOMONEDA en la que se pagara la orden | Se aceptan dos valores el 1 y el 2: 1 = se debe de ingresar el total de la orden en moneda FIAT, es decir en MXN (Peso mexicano) 2 = se debe de ingresar el total de la orden en la CRIPTOMONDA con la que se pagara la orden llámese total de la orden al parámetro de esta lista llamado total |
| total | Únicamente obligatorio cuando type_order se envié con valor 1 | Es el monto total de la orden que el cliente deberá de pagar Hay que tomar en cuenta que la comisión que se paga a AceptaBits por el uso del servicio se retira del total de la orden, ya sea que se ingrese manualmente con este parámetro o que sea calculado por medio del carrito de compras | ejemplo: 50, 20.23, 0.0056, 1.56300008, etc. Se deberá de ingresar el monto total de la orden que el cliente deberá de pagar, este valor debe de ser numérico, si el monto requiere el uso de decimales se deberán de enviar de la siguiente manera: * Si el parámetro type_total es igual a 1, se deberan enviar máximo 2 decimales* Si el parámetro type_total es igual a 2, se deberán de enviar máximo 8 decimales |
| include_agent | Únicamente obligatorio cuando el cliente tiene asignado un agente de ventas | Indica si se incluirá al agente de ventas en la orden | Se aceptan dos valores el 0 y el -1: 0 = no quiero incluir al agente de ventas en la orden -1 = si quiero incluir al agente de ventas en la orden Este parámetro es únicamente obligatorio si el cliente utilizado en la orden de venta tiene asignado un agente de ventas, para saber si un cliente tiene asignado un agente de ventas consulte los metodos get-customers, add-customer o show-customer En estos métodos encontraras más detalles, pero para resumir, si el cliente tiene los campos name_agent y code_agent con un valor que no sea null significa que el cliente tiene asignado un agente de ventas, estos campos tienen el valor null significa que el cliente no tiene asignado un agente de ventas |
| services | Únicamente obligatorio cuando no se incluyan productos en el carrito de compras | Son los servicios destinados al carrito de compras Cada servicio agregado deberá de contener los siguientes parámetros: * code = Es el código del servicio que se agregara* qty = Es la cantidad de los servicios (se admiten hasta 8 decimales para número no enteros)Este parámetro se envía en formato de arreglo [] con cada uno de los servicios destinados al carrito en formato json | ejemplo:{"code":"pgbser56683545785157568","qty":1}Al ser un parámetro de tipo arreglo [] se deberán enviar todos los servicios que se requieran agregar al carrito de ese modo ejemplo: services[]: el json con un servicio services[]: el json con otro servicio services[]: ... services[]: ... Los servicios deben de pertenecer a la misma tienda a la que pertenece el cliente, para saber a qué tienda pertenece un servicio apóyate de los siguientes métodos: get-services, add-service o show-customer, en resumen podras encontrar a que tienda pertenece un servicio con los campos code_shop y name_shop |
| products | Únicamente obligatorio cuando no se incluyen servicios en el carrito de compras | Son los productos destinados al carrito de compras Cada producto agregado deberá de contener los siguientes parámetros: * code = Es el código del producto que se agregara* qty = Es la cantidad de los productos (se admiten hasta 8 decimales para número no enteros)Este parámetro se envía en formato de arreglo [] con cada uno de los productos destinados al carrito en formato json | ejemplo:{"code":"pgbpro6788273824117159","qty":"2.5"}Al ser un parámetro de tipo arreglo [] se deberán enviar todos los productos que se requieran agregar al carrito de ese modo ejemplo: products[]: el json con un producto products[]: el json con otro producto products[]: ... products[]: ... Los productos deben de pertenecer a la misma tienda a la que pertenece el cliente, para saber a qué tienda pertenece un producto apóyate de los siguientes métodos: get-products, add-product o show-product, en resumen podrás encontrar a que tienda pertenece un producto con los campos code_shop y name_shop |
| concept | No | Es el concepto que vas a darle a la orden | ejemplo: venta mesa 15, pedido no.6398, reparación refrigerador, etc. Deveras de ingresar el concepto con el que quieres identificar a la orden, recomendamos ampliamente utilizarlo para saber de una manera más sencilla de que fue la orden, puede omitirse e identificarla únicamente con el código de orden pero por comodidad del usuario dueño de la cuenta de AceptaBits recomendamos utilizarlo |
Para despejar dudas sobre como enviar los parámetros te recomendamos ingresar en la sección de Ejemplos de la presente documentación
Lista de códigos
| Código | Descripción |
|---|---|
| 0057 | Orden calculada con éxito |
| Código | Descripción |
|---|---|
| 0000 | El Token API no es correcto y la autenticación del usuario ha fallado |
| 0003 | El Token API no es correcto y la autenticación del usuario ha fallado |
| 1314 | El Token API no es correcto y la autenticación del usuario ha fallado |
| 1315 | El código de cliente es requerido |
| 1316 | El código de moneda es requerido |
| 1317 | El tipo de orden es requerido (ingresa el valor 1 para órdenes donde se ingresará el total manualmente o el valor 2 para calcular el total de la orden usando el carrito de compras) |
| 1318 | El tipo de orden debe de tener el valor 1 o el valor 2 |
| 1319 | El tipo de orden debe de tener el valor 1 o el valor 2 |
| 1320 | El tipo de orden debe de tener el valor 1 o el valor 2 |
| 1356 | El tipo de total es requerido (ingresa el valor 1 para órdenes donde se ingresara el total manualmente en moneda FIAT o el valor 2 para órdenes donde se ingresara el total manualmente en la CRIPTOMONEDA en la que se pagara la orden) |
| 1357 | El tipo de total debe ser 1 o 2 |
| 1358 | El tipo de total debe ser 1 o 2 |
| 1359 | El tipo de total debe ser 1 o 2 |
| 1408 | Es requerido indicar si se incluirá al agente en la orden de venta |
| 1409 | Para indicar si se incluirá al agente en la orden de venta se debe de enviar el valor 0 para un NO o el valor -1 para un SI |
| 1321 | El total de la orden es requerido |
| 1352 | El total ingresado en moneda FIAT, es decir en MXN (Peso mexicano) debe ser numérico y si se ingresan decimales deberá de contar con máximo 2 |
| 1353 | El total ingresado en moneda FIAT, es decir en MXN (Peso mexicano) debe ser numérico y si se ingresan decimales deberá de contar con máximo 2 |
| 1354 | El total ingresado en CRIPTOMONEDA, es decir en la criptomoneda con la que se pagara la orden debe ser numérico y si se ingresan decimales deberá de contar con máximo 8 |
| 1355 | El total ingresado en CRIPTOMONEDA, es decir en la criptomoneda con la que se pagara la orden debe ser numérico y si se ingresan decimales deberá de contar con máximo 8 |
| 1322 | Es necesario ingresar al menos un producto o un servicio al carrito de compras con cantidad mayor a 0 |
| 1616 | Los productos deben ingresarse en el formato adecuado |
| 1617 | Los servicios deben ingresarse en el formato adecuado |
| 1323 | El código de moneda ingresado no es soportado en la plataforma (código de moneda incorrecto) |
| 1324 | El cliente al que se asignara la orden no existe (código de cliente incorrecto) |
| 1610 | El total ingresado en moneda FIAT, es decir en MXN (Peso mexicano) debe ser numérico y si se ingresan decimales deberá de contar con máximo 2 |
| 1611 | El total ingresado en moneda FIAT, es decir en MXN (Peso mexicano) debe ser numérico y si se ingresan decimales deberá de contar con máximo 2 |
| 1612 | El total ingresado en CRIPTOMONEDA, es decir en la criptomoneda con la que se pagara la orden debe ser numérico y si se ingresan decimales deberá de contar con máximo 8 |
| 1613 | El total ingresado en CRIPTOMONEDA, es decir en la criptomoneda con la que se pagara la orden debe ser numérico y si se ingresan decimales deberá de contar con máximo 8 |
| 1361 | Uno o más de los servicios agregados al carrito de compras no tiene precio fijo MXN, es necesario ingresar el total de la orden manualmente ya sea en FIAT o CRIPTO y cambiar el tipo de orden a valor 1 |
| 1362 | Es necesario ingresar al menos un producto o un servicio al carrito de compras con cantidad mayor a 0 |
| 1621 | Alguno de los servicios ingresados en el carrito de compras no cumple con el formato correcto en la cantidad enviada, este valor debe de ser numérico y con un máximo de 8 decimales para los valores que no sean enteros |
| 1622 | Alguno de los productos ingresados en el carrito de compras no cumple con el formato correcto en la cantidad enviada, este valor debe de ser numérico y con un máximo de 8 decimales para los valores que no sean enteros |
| 1326 | El Token API no es correcto y la autenticación del usuario ha fallado |
| 1327 | Ocurrió un problema y no es posible crear la nueva orden, inténtelo nuevamente o consulte con soporte técnico para más ayuda |
| 1620 | Ocurrió un problema y no es posible crear la nueva orden, inténtelo nuevamente o consulte con soporte técnico para más ayuda |
Ejemplo de respuesta EXITOSA
Código HTTP 200
{
"status": true,
"success": {
"code": "0057"
},
"data": {
"code_customer": "pgbcus56777697528357625",
"code_agent": null,
"code_user": "MB-29263565",
"code_currency": "PBT",
"name_currency": "PesoBits",
"code_shop": "pgbsho44747793463129176",
"commission_percent": "1.00000000",
"total": "214.28571428",
"subtotal": "212.14285713",
"commission": "2.14285715",
"total_mxn": "600.00",
"subtotal_mxn": "594.00",
"commission_mxn": "6.00",
"amount_remaining": "214.29",
"currency_rate": "2.80",
"cart": {
"products": [
{
"code": "pgbpro9777846867311479",
"name": "Vela de vainilla grande",
"qty": "4",
"price_mxn": "150.00000000"
}
],
"services": []
},
"cart_total_mxn": "600.00",
"cart_total_cripto": "214.28571428",
"can_create": -1,
"concept": null
}
}
Descripción de la respuesta
- Revisar el listado de
códigos EXITOSOpara conocer el significado desuccesscode. data- muestra la información de la orden calculada (no se ha generado ninguna orden aun)code_customer- Código del cliente al que pertenecería la orden de ventacode_agent- Código del agente de ventas al que pertenecería la orden de venta, si la orden no tiene asignado un agente de ventas se mantendra este campo con valor nullcode_user- Código del usuario principal dueño de la cuenta de AceptaBits (Es el mismo código de usuario de MercadoBits)code_currency- Muestra el código de la moneda con la que se debe de pagar la orden de ventaname_currency- Muestra el nombre de la moneda con la que se debe de pagar la orden de ventacode_shop- Código de la tienda al que pertenecería la orden de ventacommission_percent- Muestra el porcentaje de comisión que la orden pagara a AceptaBits (se utiliza este valor para calcular el campocommission)total- Muestra la cantidad total a pagar de la orden de ventasubtotal- Muestra la cantidad que recibirá el vendedor una vez la orden este pagadacommission- Muestra la comisión que el vendedor pagara a AceptaBits una vez que la orden este pagadatotal_mxn- Muestra una representación del campototalen MXN (Peso mexicano)subtotal_mxn- Muestra una representación del camposubtotalen MXN (Peso mexicano)commission_mxn- Muestra una representación del campocommissionen MXN (Peso mexicano)amount_remaining- Muestra la cantidad restante que faltaría por pagar en la orden (como es una orden calculada se muestra el mismo valor que total)currency_rate- Muestra el tipo de cambio de la criptomoneda que se utilizo en la orden, se expresa en MXN (Peso mexicano)cart- muestra el carrito de compras que se va a generar en la ordenproducts- arreglo que contiene los productos ingresados en el carritocode- Muestra el código del productoname- Muestra el nombre del productoqty- Indica la cantidad del productoprice_mxn- Muestra el precio unitario en MXN (Peso mexicano) del producto
services- arreglo que contiene los servicios ingresados en el carritocode- Muestra el código del servicioname- Muestra el nombre del servicioqty- Indica la cantidad del servicioprice_mxn- Muestra el precio unitario en MXN (Peso mexicano) del servicio
cart_total_mxn- muestra el total en MXN (Peso mexicano) de todos los elementos ingresados en el carrito de compras (es la sumatoria de cada producto y/o servicio, utilizando su precio unitario X la cantidad ingresada)cart_total_cripto- Es el equivalente del campocart_total_mxnen la criptomoneda con la que se pretende pagar la ordenconcept- Muestra el concepto que se le asignará a la orden de venta, si no se le asigna ningún concepto este campo se mantendrá con valor nullcan_create- Este campo indica si la orden se puede crear sin problema o no, los valores posibles son:- 0 = no se puede crear la orden (el total de la orden siempre debe de ser mayor a 0)
- -1 = la orden se puede crear sin problema
Total, Subtotal y Comisión:
En la orden podrás observar un campo llamado total, este campo es la combinación del campo subtotal y commission, es decir, el campo total es la suma del campo subtotal y el campo commission, este valor es el total que se deberá de depositar en la orden para que se considere pagada, como observación adicional, el valor que aparece en este campo es el valor que se ingresó como total al momento de generar la orden
El campo subtotal es la cantidad que recibirá el vendedor una vez que la orden este pagada, es decir, es la cantidad restante que se obtiene como resultado de quitar la comisión de AceptaBits al Total de la orden, es importante señalar que si existe un excedente en la orden cuando ya se ha pagado (se depositó de más o se pagó de más) se le entregara al vendedor, el único monto que obtiene AceptaBits es el mostrado en el campo comission.
El campo comission representa la cantidad que la orden destinara como comisión por el uso del servicio a AceptaBits, este valor se calcula tomando el porcentaje de comisión (que es del 1% actualmente) y extrayendo dicho porcentaje del monto encontrado en el campo total de la orden, ya sea que se haya ingresado manualmente en la criptomoneda, manualmente en moneda FIAT y después convertido a la criptomoneda o calculado usando el carrito de compras, ejemplo, si la orden se generó por un total de 200 PesoBits (PBT), entonces la comisión será de 2 PesoBits (PBT), puedes consultar el porcentaje actual de comisión utilizando el método: get-commission_percent
Carrito de compras:
Como ya se ha mencionado con anterioridad, las órdenes de venta necesitan por lo menos un producto o un servicio para poder generarse, estos productos y servicios se encuentran en el campo cart que es el carrito de compras, a diferencia del método add-order, en este campo se encuentran separados por dos arreglos, uno para los productos agregados y otro para los servicios agregados, una vez la orden se genera el campo cart pasa a ser un solo arreglo donde se incluyen todos los productos y/o servicios utilizados,
Cada elemento dentro del carrito de compras esta compuesto de la siguiente estructura:
code- Muestra el código del producto o el servicioname- Muestra el nombre del producto o servicioqty- Indica la cantidad del producto o servicioprice_mxn- Muestra el precio unitario en MXN (Peso mexicano) del producto o servicio
Algunas cosas a tener en consideracion:
- El método calculate-order como ya se ha mencionado no genera ninguna orden de venta, es un método meramente informativo para revisar la información de una orden antes de ser creada,
- No utilices este método para mostrar la información de pago a tu cliente, ya que no consta del elemento más importante que es la dirección de depósito
- utiliza únicamente este método para apoyarte antes de crear una orden de venta si así lo requieres
Ejemplo de respuesta FALLIDA
Código HTTP 400, Código HTTP 401, Código HTTP 500
{
"status": false,
"error": {
"code": "1352"
}
}
Descripción de la respuesta
- Revisar el listado de
códigos ERRORpara conocer la causa y saber cómo corregir - Si se obtiene un código HTTP
500comunicarse a soporte técnico - Si se obtiene un código HTTP
401revisar que el Token API este correcto
Si tienes alguna duda recuerda que siempre puedes contactar con el equipo de soporte para desarrolladores ingresando en el siguiente enlace: Soporte para desarrolladores.