{
  "info": {
    "_postman_id": "a1b2c3d4-e5f6-7890-1234-volty567890",
    "name": "Volty Alpha — API",
    "description": "## DEPRECATED — 22 jun 2026\n\n**Esta collection estática está deprecada.** A partir de PR #103, las collections Postman se sincronizan automáticamente desde el OpenAPI live de producción vía GitHub Actions (`scripts/sync_postman_collections.py` + `.github/workflows/sync_postman.yml`).\n\nLos workspaces compartidos de los partners ya tienen la collection auto-sincronizada. Este archivo estático permanece en el repo SOLO como fallback histórico — no se edita ni se distribuye. Para detalles operativos: `docs/operaciones/POSTMAN_AUTO_SYNC.md`.\n\n---\n\nCollection oficial de Volty API para alpha partners (Ctrlsun, Ctrlfleet).\n\n## Cómo usar\n\n1. Abre la pestaña **Variables** de esta collection y reemplaza:\n   - `apiKey` con tu key real (formato `volty_test_xxx`)\n   - `customerId` después de crear tu primer customer (request 3.1)\n   - `rpu` con un número de RPU CFE válido (12 dígitos)\n\n2. Empieza por **1. Health & Auth → 1.2 Validar API key** para confirmar conexión.\n\n3. Sigue tu QUICKSTART específico (Ctrlsun o Ctrlfleet) para el flow recomendado.\n\n## Soporte\n\n- Email: `danna@volty.mx`\n- Docs interactivas: https://staging-api.volty.mx/docs",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "baseUrl", "value": "https://staging-api.volty.mx", "type": "string" },
    { "key": "apiKey", "value": "volty_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "type": "string" },
    { "key": "customerId", "value": "", "type": "string" },
    { "key": "credencialId", "value": "", "type": "string" },
    { "key": "rpu", "value": "508941006021", "type": "string" },
    { "key": "jobId", "value": "", "type": "string" },
    { "key": "webhookId", "value": "", "type": "string" }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      { "key": "token", "value": "{{apiKey}}", "type": "string" }
    ]
  },
  "item": [
    {
      "name": "1. Health & Auth",
      "item": [
        {
          "name": "1.1 Health check (sin auth)",
          "request": {
            "method": "GET",
            "header": [],
            "url": { "raw": "{{baseUrl}}/salud", "host": ["{{baseUrl}}"], "path": ["salud"] }
          },
          "response": []
        },
        {
          "name": "1.2 Validar API key + ver info de tu org",
          "request": {
            "method": "GET",
            "header": [],
            "url": { "raw": "{{baseUrl}}/v1/auth/info", "host": ["{{baseUrl}}"], "path": ["v1", "auth", "info"] }
          },
          "response": []
        }
      ]
    },
    {
      "name": "2. Clientes (CRUD completo)",
      "item": [
        {
          "name": "2.1 Crear cliente",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"nombre\": \"Empresa Demo S.A. de C.V.\",\n  \"external_ref\": \"tu-id-interno-001\",\n  \"email\": \"contacto@empresa-demo.com\",\n  \"rfc\": \"EDC101010ABC\"\n}"
            },
            "url": { "raw": "{{baseUrl}}/v1/clientes", "host": ["{{baseUrl}}"], "path": ["v1", "clientes"] }
          },
          "response": []
        },
        {
          "name": "2.2 Listar clientes (paginado)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/clientes?limit=50&offset=0",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "clientes"],
              "query": [
                { "key": "limit", "value": "50" },
                { "key": "offset", "value": "0" },
                { "key": "buscar", "value": "", "disabled": true, "description": "Texto en nombre o RFC" },
                { "key": "external_ref", "value": "", "disabled": true, "description": "Filtrar por referencia externa" }
              ]
            }
          },
          "response": []
        },
        {
          "name": "2.3 Obtener cliente por ID",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/clientes/{{customerId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "clientes", "{{customerId}}"]
            }
          },
          "response": []
        },
        {
          "name": "2.4 Actualizar cliente",
          "request": {
            "method": "PATCH",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"nombre\": \"Empresa Demo (nuevo nombre)\",\n  \"telefono\": \"+52 55 1234 5678\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/v1/clientes/{{customerId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "clientes", "{{customerId}}"]
            }
          },
          "response": []
        },
        {
          "name": "2.5 Eliminar cliente (cascade a RPUs y credenciales)",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/clientes/{{customerId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "clientes", "{{customerId}}"]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "3. Credenciales CFE (cifradas con KMS)",
      "item": [
        {
          "name": "3.1 Guardar credenciales CFE",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"customer_id\": \"{{customerId}}\",\n  \"cfe_username\": \"Usuario1234M\",\n  \"cfe_password\": \"PasswordRealCFE\",\n  \"etiqueta\": \"Empresa Demo — CFE master\",\n  \"es_activa\": true\n}"
            },
            "url": { "raw": "{{baseUrl}}/v1/credenciales", "host": ["{{baseUrl}}"], "path": ["v1", "credenciales"] }
          },
          "response": []
        },
        {
          "name": "3.2 Listar credenciales (metadata, NO passwords)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/credenciales?limit=50&offset=0",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "credenciales"],
              "query": [
                { "key": "limit", "value": "50" },
                { "key": "offset", "value": "0" },
                { "key": "customer_id", "value": "{{customerId}}", "disabled": true },
                { "key": "solo_activas", "value": "false", "disabled": true }
              ]
            }
          },
          "response": []
        },
        {
          "name": "3.3 Actualizar credencial — solo etiqueta",
          "request": {
            "method": "PATCH",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"etiqueta\": \"Empresa Demo — CFE master (renamed)\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/v1/credenciales/{{credencialId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "credenciales", "{{credencialId}}"]
            }
          },
          "response": []
        },
        {
          "name": "3.4 Actualizar credencial — reset password CFE",
          "request": {
            "method": "PATCH",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"cfe_username\": \"NuevoUsuario\",\n  \"cfe_password\": \"NuevoPasswordCFE\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/v1/credenciales/{{credencialId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "credenciales", "{{credencialId}}"]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "4. RPUs (medidores CFE)",
      "item": [
        {
          "name": "4.1 Dar de alta RPU — modo último (default)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"customer_id\": \"{{customerId}}\",\n  \"numero_rpu\": \"{{rpu}}\",\n  \"nombre_servicio\": \"NOMBRE COMO APARECE EN CFE\",\n  \"modo\": \"ultimo\"\n}"
            },
            "url": { "raw": "{{baseUrl}}/v1/rpus", "host": ["{{baseUrl}}"], "path": ["v1", "rpus"] }
          },
          "response": []
        },
        {
          "name": "4.2 Dar de alta RPU — GDMTH últimos 12",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"customer_id\": \"{{customerId}}\",\n  \"numero_rpu\": \"{{rpu}}\",\n  \"nombre_servicio\": \"NOMBRE COMO APARECE EN CFE\",\n  \"modo\": \"ultimos_12\"\n}"
            },
            "url": { "raw": "{{baseUrl}}/v1/rpus", "host": ["{{baseUrl}}"], "path": ["v1", "rpus"] }
          },
          "response": []
        },
        {
          "name": "4.3 Dar de alta RPU — histórico completo (Fleet onboarding)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"customer_id\": \"{{customerId}}\",\n  \"numero_rpu\": \"{{rpu}}\",\n  \"nombre_servicio\": \"NOMBRE COMO APARECE EN CFE\",\n  \"modo\": \"historico_completo\",\n  \"auto_actualizar\": false,\n  \"alertas_activas\": true\n}"
            },
            "url": { "raw": "{{baseUrl}}/v1/rpus", "host": ["{{baseUrl}}"], "path": ["v1", "rpus"] }
          },
          "response": []
        },
        {
          "name": "4.4 Listar RPUs (paginado + filtros)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/rpus?limit=50&offset=0",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "rpus"],
              "query": [
                { "key": "limit", "value": "50" },
                { "key": "offset", "value": "0" },
                { "key": "customer_id", "value": "{{customerId}}", "disabled": true },
                { "key": "estado", "value": "activo", "disabled": true, "description": "pendiente | activo | fallido | pausado | archivado" },
                { "key": "buscar", "value": "", "disabled": true, "description": "Texto en numero_rpu o nombre_servicio" }
              ]
            }
          },
          "response": []
        },
        {
          "name": "4.5 Obtener RPU por número CFE",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/rpus/{{rpu}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "rpus", "{{rpu}}"]
            }
          },
          "response": []
        },
        {
          "name": "4.6 Archivar RPU + encolar baja en MiEspacio CFE",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/rpus/{{rpu}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "rpus", "{{rpu}}"]
            }
          },
          "response": []
        },
        {
          "name": "4.7 Forzar scrape ad-hoc (solo Enterprise)",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/rpus/{{rpu}}/refresh",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "rpus", "{{rpu}}", "refresh"]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "5. Recibos (endpoint principal de Volty)",
      "item": [
        {
          "name": "5.1 Recibos de un RPU (auto-detecta tarifa)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/rpus/{{rpu}}/recibos",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "rpus", "{{rpu}}", "recibos"]
            }
          },
          "response": []
        },
        {
          "name": "5.2 Recibos con límite explícito",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/rpus/{{rpu}}/recibos?limite=24",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "rpus", "{{rpu}}", "recibos"],
              "query": [{ "key": "limite", "value": "24", "description": "1-120" }]
            }
          },
          "response": []
        },
        {
          "name": "5.3 Descargar recibos — modo `ultimo` (sync con polling) ⭐ flow rápido recomendado",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"nombre_titular\": \"NOMBRE TAL CUAL APARECE EN EL ÚLTIMO RECIBO\",\n  \"metadata\": {\n    \"installer_id\": \"opcional_tu_id_interno_de_usuario\"\n  }\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/v1/rpus/{{rpu}}/recibos/descargar?modo=ultimo",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "rpus", "{{rpu}}", "recibos", "descargar"],
              "query": [
                { "key": "modo", "value": "ultimo", "description": "Único recibo más reciente. Sync con fallback async." }
              ]
            },
            "description": "**El endpoint principal de Volty.** Le pasas un RPU + nombre del titular y te devolvemos el último recibo en 1 sola request — sin polling, sin webhooks intermedios. Es la UX que diferencia a Volty.\n\nEn modo `ultimo` nos quedamos esperando hasta 90 segundos para devolverte el PDF y XML del recibo más reciente. Si todo sale bien, recibes un `200` con todo listo para leer.\n\nSi el portal de CFE se pone lento ese día (suele pasar en horas pico), te devolvemos un `202` con un `job_id` y tú vas a `GET /v1/jobs/{job_id}` cada 10–15 segundos hasta que el job llegue a un **estado final**. Es nuestra forma de no dejarte colgado en una request HTTP que se eternice.\n\n### Cuándo dejar de polear\n\nUn job pasa por `en_cola` → `corriendo` y termina en uno de cuatro estados finales:\n\n| Estado final | Qué significa |\n|---|---|\n| `exitoso` | Se descargaron todos los recibos pedidos. |\n| `parcial` | Se descargaron algunos y otros no. Revisa `progreso_hecho` y `progreso_fallido`. **Es final: nunca va a pasar a `exitoso`.** |\n| `fallido` | No se pudo completar. El motivo viene en `error_mensaje`. |\n| `cancelado` | El job se canceló manualmente. |\n\nDetén el loop cuando el estado sea **cualquiera de esos cuatro**, no solo `exitoso`, y ponle un tope duro de intentos o de tiempo.\n\n### Lo que puedes recibir\n\n- **200 con cache hit (~50 ms)**: ya teníamos el recibo en cache global. Te lo devolvemos sin ir al portal. `nombre_titular` se ignora cuando hay cache hit porque el dato cacheado ya está validado.\n\n- **200 con scrape completado (30–90 s)**: hicimos el scrape en línea. Bills + URLs presigned a PDF y XML (TTL 300 s).\n\n- **202 con `razon=timeout_sync`**: el scrape se está tomando más de 90 s. Te damos un `job_id` para polear.\n\n- **202 con `razon=pool_saturado`**: todas las cuentas del pool están ocupadas o en cooldown. El job se encola y arranca en cuanto se libere una credencial.\n\n- **4xx con `error.mensaje_cfe`**: CFE rechazó el alta con un mensaje específico (\"el nombre no coincide\", \"el RPU no existe\", \"el total a pagar no coincide\"). Devolvemos el texto literal en `error.mensaje_cfe` para que sepas qué corregir.\n\n### Requisito de scope\n\nTu API key debe tener scope `recibos:ultimo`. Si no lo tiene → 403 con `codigo=modo_no_contratado` y la lista de modos disponibles para tu plan."
          },
          "response": []
        },
        {
          "name": "5.4 Descargar recibos — modo `ultimos_12` (async, ideal para GDMTH)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"nombre_titular\": \"NOMBRE TAL CUAL APARECE EN EL ÚLTIMO RECIBO\",\n  \"metadata\": {\n    \"installer_id\": \"opcional_tu_id_interno_de_usuario\"\n  }\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/v1/rpus/{{rpu}}/recibos/descargar?modo=ultimos_12",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "rpus", "{{rpu}}", "recibos", "descargar"],
              "query": [
                { "key": "modo", "value": "ultimos_12", "description": "Últimos 12 recibos (recomendado GDMTH). Siempre async." }
              ]
            },
            "description": "Trae los últimos 12 recibos del RPU. Ideal para tarifas GDMTH (horarias industriales) donde análisis de demanda requiere histórico. Como puede tomar varios minutos, siempre va por la vía async — te damos el `job_id` desde el primer segundo.\n\n### Lo que recibes\n\n- **202 con `job_id` y `razon=modo_async`**: aceptamos el trabajo. Vete a `GET /v1/jobs/{job_id}` cada 30–60 segundos. Cuando `estado=exitoso`, los recibos quedan disponibles vía `GET /v1/rpus/{numero_rpu}/recibos`.\n\n- **202 con `razon=pool_saturado`**: pool ocupado. El job se encola y arranca cuando hay capacidad.\n\n- **4xx con `error.mensaje_cfe`**: rechazo del portal CFE con mensaje literal.\n\n### Requisito de scope\n\nTu API key debe tener scope `recibos:ultimos_12`."
          },
          "response": []
        },
        {
          "name": "5.5 Descargar recibos — modo `historico` (async, todo el historial)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"nombre_titular\": \"NOMBRE TAL CUAL APARECE EN EL ÚLTIMO RECIBO\",\n  \"metadata\": {\n    \"installer_id\": \"opcional_tu_id_interno_de_usuario\"\n  }\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/v1/rpus/{{rpu}}/recibos/descargar?modo=historico",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "rpus", "{{rpu}}", "recibos", "descargar"],
              "query": [
                { "key": "modo", "value": "historico", "description": "Histórico completo del RPU. Siempre async." }
              ]
            },
            "description": "Trae todo el historial disponible del RPU — útil para onboarding tipo Fleet donde necesitas la vida útil completa del cliente. Como puede tomar varios minutos (12-30 recibos típicos), siempre va por la vía async.\n\n### Lo que recibes\n\n- **202 con `job_id` y `razon=modo_async`**: aceptamos el trabajo. Polea `GET /v1/jobs/{job_id}` cada 30–60 segundos.\n\n- **202 con `razon=pool_saturado`**: pool ocupado, encolado para arrancar cuando libere capacidad.\n\n- **4xx con `error.mensaje_cfe`**: rechazo del portal CFE con mensaje literal (antes incluso de empezar el histórico).\n\n### Requisito de scope\n\nTu API key debe tener scope `recibos:historico`."
          },
          "response": []
        }
      ]
    },
    {
      "name": "6. Jobs (monitoreo de scrapes)",
      "item": [
        {
          "name": "6.1 Listar jobs (paginado + filtros)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/jobs?limit=50&offset=0",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "jobs"],
              "query": [
                { "key": "limit", "value": "50" },
                { "key": "offset", "value": "0" },
                { "key": "estado", "value": "corriendo", "disabled": true, "description": "en_cola | corriendo | exitoso | parcial | fallido | cancelado" },
                { "key": "tipo", "value": "descarga_inicial", "disabled": true },
                { "key": "rpu_id", "value": "", "disabled": true }
              ]
            }
          },
          "response": []
        },
        {
          "name": "6.2 Obtener detalle de un job",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/jobs/{{jobId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "jobs", "{{jobId}}"]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "7. Webhooks (notificaciones push)",
      "item": [
        {
          "name": "7.1 Crear webhook (con API key)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"nombre\": \"Webhook principal de eventos\",\n  \"url\": \"https://tu-backend.ejemplo.com/volty-events\",\n  \"eventos\": [\n    \"bill.created\",\n    \"cfe.down\",\n    \"rpu.alta_fallo\"\n  ]\n}"
            },
            "url": { "raw": "{{baseUrl}}/v1/webhooks", "host": ["{{baseUrl}}"], "path": ["v1", "webhooks"] }
          },
          "response": []
        },
        {
          "name": "7.2 Histórico de deliveries (debug)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/webhooks/{{webhookId}}/deliveries?limit=50&offset=0",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "webhooks", "{{webhookId}}", "deliveries"],
              "query": [
                { "key": "limit", "value": "50" },
                { "key": "offset", "value": "0" }
              ]
            }
          },
          "response": []
        }
      ]
    }
  ]
}
