urieljareth/cotizador
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4ee87f1a26ea3dabf02761220ba80fca003a027a
cotizador/api/COTIZADOR_API_SKILL.md
T
urieljareth 31cdce03a0 1
2026-06-10 02:04:37 -06:00

12 KiB
Raw Blame History

Cotizador E3 — API Documentation for AI Skills

Overview

REST API for Consultoría E3's digital marketing quotation system. Allows AI agents to manage clients, browse service catalogs, create quotations, calculate financing, generate PDF/Excel documents, and manage the full sales pipeline.

Base URL: http://localhost:8000 Auth: API Key via X-API-Key header or Authorization: Bearer <key> Content-Type: application/json OpenAPI Spec: GET /openapi.json (no auth required)

Domain Context

Consultoría E3 is a digital marketing agency in Querétaro, México. Services are organized in 4 project phases:

  • Fase 0 — Auditoría / Acompañamiento: Initial assessments and ongoing consulting
  • Fase 1 — Setup e Infraestructura: One-time setup (websites, branding, CRM config)
  • Fase 2 — Publicidad y Manejo: Ongoing advertising and social media management
  • Fase 3 — Contenido y SEO: Content creation and search engine optimization

Two payment types:

  • unico: One-time payment
  • mensual: Monthly recurring payment

Currency: MXN (Mexican Pesos) or USD. IVA (tax) rate: 16%.

Authentication

API Key (for agents)

X-API-Key: your-api-key-here

or

Authorization: Bearer your-api-key-here

JWT (for human login)

POST /auth/login
Body: { "email": "[email protected]", "password": "secret" }
Response: { "user": { "id", "name", "email", "role" } }
Sets cookie: cotizador-session (httpOnly, 7 days)

Endpoints Reference

Health & Info

GET /health

Health check endpoint. No auth required.

  • Response: { "status": "ok", "timestamp": "2026-05-03T..." }

GET /api-info

API capabilities and version info.

  • Response: { "name": "Cotizador E3 API", "version": "1.0.0", "capabilities": [...] }

Clients (Clientes)

GET /clientes

List clients with optional search and pagination.

  • Query params: ?q=texto&page=1&limit=50
  • Response: { "data": [Cliente], "meta": { "total", "page", "limit", "pages" } }

POST /clientes

Create a new client.

  • Body:
{
  "nombre": "Juan Pérez",
  "empresa": "ACME Corp",
  "email": "[email protected]",
  "telefono": "4421234567"
}
  • Response (201): Full Cliente object with id

GET /clientes/{id}

Get client details including recent quotations.

  • Response: Cliente object + cotizaciones array

PUT /clientes/{id}

Update client information.

  • Body: Same as POST (all fields optional for update)

DELETE /clientes/{id}

Delete client. Returns 409 if client has quotations.

  • Response (200): { "ok": true }
  • Error (409): { "error": "Cliente tiene N cotizaciones asociadas" }

List all active services with optional filters.

  • Query params: ?fase=0&tipoPago=mensual&categoriaId=xxx&q=seo
  • Response: Array of ServicioCatalogo objects

Each service:

{
  "id": "cuid",
  "nombre": "Posicionamiento SEO",
  "descripcion": "...",
  "fase": 3,
  "tipoPago": "mensual",
  "precioBase": 2900,
  "tiempoEntrega": "7 - 14 dias",
  "entregablesDefault": ["Keyword research", "On-page optimization"],
  "categoriaId": "cuid",
  "variante": null,
  "activo": true,
  "orden": 0
}

Create a new service.

  • Body:
{
  "nombre": "Nuevo Servicio",
  "descripcion": "Descripción del servicio",
  "fase": 1,
  "tipoPago": "unico",
  "precioBase": 5000,
  "tiempoEntrega": "7 - 14 dias",
  "entregablesDefault": ["Entregable 1", "Entregable 2"],
  "categoriaId": "cuid",
  "variante": null,
  "orden": 0
}

GET /catalogo/{id}

Get service details with category info.

PUT /catalogo/{id}

Update service. Same body as POST.

DELETE /catalogo/{id}

Soft-delete if used in quotations, hard-delete otherwise.

  • Response: { "ok": true, "archived": true|false }

Categories (Categorías)

Available: SEO (#10b981), Marketing (#6366f1), Paid Media (#f59e0b), Desarrollo Web (#3b82f6), Automatizaciones (#8b5cf6), CRM (#ec4899), Desarrollo Personalizado (#14b8a6)

GET /categorias

List all categories ordered by orden.

POST /categorias

  • Body: { "nombre": "Nueva Cat", "descripcion": "...", "color": "#6b7280", "orden": 0 }

GET /categorias/{id}

Get category with its services.

PUT /categorias/{id}

  • Body: { "nombre", "descripcion", "color", "orden", "activo" }

DELETE /categorias/{id}

Returns 409 if category has associated services.

Quotations (Cotizaciones)

GET /cotizaciones

List quotations with filters.

  • Query params: ?estado=borrador&asesorId=xxx&clienteId=xxx&q=texto&desde=2026-01-01&hasta=2026-12-31&page=1&limit=50
  • Response: Array with full relations (cliente, asesor, servicios+catalogo, planBucefalo)

POST /cotizaciones

Create a complete quotation. Auto-creates client if not found.

  • Body:
{
  "numero": "UJ2605AG001",
  "fecha": "2026-05-03",
  "vigencia": "2026-05-24",
  "moneda": "MXN",
  "tipoCambio": "NA",
  "proyecto": "MKT Digital",
  "esquemaPago": "Pago Unico/Mensual",
  "incluirBonos": false,
  "incluirFinanciamiento": false,
  "observaciones": "",
  "asesorId": "cuid",
  "cliente": {
    "nombre": "Juan Pérez",
    "empresa": "ACME Corp",
    "email": "[email protected]",
    "telefono": "4421234567"
  },
  "servicios": [
    {
      "catalogoId": "cuid",
      "nombre": "SEO On-Page",
      "fase": 3,
      "tipoPago": "mensual",
      "precio": 2900,
      "tiempoEntrega": "7 - 14 dias",
      "entregables": ["Keyword research", "On-page SEO"]
    }
  ],
  "planBucefalo": {
    "nivel": "basico",
    "precio": 1000
  }
}

GET /cotizaciones/{id}

Get quotation with all relations.

PUT /cotizaciones/{id}

Update quotation. Replaces all services in a transaction.

  • Body: Same as POST without numero and asesorId. Optional estado.

DELETE /cotizaciones/{id}

Hard-delete with cascade.

PATCH /cotizaciones/{id}/precio

Update price of a single service.

  • Body: { "servicioId": "cuid", "precio": 7500 }

PATCH /cotizaciones/{id}/estado

Change quotation status.

  • Body: { "estado": "enviada" } — borrador, enviada, aprobada, rechazada

POST /cotizaciones/{id}/duplicate

Duplicate quotation as new copy in borrador state.

Packages (Paquetes)

GET /paquetes

List active packages with nested phases and services.

POST /paquetes

  • Body:
{
  "nombre": "Paquete Básico",
  "descripcion": "...",
  "fases": [
    { "nombre": "Auditoría", "orden": 0 },
    { "nombre": "Setup", "orden": 1 }
  ]
}

GET /paquetes/{id}

Get package with full nested structure.

PUT /paquetes/{id}

  • Body: { "nombre", "descripcion", "activo" }

DELETE /paquetes/{id}

Hard-delete with cascade.

POST /paquetes/{id}/manage

Multi-action endpoint:

  • { "action": "addFase", "nombre": "Fase 3", "orden": 2 }
  • { "action": "updateFase", "faseId": "cuid", "nombre": "New Name", "orden": 1 }
  • { "action": "deleteFase", "faseId": "cuid" }
  • { "action": "addServicio", "servicioCatalogoId": "cuid", "fasePaqueteId": "cuid" }
  • { "action": "removeServicio", "servicioCatalogoId": "cuid", "fasePaqueteId": "cuid" }

Configuration (Configuración)

Allowed keys: color_primario, color_secundario, logo_base64, razon_social, rfc, domicilio_fiscal, cuenta_nacional, clabe_interbancaria, cuenta_internacional, cuenta_internacional_swift, hora_centinela, anualidad_hosting, iva, terminos_condiciones, no_incluye, notas_adicionales

GET /configuracion

  • Response: { "color_primario": "#2563eb", "razon_social": "...", ... }

PUT /configuracion

Bulk upsert. Only whitelisted keys processed.

  • Body: { "color_primario": "#ff0000", "razon_social": "Nuevo Nombre" }

Bonuses (Bonos)

Available: Centinela Web, Workshop Buyer Persona, Workshop Propuesta de Valor, Membresía Premium, Mes Gratis CRM, Script de Ventas

GET /bonos

Financing (Financiamiento)

Months Rate Commission Min Amount
3 7.7% 2.5% $300
6 10.7% 2.5% $600
9 13.7% 2.5% $900
12 16.7% 2.5% $1,200

GET /financiamiento/planes

POST /financiamiento/calcular

  • Body: { "monto": 50000, "meses": 6 }
  • Response: { "pagoMensual", "ivaMensual", "totalMensual", "comisionTotal", "granTotal" }

GET /financiamiento/simulacion/{cotizacion_id}

Auto-calculate financing for existing quotation.

Export

POST /export/pdf — PDF from draft data

GET /export/pdf/{id} — PDF from saved quotation

POST /export/excel — Excel from draft data

GET /export/excel/{id} — Excel from saved quotation

GET /export/catalogo — CSV of active services

GET /export/catalogo/plantilla — CSV import template

Import

Bulk import services from CSV. multipart/form-data with file field.

  • Response: { "creados": 5, "omitidos": 2, "errores": [...] }

Business Rules

Quotation Number

Format: UJ{YY}{MM}{AsesorInitials}{sequence} — e.g., UJ2605AG001

Quotation Validity

15 business days from issue (excludes Sat/Sun).

CRM Bucefalo Plans

basico=$1,000/mes, estandar=$3,500/mes, premium=$4,500/mes, empresarial=$7,500/mes

Client Deduplication

Matched by (nombre, empresa) pair.

Service Soft-Delete

If referenced by quotations → activo=false. Otherwise hard-delete.

Financing Formula

comisionTotal = monto × comision%
montoConComision = monto + comisionTotal
pagoMensual = montoConComision × (1 + tasa) / meses
ivaMensual = pagoMensual × 0.16
totalMensual = pagoMensual + ivaMensual
granTotal = totalMensual × meses

Common Responses

Success (paginated)

{
  "data": [...],
  "meta": { "total": 45, "page": 1, "limit": 50, "pages": 1 }
}

Error

{ "error": "Message", "detail": "Details", "code": "ERROR_CODE" }

HTTP Codes

200=OK, 201=Created, 204=No Content, 400=Bad Request, 401=Unauthorized, 404=Not Found, 409=Conflict, 500=Server Error

Agent Workflows

Create quotation

1. GET /catalogo?fase=0          → audit services
2. GET /catalogo?fase=1          → setup services
3. GET /catalogo?fase=2&tipoPago=mensual → ongoing services
4. POST /financiamiento/calcular → simulate payments
5. POST /cotizaciones            → create quotation
6. GET /export/pdf/{id}          → generate PDF

Review pipeline

1. GET /cotizaciones?estado=borrador  → pending
2. GET /cotizaciones?estado=enviada   → awaiting
3. GET /cotizaciones?estado=aprobada  → won

Negotiate price

1. GET /cotizaciones/{id}          → current state
2. PATCH /cotizaciones/{id}/precio → adjust price
3. GET /export/pdf/{id}            → regenerate PDF

MCP Integration

MCP server at /mcp for OpenClaw, Claude, ChatGPT.

Tools

Tool Description
buscar_servicios Search catalog by phase, payment type, category, text
crear_cotizacion Create complete quotation in one call
obtener_cotizacion Get quotation details
listar_cotizaciones List with filters
cambiar_estado_cotizacion Change status
actualizar_precio_servicio Adjust service price
duplicar_cotizacion Clone as draft
calcular_financiamiento Calculate payments
generar_pdf_cotizacion Generate PDF
obtener_configuracion Company config
listar_bonos Available bonuses
listar_planes_bucefalo CRM plans

Resources

Resource Description
cotizador://servicios Full catalog
cotizador://categorias Categories
cotizador://configuracion Company config

Environment

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=cotizador_e3
API_KEY=your-secret-api-key
JWT_SECRET=your-jwt-secret

Run

pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000
# Swagger: http://localhost:8000/docs
# ReDoc: http://localhost:8000/redoc
# OpenAPI: http://localhost:8000/openapi.json
Reference in New Issue View Git Blame Copy Permalink