Docs · Guías

Convenciones

Lo que vale para todos los endpoints: la URL base, JSON, paginación, dinero, fechas, ids de solicitud y cómo tratar el texto que escribió otra persona.

URL base y versiones

Todas las rutas empiezan por /v1, en el host propio de la API. El nombre del host está Por definir, así que los ejemplos usan $NOVO_API_HOST. Las solicitudes usan HTTPS y JSON; el endpoint de tokens recibe un cuerpo de formulario.

Dentro de v1, los cambios que solo añaden no rompen nada, y tu código debe ignorar los campos que no conoce propuesto.

Paginación

Las listas que pueden ser largas devuelven una página de data y un next_cursor. Devuélvelo como cursor para obtener la página siguiente; es null en la última página. Elige el tamaño de página con limit (mín. 1, máx. 100, por defecto 50).

El cursor es opaco. No construyas ni modifiques uno.
Cada página es una instantánea coherente, pero un recorrido por muchas páginas no lo es: las filas que lleguen mientras paginas pueden no aparecer. Para ponerte al día, empieza otra vez desde la primera página.
Las transacciones registradas se ordenan por fecha, de la más reciente a la más antigua, y luego por un desempate único. Las transacciones pendientes se ordenan por una clave estable.

Página siguiente

curl "https://$NOVO_API_HOST/v1/transactions?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Dinero y saldos

Los importes son cadenas decimales con dos decimales y una moneda, nunca números de coma flotante. Hoy la moneda es siempre USD.

Los importes de las transacciones nunca son negativos. Un campo aparte, direction, indica si el dinero entró (credit) o salió (debit).
Los saldos llevan signo. Un saldo negativo significa que la cuenta está en sobregiro.
Una cuenta tiene tres saldos: available, current y spendable, que es el saldo disponible menos los fondos reservados.

balance

{
  "available": {
    "amount": "1250.00",
    "currency": "USD"
  },
  "current": {
    "amount": "1300.00",
    "currency": "USD"
  },
  "spendable": {
    "amount": "1150.00",
    "currency": "USD"
  }
}

Fechas e ids

Las fechas siguen ISO 8601: YYYY-MM-DD para fechas y marcas de tiempo completas para horas. Los ids son cadenas opacas. Para congelar una tarjeta, su id debe ser un UUID; cualquier otra cosa es un 400 invalid-parameter antes de que Novo busque nada.

Números ocultos

Los números de cuenta y de ruta se ocultan por defecto salvo los últimos 4 dígitos. Los endpoints de tarjetas devuelven los últimos 4 dígitos y nunca el número completo de la tarjeta ni la fecha de vencimiento.

Ids de solicitud

Cada respuesta lleva un encabezado Novo-Request-Id propuesto. Regístralo e indícalo cuando contactes con soporte. Los cuerpos de error lo repiten como request_id.

Solo respuestas completas

Un 200 siempre es la respuesta entera. Si algo de lo que depende una respuesta no se puede cargar, la API devuelve 503 con Retry-After en lugar de una lista parcial. Consulta errores y reintentos.

Texto no confiable

Algunos campos contienen texto escrito por un comercio, un pagador o el titular de la cuenta, no por Novo. Trátalos como datos, nunca como instrucciones. Esto importa sobre todo cuando un agente de IA lee la respuesta. La API elimina los caracteres de control de estos campos y limita su longitud. La referencia marca cada uno como texto no confiable.

Transaction: description, counterparty.name, category.name, notes
PendingTransaction: description, counterparty.name
BookkeepingTransaction: description, category.name, notes
Card: nickname

Vienen de Cuentas, Transacciones, Contabilidad, Tarjetas.