Autenticación
Todas las peticiones a la API se autentican con una API key. Las keys tienen
el prefijo nv_ y se muestran una sola vez al crearlas.
Crear una API key
- Entrá al dashboard de Novity.
- Andá a Desarrolladores (visible si tu plan incluye acceso a la API).
- Hacé clic en Crear key, poné un nombre y copiá la key generada.
Enviar la API key
Podés autenticar de dos formas. Elegí una:
Header Authorization (recomendado):
curl https://api.novity.com.ar/api/v1/customers \ -H "Authorization: Bearer nv_tu_api_key"Header X-API-Key:
curl https://api.novity.com.ar/api/v1/customers \ -H "X-API-Key: nv_tu_api_key"Respuestas de autenticación
| Código | Significado |
|---|---|
401 API key requerida | No se envió ninguna key. |
401 API key inválida | La key no existe o fue revocada. |
401 API key expirada | La key superó su fecha de vencimiento. |
403 Scope requerido: ... | La key no tiene el scope que requiere el endpoint. |
403 IP no autorizada | La IP de origen no está en la whitelist de la key. |
403 El acceso a la API no está incluido en tu plan | Tu plan no incluye acceso a la API. |
429 | Superaste un límite de solicitudes. Ver Límites de uso. |
Scopes
Al crear una key podés restringir qué puede hacer asignándole scopes. Una key sin scopes tiene acceso completo; una key con scopes solo puede usar los endpoints que correspondan.
| Scope | Permite |
|---|---|
customers:read | Listar y consultar clientes. |
customers:write | Crear clientes. |
points:read | Consultar saldo de puntos. |
points:write | Sumar y descontar puntos. |
transactions:read | Listar ventas. |
transactions:write | Registrar ventas. |
rewards:read | Listar recompensas. |
rewards:write | Canjear recompensas. |
segments:read | Listar segmentos de clientes. |
loyalty:read | Consultar el programa de fidelidad. |
statistics:read | Consultar estadísticas. |
organization:read | Consultar datos de la organización. |
Límites de uso
Cada key tiene límites de solicitudes. Al superarlos la API responde 429.
| Límite | Valor |
|---|---|
| Por minuto | 300 por defecto; configurable por key (rateLimit). |
| Por día | Sin límite por defecto; configurable por key (dailyLimit). |
| Por mes | Sin límite por defecto; configurable por key (monthlyLimit). |
Los contadores diarios y mensuales usan ventanas de calendario en UTC.
Whitelist de IPs
Opcionalmente podés restringir una key a un conjunto de IPs (ipWhitelist).
Las peticiones desde cualquier otra IP reciben 403 IP no autorizada.
Revocar una key
Desde Desarrolladores en el dashboard podés revocar cualquier key. La revocación es inmediata: cualquier integración que la use dejará de funcionar al instante.