API Reference

Consulta todos los endpoints disponibles en nuestro Swagger UI:

• Swagger Ecommerce API
• Webhook.

---

Contrato OpenAPI

Además de Swagger UI, publicamos el contrato OpenAPI completo para que puedas validar, versionar y autogenerar SDKs en tus pipelines.

Descargas

• YAML
• JSON

Sustituye las URLs por las finales donde decidas alojar el contrato.

Versionado

• Usamos SemVer: MAJOR.MINOR.PATCH.
• Cambios incompatibles (breaking) solo en MAJOR con aviso previo.
• Cambios compatibles (nuevos campos opcionales, nuevos endpoints) en MINOR.
• Correcciones de errores/ejemplos en PATCH.

---

Estandar de respuestas

Éxito (200/201)

Envelope

{
  "message": "Payment created",
  "timestamp": "2024-04-16T17:44:51Z",
  "data": { /* recurso o resultado */ }
}

Ejemplo (crear pago)

{
  "message": "OK",
  "timestamp": "2024-04-16T17:44:51Z",
  "data": {
    "id": "263600a1-1514-4e57-a11d-be91e9c8e9d4",
    "merchant_reference": "INV-25-AUG-0001",
    "title": "My new payment",
    "description": "Purchase of food and groceries on March 3, 2025",
    "network": "TRON",
    "currency": "USDT",
    "amount": "1234.56",
    "confirmed_amount": "0",
    "status": "OPEN",
    "valid_until": 1755532150,
    "created_at": "2024-04-16T17:44:51Z",
    "updated_at": "2024-04-16T17:44:51Z"
  }
}

Errores (4xx/5xx)

Envelope

{
  "error": "0004",
  "title": "INVALID_REQUEST",
  "message": "The received request contains invalid data.",
  "timestamp": "2024-04-16T17:44:51Z",
  "details": [
    {
      "field": "network",
      "message": "The received field exceeds the maximum allowed length."
    }
  ]
}

• error: identificador numérico estable para que tu lógica cliente no dependa del texto.
• title: identificador en texto estable.
• message: mensaje legible para humanos.
• timestamp: fecha y hora en que se generó la respuesta.
• details: array opcional con errores por campo u otros metadatos.

Cabeceras

• Para errores de validación, recomendamos Content-Type: application/json (simple y universal).

---

Versionado en URLs

SP Cuvex utiliza versionado en la URL para garantizar compatibilidad:

• Formato: /v{número}/endpoint
• Versión actual: v1 (única versión disponible hasta el momento)
• Ejemplo: /v1/payments

---

Caching

Los endpoints de estado de pagos/invoices son sensibles y de naturaleza en tiempo real. No recomendamos cachearlos del lado cliente.
SP Cuvex puede incluir encabezados conservadores (Cache-Control: no-store) en respuestas críticas. Si tu plataforma aplica caches intermedios (CDN/proxy), desactívalos para estas rutas.

---

Rate limiting

En la versión actual no aplicamos límites de tasa formales por API Key.
Nos reservamos la posibilidad de activar protecciones anti-abuso. Si en el futuro introducimos 429 Too Many Requests, seguiremos el estándar Retry-After y publicaremos la política (cuotas y ventanas) en esta sección.

---

Compliance

SP Cuvex es un servicio no custodial: nunca tenemos control sobre los fondos de tus wallets.
La responsabilidad sobre la custodia de claves privadas, operación de wallets y registros contables recae sobre ti como comercio.

Endpoints principales

Sandbox

• Endpoint base:

  https://sp-dev.cuvex.io/ecommerce

Producción

• Endpoint base:

  https://sp.cuvex.io/ecommerce

---

Colección de Postman

Para facilitar las pruebas de integración, hemos preparado una colección de Postman con todos los endpoints y ejemplos listos para usar.

Descargar colección

📋 Descargar colección de Postman

Contenido de la colección

La colección incluye los siguientes grupos de endpoints:

• Status: Verificación del estado del servicio
• Networks: Consulta de redes blockchain soportadas
• Tokens: Consulta de tokens (stablecoins) disponibles
• Payments: Gestión completa de pagos
  • Crear pagos con idempotencia
  • Listar pagos con paginación y filtros de fecha
  • Consultar detalles de pagos específicos

Variables preconfiguradas

La colección viene con las siguientes variables configuradas:

Variable	Valor por defecto	Descripción
baseUrl	http://localhost:8080/ecommerce	URL base de la API (actualízala según tu entorno)
apiKey	your-api-key-here	Tu clave de API
paymentId	39bdc393-dbda-47a6-b812-73c2fc5cbf91	ID de ejemplo para consultas de pagos

Configuración recomendada

1. Importa la colección en Postman
2. Actualiza las variables de entorno:
   • Para sandbox: https://sp-dev.cuvex.io/ecommerce
   • Para producción: https://sp.cuvex.io/ecommerce
3. Configura tu apiKey real
4. Ejecuta las requests en orden para familiarizarte con el flujo

---

Códigos de error

En la sección Códigos de error podrás encontrar los códigos de error manejados por la API.