developers Entrar a AdvantaCloud
Árbol del API · Guías › Autenticación con Llave API

Autenticación con Llave API

Bearer

Qué permisos lleva una Llave API, cómo se envía y qué ve.

Las integraciones se autentican con una Llave API: un secreto que identifica a tu integración ante una empresa de AdvantaCloud. Cada petición la envía en el header Authorization:

HTTP
POST https://mi-empresa.advantacloud.com/graphql
Authorization: Bearer <tu llave>
Content-Type: application/json

Cuidar la llave

Guárdala como cualquier otra contraseña de servidor: en una variable de entorno o en un gestor de secretos, nunca en el código, en una app móvil ni en JavaScript que corra en el navegador. Cambiar la contraseña de un usuario no afecta a las llaves.

Permisos

La llave sólo puede usar los permisos que tiene. Cada operación de la referencia indica el permiso que necesita. Las operaciones publicadas usan éstos:

PermisoOperaciones
«Selects y autocompletes GraphQL»warehouseOptions, currencyOptions, unitOptions, priceStructureOptions, paymentMethodOptions, paymentTypeOptions, collectionTypeOptions, collectorOptions, businessUnitOptions, customerSuggestions, productSuggestions
«Cliente»customersConnection, customer, priceStructuresConnection, priceListEntriesConnection
«Creacion de Cliente»upsertCustomerAddress
«Articulos»productsConnection, product
«Ventas»ordersConnection, order, orderDefaults, orderPrintOptions, bankTerminals
«Creacion de Orden de Venta»quoteOrder, createOrder, cancelOrder
«Facturación»invoicesConnection, invoice
«Consultar Cobros»collectionsConnection, collection
«Complemento de Pago»paymentComplement
«Crear Cobros»createCollection

Algunos datos piden un permiso adicional; por ejemplo, la estructura de precios de una orden necesita también «Cliente». La referencia lo indica en cada campo.

Una llave sin el permiso no siempre recibe un error. Casi todas las listas responden vacías y las consultas de un solo registro responden null, sin errors; la lista de clientes también llega null, y las de estructuras de precios y de precios de una lista, un error sin código. Las mutaciones, quoteOrder, orderDefaults y orderPrintOptions responden HTTP 422. El API conserva así las respuestas que ya usan integraciones en producción. Cada operación de la referencia dice en «Permisos» qué recibe una llave sin el suyo; si una lista llega vacía sin razón, revisa primero los permisos de la llave.

La empresa la elige el subdominio

Una llave pertenece a una sola empresa. El subdominio de la URL elige la empresa de cada petición: una llave usada con el subdominio de otra empresa recibe HTTP 401, igual que una llave que no existe o una petición sin el header Authorization. Esa respuesta no trae cuerpo.

Qué ve una llave

  • Toda la empresa. La llave ve los registros de toda la empresa del subdominio, sin el alcance por vendedor que tiene un usuario en la aplicación.
  • A nombre de un usuario. Las órdenes de venta y los cobros quedan a nombre de un usuario: createOrder, cancelOrder y createCollection piden un userId, el usuario activo de AdvantaCloud a nombre de quien queda el registro, y orderDefaults y quoteOrder lo piden para proponer y calcular con sus valores. Pide al administrador el usuario que usará tu integración.
  • En la hora del centro de México. Los días de los filtros y las fechas con hora de las respuestas usan la zona America/Mexico_City. Ver Fechas, zonas horarias y montos.
Primeros pasos Paginación con cursores