API para desarrolladores

Empezar

1. En la aplicación, ve a Ajustes → Conexiones → API para desarrolladores y crea una clave. Elige si es de solo lectura o si permite escribir (crear clientes y facturas en borrador). La clave completa se muestra una sola vez: guárdala en un lugar seguro.

2. Envía la clave en la cabecera Authorization de cada petición:

curl https://app-production-baa2.up.railway.app/api/v1/clients \
  -H "Authorization: Bearer lk_live_TU_CLAVE"

La URL base es https://app-production-baa2.up.railway.app/api/v1. Las respuestas son JSON y los datos van dentro de data.

Endpoints

• GET /me: el negocio al que pertenece la clave y si puede escribir.
• GET /clients: lista de clientes (limit hasta 100 y offset).
• POST /clients: crea un cliente. Requiere clave de escritura.
• GET /invoices: lista de facturas; filtra con estado (borrador, emitida, pagada, vencida o anulada).
• GET /invoices/{id}: una factura con sus líneas.
• POST /invoices: crea una factura en borrador. Requiere clave de escritura y una suscripción activa.
• GET /quotes: lista de presupuestos.

Crear una factura en borrador

curl -X POST https://app-production-baa2.up.railway.app/api/v1/invoices \
  -H "Authorization: Bearer lk_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "UUID-DEL-CLIENTE",
    "lineas": [
      { "descripcion": "Servicio de diseño", "cantidad": 3, "precioUnitario": 50, "unidad": "h", "tipoIvaPct": 21 }
    ],
    "retencionIrpfPct": 15
  }'

En lugar de clientId puedes enviar newClient con name, y opcionalmente nif, email y address. El tipo de IVA debe ser 0, 4, 10 o 21. La respuesta incluye el id, el estado (siempre borrador) y el total calculado.

La API nunca emite facturas: las deja en borrador para que las revises y las emitas desde la aplicación.

Errores y límites

• 401: falta la clave o no es válida (o está revocada).
• 403: la clave es de solo lectura y la operación escribe.
• 402: la prueba ha terminado; hay que elegir un plan para crear facturas.
• 400: datos no válidos; el mensaje indica qué campo falla.
• 429: demasiadas peticiones. El límite es de 120 por minuto y por clave.

Seguridad

Tratamos las claves como contraseñas: solo guardamos su huella, así que no podemos recuperarla; si la pierdes, crea otra. Puedes revocar cualquier clave en cualquier momento y deja de funcionar al instante. No pongas la clave en código que se ejecute en el navegador de tus clientes.

¿Necesitas algo que no está? Escríbenos desde la página de contacto y lo tenemos en cuenta.