API REST — Documentación

Integra 1invoice.online con tus propios sistemas. La API sigue convenciones REST y devuelve JSON. Estable bajo /api/v1 — incrementamos versión ante breaking changes.

Inicio rápido

Inicia sesión y ve a Ajustes → API REST
Haz clic en «Crear clave», dale un nombre y copia el valor (solo se muestra una vez)
Envía la clave en el header Authorization: Bearer 1iv_... en tus peticiones

Autenticación

Todos los endpoints requieren un token Bearer en el header Authorization. Las claves están vinculadas a la organización donde se crearon — solo puedes leer datos de tu propia org.

Authorization: Bearer 1iv_<tu clave>

Respuestas de error

401 Unauthorized — falta el header o la clave es inválida/revocada
500 Internal Server Error — error de base de datos; reintenta o contáctanos

Discovery

GET /api/v1

Devuelve la lista de endpoints disponibles. No requiere credenciales.

Miembros

GET /api/v1/members?limit=50&offset=0&status=active

Devuelve los miembros de tu organización. Paginado.

limit — elementos por página (por defecto 50, máx. 200)
offset — posición de inicio (por defecto 0)
status — filtro por active, inactive, pending

Presupuestos

GET /api/v1/quotes?status=accepted

Devuelve presupuestos con estado, total, public_token e info de firma.

Facturas

GET /api/v1/invoices?status=paid

Devuelve facturas con estado de pago y fecha de vencimiento.

Webhooks

Registra una URL en Ajustes → Webhooks. Cuando ocurre un evento, hacemos POST con JSON usando estos headers:

X-1Invoice-Event — nombre del evento (p. ej. invoice.paid)
X-1Invoice-Signature — HMAC-SHA256 del body crudo con tu secret (hex)
User-Agent: 1invoice-webhooks/1

Eventos disponibles

invoice.created, invoice.sent, invoice.paid
quote.created, quote.sent, quote.accepted, quote.rejected

Rate limits

Límite blando: 60 peticiones/minuto por clave. Si te excedes recibes 429 Too Many Requests. ¿Necesitas más? Escríbenos — lo subimos a petición.

Versioning

Usamos versioning por URL. /api/v1 es estable. Los breaking changes pasan a /api/v2 con al menos 6 meses de funcionamiento en paralelo.

Estado y changelog

Consulta la hoja de ruta para el estado actual. Anunciamos cambios de API con al menos 30 días de aviso vía webhooks y banner del panel.

¿Preguntas sobre integración?
Contáctanos — te acompañamos. La primera integración suele durar menos de una hora.