add-order (modo normal)
Este método se utiliza para crear una nueva orden de venta, no existe un límite y se pueden crear tantas órdenes como lo requiera el usuario, este tipo de orden se considera como orden de pago en una sola exhibición, es decir, se genera la orden y sé espera a que se pague en su totalidad (ya sea un solo pago o pagos parciales) para ser considerada una orden pagada
Las órdenes recién creadas no contienen una dirección de depósito y no tiene configurado su fecha y hora de expiración, por lo que pueden quedar almacenadas sin ningún problema y tampoco se tendrá la preocupación de que vayan a expirar, esto pasara únicamente hasta el momento en que ya se decida abrirla para el cliente.
El termino abrir una orden para el cliente significa que una orden ya está lista para mostrarla al cliente final y que pueda realizar el pago, para esto se hará uso del método show-order-customer, una vez que este método sea ejecutado la orden generara su respectiva dirección de depósito a la cual el cliente deberá de depositar el total de la misma para poder pagarla, así mismo, se iniciara la cuenta regresiva para que la orden expire, a menos claro, que se realice el pago de la misma, ya sea el pago completo o un pago parcial (si es un pago parcial, es decir, que se deposite una parte del total de la orden, esta quedara en espera de completar el pago total de la orden y por lo tanto ya no expirara).
Para más información y la documentación completa del método ingresa en el siguiente enlace: show-order-customer.
Este método utiliza la misma estructura que el método calculate-order, con la diferencia de que al ejecutar este método se creara una nueva orden de venta, mientras que calculate-order retornara los datos como si se hubiera creado.
Por lo tanto, calculate-order será de mucha utilidad para revisar los datos finales de una orden de venta antes de crearla, por ejemplo, para revisar el total de la orden, la comisión que se cobrará, el cliente al que se asignó, el carrito de compras, etc.
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.
Para más información y la documentación completa del método ingresa en el siguiente enlace: calculate-order.
Path del método
add-order
Endpoint final
PRODUCCION
https://aceptabits.com/api/thirdparty/v1/add-order
SANDBOX DE PRUEBAS
https://sandbox.aceptabits.com/api/thirdparty/v1/add-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 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 deberán enviar maximo 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 métodos 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 numero 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 podras 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 ingersar en la sección de Ejemplos de la presente documentación
Lista de codigos
| código | Descripción |
|---|---|
| 0056 | Orden creada 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": "0056"
},
"data": {
"code": "pgbord116575637177886769",
"address": null,
"slug": "24f2bfa1256ce75c39097f2b85dd7bb9840bf2080y4c0F4wY2XsFmzgrkRu",
"amount_filled": "0.00000000",
"amount_remaining": "285.71071428",
"amount_unconfirmed": "0.00000000",
"code_customer": "pgbcus56777697528357625",
"name_customer": "Mario Chavez Alvarez",
"code_agent": null,
"name_agent": null,
"code_shop": "pgbsho44747793463129176",
"name_shop": "Velas martin",
"code_currency": "PBT",
"currency_full_name": "PesoBits (PBT)",
"name_currency": "PesoBits",
"confirmations_counter": "0",
"remaining_seconds": null,
"created_at": "2024-08-14T23:36:09.000000Z",
"created_at_format": "2024-08-14 17:36:09",
"expiration_date": null,
"expiration_date_format": null,
"isConfirming": "0",
"isExpired": "0",
"isPaid": "0",
"isWaiting": "0",
"code_blockchain": null,
"name_blockchain": null,
"total": "285.71071428",
"subtotal": "282.85360713",
"commission": "2.85710715",
"commission_percent": "1.00000000",
"total_mxn": "799.99000000",
"subtotal_mxn": "791.99000000",
"commission_mxn": "8.00000000",
"cart": [
{
"quantity": "4.00000000",
"total_mxn": "600.00000000",
"name_product": "Vela de vainilla grande",
"code_product": "pgbpro9777846867311479",
"name_service": null,
"code_service": null
},
{
"quantity": "1.00000000",
"total_mxn": "199.99000000",
"name_product": "Vela para decoración roma",
"code_product": "pgbpro6788273824117159",
"name_service": null,
"code_service": null
}
],
"concept": "Pedido no. 1696",
"type_payment_periodic": "1"
}
}
Descripción de la respuesta
- Revisar el listado de
códigos EXITOSOpara conocer el significado desuccesscode. data- muestra la información de la orden recién creadacode- Código de la orden (este código es único para cada orden dada de alta)address- Muestra la dirección de depósito de la orden, si no se ha mostrado la orden al cliente con el método show-order-customer, este campo se mantendrá con valor nullslug- Este es el identificador web de la orden (este slug es único para cada orden dada de alta, se utiliza para formar la URL de pago que se puede compartir al cliente)amount_filled- Muestra la cantidad obtenida de la orden, se va actualizando cada vez que se realiza un pago a la ordenamount_remaining- Muestra la cantidad restante que falta por obtener en la orden, se va actualizando cada vez que se realiza un pago a la ordenamount_unconfirmed- Muestra la cantidad obtenida que aún no ha completado las confirmaciones de red (en caso de que el pago no provenga de un usuario de MercadoBits, es decir de una wallet externa, si es así debera de completar las confirmaciones de red para poder reflejarse en el campoamount_filled, si el pago proviene de un usuario de MercadoBits se vera reflejado inmediatamente en el campoamount_filled)code_customer- Código del cliente al que pertenece la orden de ventaname_customer- Nombre del cliente al que pertenece la orden de ventacode_agent- Código del agente de ventas al que pertenece la orden de venta, si la orden no tiene asignado un agente de ventas se mantendrá este campo con valor nullname_agent- Nombre del agente de ventas al que pertenece la orden de venta, si la orden no tiene asignado un agente de ventas se mantendrá este campo con valor nullcode_shop- Código de la tienda al que pertenece la orden de ventaname_shop- Nombre de la tienda al que pertenece la orden de ventacode_currency- Muestra el código de la moneda con la que se debe de pagar la orden de ventacurrency_full_name- Muestra el nombre completo de la moneda con la que se debe de pagar la orden de venta (incluye nombre y código de moneda)name_currency- Muestra el nombre de la moneda con la que se debe de pagar la orden de ventaconfirmations_counter- Muestra las confirmaciones restantes para liberar elamount_unconfirmedremaining_seconds- Muestra la diferencia de tiempo hasta su fecha y hora de expiracion en segundos, si no se ha mostrado la orden al cliente con el metodo show-order-customer, este campo se mantendrá con valor nullcreated_at- Fecha y hora de creación de la orden (UTC)created_at_format- Fecha y hora de creación de la orden (America/Mexico_City)expiration_date- Fecha y hora de expiración de la orden (America/Mexico_City), si no se ha mostrado la orden al cliente con el metodo show-order-customer, este campo se mantendrá con valor nullexpiration_date_format- Fecha y hora de expiración de la orden (UTC), si no se ha mostrado la orden al cliente con el método show-order-customer, este campo se mantendrá con valor nullisConfirming- indica si la orden tiene algún pago nativo recibido y esta esperando las confirmaciones de red, los valores posibles son:- 0 = no está esperando confirmaciones de red
- -1 = si está esperando confirmaciones de red
isExpired- indica si una orden ha expirado, los valores posibles son:- 0 = no ha expirado
- -1 = ya ha expirado
isPaid- indica si una orden ya ha sido pagada en su totalidad, los valores posibles son:- 0 = la orden aún no ha sido pagada en su totalidad
- -1 = la orden ya se ha pagado en su totalidad
isWaiting- indica si la orden está en espera de ser liquidada completamente, los valores posibles son:- 0 = la orden no ha recibido ningún pago o se ha pagado en su totalidad
- -1 = la orden recibió por lo menos un pago y está en espera de ser liquidada completamente
code_blockchain- Indica el codigo del blockchain utilizado en la moneda que se selecciono en la orden (null si es para una moneda con blockchain nativo que no requiere espeficiar algun tipo de red extra, o con un valor si es una moneda tipo token)name_blockchain- Indica el nombre del blockchain utilizado en la moneda que se seleccionó en la orden (null si es para una moneda con blockchain nativo que no requiere especificar algún tipo de red extra, o con un valor si es una moneda tipo token)total- Muestra la cantidad total a pagar de la orden de ventasubtotal- Muestra la cantidad que recibirá el vendedor una vez la orden este pagada (si existe excedente, es decir que se pague de mas, el vendedor recibirá también el excedente, el único monto que pasa a formar parte de AceptaBits es el mostrado en el campocommission)commission- Muestra la comisión que el vendedor pagara a AceptaBits una vez que la orden este pagadacommission_percent- Muestra el porcentaje de comisión que la orden pagara a AceptaBits (se utiliza este valor para calcular el campocommission)total_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)cart- arreglo que contiene el carrito de compras de la orden, cada elemento dentro de este arreglo es un producto o servicio agregadoquantity- indica la cantidad del producto o serviciototal_mxn- muestra el total del presente elemento del carrito de compras expresado en MXN (Peso mexicano), se calcula de la siguiente manera:quantityXel precio en MXN del producto o servicioname_product- Muestra el nombre del producto, si el elemento es un servicio este campo se mantendrá con valor nullcode_product- Muestra el código del producto, si el elemento es un servicio este campo se mantendrá con valor nullname_service- Muestra el nombre del servicio, si el elemento es un producto este campo se mantendrá con valor nullcode_service- Muestra el código del servicio, si el elemento es un producto este campo se mantendrá con valor null
concept- Muestra el concepto que se le asigno a la orden de venta, si no se le asigno ningún concepto este campo se mantendrá con valor nulltype_payment_periodic- indica que la orden es de tipo normal
Es importante conocer y saber interpretar la combinación de ciertos campos para entender en qué estado se encuentra una orden, por ejemplo, para saber si una orden ya se pagó, si está en espera de confirmaciones de red, si ya expiro, etc., a continuación mostramos estos estados y su respectiva combinación e interpretación de sus respectivos campos:
ESTADO 1: orden recién creada en espera de ser abierta para el cliente: Este estado nos indica que se acaba de crear una orden nueva y está en espera de que sea abierta para el cliente utilizando el método: show-order-customer.
address= nullisPaid= 0isExpired= 0isConfirming= 0isWaiting= 0confirmations_counter= 0amount_filled= 0amount_unconfirmed= 0amount_remaining= tiene el valor del campo total, ejemplo: 100, 0.00056, etcexpiration_date= nullexpiration_date_format= nullremaining_seconds= null
ESTADO 2: orden recién abierta para el cliente: Este estado nos indica que la orden ya fue abierta para el cliente utilizando el método: show-order-customer, en este estado se genera la dirección de depósito y comienza a correr el tiempo hasta su expiración.
address= tiene generada la dirección de depósito, ejemplo: pbtcrt1qjr2fte8wgt0zet9tz9xcgwvjagvchrdea6a4eyisPaid= 0isExpired= 0isConfirming= 0isWaiting= 0confirmations_counter= 0amount_filled= 0amount_unconfirmed= 0amount_remaining= tiene el valor del campo total, ejemplo: 100, 0.00056, etcexpiration_date= tiene el valor de fecha y hora para su expiración, ejemplo: 2024-08-13 13:07:06, se representa en zona horaria America/Mexico_Cityexpiration_date_format= tiene el valor de fecha y hora para su expiración, ejemplo: 2024-08-13T18:07:06.000000Z, se representa en zona horaria UTCremaining_seconds= muestra el tiempo en segundos hasta su fecha y hora de expiración, ejemplo: 185
ESTADO 3: orden con un pago recibido esperando las confirmaciones de red (deposito externo que no proviene de un usuario de MercadoBits): Este estado nos indica que la orden ha recibido un depósito y se encuentra en espera de las confirmaciones de red para acreditar los fondos, en este estado la orden ya no va a expirar y se deberá de ignorar completamente los campos: expiration_date, expiration_date_format y remaining_seconds.
address= tiene generada la dirección de depósito, ejemplo: pbtcrt1qjr2fte8wgt0zet9tz9xcgwvjagvchrdea6a4eyisPaid= 0isExpired= 0isConfirming= -1isWaiting= -1confirmations_counter= muestra las confirmaciones pendientes de red para los depositos que requieren confirmaciones, ejemplo: 5amount_filled= muestra el monto que ya se ha confirmado, ejemplo: 100, 0.00056, etc. (este campo va mostrando la sumatoria de todos los depósitos recibidos confirmados, es decir va mostrando el total de depósitos que ha recibido la orden)amount_unconfirmed= tiene el valor del depósito recibido que está en espera de las confirmaciones de red, ejemplo: 70.52369854amount_remaining= tiene el valor del monto restante para completar el pago, ejemplo: 100, 0.00056, etc.
ESTADO 4: pago parcial recibido que ya a cumplido con las confirmaciones de red (deposito externo que no proviene de un usuario de MercadoBits) Este estado nos indica que la orden ha recibido un depósito parcial y ya se ha completado las confirmaciones de red, en este estado la orden ya no va a expirar y se deberá de ignorar completamente los campos: expiration_date, expiration_date_format y remaining_seconds, así mismo la orden queda en espera de ser pagada completamente.
address= tiene generada la dirección de depósito, ejemplo: pbtcrt1qjr2fte8wgt0zet9tz9xcgwvjagvchrdea6a4eyisPaid= 0isExpired= 0isConfirming= 0isWaiting= -1confirmations_counter= 0 (si aún hay depósitos pendientes por confirmación mostrara las confirmaciones pendientes que aún restan por completarse)amount_filled= muestra el monto que ya se ha confirmado, ejemplo: 100, 0.00056, etc. (este campo va mostrando la sumatoria de todos los depósitos recibidos confirmados, es decir va mostrando el total de depósitos que ha recibido la orden)amount_unconfirmed= 0 (si aún hay depósitos pendientes por confirmación mostrara el monto pendiente que aún falta por confirmarse)amount_remaining= tiene el valor del campo total menos los depósitos ya confirmados, ejemplos: 100, 0.00056, 0, etc. (si ya se pagó en su totalidad este campo mostrara el valor 0)
ESTADO 5: pago completo recibido que ya a cumplido con las confirmaciones de red (deposito externo que no proviene de un usuario de MercadoBits) Este estado nos indica que la orden ha recibido un depósito que liquida en su totalidad la orden y ya se ha completado las confirmaciones de red, en este estado la orden ya no va a expirar y se deberá de ignorar completamente los campos: expiration_date, expiration_date_format y remaining_seconds, así mismo la orden se muestra como pagada completamente.
address= tiene generada la dirección de depósito, ejemplo: pbtcrt1qjr2fte8wgt0zet9tz9xcgwvjagvchrdea6a4eyisPaid= -1isExpired= 0isConfirming= 0isWaiting= 0confirmations_counter= 0amount_filled= muestra el monto que ya se ha confirmado, en este caso el total de la orden, ejemplo: 100, 0.00056, etc. (si la orden tuvo algún excedente se mostrara aquí)amount_unconfirmed= 0amount_remaining= 0
ESTADO 6: pago parcial recibido que no necesita confirmaciones de red (deposito que proviene de un usuario de MercadoBits) Este estado nos muestra un pago parcial recibido proveniente de un usuario de MercadoBits, estos pagos se procesan al instante y no requieren de confirmaciones de red para acreditar los fondos, en este estado la orden ya no va a expirar y se deberá de ignorar completamente los campos: expiration_date, expiration_date_format y remaining_seconds, así mismo la orden queda en espera de ser pagada completamente.
address= tiene generada la dirección de depósito, ejemplo: pbtcrt1qjr2fte8wgt0zet9tz9xcgwvjagvchrdea6a4eyisPaid= 0isExpired= 0isConfirming= 0isWaiting= -1confirmations_counter= 0amount_filled= muestra el monto que ya se ha confirmado, ejemplo: 100, 0.00056, etc. (este campo va mostrando la sumatoria de todos los depósitos recibidos confirmados (en este caso de los depósitos provenientes de usuarios de MercadoBits entran directamente como depósitos confirmados), es decir va mostrando el total de depósitos que ha recibido la orden)amount_unconfirmed= 0amount_remaining= tiene el valor del campo total menos los depósitos ya confirmados, en este caso todos los depósitos que entran ya están confirmados y no necesitan confirmaciones de red, ejemplos: 100, 0.00056, 0, etc. (si ya se pagó en su totalidad este campo mostrara el valor 0)
ESTADO 7: pago completo recibido que no necesita confirmaciones de red (deposito que proviene de un usuario de MercadoBits) Este estado nos indica que la orden ha recibido un depósito que liquida en su totalidad la orden y que no necesita confirmaciones de red, en este estado la orden ya no va a expirar y se deberá de ignorar completamente los campos: expiration_date, expiration_date_format y remaining_seconds, así mismo la orden se muestra como pagada completamente.
address= tiene generada la dirección de depósito, ejemplo: pbtcrt1qjr2fte8wgt0zet9tz9xcgwvjagvchrdea6a4eyisPaid= -1isExpired= 0isConfirming= 0isWaiting= 0confirmations_counter= 0amount_filled= muestra el monto que ya se ha confirmado, en este caso el total de la orden, ejemplo: 100, 0.00056, etc. (si la orden tuvo algún excedente se mostrara aquí)amount_unconfirmed= 0amount_remaining= 0
ESTADO 8: la orden ha expirado Este estado nos muestra una orden que ha expirado, es importante que no se muestren al cliente órdenes ya expiradas, de ser necesario se deberá de generar una orden nueva para que el cliente la pague, en este estado ya no se debe de hacer nada y solamente se deberá de archivar como una orden expirada
address= tiene generada la dirección de depósito, ejemplo: pbtcrt1qjr2fte8wgt0zet9tz9xcgwvjagvchrdea6a4eyisPaid= 0isExpired= -1isConfirming= 0isWaiting= 0confirmations_counter= 0amount_filled= 0amount_unconfirmed= 0amount_remaining= tiene el valor del campo total, ejemplo: 100, 0.00056, etcexpiration_date= tiene el valor de fecha y hora para su expiración, ejemplo: 2024-08-13 13:07:06, se representa en zona horaria America/Mexico_Cityexpiration_date_format= tiene el valor de fecha y hora para su expiracion, ejemplo: 2024-08-13T18:07:06.000000Z, se representa en zona horaria UTCremaining_seconds= 0
Direccion de deposito: EL campo address es la dirección a la que el cliente final deberá de depositar el pago de la orden, esta dirección es única para cada orden generada en AceptaBits, se genera de manera automática al abrir la orden al cliente y no se puede cambiar ni ingresar de manera manual.
Se recomienda al desarrollador mostrarle al cliente esta dirección de manera muy clara y que por ningún motivo pueda ser cambiada, editada o borrada en la pantalla donde sea mostrada, esto con el propósito de minimizar la posibilidad de que un cliente pueda cometer algún error al momento de copiarla o transcribirla y posteriormente ser utilizada en su wallet para realizar el retiro de sus fondos, los fondos enviados a direcciones equivocadas serán responsabilidad del cliente, AceptaBits únicamente recibirá y acreditara fondos de las direcciones que se generen en las órdenes de venta.
Se recomienda al desarrollador mostrar la dirección de manera textual y también mostrarla en forma de código QR, estos códigos QR son muy cómodos y ampliamente utilizados en muchas plataformas al brindarle a sus usuarios la posibilidad de escanearlos para obtener de manera fácil una dirección de depósito, en AceptaBits hacemos uso de ellos para mostrar la dirección de depósito en las órdenes de venta, así mismo, brindamos a nuestros usuarios su respectivo escáner QR tanto en la página web como en la app para dispositivos móviles.
Montos en espera de confirmación por parte de la red:
Los montos que se depositen en la dirección de la orden y que provengan de una wallet externa que no sea la de MercadoBits quedaran en espera de las respectivas confirmaciones de red para cada criptomoneda, el número de confirmaciones podrá ser consultado con el método: get-payment-data.
Una vez que se reciba un depósito de esta naturaleza se actualizara el campo amount_unconfirmed con la cantidad depositada y también se actualizara el campo confirmations_counter, una vez pasadas las confirmaciones de red se actualizarán los campos de amount_filled con la cantidad ya liberada y el campo confirmations_counter con valor 0, tomando esto en cuenta veamos un par de ejemplos:
Ejemplo 1: supongamos que se recibe un pago de 0.00050000 BTC, en este caso el campo amount_unconfirmed quedara con el valor 0.00050000 y el campo confirmations_counter quedara con las confirmaciones requeridas en ese momento, por ejemplo: 6.
Ejemplo 2: Tomando el ejemplo anterior, supongamos que se recibe otro pago de 0.0006000 BTC, entonces el campo amount_unconfirmed quedara con el valor 0.00110000, esto es debido a que se suma la cantidad del primer deposito con este nuevo depósito, y que pasa con el campo confirmations_counter?, bueno en este caso se volverá a actualizar con las confirmaciones requeridas, por ejemplo: 6.
Ahora tomando en cuenta los dos ejemplos anteriores, supongamos que al primer deposito le quedaban solo 3 confirmaciones, esto no significa que deberá de esperar nuevamente las 6 confirmaciones para que ese monto se libere, conforme pasen las confirmaciones que originalmente requería se ira liberando y por lo tanto el campo amount_unconfirmed se ira actualizando, tomando este ejemplo, al pasar las 3 confirmaciones que requería el primer deposito el campo amount_unconfirmed quedaría con el valor 0.0006000 que viene siendo el monto del segundo deposito que aun está en espera de confirmarse, así mismo los montos que se van liberando también van actualizando el campo amount_filled, que en este caso quedaría con valor 0.00050000, ahora una vez que el segundo deposito sea confirmado completamente, el campo amount_unconfirmed quedaría con valor 0, el campo amount_filled quedaría con valor 0.00110000 y el campo confirmations_counter quedaría con valor 0.
Es importante saber cómo funcionan los depósitos que no provienen de usuario de MercadoBits, si no de wallets externas, ya sea otro exchange o alguna wallet nativa
Como nota final acerca de las confirmaciones de red, se debe de mencionar que se incrementa en 1 el número de confirmaciones mostradas en get-payment-data, esto es debido a que el contador comienza una vez que la transacción ha entrado a su primer bloque, por ejemplo: si se requieren 6 confirmaciones de red para Bitcoin (BTC), entonces al momento de recibir el pago se mostrara el campo confirmations_counter con valor igual a 7, es decir, las 6 confirmaciones que requiere AceptaBits + 1 confirmación que en realidad es el bloque en que entra la transacción al blockchain, este incremento +1 aplica para todos las monedas soportadas en la plataforma y a medida que se van procesando los bloques en el blockchain el valor del campo confirmations_counter ira disminuyendo (cada bloque confirmado disminuirá en 1 este campo contador).
Depósitos que provienen de usuarios de MercadoBits:
Los depósitos a la dirección de la orden que provengan de usuarios de MercadoBits (ya sea desde la web o desde la app) no pasan por el proceso de confirmaciones de red, estos depósitos se procesan de manera inmediata, por lo que veras actualizado directamente el campo amount_filled.
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 (ya sea que se ingresó manualmente en la criptomoneda, manualmente en FIAT y después convertido a la criptomoneda o calculado directamente usando el carrito de compras).
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 pagada (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 ingresan en el campo cart que es el carrito de compras (viene siendo un arreglo con X número de elementos), aquí encontraras todos los productos y servicios que se ingresaron, es decir, si se ingresó un solo producto o servicio, el carrito de compras tendrá solamente 1 elemento, si se ingresaron 3 productos o 3 servicios entonces el carrito tendrá 3 elementos y así sucesivamente.
Cada elemento está compuesto de la siguiente estructura:
quantity- indica la cantidad del producto o serviciototal_mxn- muestra el total del presente elemento del carrito de compras expresado en MXN (Peso mexicano), se calcula de la siguiente manera:quantityXel precio en MXN del producto o servicioname_product- Muestra el nombre del producto, si el elemento es un servicio este campo se mantendrá con valor nullcode_product- Muestra el código del producto, si el elemento es un servicio este campo se mantendrá con valor nullname_service- Muestra el nombre del servicio, si el elemento es un producto este campo se mantendrá con valor nullcode_service- Muestra el código del servicio, si el elemento es un producto este campo se mantendrá con valor null
Como explicación especial, ya que podría resultar confuso, hablemos del campo total_mxn, pero antes de entrar en detalles, recordemos que al momento de dar de alta un producto o un servicio se ingresa su precio en MXN (Peso mexicano), recordando también que en el caso de los servicios este precio puede omitirse, es decir que valga $0.00 MXN.
Teniendo esto en cuenta y ahora si entrando en detalles del campo total_mxn, basta con mencionar que este campo es el monto total expresado en MXN del producto o servicio que tenga ese elemento en el carrito, se calcula utilizando la cantidad ingresada del producto o servicio mostrado en el campo quantity y multiplicándola por el precio que tenga dicho producto o servicio, por ejemplo, supongamos que se agrega al carrito el producto calculadora de mano con un precio unitario es de $100.00 MXN y se vendieron 2 unidades, es decir quantity igual a 2, por lo tanto total_mxn sería igual a $200.00 MXN (En el caso de servicios que no tienen precio fijo MXN, es decir que tengan como precio $0.00, el valor del campo total_mxn siempre será 0).
La lógica anterior aplica para todos los elementos que se encuentren dentro del arreglo del carrito de compras, recordando que cada elemento es independiente uno del otro, es decir por cada producto o servicio diferente agregado al carrito se mostrara dicha información, llámese producto o servicio diferente a todo aquel producto o servicio que tiene su código de identificación diferente a otro, no a la cantidad ingresada del producto o servicio, por ejemplo, en la lógica de programación del desarrollador, puede ser que un cliente seleccione una calculadora de mano, y después de seguir explorando y al haber agregado otros productos decida que en realidad quiere 2 calculadoras de mano, bueno en este caso las dos calculadoras de mano no representan dos elementos diferentes dentro del carrito de compras, si no un solo elemento dentro del carrito de compras con un quantity igual a 2.
Para finalizar con el carrito de compras, es importante mencionar que la información de carrito de compras es meramente informativa, ya que recordemos que al momento de crear una orden podemos elegir si ingresamos el total de manera manual o utilizamos el valor de los productos y/o servicios para hacer el cálculo del total, para más información sobre como ver la información del cálculo de una orden antes de crearla ingresa a la documentación del método: calculate-order
Campo remaining_seconds:
Este campo muestra la diferencia de tiempo hasta su fecha y hora de expiración expresado en segundos, por lo tanto cada vez que consultes la información de una orden que ya ha sido abierta para el cliente este campo tendrá un valor diferente, esto es debido a que el tiempo sigue corriendo, recomendamos al desarrollador apoyarse de este campo para mostrar un temporizador descendente al cliente para indicarle cuanto tiempo le queda para pagar.
Una vez que se ha recibido por lo menos un pago en la orden, este temporizador ya no tendrá importancia, esto es debido a que las órdenes que reciban por lo menos un pago ya no expiraran y quedaran abiertas de manera indefinida hasta que se pague la orden en su totalidad, aplica tanto para depósitos que requieren confirmaciones de red o pagos instantáneos de usuarios de MercadoBits.
Para los pagos que requieren confirmaciones de red, se considera que la orden recibió un pago desde el momento en que se detectó el depósito, por lo tanto, la fecha de expiración y por ende el temporizador segundero dejaran de tener importancia, aunque tarde 1 o 2 horas en completarse las confirmaciones de red, esto por menciona un ejemplo.
SLUG para navegadores web:
Las órdenes generan un código especial llamado slug, este código podremos encontrarlo en el campo que tiene el mismo nombre slug, la función de este código es para que una orden de venta sea abierta para el cliente desde un navegador web, para ellos utilizaremos la siguiente estructura:
https://aceptabits.com/order/ + el slug de la orden
tomando de ejemplo el slug que podemos observar en el Ejemplo de respuesta EXITOSA, la url que compartirías a tu cliente para que pueda realizar el pago de la orden es el siguiente:
https://sandbox.aceptabits.com/order/24f2bfa1256ce75c39097f2b85dd7bb9840bf2080y4c0F4wY2XsFmzgrkRu
Una vez que el cliente ingrese a la url podrá observar la información de la orden, su dirección de depósito y el respectivo contador de tiempo hasta su expiración, a menos claro, que realice por lo menos un depósito a la orden.
Esta misma url es la que podemos obtener desde el panel principal de órdenes en la cuenta de AceptaBits al presionar el botón Copiar URL cuando se seleccionar una orden desde el listado de órdenes.
Algunas cosas a tener en consideración:
- Una orden se considera abierta para el cliente cuando se ha utilizado el método: show-order-customer, al ejecutar este método se genera la dirección de depósito y comienza la cuenta regresiva hasta que la orden expire
- Evita mostrar a tus clientes órdenes ya expiradas
- Las órdenes que reciban por lo menos un pago ya no expiraran y quedaran abiertas indefinidamente hasta que la orden sea pagada en su totalidad
- Los depósitos realizados a la orden que provengan de usuarios de MercadoBits (ya sea desde la web o la app) se verán reflejados de manera inmediata
- Los depósitos que provienen fuera de MercadoBits, es decir, que depositen a la dirección de la orden desde otro exchange u otra wallet tendrán que esperar las respectivas confirmaciones de red para liberar los fondos
- Apóyate con los campos *expiration_date, expiration_date_format o remaining_seconds para mostrar a tu cliente cuanto tiempo le queda para pagar o hacer un pago parcial antes de que la orden expire
- Si tienes alguna situación especial con alguna orden no dudes en comunicarte con el equipo de soporte
- Una vez que la orden se pague completamente se demorara un par minutos para que AceptaBits deposite los fondos a la wallet del usuario en su cuenta de MercadoBits, recordemos que el usuario principal de AceptaBits tiene su cuenta en MercadoBits y ahí es a donde los fondos de cada orden pagada serán depositados
Ejemplo de respuesta FALLIDA
Código HTTP 400, Código HTTP 401, Código HTTP 500
{
"status": false,
"error": {
"code": "1323"
}
}
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.