Autenticación
Cómo autenticar tus solicitudes a la API de MercaloAPI usando API Keys.
API Keys
Genera tu API key desde el dashboard (empresa → API Keys) — el valor solo se muestra una vez al crearla, así que guárdalo de inmediato. Todas las solicitudes a la API deben incluir esa key en el header Authorization, exactamente igual que el token de sesión del dashboard.
curl https://api.mercalo.co/invoice/{companyId} \
-H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json"Una key, dos ambientes
A diferencia de otras APIs, no existen keys separadas de prueba y producción. Tu API key siempre representa a tu empresa, y el ambiente al que llegan tus documentos lo determina el ambiente configurado en tu empresa (Habilitación o Producción) — el mismo que usa el dashboard. Cambiaste a Producción en el panel? La misma key ya envía documentos reales, sin necesidad de generar una nueva.
Seguridad
Nunca expongas tus API keys en código del lado del cliente (frontend) — solo en tu backend o sistema POS.
Usa variables de entorno para almacenar tus claves, nunca las subas a control de versiones.
Si sospechas que una key se filtró, revócala desde el dashboard y crea una nueva de inmediato.
Crea una key con un nombre distinto por cada sistema que integres — así puedes revocar uno sin afectar a los demás.
Errores de autenticación
| Código | Descripción | Solución |
|---|---|---|
401 | API key inválida o revocada | Verifica que la key esté completa y no haya sido revocada en el dashboard |
403 | La empresa en la URL no coincide con la key | El companyId de la ruta debe ser el de la empresa dueña de la key |
429 | Rate limit excedido | Espera y reintenta. Contacta soporte si persiste |