Integra AVEX en tus flujos

Refleja el pase del estudiante desde tu SIS. El orden es carreras → pases: resuelve los careerId con el descubrimiento (GET /api/v1/institutions/{institutionId}/careers) o crea el programa que falte con el POST de carreras (scope careers:write; renombrar/retirar sigue siendo del panel), y emite usando el code. El upsert crea en el primer push y refleja los campos mutables en los siguientes; photoUrl debe ser una URL directa (sin redirects — el fetch server-side corta en 301/302) que sirva JPG/PNG/WEBP; event empuja el cambio de estado; revoke retira el pase. Si la institución tiene captura diferida de foto (photoCaptureInInstallEmail), un create sin foto de un passType que la exige responde además photoCaptureUrl (+ photoCaptureUrlExpiresAt, 30 días): el enlace tokenizado de auto-captura que distribuyes al estudiante. Mientras la foto no llegue, el carnet instalado muestra una silueta neutra — en Apple en el espacio de la foto, en Google como banner superior de la tarjeta; al empujar la photoUrl con el mismo upsert, la foto real la reemplaza y el pase instalado se actualiza solo. studentStatus acepta exactamente Active · Inactive · Graduated · Withdrawn · Expelled · Suspended — con mayúscula inicial; un valor fuera del set responde 400. En el upsert es opcional: si viene se refleja tal cual, si se omite se conserva (un create nace Active); el upsert no emite el webhook pass.updated — para notificar a tus suscriptores el cambio de estado usa event.

curl -X POST https://www.avex.com.co/api/v1/institutions/11111111-1111-4111-8111-111111111111/careers \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "ING-IA",
  "name": "Ingeniería en Inteligencia Artificial",
  "modality": "Virtual",
  "totalPeriods": 10
}'

curl -X POST https://www.avex.com.co/api/v1/pass/upsert \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000001" \
  -H "Content-Type: application/json" \
  -d '{
  "institutionId": "11111111-1111-4111-8111-111111111111",
  "externalId": "EST-12345",
  "data": {
    "uniqueIdentifier": "1098765432",
    "careerId": "ING-SIS",
    "name": "Ana María Gómez",
    "email": "ana.gomez@example.edu.co",
    "semester": 6,
    "enrollmentYear": 2023,
    "studentStatus": "Active",
    "academicCalendarLink": null,
    "photoUrl": "https://cdn.example.edu.co/fotos/est-12345.jpg"
  }
}'

// Node 22+ / TypeScript — fetch nativo, sin dependencias externas.
const res = await fetch("https://www.avex.com.co/api/v1/pass/upsert", {
  method: "POST",
  headers: {
    Authorization: "Bearer avex_k1_<tu_clave>",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "institutionId": "11111111-1111-4111-8111-111111111111",
  "externalId": "EST-12345",
  "data": {
    "uniqueIdentifier": "1098765432",
    "careerId": "ING-SIS",
    "name": "Ana María Gómez",
    "email": "ana.gomez@example.edu.co",
    "semester": 6,
    "enrollmentYear": 2023,
    "studentStatus": "Active",
    "academicCalendarLink": null,
    "photoUrl": "https://cdn.example.edu.co/fotos/est-12345.jpg"
  }
}),
});

// 201 en la primera creación, 200 cuando reflejas un pase ya existente.
if (!res.ok) {
  throw new Error(`AVEX respondió ${res.status}`);
}

curl -X POST https://www.avex.com.co/api/v1/pass/EST-12345/event \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Content-Type: application/json" \
  -d '{
  "institutionId": "11111111-1111-4111-8111-111111111111",
  "type": "status.changed",
  "data": {
    "studentStatus": "Graduated"
  }
}'

curl -X POST https://www.avex.com.co/api/v1/pass/EST-12345/revoke \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Content-Type: application/json" \
  -d '{
  "institutionId": "11111111-1111-4111-8111-111111111111",
  "reason": "Retiro voluntario del programa"
}'

curl -X POST https://www.avex.com.co/api/v1/pass/EST-12345/period/snapshot \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000005" \
  -H "Content-Type: application/json" \
  -d '{
  "institutionId": "11111111-1111-4111-8111-111111111111",
  "periodName": "2026-2",
  "startDate": "2026-07-01",
  "dueDate": "2026-08-15",
  "totalToPay": 2500000,
  "amountPaid": 0,
  "paymentReference": "REF-2026-2-000123",
  "onlinePaymentUrl": "https://pagos.example.com/REF-2026-2-000123"
}'

Refleja al miembro y su saldo desde tu POS/CRM. Primero resuelve el programId con el descubrimiento (GET /api/v1/loyalty/programs, scope loyalty:read — paginado con page/limit, responde { data, total, page, limit }); luego el upsert crea o refleja al miembro por externalId y el snapshot empuja el balance ya computado más el nivel resuelto (por su nombre, tierName, o su UUID, tierId) — AVEX nunca calcula puntos. La misma familia trae POST .../member/{externalId}/revoke (retira el pase), GET .../member/{externalId}/install-link (el enlace tokenizado para tu canal) y, si tu POS prefiere push firmado en vez de API key, el webhook entrante /api/payments/loyalty-snapshot/{clientSlug} direccionado por accountNumber.

curl -X POST https://www.avex.com.co/api/v1/loyalty/member/upsert \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000002" \
  -H "Content-Type: application/json" \
  -d '{
  "programId": "22222222-2222-4222-8222-222222222222",
  "externalId": "SOCIO-789",
  "data": {
    "name": "Carlos Restrepo",
    "email": "carlos.restrepo@example.com",
    "phone": "+573001234567",
    "accountNumber": "ACC-0099"
  }
}'

curl -X POST https://www.avex.com.co/api/v1/loyalty/member/SOCIO-789/snapshot \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Content-Type: application/json" \
  -d '{
  "balance": 4500,
  "tierId": null
}'

El orden es upsert → enlace de instalación → snapshot o webhook → verificación. El upsert crea la cuota por tu externalId (y la refleja en pushes siguientes: solo los datos del titular; los financieros son del snapshot) y devuelve el installUrl que tú distribuyes; el snapshot empuja el acumulado pagado, el saldo restante y el estado desde tu sistema de cobranza — AVEX los refleja verbatim en el pase — o, si prefieres push firmado, el webhook entrante /api/webhooks/installment-payment/{clientSlug}. La misma familia trae POST .../{externalId}/revoke (409 si la cuota ya tiene pagos), GET .../{externalId}/install-link y GET /api/v1/verify/real-estate/{installmentId} para consultar el estado sin datos personales.

curl -X POST https://www.avex.com.co/api/v1/installment/upsert \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000006" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "CUOTA-456",
  "institutionId": "77777777-7777-4777-8777-777777777777",
  "projectName": "Torres del Parque",
  "unitIdentifier": "Torre 2 · Apto 804",
  "totalInstallments": 24,
  "currentInstallment": 3,
  "installmentAmount": 4200000,
  "dueDate": "2026-09-15",
  "holderName": "Andrés Felipe Cárdenas",
  "holderEmail": "andres.cardenas@example.com",
  "holderDocument": "1020304050"
}'

curl -X POST https://www.avex.com.co/api/v1/installment/CUOTA-456/snapshot \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Content-Type: application/json" \
  -d '{
  "accumulatedPaid": 1500000,
  "remainingBalance": 8500000,
  "status": "Active"
}'

Refleja la factura del período desde tu sistema de facturación. Con accountReference, AVEX mantiene UN pase persistente por cuenta que se actualiza cada período sin emitir un pase nuevo; el snapshot empuja el estado de pago que tu biller ya computó (AVEX nunca calcula vencimientos). Perfil conjunto residencial (PA-018): usa serviceType 'administration' y la nomenclatura del apto como accountReference ('Torre 3 · Apto 501') — la unidad se renderiza en la tarjeta del residente y la cuota mensual actualiza su pase existente.

curl -X POST https://www.avex.com.co/api/v1/utility/bill/upsert \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000003" \
  -H "Content-Type: application/json" \
  -d '{
  "institutionId": "33333333-3333-4333-8333-333333333333",
  "accountHolderName": "Luisa Fernanda Ruiz",
  "accountHolderEmail": "luisa.ruiz@example.com",
  "accountNumber": "1029384821",
  "serviceType": "electricity",
  "billingPeriod": "2026-07",
  "amountDue": 186500,
  "dueDate": "2026-08-15",
  "paymentReference": "FAC-2026-07-004821",
  "accountReference": "CONTRATO-004821"
}'

curl -X POST https://www.avex.com.co/api/v1/utility/bill/FAC-2026-07-004821/snapshot \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Content-Type: application/json" \
  -d '{
  "paymentStatus": "paid",
  "paidAt": "2026-07-01T14:30:00-05:00"
}'

curl https://www.avex.com.co/api/v1/utility/bill/FAC-2026-07-004821/install-link \
  -H "Authorization: Bearer avex_k1_<tu_clave>"

curl -X POST https://www.avex.com.co/api/v1/utility/bill/FAC-2026-07-004821/revoke \
  -H "Authorization: Bearer avex_k1_<tu_clave>"

Primero resuelve los identificadores con el descubrimiento (scope events:read): GET /api/v1/events (paginado con page/limit) te da el eventId y GET /api/v1/events/{id}/showtimes las funciones con su showtimeId — ambos UUID los exige el upsert. Luego emite entradas por externalId dentro de esa función, entrega la credencial de instalación con install-link (scope tickets:credential) y valida en puerta con el payload real del wallet. La validación es de un solo uso por entrada (already_used idempotente) y cross-tenant responde 404 sin oráculo. El evento de la función debe estar Publicado — el upsert responde 400 si todavía está en Borrador, Completado o Cancelado.

curl -X POST https://www.avex.com.co/api/v1/entertainment/ticket/upsert \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Idempotency-Key: 00000000-0000-4000-8000-000000000004" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "TICKET-2026-00891",
  "eventId": "44444444-4444-4444-8444-444444444444",
  "showtimeId": "55555555-5555-4555-8555-555555555555",
  "holderName": "Mariana Duque",
  "holderEmail": "mariana.duque@example.com",
  "seat": "14",
  "row": "C",
  "section": "Platea",
  "tierId": "66666666-6666-4666-8666-666666666666"
}'

curl "https://www.avex.com.co/api/v1/entertainment/ticket/TICKET-2026-00891/install-link?expiryDays=30" \
  -H "Authorization: Bearer avex_k1_<tu_clave>"

curl -X POST https://www.avex.com.co/api/v1/entertainment/validate \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "Content-Type: application/json" \
  -d '{
  "qrPayload": "b3f1c2d4e5f60718293a4b5c6d7e8f90|482913",
  "validatedBy": "puerta-norte-1"
}'

Sandbox de validación (dry-run)

Antes de empujar datos reales, valida tu integración con el header X-AVEX-Dry-Run: true. Corre la autenticación y la validación de schema, ownership y existencia, resuelve el recurso igual que el push real (una referencia ausente o ajena responde el mismo 404) y, cuando la fila pasaría, devuelve un 200 con la previsualización del efecto sin crear ni modificar datos — ningún pase llega a los titulares. La autenticación cuenta igual que en el push real: consume tu límite de solicitudes y actualiza el último uso de tu API key. Un 4xx bajo dry-run es el mismo 4xx que recibirías en el push real. Dos cosas solo se evalúan al escribir: el aforo por función (entertainment) y la descarga de la foto (education) — un dry-run en verde no las garantiza.

# Sandbox de validación: agrega X-AVEX-Dry-Run: true a cualquier
# endpoint de ingesta (upserts, snapshots, eventos, revocaciones y void).
# AVEX corre auth + validación + el efecto teórico y responde 200 con la
# previsualización — sin crear pases, sin push, sin email. Quita el
# header para ejecutar de verdad. La validación de puerta NO es ingesta:
# validar quema la entrada; su consulta sin quemar es /v1/verify/*.
curl -X POST https://www.avex.com.co/api/v1/installment/CUOTA-456/snapshot \
  -H "Authorization: Bearer avex_k1_<tu_clave>" \
  -H "X-AVEX-Dry-Run: true" \
  -H "Content-Type: application/json" \
  -d '{"accumulatedPaid":1500000,"remainingBalance":8500000,"status":"Active"}'

Códigos comunes

• HTTP 401SESSION_INVALID

  Falta el header Authorization, o la API key es inválida, expiró o fue revocada.

• HTTP 401CLIENT_INACTIVE

  La API key es válida pero el cliente al que pertenece está inactivo o suspendido.

• HTTP 402SUBSCRIPTION_INACTIVE

  La suscripción del cliente no está activa. Las rutas operacionales de puerta (verify y validate) quedan exentas; el resto de la API v1 bloquea hasta renovar.

• HTTP 402SUBSCRIPTION_LIMIT_EXCEEDED

  El plan del cliente quedó sin cupo para el recurso solicitado (pases, usuarios o instituciones). La suscripción sigue activa; libera cupo o amplía el plan para continuar.

• HTTP 400VALIDATION_ERROR

  El body no cumple la validación Zod del endpoint. details es el árbol de z.treeifyError: los errores se anidan por campo bajo properties, no llegan como lista plana. Ojo: este mismo code también llega con status 409 en el conflicto de catálogo del POST de carreras (código ya existente) — discrimina por status, no solo por code.

• HTTP 404RESOURCE_NOT_FOUND

  El recurso no existe o no pertenece al cliente asociado a la API key.

• HTTP 404IMAGE_SERVICE

  El fetch server-side de una imagen falló (photoUrl del upsert education): URL con redirect, host inaccesible o que filtra el User-Agent, tamaño mayor a 20 MB, timeout de 30 s, o bytes que no son una imagen decodificable. Distinto de RESOURCE_NOT_FOUND: el pase/carrera existen — la que falló fue la foto. Una falla INTERNA al procesar la foto nunca llega con este code: responde 500 INTERNAL_ERROR; y una caída de nuestro almacenamiento responde 502 EXTERNAL_SERVICE_ERROR — en ambos casos reintenta más tarde, no es tu URL.

• HTTP 409CONFLICT

  La misma Idempotency-Key está en vuelo (otro intento del mismo push sigue procesándose — reintenta en unos segundos) o su resultado original ya no está disponible (re-push con una clave nueva). Una key completada con resultado no da 409: los upserts v1 responden 200 re-entregando la respuesta original almacenada, verbatim.

• HTTP 409CONFIRMATION_REQUIRED

  La operación exige consentimiento explícito antes de proceder. En los envíos de notificación (pass/notifications, reminders/csv): la audiencia completa es Google Wallet con la cuota de notificaciones visibles (24 h) agotada y sin destinatarios Apple — nadie vería el aviso. Reintenta la MISMA request con acknowledgeNoPush=true para entregar la actualización sin notificación visible, o espera a que la ventana de cuota se libere.

• HTTP 429RATE_LIMIT_EXCEEDED

  El caller excedió el tier aplicable. Los segundos de espera llegan en el header HTTP Retry-After — nunca en el body.

• HTTP 403INSUFFICIENT_PERMISSIONS

  La credencial es válida pero no tiene permisos sobre el recurso o la operación: scope de la API key insuficiente o institución fuera del alcance asignado.

• HTTP 403FEATURE_DISABLED

  La funcionalidad que requiere el endpoint está deshabilitada para el cliente. Un administrador debe activarla antes de reintentar.

• HTTP 400PASS_TYPE_INVALID

  El tipo de pase enviado no existe en el catálogo de la institución o usa un código reservado del sistema. Corrige el campo passType del request.

• HTTP 400CUSTOM_FIELD_KEY_RESERVED

  Una clave de customFields (upsert o snapshot de utilities/installment/loyalty/entertainment) colisiona con un campo del motor de campos del vertical — sombrearía el resolver o produciría un render duplicado. Renombra la clave; las reservadas varían por vertical.

• HTTP 401WEBHOOK_UNAUTHORIZED

  Aplica a los receptores de webhooks entrantes (rutas firmadas de pagos y notificaciones), no a la API v1 con API key: la firma del webhook falta, es inválida o ya fue usada.

• HTTP 503WEBHOOK_NOT_CONFIGURED

  Aplica a los receptores de webhooks entrantes: la recepción está habilitada pero falta configurar el secreto de verificación del lado de AVEX. El emisor debe reintentar más tarde.

• HTTP 503SERVICE_UNAVAILABLE

  El gate de validación de entradas de entertainment no está disponible (llave TOTP ausente o registro incompleto). El escáner debe reintentar más tarde; el request era válido.

• HTTP 502EXTERNAL_SERVICE_ERROR

  Un servicio externo del canal (Apple Wallet, Google Wallet, el proveedor de email o nuestro almacenamiento de imágenes) falló al procesar la operación. El request era válido; reintenta con backoff.

• HTTP 500INTERNAL_ERROR

  Error interno del servidor. El mensaje es genérico a propósito y no trae detalles; reintenta y reporta a soporte si persiste.

• HTTP 501NOT_IMPLEMENTED

  El vertical del cliente aún no implementa el flujo solicitado (red de seguridad del contrato vertical-sin-flujo). El request era válido pero la operación no existe para ese vertical.