Acceso a la API y agentes de IA

SimplyQuote expone una API REST para que tus agentes de IA, scripts e integraciones trabajen con tus presupuestos y facturas en tu nombre. El acceso se controla con tokens de acceso personales con permisos limitados y revocables.

1. Activa el acceso a la API

1. Abre tu página de ajustes e inicia sesión
2. Desplázate hasta la sección «Acceso a la API y agentes de IA».
3. Ponle nombre al token, elige los permisos y pulsa «Crear token».
4. Copia el token inmediatamente: por seguridad, solo se muestra una vez.

2. Realiza una solicitud

Envía el token como token Bearer en la cabecera Authorization:

curl https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here"

3. Crea y actualiza documentos

Para crear y actualizar presupuestos y facturas se usa el mismo token con un permiso de escritura. Los totales siempre se calculan en el servidor a partir de los artículos que envíes:

curl -X POST https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Ltd",
    "client_email": "billing@acme.example",
    "items": [
      { "description": "Consulting", "quantity": 4, "unit_price": 120 },
      { "description": "Hosting (1 month)", "quantity": 1, "unit_price": 30 }
    ],
    "currency": "USD",
    "tax_rate": 10,
    "expiry_date": "2026-10-01"
  }'

Respuesta de éxito (las listas son análogas, con quotes/invoices más total/page/limit/has_more):

// Wrapped envelope (POST/PATCH/lists): { success:true, data:{ quote } }
{
  "success": true,
  "data": {
    "quote": { "id": "uuid", "quote_number": "Q-1001", "total": 528.0 }
  }
}

curl -X PATCH https://simplyquote.net/api/v1/invoices/{id} \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

Listados y paginación

Los endpoints de listado aceptan updated_since (ISO 8601), page (por defecto 1), limit (por defecto 20, máximo 100) y status (sin distinción de mayúsculas; los valores desconocidos se ignoran). Las respuestas incluyen total, page, limit y has_more.

GET /api/v1/quotes?status=sent&page=1&limit=20&updated_since=2026-01-01T00:00:00Z

Reglas de campos para crear y actualizar

items es obligatorio en POST: array no vacío, cada línea con description no vacía, quantity > 0 (por defecto 1), unit_price >= 0 (por defecto 0). tax_rate es porcentaje (0–100); al crear, tax_rate > 0 implica tax_enabled. currency se guarda en mayúsculas. issue_date acepta cualquier fecha válida (se guarda AAAA-MM-DD). Los presupuestos usan expiry_date y las facturas due_date (se acepta cualquiera de los dos alias, null lo borra). Estado: presupuestos draft|sent, facturas draft|sent|viewed|paid|cancelled — paid registra paid_at. Los totales siempre se recalculan en el servidor.

4. Úsalo con un agente de IA

Dale a tu agente la URL base, tu token y la lista de puntos finales de abajo. Instrucciones de ejemplo para cualquier agente que use herramientas (Claude, GPT, LangChain, etc.):

Puedes acceder a mi cuenta de SimplyQuote.
URL base: https://simplyquote.net
En cada solicitud, envía la cabecera: Authorization: Bearer sq_tu_token_aqui
Puntos finales disponibles: GET/POST /api/v1/quotes, GET/PATCH /api/v1/quotes/{id},
GET/POST /api/v1/invoices, GET/PATCH /api/v1/invoices/{id}, POST /api/mcp
Las listas admiten ?page, ?limit (máx. 100), ?status y ?updated_since y devuelven { success:true, data:{ quotes|invoices, total, page, limit, has_more } }.
Las lecturas individuales devuelven el objeto sin envoltorio. {id} es el UUID, no el número de documento.
Usa POST para crear documentos: envía siempre items con description, quantity y unit_price.

5. Conexión mediante MCP (recomendado para agentes)

SimplyQuote incluye un servidor MCP (Model Context Protocol) integrado en /api/mcp (HTTP streaming sin estado, JSON-RPC 2.0). Los agentes que admiten servidores MCP remotos (Claude, ChatGPT, Cursor, VS Code, etc.) pueden conectarse directamente con tu token, sin necesidad de ingeniería de prompts. Herramientas disponibles:

list_quotesget_quotecreate_quotelist_invoicesget_invoicecreate_invoice

{
  "mcpServers": {
    "simplyquote": {
      "type": "http",
      "url": "https://simplyquote.net/api/mcp",
      "headers": {
        "Authorization": "Bearer sq_your_token_here"
      }
    }
  }
}

Ejemplo de llamada a una herramienta (JSON-RPC 2.0: se rechazan los lotes, las notificaciones devuelven 202 y GET devuelve 405):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_quotes", "arguments": { "limit": 5 } }
}

Cada llamada a una herramienta se comprueba con los permisos de tu token: un token de solo lectura puede listar y consultar, mientras que crear presupuestos o facturas requiere el permiso de escritura correspondiente.

Puntos finales

Permisos

• quotes:read — Leer tus presupuestos
• invoices:read — Leer tus facturas
• clients:read — Reservado — aún sin endpoint propio de clientes (los datos del cliente están en presupuestos/facturas)
• quotes:write — Crear y actualizar presupuestos
• invoices:write — Crear y actualizar facturas
• clients:write — Reservado — aún sin endpoint propio de clientes (los datos del cliente se crean/actualizan implícitamente al guardar presupuestos/facturas)

Formato de respuesta y errores

Los endpoints REST usan dos formatos; comprueba cuál aplica en cada caso:

{
  "success": true,
  "data": { ... },
  "error": { "code": "...", "message": "...", "details": { ... } }
}

Las lecturas individuales devuelven el objeto simple de arriba (sin envoltorio), con errores planos { error, message } — p. ej. 404 si el id no existe. Las listas y POST/PATCH usan siempre el sobre.

// Flat envelope (single GET): bare object, no success/data wrapper
{
  "id": "uuid",
  "quote_number": "Q-1001",
  "status": "sent",
  "total": 528.0
}

// unknown id:
{ "error": "not_found", "message": "Quote not found" }

• success — true si hay éxito, false si falla
• data — los datos cuando la solicitud tiene éxito
• error — código de error, mensaje y detalles opcionales cuando falla

Los códigos de error más habituales:

• UNAUTHORIZED — Falta el token, o no es válido o ha caducado (HTTP 401)
• FORBIDDEN — El token no tiene el permiso requerido (HTTP 403)
• VALIDATION_ERROR — El cuerpo de la solicitud no superó la validación (HTTP 400)
• NOT_FOUND — El documento solicitado no existe (HTTP 404)
• DATABASE_ERROR — Error de almacenamiento al procesar la solicitud (HTTP 500)
• RATE_LIMIT — Demasiadas solicitudes: reintenta más tarde (HTTP 429)

Webhooks, OAuth y referencia completa

Webhooks: gestiona suscripciones con GET/POST/PATCH/DELETE /api/v1/webhooks (cualquier token válido, sin permiso específico). La url debe ser un endpoint HTTPS público. El secreto solo se devuelve al crear — verifica las entregas con la cabecera X-SimplyQuote-Signature (HMAC-SHA256).

Las apps asociadas usan OAuth 2.0 (/api/oauth/authorize, /api/oauth/token, /api/oauth/revoke) en lugar de tokens personales. Detalles en docs/API.md y en la especificación legible por máquinas en /api/v1/openapi.json.

Notas de seguridad

• Los tokens se guardan con hash: SimplyQuote nunca conserva el token en texto plano.
• Concede solo los permisos que tu agente necesite; los de solo lectura suelen ser suficientes.
• Revoca un token en cualquier momento desde Ajustes para cortar el acceso de inmediato.
• Hay una especificación legible por máquinas para agentes en /api/v1/openapi.json