API

Olvano dispone de una API REST para conectar tus propios sistemas — crea y consulta facturas, gestiona contactos y escucha eventos mediante webhooks. Esta página te lleva desde la obtención de un token hasta tu primera llamada; la lista completa y ejecutable de endpoints está en la referencia interactiva.

Antes de empezar

Necesitas dos cosas:

1. Una cuenta en el plan byznys (el plan gratuito no incluye API).
2. Un token de API vinculado a esa cuenta (ver más abajo).

Los tokens los crea el propietario de la cuenta. Cada token pertenece a exactamente una cuenta y lleva sus propios permisos (scopes), de modo que puedes emitir un token distinto por integración.

Crear un token de API

En la aplicación ve a Configuración → Tokens de API (/app/{slug}/settings/api-tokens), elige Nuevo token, dale un nombre y selecciona sus permisos. El token en texto plano se muestra una sola vez — cópialo de inmediato y guárdalo en un lugar seguro.

Los tokens llevan el prefijo sg_. Solo se almacena un resumen HMAC, por lo que el token no puede volver a mostrarse — si lo pierdes, crea uno nuevo y elimina el antiguo.

Permisos (scopes)

Leer (GET) recursos comunes no requiere ningún scope; escribir sí. Las operaciones exclusivas del propietario (gestión de tokens, webhooks y cuentas bancarias) nunca están disponibles para un token de API — incluso uno emitido por un propietario devuelve 403.

Autenticación y URL base

Autentifica cada solicitud con el token en la cabecera Authorization:

Authorization: Bearer sg_your_token

La URL base es el dominio de tu instancia + /api. Los endpoints de cuenta tienen la forma /api/accounts/{slug}/…. Los ejemplos de abajo usan variables de entorno:

export STARGATE="https://app.stargate.app"   # replace with your instance domain (locally http://localhost:3000)
export SLUG="your-account-slug"
export TOKEN="sg_your_token"

Tu primera solicitud

Lista las facturas de una cuenta:

curl "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN"

La respuesta es una lista paginada:

{
  "invoices": [ { "id": "…", "number": "2026-0001", "status": "open", "total": "3630.00" } ],
  "total": 128,
  "page": 1,
  "pageSize": 40
}

Paginación, ordenación y búsqueda

Los endpoints de lista aceptan estos parámetros de consulta:

Las facturas también se pueden filtrar por status, documentType y subjectId. Un parámetro inválido nunca rompe el listado — se usa el valor por defecto en su lugar (p. ej. ?page=abc → 1). Cada respuesta incluye total, page y pageSize, por lo que el número de páginas es fácil de calcular.

Crear una factura

curl -X POST "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": "CUSTOMER_ID",
    "lines": [
      { "name": "Consulting", "quantity": 2, "unitPrice": "1500", "vatRate": 21 }
    ]
  }'

subjectId es el identificador del cliente — obtenlo desde el listado de contactos (GET /api/accounts/$SLUG/subjects) o crea uno con POST …/subjects. Los campos obligatorios son subjectId y al menos una línea en lines (cada una con name y unitPrice). Opcionalmente puedes enviar documentType, currency, variableSymbol, due, issuedOn y otros — esquema completo en la referencia interactiva.

Una llamada exitosa devuelve 201 y la factura creada:

{ "invoice": { "id": "…", "number": "2026-0002", "status": "open", "total": "3630.00" } }

Errores

Los errores comparten un envoltorio consistente — un estado HTTP más JSON con statusMessage y un campo data para el tratamiento automático:

{
  "statusCode": 400,
  "statusMessage": "Invalid invoice",
  "data": { "formErrors": [], "fieldErrors": { "subjectId": ["Required"] } }
}

Para errores de dominio, data.code es un código legible por máquinas (p. ej. subject_not_found) más fiable que el texto del mensaje.

Límites del plan

El plan free no permite llamadas a la API (cuota 0); el plan byznys incluye la API y todas las funciones. Cuando se supera un límite (p. ej. número de contactos) la API devuelve 402 con plan_limit_reached; para una función fuera del plan (webhooks, gastos…) devuelve 403 con plan_feature_unavailable. Consulta los límites y el uso actuales de tu cuenta con:

curl "$STARGATE/api/accounts/$SLUG/entitlements" -H "Authorization: Bearer $TOKEN"

Webhooks

Un webhook te notifica de eventos en tiempo real, sin necesidad de sondear la API. Los webhooks son una función del plan byznys y los gestiona el propietario de la cuenta.

Regístralos mediante la API (o desde la configuración de la cuenta):

curl -X POST "$STARGATE/api/accounts/$SLUG/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/hooks/stargate",
    "events": ["invoice_paid", "invoice_sent"],
    "authHeader": "Bearer your-shared-secret"
  }'

Indica nombres concretos en events, o * para todos. Eventos disponibles:

invoice_created, invoice_sent, invoice_paid, invoice_overdue, invoice_cancelled, invoice_uncollectible, invoice_viewed, invoice_reminder_sent, recurring_generator_invoice_created.

Olvano envía un POST a tu URL con el cuerpo:

{ "event_name": "invoice_paid", "body": { "…": "event data" } }

• Si configuras authHeader, se envía como cabecera Authorization — úsalo para verificar que la solicitud proviene realmente de Olvano.
• Cada entrega lleva una cabecera Idempotency-Key (UUID) — úsala para deduplicar.
• Las entregas se reintentan hasta 5 veces con backoff exponencial hasta que tu servidor devuelva un estado 2xx. Las entregas fallidas se listan en GET …/webhooks/{id}/failed_deliveries.

Referencia interactiva

La lista completa y siempre actualizada de endpoints — con parámetros, esquemas y la posibilidad de llamarlos directamente desde el navegador:

• Abrir la referencia de la API (/api-docs)
• Esquema OpenAPI legible por máquinas: /api/_openapi.json