Comunicación con punto de venta
Tu terminal habla con SPIDI en dos fases: pairing (una sola vez) y luego operación firmada con HMAC (en cada petición).
Fase 1 — Pairing (vinculación)
Ocurre una sola vez en la vida del dispositivo.
# 1) el admin (con Bearer) registra el serial y genera un OTP
POST /api/v1/merchants/{merchantId}/pos-terminals/{serialNumber}/pairing
Authorization: Bearer <token>
# 2) el POS canjea el OTP y obtiene su Secret Key
POST /api/v1/pos-terminals/{serialNumber}/pairing/activate
{ "code": "889904" }
El servidor valida el código, genera una Secret Key y la asocia al serial; el POS la guarda en memoria segura. A partir de aquí, la Secret Key nunca vuelve a viajar por internet.
Fase 2 — Firma HMAC en cada petición
Ya vinculado, toda petición del POS se firma con HMAC-SHA256 a partir de cuatro elementos:
| # | Elemento | Detalle |
|---|---|---|
| 1 | Body | El JSON del cuerpo. En GET o sin cuerpo, cadena vacía "" |
| 2 | Timestamp | ISO 8601, enviado en x-pos-timestamp |
| 3 | URL | El path completo, incluyendo query string |
| 4 | Secret Key | La clave persistida en el pairing |
message = body + "\n" + timestamp + "\n" + url
signature = HMAC_SHA256(message, secret_key)
Cabeceras obligatorias en toda petición POS:
| Cabecera | Valor |
|---|---|
x-pos-signature | La firma HMAC-SHA256 en hexadecimal |
x-pos-timestamp | El mismo timestamp ISO 8601 usado en la firma |
En un
GET(sin cuerpo),body = "", así que elmessageempieza por el salto de línea. La URL debe llevar el query string tal cual se envía.
Operaciones del terminal
| Operación | Método | Endpoint | Body |
|---|---|---|---|
| Listar transacciones | GET | /api/v1/pos-terminals/{serial}/transactions?status=PENDING | "" |
| Consultar una orden | GET | /api/v1/pos-terminals/{serial}/transactions/{orderId} | "" |
| Confirmar pago | POST | /api/v1/pos-terminals/{serial}/transactions/{orderId}/commit | JSON |
| Confirmar anulación | POST | /api/v1/pos-terminals/{serial}/transactions/{orderId}/cancellation/commit | "" |
| Cierre de lote | POST | /api/v1/pos-terminals/{serial}/settlements | JSON |
Por qué es seguro
- Sin contraseñas en el dispositivo: nada que anotar en un papel.
- Integridad: si alguien altera el monto, la URL o el timestamp, la firma falla y el servidor rechaza.
- Anti-replay: el
x-pos-timestamppermite descartar peticiones viejas o duplicadas. - Control: si el POS se pierde, el admin lo desvincula y la Secret Key queda invalidada al instante.