API Publica

La API Publica de Fidely permite a integradores externos conectarse a la plataforma para gestionar clientes, transacciones, canjes y mas.

URL Base

https://fidely20backend.azurewebsites.net/api/v1

Autenticacion

Todos los endpoints de la API publica requieren autenticacion mediante Client ID y Client Secret en los headers HTTP:

X-Client-Id: tu-client-id
X-Client-Secret: tu-client-secret

Obtener credenciales

Las credenciales se generan desde el backoffice de Fidely:

1. Ingresa al backoffice de tu comercio
2. Ve a Configuracion > API Clients
3. Crea un nuevo API Client indicando un nombre descriptivo (ej: "POS Externo", "ERP")
4. Se generara un client_id (UUID) y un client_secret

Importante

El client_secret solo se muestra una vez al momento de la creacion. Guardalo en un lugar seguro. Si lo perdes, podes regenerarlo desde el backoffice (esto invalida el anterior inmediatamente).

Scopes

Cada API Client puede tener permisos granulares (scopes) que limitan que operaciones puede realizar:

Scope	Descripcion
clients:read	Consultar clientes, beneficios, tipos de cliente
clients:write	Crear clientes
transactions:read	Consultar historial de transacciones
transactions:write	Crear transacciones (sumar puntos)
swap:write	Canjear puntos / cash / stamps
catalog:read	Consultar catalogo de productos
giftcards:read	Consultar saldo de giftcards
giftcards:write	Cargar / descontar saldo de giftcards
*	Acceso total

Si no se configuran scopes, el client tiene acceso total.

Ejemplo de request

curl -X GET https://fidely20backend.azurewebsites.net/api/v1/store \
  -H "X-Client-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-Client-Secret: 1a2b3c4d5e6f7890abcdef1234567890abcdef123456"

Errores de autenticacion

Codigo	Mensaje	Causa
401	X-Client-Id and X-Client-Secret headers are required	Faltan los headers
401	Invalid client credentials	Client ID no existe o secret incorrecto
403	API client is disabled	El client fue deshabilitado
403	Insufficient permissions. Required scope: ...	El client no tiene el scope necesario

Formato de respuesta

• Todas las respuestas son JSON
• Los errores devuelven { "error": "mensaje" } con el codigo HTTP apropiado
• Las fechas usan formato YYYY-MM-DD HH:mm:ss

Rate Limiting

Cada API Client tiene un limite de requests por minuto (default: 60). Si se excede, la API responde 429 Too Many Requests.

Auditoria

Todas las operaciones realizadas via API publica quedan registradas con:

• El client_id que realizo la operacion
• IP de origen
• Timestamp
• Duracion del request

Cuando se crean clientes o transacciones via API, el campo created_by_api_client queda registrado en la base de datos.