Cómo generar y gestionar API Keys

La API REST de Peakly te permite integrar la facturación en tus propios sistemas: crear comprobantes desde tu ERP, sincronizar clientes desde tu e-commerce, automatizar envíos de facturas y consultar datos de ventas programáticamente. Las API keys son la forma de autenticarte en la API.

Requisitos previos

• Tener una cuenta activa en Peakly
• Haber creado una organización con los datos fiscales completos
• Tener permisos para gestionar API keys en la organización (por ejemplo, rol administrador)
• Para emitir comprobantes electrónicos: certificado ARCA configurado y punto de venta habilitado

Crear una API key

1. En el menú lateral, en el grupo Conectar, entrá a Desarrolladores y elegí API Keys
2. Presioná el botón Crear API key en la esquina superior derecha
3. Completá el formulario:
   • Nombre: un nombre descriptivo que identifique la integración (ej. "Integración ERP", "TiendaNube", "Script de reportes")
   • Vencimiento: elegí entre 30, 60 o 90 días o Sin vencimiento (viene 90 días por defecto). Recomendamos siempre poner vencimiento.
4. Hacé clic en Crear API key
5. En la ventana API key creada, copiá la key inmediatamente y guardala en un lugar seguro (gestor de contraseñas, secrets manager, variable de entorno). Después hacé clic en Listo

Usar la API key

Para autenticarte en la API, enviá la key en el header X-API-Key de cada request HTTP. La key identifica tu organización automáticamente:

# cURL
curl https://api.peakly.ar/v1/customers \
  -H "X-API-Key: pk_tu_api_key_aqui" \
  -H "Content-Type: application/json"

// Node.js / TypeScript
const response = await fetch('https://api.peakly.ar/v1/customers', {
  headers: {
    'X-API-Key': 'pk_tu_api_key_aqui',
    'Content-Type': 'application/json',
  },
});
const { data: customers } = await response.json();
console.log(customers);

# Python
import requests

response = requests.get(
    'https://api.peakly.ar/v1/customers',
    headers={'X-API-Key': 'pk_tu_api_key_aqui'}
)
customers = response.json()['data']
print(customers)

Las respuestas traen el resultado en el campo data (objeto o array). Los listados usan paginación por cursor: junto a data vienen nextCursor y hasMore; para pedir la página siguiente enviá cursor con el valor de nextCursor (el tamaño de página se ajusta con page_size, por defecto 50 y máximo 100):

// Respuesta de ejemplo — GET /v1/customers (algunos campos omitidos)
{
  "data": [
    {
      "id": 1,
      "businessName": "Distribuidora Norte SRL",
      "taxId": "30345678901",
      "email": "contacto@distribuidoranorte.com.ar",
      "isActive": true
    }
  ],
  "nextCursor": "eyJpZCI6MTIzfQ==",
  "hasMore": true
}

Recursos disponibles

Con tu API key podés acceder a todos los recursos de tu organización en Peakly:

• Clientes — GET /v1/customers, POST /v1/customers, PATCH /v1/customers/:id, DELETE /v1/customers/:id
• Productos — GET /v1/products, POST /v1/products, PATCH /v1/products/:id
• Comprobantes de venta — GET /v1/sales/sales-receipts, POST /v1/sales/sales-receipts (borrador), POST /v1/sales/sales-receipts/:id/confirm (emitir con ARCA)
• Talonarios — GET /v1/receipt-books (listar puntos de venta configurados)
• Reportes — GET /v1/sales/reports/sales-by-customer, /v1/sales/reports/sales-by-product, /v1/sales/reports/vat-sales-book

Gestionar API keys existentes

En Desarrolladores > API Keys ves todas tus keys en una tabla con las siguientes columnas:

• Nombre: la etiqueta que le diste al crearla
• Key: vista previa parcial (pk_… y los últimos 4 caracteres)
• Estado: Activa, Deshabilitada o Expirada
• Creada y Vencimiento
• Último uso: cuándo se usó por última vez

Deshabilitar o habilitar una API key

Si necesitás suspender temporalmente el acceso de una integración, podés deshabilitar la key sin eliminarla. Hacé clic en el menú de tres puntos (⋯) a la derecha de la key y seleccioná Deshabilitar. Para volver a activarla, abrí el mismo menú y seleccioná Habilitar. Las keys expiradas no muestran esta opción y no pueden habilitarse nuevamente.

Eliminar una API key

Si una key ya no es necesaria o fue comprometida, hacé clic en el menú de tres puntos (⋯) y seleccioná Eliminar. Se te pedirá confirmación (¿Eliminar API key?) antes de completar la acción. Esta operación es irreversible: cualquier sistema que use esa key dejará de funcionar de inmediato.

Rotar una API key

Rotar una key significa reemplazarla por una nueva sin interrumpir el servicio. Seguí estos pasos para hacerlo sin downtime:

1. En Desarrolladores > API Keys, creá una nueva key (ej. "Integración ERP — nueva")
2. Copiá la nueva key y actualizá la variable de entorno o el secrets manager en tu sistema
3. Desplegá o reiniciá tu sistema para que use la key nueva
4. Verificá que el sistema funcione correctamente con la key nueva (revisá logs por unos minutos)
5. Volvé a Desarrolladores > API Keys y eliminá la key anterior

Buenas prácticas

• Creá una API key distinta para cada integración o sistema externo
• Usá nombres descriptivos para identificar fácilmente cada key
• Configurá siempre un vencimiento — especialmente en entornos de prueba
• Rotá las keys periódicamente: creá una nueva, actualizá tu sistema y eliminá la anterior
• Guardá las keys en variables de entorno o en un secrets manager, nunca en el código fuente
• Si sospechás que una key fue comprometida, deshabilitala o eliminala inmediatamente

Errores comunes

Cuando algo falla, la API devuelve un código HTTP estándar y un cuerpo JSON con los campos statusCode, error y message. Estos son los errores más frecuentes (los mensajes llegan en inglés):

• 401 — "Missing or invalid authentication": no enviaste el header X-API-Key (o está vacío)
• 401 — "Invalid API key": la key no existe, fue eliminada, está deshabilitada o venció
• 403: tu key o tu usuario no tiene permisos suficientes para esa operación
• 400 — error de validación: faltan campos requeridos o tienen formato incorrecto; el campo details lista cada problema
• 429: superaste el límite de requests por minuto de tu plan; esperá unos segundos y reintentá
• 500: problema temporal en Peakly; reintentá la operación en unos minutos

Referencia de la API

Explorá todos los endpoints, parámetros y schemas de respuesta en la referencia interactiva en peakly.ar/docs. Podés probar requests directamente desde el navegador sin necesidad de Postman.

Si preferís importar la especificación en tu cliente REST, descargá el schema OpenAPI en formato JSON desde api.peakly.ar/openapi.json y cargalo en Postman o Insomnia.

Para Postman tenés además la colección lista para importar en api.peakly.ar/postman-collection.json, con todos los endpoints agrupados por recurso y variables predefinidas.

Próximos pasos

• Hacer el recorrido guiado — Desarrolladores > API Quickstart te lleva de crear la key a emitir tu primera factura (ver el artículo API Quickstart)
• Explorar la API interactiva — probá endpoints en tiempo real en peakly.ar/docs
• Crear tu primer comprobante via API — seguí la guía en Ventas > Crear comprobante
• Configurar ARCA — necesario para emitir comprobantes electrónicos, ver Factura electrónica > Configurar