API Pública de Vendty (1.0.0)

API pública de Vendty para integraciones con partners, ERPs y aplicaciones a medida. REST · JSON · OAuth2 (Personal Access Tokens con scopes).

• URL base de producción: https://api-pub.vendty.com/v1
• Fase 1 (lectura): Productos, Categorías, identidad del cliente API (/v1/me), health — en producción
• Fase 2 (lectura): Clientes (terceros), Ventas con detalles y pagos, Métodos de pago, Grupos de clientes — en producción
• Fase 3: Mutaciones (POST/PATCH), Webhooks, Developer Portal — planeado

Seguridad por defecto

• HTTPS obligatorio, HSTS, IDs opacos (sin enumeración secuencial).
• Límites de uso por cliente con planes (Básico / Pro / Empresarial).
• Auditoría de todas las llamadas: tanto las exitosas como las fallidas.
• Usuarios MySQL solo de lectura por negocio — un token de lectura filtrado no puede modificar nada.

Contrato estable

Una vez publicada una versión bajo /v1/, el contrato se preserva: no se eliminan endpoints, no se quitan campos, no se cambian tipos. Los cambios incompatibles van a /v2/.

Pensada para integraciones reales

• Paginación amistosa (per_page hasta 200, links.next para iterar).
• Sincronización incremental con ?updated_since.
• Idempotency keys obligatorias en cada mutación (cuando Fase 3 entregue las escrituras).

Si tienes problemas con tu integración: incluye siempre el header X-Request-Id de la respuesta cuando contactes a tu representante de Vendty. Con ese ID ubicamos la llamada exacta en menos de un minuto.

En 5 minutos haces tu primera llamada autenticada a la API y confirmas que tus credenciales funcionan.

• Un Bearer token emitido a tu aplicación por Vendty. Si todavía no tienes uno, tu representante de Vendty registra un ApiClient para tu negocio y te entrega un token. Los tokens se muestran una sola vez al emitirlos — guárdalo en un lugar seguro (gestor de contraseñas, vault, no en el repositorio de tu aplicación).
• curl o cualquier cliente HTTP.

curl -s https://api-pub.vendty.com/v1/me \
  -H "Authorization: Bearer TU_TOKEN_AQUI"

Respuesta esperada (HTTP 200):

{
  "data": {
    "id": "8d3b1bff-…",
    "name": "Mi aplicación",
    "rate_tier": "basic",
    "scopes": [],
    "allowed_origins": [],
    "created_at": "2026-05-11T18:35:00+00:00"
  },
  "meta": { "request_id": "f7ad…" }
}

Si recibes 401 unauthenticated → el token está mal, expiró o fue revocado. Contacta a Vendty.

Si recibes 403 tenant_not_enabled → tu negocio aún no ha completado el alta para la API. Contacta a Vendty.

El campo data.scopes te dice qué puede hacer tu token. Los permisos más comunes:

Si el arreglo data.scopes viene vacío, tu token solo puede llamar a /v1/me y /v1/health. Para usar endpoints de negocio pídele a Vendty un token con los scopes que necesitas.

3. Lee los headers de cada respuesta

Todas las respuestas incluyen:

4. Las llamadas que mutan requieren Idempotency-Key

Cada POST, PATCH, PUT o DELETE debe llevar el header Idempotency-Key con un UUID v4. Si repites la misma llamada con la misma key (dentro de 24 h) recibes la respuesta original — sirve para reintentar de forma segura ante caídas de red.

curl -X POST https://api-pub.vendty.com/v1/customers \
  -H "Authorization: Bearer TU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "identification_type": "NIT",
    "identification": "900123456",
    "business_name": "Distribuidora ACME SAS",
    "country": "CO"
  }'

Nota: los endpoints de escritura llegan con Phase 2/3. En este momento (Phase 1) solo están disponibles las lecturas de productos y categorías.

Todos los errores siguen el mismo formato:

{
  "error": {
    "code": "validation_failed",
    "message": "La información proporcionada no es válida.",
    "details": { "fields": { "email": ["El campo email debe ser una dirección válida."] } },
    "request_id": "f7ad…"
  }
}

Programa tu lógica contra error.code (estable, legible por máquina). El campo error.message es para humanos y puede cambiar.

• Referencia completa de endpoints: API Reference.
• Detalles de autenticación: Authentication.
• Catálogo completo de códigos de error: Errores.
• Endpoint de productos: Productos.

Toda llamada a /v1/* (excepto /v1/health) debe llevar un token Bearer de Passport en el header Authorization:

Authorization: Bearer tu_token

Los tokens los emite Vendty — no hay endpoint público de registro ni de login. Para obtener un token, contacta a tu representante de Vendty.

Un token tiene:

• Un cliente — la aplicación (ApiClient) a la que pertenece.
• Una etiqueta — nombre legible (ej. "Producción Siigo 2026") para identificarlo en los logs de auditoría.
• Scopes — qué puede hacer (ver más abajo).
• Una fecha de expiración — normalmente 365 días. Los tokens expirados devuelven 401 unauthenticated.

Puedes inspeccionar tu token activo con GET /v1/me.

Los tokens llevan cero o más scopes del catálogo. Por defecto un token no trae ningún scope — cada endpoint exige al menos uno. Pedir un scope que no tienes devuelve 403 scope_missing.

• Nunca subas un token al control de versiones (Git). Usa variables de entorno o un gestor de secretos.
• Nunca lo registres en logs. Si necesitas correlacionar, registra el request_id.
• Trátalo como una contraseña — si crees que fue filtrado, solicita rotación inmediatamente.

Si llamas a la API desde un navegador, el origen de tu aplicación debe estar en la lista permitida (allowed_origins) de tu cliente. No se permiten comodines (*). Envía a Vendty los dominios desde los que vas a llamar cuando pidas tu token.

Todas las respuestas no-2xx siguen este formato:

{
  "error": {
    "code": "<string_estable_legible_por_maquina>",
    "message": "<texto_para_humanos>",
    "details": { ... opcional ... },
    "request_id": "<uuid>"
  }
}

error.code es el contrato. Es estable entre versiones. error.message es para humanos y puede cambiar en cualquier momento.

Una respuesta con header Idempotent-Replay: true es una copia exacta de la respuesta original asociada al mismo Idempotency-Key. Trátala igual que la primera respuesta.

• Toma error.code como única fuente de verdad para tu lógica de cliente. Compara contra el string; no parsees error.message.
• Siempre registra request_id. Cuando contactes a soporte de Vendty, es el dato más útil.
• Política de reintentos: 429 y 503 son razonables para reintentar con backoff. El resto de 4xx no se reintentan — corrige tu llamada.
• Idempotencia: cada reintento de una llamada mutativa debe reusar el mismo Idempotency-Key que el original. Keys distintos producen efectos distintos (o un 409 si reusas mal).

Health check e identidad del cliente API

Catálogo de productos y categorías

Terceros (clientes) y grupos

Ventas, líneas de detalle, pagos y métodos de pago