############################################################################### # Volty Alpha — Collection de requests pre-armados # # Cómo usar: # - VS Code: instala extensión "REST Client" de Huachao Mao # - JetBrains IDEs: soporte nativo a .http files # - Convertir a Postman: https://github.com/usagebot/restclient2postman # # Cómo correr un request: # 1. Reemplaza las variables abajo con tus valores # 2. Click en "Send Request" arriba del bloque ### que quieras correr # ############################################################################### # Variables — reemplaza con tus valores reales ############################################################################### @baseUrl = https://staging-api.volty.mx @apiKey = volty_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # Tu X-Volty-Partner-Token (Cloudflare bypass). Te lo enviamos en el email # de onboarding. Formato: empieza con `vptkn_` seguido de ~32 chars. # Sin este header, Cloudflare puede responder 403 con HTML "Just a moment..." # desde IPs de datacenter (por ejemplo si corres este .http desde un CI/CD). # Detalle: docs/operaciones/CLOUDFLARE_WAF_PARTNERS.md. @partnerToken = vptkn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # Después de crear tu primer customer (req 3.2), copia su ID acá: @customerId = paste-customer-id-here # Después de crear un RPU (req 5.2), su número va acá (es el numero_rpu, no UUID): @rpu = 508941006021 # Después de crear una credencial CFE, su ID va acá: @credencialId = paste-credencial-id-here # Después de encolar un job (alta RPU, refresh, baja), su ID va acá: @jobId = paste-job-id-here # Después de crear un webhook, su ID va acá: @webhookId = paste-webhook-id-here # Opcional — solo si manejas webhooks vía dashboard endpoints (JWT): @orgId = your-org-id-uuid @jwt = paste-jwt-from-supabase-auth-login ############################################################################### # 1. Health & meta — sin auth ############################################################################### ### 1.1 Health check GET {{baseUrl}}/salud ### 1.2 Versión + metadata GET {{baseUrl}}/ ### 1.3 OpenAPI spec GET {{baseUrl}}/openapi.json ############################################################################### # 2. Validar tu API key ############################################################################### ### 2.1 Info de tu API key + org (endpoint estilo Stripe /v1/account) GET {{baseUrl}}/v1/auth/info Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ############################################################################### # 3. Clientes finales (customers) # # Crea un customer por cada "tenant" en tu org: # - ctrlsun: 1 customer "default" para todos sus RPUs # - ctrlfleet: 1 customer por cada end-client que onboardean ############################################################################### ### 3.1 Crear customer (mínimo) POST {{baseUrl}}/v1/clientes Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "nombre": "Empresa Demo S.A. de C.V." } ### 3.2 Crear customer (con todos los campos) POST {{baseUrl}}/v1/clientes Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "nombre": "Empresa Demo S.A. de C.V.", "external_ref": "tu-id-interno-001", "email": "operaciones@empresa-demo.com", "rfc": "EDC101010ABC", "telefono": "+52 55 1234 5678", "ciudad": "Ciudad de México" } ############################################################################### # 4. Credenciales CFE # # IMPORTANTE: el password se cifra con AWS KMS antes de tocar disco. # Nunca se devuelve en claro. El cliente debe existir antes (req 3.x). ############################################################################### ### 4.1 Guardar credenciales CFE de un customer POST {{baseUrl}}/v1/credenciales Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "customer_id": "{{customerId}}", "cfe_username": "Usuario1234M", "cfe_password": "PasswordRealCFE", "etiqueta": "Empresa Demo — CFE master", "es_activa": true } ### 4.2 Agregar segunda credencial (si el customer tiene múltiples logins CFE) # Al pasar es_activa: true, Volty desactiva automáticamente las otras del # mismo customer. Mantiene UNA activa a la vez por customer. POST {{baseUrl}}/v1/credenciales Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "customer_id": "{{customerId}}", "cfe_username": "Usuario_Backup", "cfe_password": "PasswordBackup", "etiqueta": "Empresa Demo — backup", "es_activa": false } ############################################################################### # 5. RPUs (medidores CFE) # # Cada RPU pertenece a un customer. Al crearse encola un job de descarga # que el worker procesa en SEGUNDO PLANO (async). El POST devuelve al # instante con el RPU creado — los recibos llegan después. # # ⏱ Tiempo típico del scrape inicial: ~5 minutos. # Cliente con histórico >5 años o tarifa GDMTH: hasta ~15 min. # No bloquees al usuario esperando — usa webhooks (sección 6). # # El modo define qué descargar y almacenar en S3 al scrape inicial: # "ultimo" — solo el último recibo (ahorras storage) # "ultimos_12" — 12 más recientes (recomendado para GDMTH/HM) # "historico_completo" — TODOS los disponibles (DEFAULT del modelo; # ideal para Fleet onboarding) # # Flujo recomendado para integradores: # 1. POST /webhooks ← registra tu URL para evento "bill.created" # 2. POST /v1/rpus ← crea el RPU (encola scrape automáticamente) # 3. (espera al webhook) ← Volty te avisa cuando los recibos están listos # 4. GET /v1/rpus/{rpu}/recibos ← descarga PDFs/XMLs con URLs firmadas # # Nota sobre las 2 capas: # - Capa Storage (modo arriba) → qué descargamos y guardamos # - Capa Consume (GET /v1/rpus/{rpu}/recibos) → qué te devolvemos # (auto-detecta: GDMTH → 12, otras → 1, override con ?limite=N) ############################################################################### ### 5.1 RPU GDMTH (descarga 12 períodos para análisis horario) POST {{baseUrl}}/v1/rpus Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "customer_id": "{{customerId}}", "numero_rpu": "{{rpu}}", "nombre_servicio": "NOMBRE COMO APARECE EN CFE", "modo": "ultimos_12" } ### 5.2 RPU NO-GDMTH (otras tarifas: solo el último recibo, ahorra storage) POST {{baseUrl}}/v1/rpus Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "customer_id": "{{customerId}}", "numero_rpu": "{{rpu}}", "nombre_servicio": "NOMBRE COMO APARECE EN CFE", "modo": "ultimo" } ### 5.3 RPU con histórico completo (ideal para Fleet onboarding — vida útil del cliente) POST {{baseUrl}}/v1/rpus Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "customer_id": "{{customerId}}", "numero_rpu": "{{rpu}}", "nombre_servicio": "PLANTA EMPRESA DEMO MATRIZ", "modo": "historico_completo", "auto_actualizar": false, "alertas_activas": true } ############################################################################### # 5.x — Recuperación: nombre_servicio NO coincide con CFE # # ⚠️ El campo `nombre_servicio` debe coincidir EXACTAMENTE con el registro # de CFE: case (mayúsculas/minúsculas), espacios, "S.A. de C.V." o "SA DE CV", # acentos, puntos. CFE valida byte-a-byte al dar de alta el RPU. # # Cómo conseguir el nombre correcto: abre un recibo CFE (PDF) de ese RPU, # campo "Nombre del Servicio" → cópialo literal. # # Detección programática del fallo: # GET /v1/rpus/{numero_rpu} → ultimo_scrape_estado == "rpu_no_encontrado_cfe" # `ultimo_scrape_error` trae el texto exacto que CFE devolvió. # # Recuperación SIN destruir customer/credencial/RPU: # PATCH /v1/rpus/{numero_rpu} con el nombre correcto # POST /v1/rpus/{numero_rpu}/retry ############################################################################### ### 5.4 Actualizar nombre_servicio (corregir tras rechazo de CFE) PATCH {{baseUrl}}/v1/rpus/{{rpu}} Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "nombre_servicio": "EL NOMBRE EXACTO DEL RECIBO CFE" } ### 5.5 Reintentar scrape sin recrear el RPU # Acepta body opcional `{"modo": "ultimo"}` para overridear (ej. para probar # rápido con 1 recibo antes de re-correr histórico completo). Sin body usa # el modo guardado en el RPU. # Devuelve 409 si ya hay un job 'en_cola' o 'corriendo' del mismo RPU. POST {{baseUrl}}/v1/rpus/{{rpu}}/retry Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "modo": "ultimo" } ############################################################################### # 6. Consumir recibos (el endpoint principal de Volty) # # Dos formas de pedir recibos a Volty: # # A) Async (flow tradicional — secciones 6.1 y 6.2): # - Tú ya creaste el RPU (sección 5) y Volty lo está scrapeando en # background. # - Esperas el webhook bill.created, después consultas GET /recibos. # - Útil cuando no urge la respuesta. # # B) Sync 1-request (RECOMENDADO — secciones 6.3 a 6.5): # - POST /v1/rpus/{rpu}/recibos/descargar?modo=ultimo|ultimos_12|historico # - Volty resuelve en línea o devuelve job_id para polling, según el # modo y la carga del pool. # - Es la mejor UX para tu cliente final (pide su recibo, en 90s lo # tiene). # - Soporta auto-creación del RPU on-the-fly (no requiere POST /v1/rpus # previo si no quieres). ############################################################################### ### 6.1 Recibos de un RPU (async — cuando ya scrapeaste antes) # Lógica auto-detectada: GDMTH devuelve 12, otras tarifas devuelven 1 GET {{baseUrl}}/v1/rpus/{{rpu}}/recibos Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 6.2 Recibos con override de límite GET {{baseUrl}}/v1/rpus/{{rpu}}/recibos?limite=24 Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 6.3 Descargar recibos — modo `ultimo` (sync con polling) ⭐ flow rápido recomendado # Pides el recibo más reciente y Volty resuelve en línea hasta 90s. # Si CFE se tarda más, devuelve 202 + job_id para polling. # Si hay cache hit cross-org, responde en ~50ms. # Requisito: tu API key debe tener scope `recibos:ultimo`. # # Campo `metadata` OPCIONAL (PR-3 v5, 21 ago 2026): # Si tu plataforma tiene identificador de usuario end-client, envíalo como # `metadata.installer_id` para trazabilidad Sentry ("Affected Users" # feature). Backward compat 100%: sin metadata funciona idéntico. Volty # hace eco del installer_id en el webhook `bill.created`. POST {{baseUrl}}/v1/rpus/{{rpu}}/recibos/descargar?modo=ultimo Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "nombre_titular": "NOMBRE TAL CUAL APARECE EN EL ÚLTIMO RECIBO CFE", "metadata": { "installer_id": "opcional_tu_id_interno_de_usuario" } } ### 6.4 Descargar recibos — modo `ultimos_12` (async, GDMTH-friendly) # Últimos 12 recibos. Siempre async — devuelve 202 + job_id. # Polea GET /v1/jobs/{job_id} cada 30-60s hasta un estado final (ver 9.17). # Requisito: scope `recibos:ultimos_12`. # NOTA: campo `metadata` opcional aplica igual — ver 6.3 arriba. POST {{baseUrl}}/v1/rpus/{{rpu}}/recibos/descargar?modo=ultimos_12 Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "nombre_titular": "NOMBRE TAL CUAL APARECE EN EL ÚLTIMO RECIBO CFE", "metadata": { "installer_id": "opcional_tu_id_interno_de_usuario" } } ### 6.5 Descargar recibos — modo `historico` (async, todo el historial) # Todo el historial disponible — útil para onboarding Fleet (vida útil del # cliente). Siempre async. Polea GET /v1/jobs/{job_id} hasta un estado final (ver 9.17). # Requisito: scope `recibos:historico`. # NOTA: campo `metadata` opcional aplica igual — ver 6.3 arriba. POST {{baseUrl}}/v1/rpus/{{rpu}}/recibos/descargar?modo=historico Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "nombre_titular": "NOMBRE TAL CUAL APARECE EN EL ÚLTIMO RECIBO CFE", "metadata": { "installer_id": "opcional_tu_id_interno_de_usuario" } } ############################################################################### # 7. Webhooks (requieren JWT temporalmente — no API key) # # La gestión de webhooks aún requiere JWT de dashboard. Para alpha cerrada, # avísanos por soporte y nosotros te configuramos tu webhook al inicio. # # Cuando entremos a beta agregamos POST /v1/webhooks con API key. ############################################################################### ### 7.1 Listar mis webhooks (requiere JWT) GET {{baseUrl}}/webhooks?organization_id={{orgId}} Authorization: Bearer {{jwt}} ### 7.2 Crear un webhook (requiere JWT) POST {{baseUrl}}/webhooks?organization_id={{orgId}} Authorization: Bearer {{jwt}} Content-Type: application/json { "nombre": "Webhook principal de eventos", "url": "https://tu-backend.ejemplo.com/volty-events", "eventos": [ "bill.created", "cfe.down", "rpu.alta_fallo" ] } ### 7.3 Probar un webhook POST {{baseUrl}}/webhooks/{{webhookId}}/probar Authorization: Bearer {{jwt}} ### 7.4 Ver histórico de envíos de un webhook GET {{baseUrl}}/webhooks/{{webhookId}}/deliveries?limite=50 Authorization: Bearer {{jwt}} ############################################################################### # 8. Verificación de firma HMAC en tu backend (cuando recibas webhooks) ############################################################################### # # Cuando recibas un POST de Volty, el header X-Volty-Signature contiene # HMAC-SHA256 hexadecimal del cuerpo, firmado con el "secreto" devuelto al # crear el webhook. # # Ejemplo en Python: # # import hmac, hashlib # firma_esperada = hmac.new( # secreto_webhook.encode(), # msg=request.body, # digestmod=hashlib.sha256, # ).hexdigest() # if firma_esperada != request.headers["X-Volty-Signature"]: # return 401 # firma inválida — posible suplantación # # Verifica SIEMPRE la firma antes de procesar el evento. Sin esto cualquiera # que conozca tu URL puede mandarte eventos falsos. ############################################################################### # 9. /v1/* CRUD adicional (GET / PATCH / DELETE) — vía API key # # Estos endpoints complementan los POST de las secciones 3-5 para que tu # backend pueda hacer audit, update y baja sin necesidad de JWT ni dashboard. ############################################################################### # --- Clientes --- ### 9.1 Listar clientes (paginado + filtros) GET {{baseUrl}}/v1/clientes?limit=50&offset=0 Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.2 Listar clientes con búsqueda por nombre GET {{baseUrl}}/v1/clientes?limit=50&offset=0&buscar=empresa Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.3 Listar clientes filtrando por external_ref (reconciliación) GET {{baseUrl}}/v1/clientes?external_ref=tu-id-interno-001 Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.4 Obtener cliente por ID GET {{baseUrl}}/v1/clientes/{{customerId}} Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.5 Actualizar datos del cliente PATCH {{baseUrl}}/v1/clientes/{{customerId}} Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "nombre": "Empresa Demo (renombrada)", "telefono": "+52 55 9876 5432" } ### 9.6 Eliminar cliente (cascade a RPUs, credenciales, recibos) # ⚠️ Hard delete — archivos en S3 NO se borran automáticamente DELETE {{baseUrl}}/v1/clientes/{{customerId}} Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} # --- Credenciales --- ### 9.7 Listar credenciales (sin passwords, solo metadata) GET {{baseUrl}}/v1/credenciales?limit=50&offset=0 Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.8 Listar credenciales filtrando por customer GET {{baseUrl}}/v1/credenciales?customer_id={{customerId}}&solo_activas=true Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.9 Actualizar solo etiqueta de una credencial PATCH {{baseUrl}}/v1/credenciales/{{credencialId}} Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "etiqueta": "Empresa Demo — CFE master (renamed)" } ### 9.10 Reset password CFE (re-cifra con KMS) # Útil cuando el end-client cambia su password en CFE PATCH {{baseUrl}}/v1/credenciales/{{credencialId}} Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "cfe_username": "NuevoUsuario", "cfe_password": "NuevoPasswordCFE" } # --- RPUs --- ### 9.11 Listar RPUs (paginado + filtros) GET {{baseUrl}}/v1/rpus?limit=50&offset=0 Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.12 Listar RPUs de un customer específico GET {{baseUrl}}/v1/rpus?customer_id={{customerId}}&estado=activo Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.13 Obtener RPU por número CFE GET {{baseUrl}}/v1/rpus/{{rpu}} Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.14 Archivar RPU + encolar baja en MiEspacio CFE DELETE {{baseUrl}}/v1/rpus/{{rpu}} Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} # --- Jobs --- ### 9.15 Listar jobs recientes GET {{baseUrl}}/v1/jobs?limit=50&offset=0 Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.16 Listar jobs filtrando por estado y tipo GET {{baseUrl}}/v1/jobs?estado=corriendo&tipo=descarga_inicial Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ### 9.17 Detalle de un job (polling para tracking de scrape) # Estados finales de un job: exitoso, parcial, fallido, cancelado. # Deten el polling en cualquiera de los cuatro, no solo en exitoso — # un job en `parcial` NUNCA va a pasar a `exitoso`. GET {{baseUrl}}/v1/jobs/{{jobId}} Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} # --- Webhooks (con API key, sin JWT) --- ### 9.18 Crear webhook con API key (no JWT necesario) POST {{baseUrl}}/v1/webhooks Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} Content-Type: application/json { "nombre": "Webhook principal de eventos", "url": "https://tu-backend.ejemplo.com/volty-events", "eventos": [ "bill.created", "cfe.down", "rpu.alta_fallo" ] } ### 9.19 Histórico de deliveries de un webhook (debug) GET {{baseUrl}}/v1/webhooks/{{webhookId}}/deliveries?limit=50&offset=0 Authorization: Bearer {{apiKey}} X-Volty-Partner-Token: {{partnerToken}} ############################################################################### # Tips finales ############################################################################### # # - El header X-Request-Id en cada respuesta de Volty te da un ID único. # Inclúyelo cuando reportes bugs — nos permite encontrar tu request en logs. # # - Para debug: agrega -v a curl o usa el inspector del REST Client de VS Code. # # - Códigos de error que devuelve Volty: # 401 → API key inválida, revocada o ausente # 402 → Servicio temporalmente no disponible (response neutral, codigo `servicio_no_disponible`) # 403 → Customer no es de tu org (security boundary) # 404 → Recurso no existe (customer, RPU, etc.) # 409 → Conflict — recurso duplicado (ej. RPU ya registrado) # 422 → Pydantic validation — campo del body mal nombrado o tipo incorrecto # 429 → Rate limit (durante alpha no se enforce) # 5xx → Bug nuestro. Avisa por soporte con el X-Request-Id. # # - Durante alpha NO hay rate limits duros. Sé razonable — no nos hagas # stress test no anunciado, eso lo coordinamos juntos si quieren probarlo. # ###############################################################################