API keys

Una clave es la contraseña de una máquina: tu sistema (clave de API), o tu asistente de IA (clave MCP). Se gestiona en Integraciones → API y Integraciones → MCP. Se usa así, en cada pedido a la API:

Authorization: Bearer ask_live_XXXXXXXX

La clave pertenece a un contribuyente: todo lo que haga queda en su cuenta y en su ambiente (homologación o producción). Una misma clave sirve en los dos ambientes; lo que cambia es el ambiente de la cuenta.

Tipos de clave

Al crear una clave elegís su tipo, que define qué permisos tiene. Elegí siempre el más chico que alcance.

Tipo	Permisos	Para qué
Completa	Emitir, consultar y configurar	El sistema que factura: tu tienda, tu ERP
Solo lectura	Consultar y previsualizar	Un tablero de reportes, una conciliación
Facturación masiva	Emitir, consultar y usar los lotes. No configura	Un proceso que manda planillas o lotes grandes. Es un permiso aparte: las claves «completas» no lo traen
A medida	Solo los permisos que elijas: consultar, emitir, lotes, seguimiento de cobro, compras, datos fiscales, certificado o webhooks	Una integración que necesita exactamente una cosa (p. ej. solo webhooks y consulta). Es lo más seguro
MCP	Consultar, previsualizar y emitir únicamente lo previsualizado desde un asistente	Claude, Cursor o VS Code. Ver MCP. Solo entra al MCP

Clave a medida: al crearla tildás los permisos que necesita (Consultar comprobantes, Emitir comprobantes, Facturación masiva y abonos, Seguimiento de cobro, Ver compras y proveedores, Administrar compras y proveedores, Datos fiscales y puntos de venta, Certificado de ARCA, Webhooks). Nunca puede incluir administrar el equipo ni las claves, cambiar de ambiente ni ver el cobro (eso es solo de personas), y no puede tener más de lo que tiene quien la crea.

Las claves de API y las de MCP no son intercambiables. Una clave MCP solo funciona en /mcp (en la API REST responde 403 con AS-2022) y una clave de API (completa, solo lectura o masiva) no entra al MCP (también 403 con AS-2022). Así un asistente de IA con su clave no puede tocar nada fuera de las herramientas del MCP. Si necesitás las dos cosas, creá una clave de cada tipo.

Qué puede hacer cada una

Operación	Solo lectura	Completa	Facturación masiva
Consultar (comprobantes, PDF, puntos de venta, receptores, uso, catálogos)	✅	✅	✅
Previsualizar (POST /v1/invoices/preview)	✅	✅	✅
Emitir (POST /v1/invoices)	❌	✅	✅
Facturación masiva (/v1/invoice-batches)	❌	❌	✅
Configurar (datos fiscales, nombres de puntos de venta, certificado)	❌	✅	❌
Cambiar de ambiente, crear o revocar claves, administrar el equipo	solo desde la consola	solo desde la consola	solo desde la consola

Un permiso que falta responde 403 con AS-2014. La tabla de cada endpoint con su permiso está en la referencia de la API.

Las claves no crean claves ni cambian el ambiente. Esas acciones se hacen a propósito, con tu usuario, desde la consola: así una clave filtrada no puede generar otras ni mandar tus integraciones a producción.

Crear una clave

1. Entrá a Integraciones → API (o MCP).
2. Poné un nombre que diga para qué sistema es («Tienda online», «Conciliación»).
3. Elegí el tipo.
4. Copiala en ese momento: se muestra una sola vez.

Solo el Titular y los Administradores pueden crear claves. Tu plan puede limitar cuántas claves activas tenés y si podés usar API o MCP.

Buenas prácticas

• Una clave por sistema. Si una se filtra, la revocás sin afectar al resto, y sabés exactamente qué sistema dejó de funcionar. En Integraciones → API ves cuándo se usó cada una por última vez.
• Dale solo lo que necesita. Un tablero de reportes alcanza con «Solo lectura»; un sistema que solo emite no necesita «Facturación masiva».
• Guardala en un gestor de secretos o en variables de entorno del servidor. No en el código, no en el repositorio, no en un chat, y nunca en una página web o app móvil: la API es de servidor a servidor.
• Rotala de vez en cuando: creá la nueva, cambiá tu sistema y revocá la vieja. Las dos funcionan a la vez hasta que revocás una.
• Ponele vencimiento. Al crearla desde la consola podés elegir que venza en 30 días, 90 días o 1 año (o que no venza). Una clave vencida deja de funcionar sola y no ocupa lugar en el máximo de claves; en la lista ves quién la creó y cuándo vence.
• Revocala cuando alguien deje de usarla o ante la menor duda: deja de funcionar al instante.

Se muestra una sola vez

Al crearla ves la clave completa. Después solo se ve el comienzo (ask_live_AbC…) y cuándo se usó por última vez. Si la perdés, revocala y creá otra. En nuestros sistemas solo guardamos una huella de la clave (no la clave), así que no podemos recuperarla.

Si algo falla

Respuesta	Qué pasó
401 (AS-2008)	Falta el header, el formato no es Bearer ask_live_…, o la clave está revocada o mal copiada
403 (AS-2014)	La clave no tiene el permiso de esa operación (por ejemplo, una de «Solo lectura» intentando emitir)
403 (AS-2022)	Clave de otro tipo: una clave MCP en la API REST, o una clave de API en el MCP
403 (AS-2012)	La API (o el MCP) está deshabilitada en el plan de tu cuenta
403 (AS-2027)	Tu plan no incluye esa función (facturación masiva y abonos, o webhooks)
403 (AS-2002 / AS-2003)	La cuenta está suspendida o dada de baja
429 (AS-2020)	Demasiados pedidos seguidos con esa clave: esperá lo que indica Retry-After

Más sobre límites y reintentos en API: primeros pasos.