Autenticación
La API acepta autenticación por API key o, en la aplicación web, por cookie de sesión (accessToken).
Prioridad: cookie frente a API key
Si la petición incluye una cookie de sesión válida (accessToken), el servidor usa solo esa sesión y no interpreta la API key de los headers en esa misma petición. Para probar integraciones con llave desde un navegador donde ya iniciaste sesión en abaco, usá una ventana privada, otro perfil o borrá las cookies del API; en scripts y servidores no suele haber cookie, así que la API key se aplica con normalidad.
Formato del token
El token debe tener la forma:
<Key ID>:<Secret>Al crear una llave, el Secret se genera en base64url (similar a base64, seguro para URLs). Por ejemplo, si tu Key ID es abk_abc123 y tu Secret es tu_secret_base64url, el token completo sería:
abk_abc123:tu_secret_base64urlEl primer carácter : separa Key ID y Secret; el Secret generado por abaco no contiene :.
Cómo enviarlo
Opción 1: Header Authorization (recomendado)
Recomendado sobre todo si llamás a la API desde un navegador en otro origen (CORS): este header está siempre permitido en las peticiones preflight.
Authorization: Bearer abk_abc123:tu_secret_base64urlOpción 2: Header X-API-Key
Válido también desde navegador en otro origen: el API declara X-API-Key en CORS junto con Authorization.
X-API-Key: abk_abc123:tu_secret_base64urlEjemplo con curl
Sustituye TU_KEY_ID, TU_SECRET y https://api.abaco.hn por tus valores:
curl -X GET "https://api.abaco.hn/business-partners" \
-H "Authorization: Bearer TU_KEY_ID:TU_SECRET"Respuestas de error (códigos en JSON)
| HTTP | Código (code) | Significado |
|---|---|---|
| 401 | TOKEN_MISSING | No hay cookie de sesión válida ni API key en los headers. |
| 401 | INVALID_API_KEY | Key ID inexistente, revocado, o Secret incorrecto. |
| 401 | API_KEY_EXPIRED | La llave tiene fecha de expiración y ya venció. |
| 401 | API_KEY_NO_USER | La llave es válida pero no se pudo asociar un usuario de la empresa (p. ej. sin propietario ni administrador activo en la compañía). |
| 401 | TOKEN_EXPIRED / INVALID_TOKEN / SESSION_EXPIRED | Relacionados con la sesión web (JWT/cookie), no con la API key. |
| 403 | WEB_SESSION_REQUIRED | La ruta solo admite sesión web (no API key), p. ej. cambio de compañía o gestión de permisos de usuarios. |
| 403 | API_KEY_MANAGEMENT_FORBIDDEN | La gestión de llaves no está disponible con credenciales de integración (API key). Usá la aplicación web. |
| 403 | API_KEY_DELETE_FORBIDDEN | Las API keys no pueden ejecutar ninguna petición DELETE; use la aplicación web para eliminar recursos. |
| 429 | RATE_LIMIT_EXCEEDED | Demasiadas peticiones con la misma API key en la ventana de tiempo. Ver Límites y cuotas. |
Los cuerpos de error suelen incluir message en español además de code.
Las llaves de API no se gestionan desde los flujos documentados para integradores (ni con API key ni automatizando la API con token de sesión): la creación y revocación es solo en la aplicación web (abaco.hn → Configuración > Integraciones), con rol de propietario o administrador.
Operaciones DELETE: con API key, cualquier petición DELETE responde 403 con código API_KEY_DELETE_FORBIDDEN. La eliminación de registros (productos, documentos, socios, etc.) debe hacerse desde la aplicación web con sesión iniciada.
Ámbito de la compañía: al usar API key, todas las peticiones se asocian automáticamente a la empresa de esa llave. No intente fijar en la petición el contexto de otra empresa: el servidor toma el ámbito solo desde la llave y evita acceso a datos ajenos.
Informes contables: con API key, el acceso a plantillas e informes contables no exige el permiso granular accounting.reports.view que aplica a usuarios web; la llave opera en el ámbito de la empresa de la llave.