Documentación / Recursos Avançados
Recursos Avançados

Cómo Controlar la Lista de Acceso de Citas vía API Externa

Resumen

eAgenda permite validar, de forma automática, si un cliente está autorizado a realizar una cita utilizando una Lista de Acceso conectada a una API externa.

Cuando el cliente informa el CPF durante la cita, eAgenda envía una solicitud HTTP POST a la URL configurada, utilizando timestamp y firma HMAC-SHA256 para garantizar la seguridad e integridad de la comunicación.

En este documento encontrará:

  • Cómo funciona la estructura de la solicitud enviada por eAgenda
  • Cómo desarrollar la API externa responsable de la validación
  • Cómo crear la Lista de Acceso que valida vía API externa
  • Cómo compartir el enlace de esa lista con sus clientes

Estructura de la Solicitud Enviada por eAgenda

Cuerpo de la Solicitud (JSON)

eAgenda envía el identificador informado por el cliente en el campo configurado (ej.: CPF):

{ “identifier”: “12345678901” }

{
  "identifier": "12345678901"
}

Encabezados Enviados

Los encabezados agregan seguridad y autenticación:

  • X-Timestamp: timestamp UNIX de la solicitud
  • X-Signature: hash HMAC-SHA256 generado a partir del cuerpo + timestamp
  • Content-Type: application/json

Método

POST

Cómo Desarrollar su API Externa

La API externa debe:

  1. Verificar el timestamp para evitar replay attacks
  2. Validar la firma HMAC-SHA256
  3. Verificar si el identificador informado está autorizado
  4. Responder con { "authorized": true/false }

Ejemplo completo en Python + Flask

from flask import Flask, request, jsonify import hmac import hashlib import time

app = Flask(__name__)

SECRET_KEY = “mi-clave-secreta-super-segura-123”

CLIENTES_AUTORIZADOS = [ “01234567890”, “12345678901”, “98765432100”, “11122233344” ]

TIME_TOLERANCE = 120

def verify_signature(body, timestamp, received_signature): message = body + timestamp expected_signature = hmac.new( SECRET_KEY.encode(‘utf-8’), message.encode(‘utf-8’), hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected_signature, received_signature)

@app.route(‘/validate’, methods=[‘POST’]) def validate_client(): timestamp_header = request.headers.get(‘X-Timestamp’) signature_header = request.headers.get(‘X-Signature’)

if not timestamp\_header or not signature\_header:
    return jsonify({"error": "Los headers X-Timestamp y X-Signature son obligatorios"}), 400

body = request.get\_data(as\_text=True)

try:
    request\_time = int(timestamp\_header)
    current\_time = int(time.time())
    diff = abs(current\_time - request\_time)
    if diff > TIME\_TOLERANCE:
        return jsonify({"authorized": False, "error": "Solicitud expirada"}), 403
except:
    return jsonify({"error": "Timestamp inválido"}), 400

if not verify\_signature(body, timestamp\_header, signature\_header):
    return jsonify({"authorized": False, "error": "Firma inválida"}), 403

data = request.get\_json()
identifier = data.get("identifier")

if not identifier:
    return jsonify({"error": "El campo 'identifier' es obligatorio"}), 400

autorizado = identifier in CLIENTES\_AUTORIZADOS

return jsonify({"authorized": autorizado, "identifier": identifier}), 200

@app.route(‘/health’, methods=[‘GET’]) def health(): return jsonify({ “status”: “online”, “secret_key_configured”: True, “authorized_clients_count”: len(CLIENTES_AUTORIZADOS) }), 200

if __name__ == “__main__”: app.run(debug=True, port=5000)

from flask import Flask, request, jsonify
import hmac
import hashlib
import time

app = Flask(__name__)

SECRET_KEY = "mi-clave-secreta-super-segura-123"

CLIENTES_AUTORIZADOS = [
    "01234567890",
    "12345678901",
    "98765432100",
    "11122233344"
]

TIME_TOLERANCE = 120

def verify_signature(body, timestamp, received_signature):
    message = body + timestamp
    expected_signature = hmac.new(
        SECRET_KEY.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_signature, received_signature)

@app.route('/validate', methods=['POST'])
def validate_client():
    timestamp_header = request.headers.get('X-Timestamp')
    signature_header = request.headers.get('X-Signature')

    if not timestamp_header or not signature_header:
        return jsonify({"error": "Los headers X-Timestamp y X-Signature son obligatorios"}), 400

    body = request.get_data(as_text=True)

    try:
        request_time = int(timestamp_header)
        current_time = int(time.time())
        diff = abs(current_time - request_time)
        if diff > TIME_TOLERANCE:
            return jsonify({"authorized": False, "error": "Solicitud expirada"}), 403
    except:
        return jsonify({"error": "Timestamp inválido"}), 400

    if not verify_signature(body, timestamp_header, signature_header):
        return jsonify({"authorized": False, "error": "Firma inválida"}), 403

    data = request.get_json()
    identifier = data.get("identifier")

    if not identifier:
        return jsonify({"error": "El campo 'identifier' es obligatorio"}), 400

    autorizado = identifier in CLIENTES_AUTORIZADOS

    return jsonify({"authorized": autorizado, "identifier": identifier}), 200

@app.route('/health', methods=['GET'])
def health():
    return jsonify({
        "status": "online",
        "secret_key_configured": True,
        "authorized_clients_count": len(CLIENTES_AUTORIZADOS)
    }), 200

if __name__ == "__main__":
    app.run(debug=True, port=5000)

Ejemplos de respuesta

Cliente autorizado

{ “authorized”: true, “identifier”: “12345678901” }

{
  "authorized": true,
  "identifier": "12345678901"
}

Cliente no autorizado

{ “authorized”: false, “identifier”: “12345678901” }

{
  "authorized": false,
  "identifier": "12345678901"
}

Cómo Crear la Lista de Acceso que Valida vía API Externa

Paso 1 — Acceder a la plataforma

  1. Ingrese en: [https://eagenda.com.br](https://eagenda.com.br)
  2. Inicie sesión con su cuenta.

Paso 2 — Acceder al menú correcto

  1. En el menú lateral, haga clic en Cuenta
  2. Haga clic en Acceso de Clientes

Paso 3 — Crear nueva lista

  1. Haga clic en Nueva Lista

  1. En el campo Nombre de la Lista, coloque cualquier nombre (ej.: teste)
  2. Los demás campos pueden quedar en blanco

Paso 4 — Configurar el tipo de validación

  • Inicio de sesión obligatorio: desmarcar
  • Usar Lista Externa de Acceso: marcar
  • Tipo de Clave de Acceso: seleccionar CPF

Paso 5 — Configurar integración externa

Completar:

  • URL de la API Externa: Ej.: https://suservidor.com/validate
  • Clave Secreta: Ej.: mi-clave-secreta-super-segura-123

Paso 6 — Finalizar

Haga clic en Guardar.

Su lista está lista para validar automáticamente cada CPF a través de la API externa.

Cómo Compartir la Lista con los Clientes

  1. En eAgenda, vaya a Cuenta → Acceso de Clientes
  2. Localice la lista creada
  3. Haga clic en Acciones
  4. Seleccione Copiar enlace compartido

Ese enlace puede ser enviado a los clientes: Ellos ingresan el CPF → el sistema consulta la API → libera o bloquea automáticamente la cita.

Contáctenos o Conozca Más

Estamos a su disposición para ayudarle. Acceda a nuestros canales oficiales:

📞 WhatsApp : Haga clic aquí para enviarnos un mensaje 🌐 Plataforma eAgenda : Conozca eAgenda 🏢 Nuestra Empresa : Mupi Systems – Soluciones Innovadoras 📧 Correo electrónico : contato@mupisystems.com.br 📚 Tutoriales y Documentación : Acceda a nuestras guías y tutoriales