Inicio rápido (5 minutos)

Este tutorial te lleva de cero a tu primer request exitoso.

1. Crea tu cuenta (o inicia sesión)

Si todavía no tienes cuenta de developer, crea una aquí — pay-as-you-go, sin cuota mensual. Si ya tienes, ve a iniciar sesión.

Cualquiera de los dos caminos te lleva al Dashboard de Finova for Developers, donde administras tus API keys, ves tu consumo y los logs de tu integración.

2. Genera una API key

Desde el Dashboard, click en Generar API key. Asígnale un nombre que recuerdes (ej. Sitio público producción) y elige sus permisos en la grilla 4×4. Para empezar, te sugiero Solo lectura — esto te permite consumir el catálogo sin riesgo de modificar datos.

Si quieres limitar desde qué dominios se podrán usar tus API keys (recomendado para integraciones en sitios web), agrega los dominios permitidos en la configuración del Developers::Account. Déjalo vacío si vas a integrar desde un servidor (sin browser).

Al guardar verás el secret completo. Cópialo ahora:

finova_sk_abcdef0123456789abcdef0123456789

Si cierras el modal sin copiarlo, tendrás que revocar esta key y crear otra. Es la única vez que lo verás.

3. Tu primer request

Lista los productos de tu empresa:

cURL

curl https://developers.fi-nova.com/api/v1/products \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO'

JavaScript

const res = await fetch(
  'https://developers.fi-nova.com/api/v1/products',
  { headers: { Authorization: 'Bearer finova_sk_TU_SECRETO' } }
);
const { data, meta } = await res.json();
console.log(data);

Ruby

require 'net/http'
require 'json'

uri = URI('https://developers.fi-nova.com/api/v1/products')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer finova_sk_TU_SECRETO'

res  = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
body = JSON.parse(res.body)
puts body['data']

Respuesta esperada:

{
  "data": [
    {
      "id": "65a0c0f1234567890abcdef0",
      "name": "Servicio de página web",
      "sku": "WEB-001",
      "product_type": "service",
      "is_active": true,
      "currency": "mxn",
      "price_cents": 1500000,
      "..."
    }
  ],
  "meta": { "page": 1, "limit": 25, "total": 1, "total_pages": 1 }
}

4. Crea un lead desde tu sitio

Si tienes un formulario de contacto, puedes registrar el lead directamente en tu cuenta de Finova. La key necesita el scope create-leads.

cURL

curl -X POST https://developers.fi-nova.com/api/v1/leads \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: form-submission-abc-123' \
  -d '{
    "data": {
      "name":  "Laura Méndez",
      "email": "laura@example.com",
      "phone": "+52 656 1234567",
      "source": "sitio_web",
      "metadata": { "utm_campaign": "primavera" }
    }
  }'

JavaScript

await fetch('https://developers.fi-nova.com/api/v1/leads', {
  method: 'POST',
  headers: {
    Authorization:    'Bearer finova_sk_TU_SECRETO',
    'Content-Type':   'application/json',
    'Idempotency-Key': 'form-submission-abc-123',
  },
  body: JSON.stringify({
    data: {
      name:  'Laura Méndez',
      email: 'laura@example.com',
      phone: '+52 656 1234567',
      source: 'sitio_web',
      metadata: { utm_campaign: 'primavera' },
    },
  }),
});

El header Idempotency-Key asegura que si el usuario hace doble-click o tu red reintenta el request, no creamos dos leads. Ver Idempotencia.

5. Siguientes pasos

• Autenticación — formato del token, rotación, revocación.
• Errores — códigos y cómo manejarlos.
• Rate limiting — qué pasa si haces demasiados requests.
• Referencia — todos los endpoints con sus parámetros.

¿Te quedaste atorado? Escríbenos a developers@fi-nova.com con el prefix + last_four de tu key y el timestamp del request.