Docs · Primeros pasos

Inicio rápido

Dos llamadas hasta tu primer saldo: cambia las credenciales del cliente por un token y luego consulta tus cuentas.

1. Crea un cliente en la app de Novo

El titular de la cuenta crea un cliente de API en la app de Novo, después de un paso de verificación, y elige sus scopes. Para esta guía basta con accounts:read. La app muestra el client secret una sola vez: guárdalo como una contraseña.

2. Cambia las credenciales por un token

Envía el client id y el secret con HTTP Basic al endpoint de tokens. La respuesta es un token bearer opaco que vence después de expires_in segundos (900, es decir, 15 minutos) propuesto. Reutilízalo hasta que venza en lugar de pedir uno nuevo en cada llamada.

Solicitud

curl -X POST "https://$NOVO_API_HOST/v1/oauth/token" \
  -u "nvo_client_example:$CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Respuesta

{
  "access_token": "nvo_at_example_opaque_token",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "accounts:read transactions:read"
}

3. Consulta tus cuentas

Envía el token como Authorization: Bearer. Los números de cuenta y de ruta llegan ocultos salvo los últimos 4 dígitos, y los saldos son cadenas decimales.

Solicitud

curl "https://$NOVO_API_HOST/v1/accounts" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Respuesta

{
  "data": [
    {
      "id": "acct_example_01",
      "name": "xxxxxx1234",
      "type": "EXAMPLE_TYPE",
      "status": "EXAMPLE_STATUS",
      "account_number_last4": "1234",
      "routing_number_last4": "5678",
      "balance": {
        "available": {
          "amount": "1250.00",
          "currency": "USD"
        },
        "current": {
          "amount": "1300.00",
          "currency": "USD"
        },
        "spendable": {
          "amount": "1150.00",
          "currency": "USD"
        }
      },
      "opened_at": "2024-03-14"
    }
  ]
}

Lo mismo en TypeScript

TypeScript

const host = process.env.NOVO_API_HOST;
const basic = Buffer.from(`nvo_client_example:${process.env.CLIENT_SECRET}`).toString("base64");

// 1. Cambia las credenciales del cliente por un token de corta duración.
const token = await fetch(`https://${host}/v1/oauth/token`, {
  method: "POST",
  headers: {
    Authorization: `Basic ${basic}`,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: "grant_type=client_credentials",
}).then((r) => r.json());

// 2. Consulta las cuentas con él.
const accounts = await fetch(`https://${host}/v1/accounts`, {
  headers: { Authorization: `Bearer ${token.access_token}` },
}).then((r) => r.json());

console.log(accounts.data[0].balance.available);
// { amount: "1250.00", currency: "USD" }

Siguientes pasos

Recorre las transacciones con un cursor, aprende las convenciones y lee cómo manejar los errores y reintentos. Si las llamadas las hace un agente, dale el token de acceso de corta duración y guarda el client secret en tu gestor de secretos, donde solo lo usa tu intercambio de tokens.