Crear Facturas de Bitcoin: Guía Técnica Esencial

En el creciente mundo de las finanzas digitales, aceptar pagos en criptomonedas como Bitcoin se ha convertido en una ventaja competitiva para muchos negocios. Sin embargo, para hacerlo de manera profesional y escalable, no basta con compartir una dirección de wallet. Es fundamental generar facturas claras y automatizadas. Este proceso, aunque técnico, es accesible a través de servicios como BitPay, que ofrecen una API robusta para la creación y gestión de facturas de criptomonedas. En esta guía completa, desglosaremos el proceso técnico para crear una factura de Bitcoin, explorando cada parámetro y opción disponible para que puedas integrar esta funcionalidad en tu sistema de manera eficiente y segura.

Fundamentos de la Creación de Facturas con la API

El método principal para crear una factura de Bitcoin a través de BitPay es mediante una solicitud HTTP POST al endpoint bitpay.com/invoices. Esta solicitud no es un simple formulario; debe contener un cuerpo de mensaje con los detalles de la factura codificados en formato JSON. Para que el servidor de BitPay procese correctamente tu solicitud, es crucial incluir encabezados HTTP específicos:

• content-type: Debe establecerse en application/json para indicar que el cuerpo de la solicitud está en formato JSON.
• x-accept-version: Debe tener el valor 2.0.0 para asegurar que estás utilizando la versión correcta de la API.

Si la solicitud se procesa con éxito, el servidor responderá con un objeto JSON que contiene todos los detalles de la factura recién creada. En caso de error, la respuesta también será un objeto JSON, pero contendrá un campo de error con detalles sobre el tipo y el mensaje del problema. Es importante tener en cuenta que existen límites de uso: un comerciante no puede crear más de 100 facturas por hora, además de otros límites por segundo y minuto para evitar el abuso del sistema.

Campos Obligatorios: La Base de tu Factura

Para que una factura sea válida, hay ciertos campos que son absolutamente indispensables. Sin ellos, la API rechazará la solicitud. Estos campos constituyen la información mínima necesaria para definir una transacción.

Parámetro	Descripción
price	Este es el monto que se debe cobrar al comprador. Un aspecto muy útil es que puedes especificar este valor en una moneda fiduciaria (como USD o EUR) y BitPay lo convertirá automáticamente a Bitcoin (BTC) utilizando las tasas de cambio del mercado en ese momento.
currency	Es el código de la moneda en la que se ha establecido el parámetro price. BitPay admite una amplia gama de divisas, incluyendo USD, EUR, BTC y muchas otras que se pueden consultar en su página de tasas de cambio.
token	Este es tu token de API, una clave secreta que autentica tus solicitudes. Puedes obtener este token desde tu panel de control de comerciante en BitPay o generarlo mediante la propia API REST. Es tu llave de acceso al servicio.

Personalización Avanzada: Campos Opcionales para una Mejor Experiencia

Más allá de los campos básicos, la API de BitPay ofrece una gran cantidad de parámetros opcionales que te permiten personalizar el flujo de pago, recibir notificaciones automáticas y mejorar la experiencia tanto para ti como para tu cliente.

Notificaciones de Pago Instantáneas (IPN)

Las Notificaciones de Pago Instantáneas (IPN), también conocidas como webhooks, son esenciales para la automatización. Permiten que el servidor de BitPay envíe una notificación a una URL tuya cada vez que el estado de una factura cambia (por ejemplo, cuando se paga).

• posData: Esta es una variable de paso (passthru). Su contenido no es procesado por BitPay, sino que se te devuelve intacto en las notificaciones. Es extremadamente útil para correlacionar la factura de BitPay con un pedido o un cliente en tu propio sistema. Por ejemplo, podrías enviar un objeto JSON como: '{ "ref": 711454, "affiliate": "spring112" }'.
• notificationURL: Aquí especificas la URL de tu servidor a la que BitPay enviará las notificaciones POST. Es obligatorio que esta URL utilice el protocolo HTTPS para garantizar la seguridad de los datos.
• transactionSpeed: Este es un parámetro de gestión de riesgo crucial. Define cuántas confirmaciones en la blockchain se requieren antes de que consideres la factura como "confirmada" y procedas a entregar el producto o servicio. Las opciones son:
  • high: La factura se considera confirmada inmediatamente después de recibir el pago (0 confirmaciones). Es más rápido pero menos seguro.
  • medium: Se espera 1 confirmación de bloque (aproximadamente 10 minutos para Bitcoin). Ofrece un buen equilibrio entre velocidad y seguridad.
  • low: Se esperan 6 confirmaciones de bloque (aproximadamente 60 minutos para Bitcoin). Es la opción más segura, ideal para transacciones de alto valor.

Gestión del Flujo del Pedido y Redirecciones

Puedes controlar a dónde se dirige el comprador después de interactuar con la factura, lo que mejora la experiencia de usuario y la integración con tu tienda online.

• redirectURL: La URL a la que el comprador será redirigido después de completar un pago con éxito.
• closeURL: La URL a la que el comprador será redirigido si decide no pagar y hace clic en el botón de cerrar la factura.
• autoRedirect: Por defecto es false. Si lo estableces en true, el comprador será redirigido automáticamente a la redirectURL al pagar, o a la closeURL si la factura expira. Si activas esta opción, el campo redirectURL se vuelve obligatorio.

Información Adicional y Datos del Comprador

Para una mejor contabilidad y personalización, puedes incluir información adicional en la factura.

• orderId: Un identificador interno de tu sistema para asociarlo a la factura de BitPay.
• itemDesc: Una breve descripción del artículo o servicio, que se mostrará en la página de pago de BitPay.
• Buyer object: Un objeto JSON que puede contener información detallada del comprador, como name, address1, address2, locality, region, postalCode, country, email y phone.

Interpretando la Respuesta del Servidor de BitPay

Una vez que envías tu solicitud POST, recibirás una respuesta JSON detallada. Comprender esta respuesta es clave para manejar la factura correctamente. Aquí desglosamos algunos de los campos más importantes del objeto de respuesta:

• url: La URL de pago que debes presentar a tu cliente. Al visitar esta página, verá las opciones para pagar la factura.
• status: El estado inicial de la factura, que generalmente es "new".
• id: El identificador único de la factura en el sistema de BitPay.
• invoiceTime y expirationTime: Marcas de tiempo (timestamps) en milisegundos que indican cuándo se creó la factura y cuándo expirará (normalmente después de 15 minutos).
• price y currency: El precio y la moneda que estableciste en tu solicitud.
• paymentTotals: Un objeto que muestra el monto a pagar desglosado en las diferentes criptomonedas soportadas, expresado en su unidad mínima (por ejemplo, satoshis para BTC).
• paymentDisplayTotals: Similar al anterior, pero muestra los montos en un formato legible para el ser humano (ej. "0.000296" BTC).
• exchangeRates: Un objeto muy completo que detalla todas las tasas de cambio utilizadas por BitPay en el momento de la creación de la factura entre las diferentes criptomonedas y monedas fiduciarias.
• token: Un token único para esta factura específica, que se puede usar para recuperarla más tarde mediante una solicitud GET.

Esta rica respuesta te proporciona toda la información necesaria para mostrar los detalles del pago al cliente y para rastrear el estado de la factura en tu sistema.

Preguntas Frecuentes (FAQ)

¿Qué necesito para empezar a crear facturas de Bitcoin con BitPay?

Para comenzar, necesitas una cuenta de comerciante en BitPay. Una vez que la tengas, deberás generar un token de API desde tu panel de control. Este token es la clave que te autenticará al comunicarte con la API.

¿Puedo establecer el precio en mi moneda local en lugar de BTC?

Sí, y de hecho es la práctica recomendada. Puedes especificar el price en USD, EUR u otra moneda fiduciaria soportada, y BitPay se encargará de calcular el monto equivalente en Bitcoin y otras criptomonedas en tiempo real, protegiéndote de la volatilidad de precios.

¿Qué es `transactionSpeed` y por qué es importante?

Es un parámetro de gestión de riesgo que define cuántas confirmaciones de bloque se deben esperar antes de considerar el pago como finalizado. Una velocidad 'alta' (0 confirmaciones) es más rápida pero susceptible a riesgos como el doble gasto, mientras que una velocidad 'baja' (6 confirmaciones) es mucho más segura pero más lenta. La elección depende del valor de la transacción y tu tolerancia al riesgo.

¿Qué pasa si hay un error al crear la factura?

Si tu solicitud POST tiene algún problema (por ejemplo, falta un campo obligatorio o el JSON está mal formado), la API de BitPay no devolverá una factura. En su lugar, recibirás una respuesta JSON con un objeto error que contendrá un type y un message descriptivo para ayudarte a depurar el problema.

¿Hay un límite en la cantidad de facturas que puedo crear?

Sí, BitPay impone límites de tasa para prevenir el abuso del servicio. Generalmente, un comerciante está restringido a no más de 100 facturas por hora, con límites más estrictos por minuto y por segundo. Si planeas un volumen muy alto, es posible que necesites contactar a su equipo de soporte.