API de Propuls — documentación para desarrolladores

1. Acceso por plan

👑 BUSINESS — Solo lectura

• GET prospectos, ofertas, presupuestos/facturas, estadísticas
• 100 solicitudes/hora
• Cualquier solicitud POST / PATCH / DELETE devuelve 403

💎 PLATINUM — Lectura + Escritura

• Todo Business + creación / modificación / eliminación
• Prospectos, ofertas, presupuestos/facturas, IA, citas
• 500 solicitudes/hora

2. Autenticación

Todas las solicitudes incluyen un Bearer token en la cabecera Authorization.

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects

Genera tu clave desde Ajustes → Claves API.

3. Endpoints

GET/prospectsBusiness + Platinum

Lista de prospectos (filtros: status, country, limit, offset).

Ejemplo cURL

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects?limit=50

GET/prospects/{id}Business + Platinum

Detalle de un prospecto.

Ejemplo cURL

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

GET/prospects/{id}/proposalsBusiness + Platinum

Ofertas comerciales de un prospecto.

Ejemplo cURL

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

GET/documentsBusiness + Platinum

Lista de presupuestos/facturas (filtros: type, status).

Ejemplo cURL

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/documents?type=invoice&status=paid

GET/statsBusiness + Platinum

Estadísticas (period=month|quarter|year).

Ejemplo cURL

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/stats?period=month

POST/prospectsSolo Platinum

Crear un prospecto. Reservado al plan Platinum.

Body

{ "name": "Jane Doe", "company": "Acme", "email": "jane@acme.io", "budget": 5000, "currency": "EUR" }

Ejemplo cURL

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","company":"Acme"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects

PATCH/prospects/{id}Solo Platinum

Actualizar un prospecto. Reservado al plan Platinum.

Body

{ "status": "won", "budget": 8000 }

Ejemplo cURL

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"won"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

DELETE/prospects/{id}Solo Platinum

Eliminar un prospecto. Reservado al plan Platinum.

Ejemplo cURL

curl -X DELETE -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

POST/prospects/{id}/proposalsSolo Platinum

Crear una oferta. Reservado al plan Platinum.

Body

{ "title": "Refonte site", "amount": 3500, "currency": "EUR" }

Ejemplo cURL

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"title":"Refonte"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

PATCH/proposals/{id}Solo Platinum

Actualizar una oferta. Reservado al plan Platinum.

Body

{ "status": "sent" }

Ejemplo cURL

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"sent"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/proposals/ID

POST/prospects/{id}/documentsSolo Platinum

Crear un presupuesto o una factura. Reservado al plan Platinum.

Body

{ "type": "invoice", "amount": 2500, "currency": "EUR" }

Ejemplo cURL

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"type":"invoice","amount":2500}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/documents

POST/emails/generateSolo Platinum

Generar un email IA personalizado. Reservado al plan Platinum.

Body

{ "prospect_id": "...", "template": "first_contact" }

Ejemplo cURL

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/emails/generate

POST/whatsapp/generateSolo Platinum

Generar un mensaje de WhatsApp con IA. Reservado al plan Platinum.

Body

{ "prospect_id": "...", "template": "relance douce" }

Ejemplo cURL

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/whatsapp/generate

4. Ejemplos cURL por plan

Elige la sección que corresponde a tu plan. Las solicitudes de escritura con una clave Business devuelven un 403 plan_forbidden_write.

👑 BUSINESS

Ejemplos Business (solo lectura)

GET/prospects

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects?limit=50

GET/prospects/{id}

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

GET/prospects/{id}/proposals

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

GET/documents

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/documents?type=invoice&status=paid

GET/stats

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/stats?period=month

💎 PLATINUM

Ejemplos Platinum (lectura + escritura)

GET/prospects

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects?limit=50

GET/prospects/{id}

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

GET/prospects/{id}/proposals

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

GET/documents

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/documents?type=invoice&status=paid

GET/stats

curl -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/stats?period=month

POST/prospects

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","company":"Acme"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects

PATCH/prospects/{id}

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"won"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

DELETE/prospects/{id}

curl -X DELETE -H "Authorization: Bearer sk_live_xxx" \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID

POST/prospects/{id}/proposals

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"title":"Refonte"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/proposals

PATCH/proposals/{id}

curl -X PATCH -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"status":"sent"}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/proposals/ID

POST/prospects/{id}/documents

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"type":"invoice","amount":2500}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/prospects/PROSPECT_ID/documents

POST/emails/generate

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/emails/generate

POST/whatsapp/generate

curl -X POST -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" -d '{"prospect_id":"..."}' \
  https://propulse-ton-freelance.lovable.app/api/public/v1/whatsapp/generate

5. Ejemplos de código

Python

import requests
r = requests.get(
  "https://propulse-ton-freelance.lovable.app/api/public/v1/prospects",
  headers={"Authorization": "Bearer sk_live_xxx"}
)
print(r.json())

JavaScript

const r = await fetch(
  "https://propulse-ton-freelance.lovable.app/api/public/v1/prospects",
  { headers: { Authorization: "Bearer sk_live_xxx" } }
);
console.log(await r.json());

6. Códigos de error y mensajes accionables

Cada error devuelve un JSON estructurado: { error, code, upgrade_url?, docs_url?, retry_after_seconds?, limit_per_hour? }. code — para mostrar un mensaje traducido y proponer la acción correspondiente al usuario.

HTTP	code	Significado y acción recomendada
401	invalid_key	Clave API inválida o revocada. Genera una nueva clave en Ajustes → Claves API.
403	plan_no_api_access	El plan no da acceso a la API. Mensaje sugerido: «Esta acción requiere un plan Business o Platinum — mejorar de plan ».
403	plan_forbidden_write	Solicitud de escritura (POST/PATCH/DELETE) con una clave Business. Mensaje sugerido: «Esta acción requiere el plan Platinum — mejorar ». La URL de la acción se entrega en `upgrade_url`.
400	—	Campo ausente o inválido. Corrige el payload.
404	—	Recurso no encontrado.
429	rate_limited	Cuota horaria alcanzada (100/h Business · 500/h Platinum). El body incluye `retry_after_seconds` & `limit_per_hour`. Mensaje sugerido: «Límite de solicitudes alcanzado, reinténtalo en X minutos — ver los rate limits ». La cabecera HTTP `Retry-After`.
500	internal_error	Error temporal del servidor. Reinténtalo o contacta con soporte.

Ejemplo 403 (Business POST):

{
  "error": "This action requires the Platinum plan. Business API keys are read-only.",
  "code": "plan_forbidden_write",
  "upgrade_url": "https://propulse-ton-freelance.lovable.app/app/upgrade",
  "docs_url": "https://propulse-ton-freelance.lovable.app/docs/api"
}

Ejemplo 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": "Rate limit exceeded (100/hour). Retry in a few minutes.",
  "code": "rate_limited",
  "retry_after_seconds": 3600,
  "limit_per_hour": 100,
  "docs_url": "https://propulse-ton-freelance.lovable.app/docs/api#rate-limits"
}

7. Límites por endpoint (rate limits detallados)

Todas las solicitudes de la v1 comparten el mismo contador horario por cuenta (endpoint interno api_v1): 100 req/h en Business, 500 req/h en Platinum. El contador se reduce con cada solicitud autenticada, sea cual sea el verbo.

Método	Endpoints	Business (solo lectura)	Platinum
GET	/prospects, /prospects/:id, /prospects/:id/proposals, /prospects/:id/documents, /proposals/:id, /documents, /stats	✅ 100 req/h	✅ 500 req/h
POST	/prospects, /prospects/:id/proposals, /prospects/:id/documents, /emails/generate, /whatsapp/generate	❌ 403 `plan_forbidden_write`	✅ 500 req/h
PATCH	/prospects/:id, /proposals/:id	❌ 403 `plan_forbidden_write`	✅ 500 req/h
DELETE	/prospects/:id	❌ 403 `plan_forbidden_write`	✅ 500 req/h

Ejemplo 429 — cuota de lectura superada (GET):

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": "Rate limit exceeded (100/hour). Retry in a few minutes.",
  "code": "rate_limited",
  "retry_after_seconds": 3600,
  "limit_per_hour": 100,
  "docs_url": ".../docs/api#rate-limits"
}

Ejemplo 403 — escritura con una clave Business:

HTTP/1.1 403 Forbidden

{
  "error": "This action requires the Platinum plan. Business API keys are read-only.",
  "code": "plan_forbidden_write",
  "upgrade_url": ".../app/upgrade",
  "docs_url": ".../docs/api"
}

Buenas prácticas:

Respeta la cabecera Retry-After en lugar de reintentar de inmediato.
Aplica un backoff exponencial (2s → 4s → 8s → …) en los errores 429 y 500.
Agrupa las lecturas: prefiere un GET /prospects?limit=100 a 100 GET /prospects/:id.
Cachea en el cliente las respuestas GET /stats.