Cómo conectar tu app o ERP a la API de QuoteCrest

En la parte 1 configuramos un espacio de trabajo de QuoteCrest — Stripe, sincronización contable, tipos impositivos, condiciones y una biblioteca de artículos. Ahora conectaremos ese espacio de trabajo con tu propia aplicación o ERP para que los presupuestos fluyan por tus sistemas existentes en lugar de por una pestaña del navegador.

La REST API de QuoteCrest da a los equipos del plan Business toda la superficie de la app: presupuestos y líneas de detalle, clientes, la biblioteca de artículos, tipos impositivos, plantillas de condiciones, pagos, el generador de presupuestos con IA y los disparadores de sincronización contable. La referencia completa está en quotecrest.com/api-docs; este artículo es la visita guiada desde cero hasta la primera llamada a la API.

Paso 1: Registra una aplicación OAuth

En QuoteCrest, ve a Configuración → Desarrolladores y haz clic en Registrar aplicación. Necesitarás tres cosas:

• Nombre — se muestra a tu equipo en la pantalla de autorización ("ERP Sync", "Acme Field App").
• Redirect URI — adónde envía QuoteCrest a los usuarios después de autorizar. Debe ser HTTPS (localhost está permitido para desarrollo). Una URI por línea.
• Scopes — read para acceso de lectura, write para crear y actualizar. Solicita solo lo que necesites.

Mantén activado Cliente confidencial para apps del lado del servidor que puedan proteger un secreto. Al crearla obtienes un Client ID y — exactamente una vez — un Client Secret. Copia el secreto de inmediato; se guarda con hash y no se puede volver a mostrar.

Paso 2: Autoriza con OAuth 2.0 + PKCE

QuoteCrest usa el grant de Authorization Code con PKCE, obligatorio para todos los clientes. El flujo:

1. Genera un code verifier y un challenge. Una cadena aleatoria y su hash SHA-256, codificado en base64url:

code_verifier  = random 43-128 char string
code_challenge = base64url( sha256(code_verifier) )

2. Envía al usuario a la pantalla de autorización:

GET https://quotecrest.com/oauth/authorize
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=https://yourapp.com/callback
    &response_type=code
    &scope=read+write
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

El usuario inicia sesión, ve lo que tu app podrá hacer y aprueba. QuoteCrest redirige de vuelta a tu redirect_uri con un parámetro ?code=.

3. Intercambia el código por tokens:

curl -X POST https://quotecrest.com/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=https://yourapp.com/callback \
  -d code=AUTHORIZATION_CODE \
  -d code_verifier=CODE_VERIFIER

Recibes un access_token (válido 2 horas), un refresh_token y los scopes concedidos. Los access tokens están vinculados a un solo equipo — el equipo del usuario que autorizó. Los refresh tokens rotan en cada uso: cada refresh devuelve un par nuevo y el refresh token antiguo queda invalidado, así que persiste el par más reciente de forma atómica.

Paso 3: Haz tu primera llamada

Cada petición envía el token como cabecera Bearer. Empieza con /me, que devuelve el equipo autorizado, sus valores predeterminados (condiciones de pago, vencimiento de presupuestos, modo de precios) y los scopes de tu token:

curl https://quotecrest.com/api/v1/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

Los endpoints de listado se paginan con page y per_page (máximo 100) y devuelven un bloque meta con los totales.

Paso 4: El flujo ERP esencial

Una integración típica refleja lo que hace una persona en la app — crear el cliente, armar el presupuesto, enviarlo y estar atento a la aceptación y al pago.

Crea un cliente:

curl -X POST https://quotecrest.com/api/v1/clients \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": {"name": "Meridian Property Group", "email": "ops@meridian.example"}}'

Crea un presupuesto — los valores predeterminados del equipo (plantilla de condiciones, vencimiento, condiciones de pago, modo de precios) se aplican automáticamente a todo lo que omitas:

curl -X POST https://quotecrest.com/api/v1/quotes \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quote": {"title": "Lobby renovation", "client_id": 42, "payment_percentage": 30}}'

Añade las líneas de detalle en una sola llamada con bulk_create y después envía:

curl -X POST https://quotecrest.com/api/v1/quotes/7/line_items/bulk_create ...
curl -X POST https://quotecrest.com/api/v1/quotes/7/send \
  -H "Authorization: Bearer ACCESS_TOKEN"

send envía al cliente por correo su enlace al portal; usa publish en su lugar si tu app entrega el enlace por su cuenta. El campo portal_url del presupuesto es la página que ve el cliente, y GET /api/v1/quotes/7/pdf devuelve el PDF renderizado para tu propio archivo de documentos.

Haz seguimiento de la aceptación y el pago consultando el presupuesto (status, payment_status, payment_due) o listando /api/v1/payments — cada pago incluye el importe, las comisiones y el neto. Cuando un presupuesto se acepta con la sincronización automática activada, la factura llega a QuickBooks o Xero sin otra llamada a la API; también puedes lanzar una descarga del catálogo en cualquier momento con POST /api/v1/integrations/quickbooks/sync (o xero).

O sáltate por completo el armado manual. Una sola llamada al generador de presupuestos con IA convierte una descripción del trabajo en lenguaje natural en un borrador completo — título, alcance del trabajo y líneas con precios que usan tu biblioteca de artículos y tus categorías:

curl -X POST https://quotecrest.com/api/v1/ai_quotes \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Replace 12 windows in a two-story office, energy-efficient double glazing", "client_id": 42}'

Errores, límites y buen comportamiento

• 401 — token ausente, caducado o revocado. Refresca y reintenta.
• 403 plan_required — el equipo no está en Business. 403 feature_disabled — un feature flag (p. ej., la generación con IA) está desactivado para el equipo.
• 402 insufficient_credits — el saldo de créditos de IA del equipo está agotado.
• 422 — errores de validación, con los detalles en el cuerpo de la respuesta.
• 429 — límite de peticiones alcanzado. El tráfico general de la API se limita por IP; la generación con IA se limita a 10 peticiones por minuto por equipo. Espera y reintenta después del retraso indicado.

Dos hábitos mantendrán tu integración aburrida (en el buen sentido): trata el client secret y los refresh tokens como contraseñas — solo del lado del servidor, cifrados en reposo — y construye tu sincronización con idempotencia, comprobando si existe un registro antes de crearlo, porque tus usuarios siempre pueden editar cosas directamente en QuoteCrest.

La referencia completa de endpoints, los esquemas y los formatos de error están en quotecrest.com/api-docs. Si construyes algo sobre la API, de verdad nos encantaría saberlo.