Antes de empezar

Antes de la primera llamada necesitas dos cosas: saber contra qué host hablas y tener un token. Se resuelven en cinco minutos.

Los dos entornos

Entorno	URL base	Para qué
Sandbox	https://dev.api.spuntodeventa.com	Integrar y probar. Es donde vives mientras desarrollas.
Producción	https://api.spuntodeventa.com	Dinero real. Solo cuando SPIDI te habilite.

Todas las rutas de esta documentación son relativas a esa base. Cuando leas POST /api/v1/merchants/auth/login, en sandbox eso es https://dev.api.spuntodeventa.com/api/v1/merchants/auth/login.

Un alias que quizá encuentres

El host sandbox.api.spidipagos.com responde exactamente igual que dev.api.spuntodeventa.com: es el mismo servicio con otro nombre, y aparece en material más antiguo de SPIDI. Usa el de la tabla, que es el que declara el contrato.

Registra tu comercio

Una vez, y sin token —este endpoint es público:

curl -X POST https://dev.api.spuntodeventa.com/api/v1/merchants \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Comercio de Ejemplo C.A.",
    "taxId": "J-12345678-9",
    "email": "contacto@comercio.com",
    "password": "Password123!",
    "phone": "+584121234567",
    "address": "Calle Principal, Edificio 1, Caracas"
  }'

Obligatorios: legalName, taxId, email y password. El resto ayuda pero no bloquea.

Consigue tu token

curl -X POST https://dev.api.spuntodeventa.com/api/v1/merchants/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "contacto@comercio.com", "password": "Password123!" }'

Respuesta:

{
  "title": "Autenticación Exitosa",
  "detail": "Se ha generado el token de acceso correctamente y el usuario ha sido autenticado.",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "merchantId": "MERCHANT-998877"
  }
}

Guarda dos cosas de ahí:

• accessToken — va en la cabecera Authorization: Bearer <tu-token> de toda petición de tu backend.
• merchantId — es el {merchantId} que aparece en media docena de rutas de esta doc.

El token dura expiresIn segundos (una hora en sandbox). No hay refresh token: cuando caduca, vuelves a llamar a /auth/login. Si tu backend hace muchas llamadas, pide el token una vez y reúsalo hasta que falte poco para vencer; no pidas uno por petición.

Quién usa qué llave

Esta es la distinción que más confunde al principio, y conviene tenerla clara desde ya:

Quién llama	Con qué se autentica	Ejemplo
Tu backend / ERP	Authorization: Bearer <token>	Crear un pago, anular, consultar cierres
El terminal físico	Firma HMAC en x-pos-signature	Listar pendientes, confirmar el pago con la tarjeta

El terminal nunca usa tu token, y tu backend nunca usa la llave del terminal. De eso trata Comunicación con punto de venta.

→ Siguiente: Conceptos (Merchant) para el modelo completo, o directo a Recibir una venta si prefieres empezar por el flujo.