Integración de Pre-Órdenes con QR

Introducción

Este documento describe los endpoints de la API de TotalCoin para gestionar pre-órdenes con generación y procesamiento de códigos QR.

Autenticación

El control de acceso a la API se realiza mediante OAuth 2.0 con Tokens Bearer.

Endpoint

POST api/auth/login

Solicitud

{
    "username": "",
    "password": ""
}

Campo	Tipo	Descripción	Requerido
username	String	Nombre de usuario	Sí
password	String	Contraseña	Sí

Respuesta (HTTP 200)

{
    "token": "",
    "expires_in": 3600
}

Campo	Tipo	Descripción
token	String	Token de autenticación
expires_in	Number	Validez del token en segundos

Posibles Errores

Código	Descripción
401	Credenciales inválidas o no existentes
403	Sin permisos para acceder a la API

Credenciales: Deben solicitarse al departamento técnico.

Crear Pre-Orden

Crea una nueva pre-orden y genera un código QR para el pago.

Endpoint

POST api/pre-orders

Solicitud

{
    "amount": 100.00,
    "currency": "USD",
    "description": "Pre-orden para producto X",
    "expiration_date": "2024-04-26T23:59:59Z",
    "customer": {
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com",
        "phone": "+1234567890"
    }
}

Campo	Tipo	Descripción	Requerido
amount	Number	Monto de la orden	Sí
currency	String	Código de moneda (USD, EUR, etc.)	Sí
description	String	Descripción de la orden	Sí
expiration_date	String	Fecha ISO 8601 cuando expira la pre-orden	Sí
customer	Object	Información del cliente	Sí
customer.name	String	Nombre completo del cliente	Sí
customer.email	String	Correo electrónico del cliente	Sí
customer.phone	String	Número de teléfono del cliente	Sí

Respuesta (HTTP 201)

{
    "id": "pre_order_123",
    "status": "pending",
    "qr_code": "data:image/png;base64,...",
    "payment_url": "https://totalcoin.com/pay/pre_order_123",
    "created_at": "2024-03-26T10:00:00Z",
    "expires_at": "2024-04-26T23:59:59Z"
}

Campo	Tipo	Descripción
id	String	Identificador único de la pre-orden
status	String	Estado actual de la pre-orden
qr_code	String	Imagen del código QR codificada en base64
payment_url	String	URL para el procesamiento del pago
created_at	String	Marca de tiempo de creación
expires_at	String	Marca de tiempo de expiración

Posibles Errores

Código	Descripción
400	Parámetros de solicitud inválidos
401	No autorizado - Token inválido o faltante
403	Prohibido - Permisos insuficientes

Obtener Estado de Pre-Orden

Obtiene el estado actual de una pre-orden.

Endpoint

GET api/pre-orders/{id}

Respuesta (HTTP 200)

{
    "id": "pre_order_123",
    "status": "paid",
    "amount": 100.00,
    "currency": "USD",
    "description": "Pre-orden para producto X",
    "customer": {
        "name": "Juan Pérez",
        "email": "juan@ejemplo.com",
        "phone": "+1234567890"
    },
    "payment_details": {
        "transaction_id": "txn_456",
        "payment_method": "qr",
        "paid_at": "2024-03-26T11:00:00Z"
    },
    "created_at": "2024-03-26T10:00:00Z",
    "expires_at": "2024-04-26T23:59:59Z"
}

Campo	Tipo	Descripción
id	String	Identificador único de la pre-orden
status	String	Estado actual (pending, paid, expired, cancelled)
amount	Number	Monto de la orden
currency	String	Código de moneda
description	String	Descripción de la orden
customer	Object	Información del cliente
payment_details	Object	Información del pago (solo presente si está pagado)
created_at	String	Marca de tiempo de creación
expires_at	String	Marca de tiempo de expiración

Posibles Errores

Código	Descripción
401	No autorizado - Token inválido o faltante
403	Prohibido - Permisos insuficientes
404	Pre-orden no encontrada

Notificaciones Webhook

Los webhooks se envían para notificar cambios de estado en las pre-órdenes.

Tipos de Eventos

Evento	Descripción
pre_order.paid	La pre-orden ha sido pagada
pre_order.expired	La pre-orden ha expirado
pre_order.cancelled	La pre-orden ha sido cancelada

Payload del Webhook

{
    "event": "pre_order.paid",
    "data": {
        "id": "pre_order_123",
        "status": "paid",
        "amount": 100.00,
        "currency": "USD",
        "payment_details": {
            "transaction_id": "txn_456",
            "payment_method": "qr",
            "paid_at": "2024-03-26T11:00:00Z"
        }
    },
    "timestamp": "2024-03-26T11:00:00Z"
}

Configuración de Webhook: Contacte al departamento técnico para configurar los endpoints de webhook y recibir las credenciales necesarias.