Referencia API

Referencia completa del API SmartID V5. Todos los endpoints aceptan payloads JSON y requieren autenticación con token Bearer.

Descripción General

Autenticación: Todos los endpoints requieren el header Authorization: Bearer <license_key>. Se proporcionan llaves de licencia separadas para ambientes de desarrollo/QA y producción.

Procesamiento Asíncrono: Todos los endpoints procesan las solicitudes de forma asíncrona y devuelven un estado 200 OK inmediato. Se recomienda que tu backend llame al API de forma asíncrona, preferiblemente en un hilo separado.

Registra un evento de inicio de sesión del usuario con datos de huella digital del dispositivo recopilados por el SDK.

Atributos de la Solicitud

channelId integer required

Identificador numérico del canal digital.

user string required

Identificador único del usuario que inició sesión.

session string optional

Identificador de sesión.

publicIp string required

Dirección IP pública desde la cual el usuario accedió al canal.

data string required

Información cifrada del dispositivo desde el SDK de SmartID.

Endpoint HTTP

POST

Dev/QA:

JSON

{
  "channelId": 2,
  "user": "jlopez",
  "session": "445613456fa",
  "publicIp": "20.201.64.54",
  "data": "ujOmfzNv5l/1SW+clQ==..."
}

cURL

curl -X POST \\
  https://<api-url>/api/v5/analytics/app/login \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer <license>" \\
  -d '{
  "channelId": 2,
  "user": "jlopez",
  "session": "445613456fa",
  "publicIp": "20.201.64.54",
  "data": "ujOmfzNv5l/1SW+clQ==..."
}'

Logout

Registra un evento de cierre de sesión del usuario.

Atributos de la Solicitud

channelId integer required

Identificador numérico del canal digital.

user string required

Identificador único del usuario que cerró sesión.

session string required

Identificador de sesión.

publicIp string optional

Dirección IP pública.

data string optional

Información cifrada del dispositivo (opcional para logout).

Endpoint HTTP

POST /api/v5/analytics/app/logout

JSON

{
  "channelId": 2,
  "user": "jlopez",
  "session": "445613456fa",
  "publicIp": "20.201.64.54",
  "data": "ujOmfzNv5l/1SW+clQ==..."
}

Registrar Operación

Registra un evento de transacción u operación para el motor de prevención de fraude transaccional. Cada operación debe estar asociada a una sesión de login activa usando los mismos valores de channelId, account.client y account.session enviados en la solicitud de Login.

Atributos de la Solicitud

channelId integer required

Identificador numérico del canal digital.

transaction object required ▾

Detalles de la transacción.

category string required — Category (e.g., "add account", "transfer")

type string required — Sub-type (e.g., "ach", "third parties")

description string optional — Description or comment

reference string optional — Transaction reference ID

date string optional — Optional date

details object optional — Key-value dictionary for additional data

account object required ▾

Usuario que ejecuta la transacción.

client string required — User ID in format "codeuser"

session string required — Session identifier

email string optional — User email

phoneNumber string optional — User phone

accountNumber string optional — Encrypted account number

bank string optional — Encrypted bank identifier

order object conditional

Requerido si la operación involucra un monto monetario.

amount decimal required — Operation amount

currency string required — Currency code (e.g., "GTQ", "USD")

timestamp string required

Fecha y hora de la transacción en formato ISO 8601.

accountTo object optional ▾

Beneficiario de la transacción.

client string — Beneficiary ID

email string — Beneficiary email

accountNumber string — Destination account (encrypted)

bank string — Destination bank (encrypted)

creditCard object optional ▾

Información de tarjeta de crédito si aplica.

bin string — Card BIN

hash string — Card hash

last4Digits string — Last 4 digits

token string — Card token

Endpoint HTTP

POST /api/v5/analytics/app/operation

JSON

{
  "channelId": 1,
  "transaction": {
    "category": "add account",
    "type": "ach",
    "description": "account name",
    "reference": "operation reference",
    "date": "datetime",
    "details": {
      "key": "value"
    }
  },
  "account": {
    "client": "1564651jlopez",
    "clientRefId": 0,
    "clientRefIdStr": "",
    "email": "",
    "phoneNumber": "",
    "session": "7gf7asdf4as7f",
    "accountNumber": "g489as4fa57gwad4a5g==",
    "bank": "ga8sdasfgasga=="
  },
  "order": {
    "amount": 0.00,
    "currency": "GTQ"
  },
  "accountTo": {
    "client": "",
    "accountNumber": "",
    "bank": ""
  },
  "debitFrom": {
    "account": "",
    "bank": "",
    "currency": ""
  },
  "creditTo": {
    "account": "",
    "bank": "",
    "currency": ""
  },
  "creditCard": {
    "bin": "",
    "hash": "",
    "last4Digits": "",
    "token": ""
  }
}