# Checklist de seguridad — Bitalcer Partner API

Las credenciales de esta API mueven fondos reales (en producción). Esta lista
es la base mínima esperada antes de operar — no es exhaustiva, ajústala a tu
propio modelo de riesgo.

## Manejo del `hmac_secret`

- [ ] El `hmac_secret` se muestra **una sola vez**, al generarse o rotarse —
      Bitalcer nunca lo almacena en texto plano ni puede volver a mostrártelo.
      Si lo pierdes, la única opción es rotarlo (lo cual invalida el anterior
      de inmediato).
- [ ] Nunca lo incluyas en el código fuente ni en control de versiones —
      guárdalo en un gestor de secretos (Vault, AWS Secrets Manager, variables
      de entorno inyectadas en runtime, etc.).
- [ ] Nunca lo envíes en el cuerpo o la URL de un request — solo se usa
      localmente para calcular `x-signature`, jamás viaja por la red.
- [ ] El mismo principio aplica al `webhook_secret` (firma de los webhooks
      entrantes) — es un secreto **distinto** del `hmac_secret` de tus
      requests salientes, rótalo con la misma disciplina.

## Rotación de claves

- [ ] Rota `api_key`/`hmac_secret` periódicamente (recomendado: cada 90 días)
      y de inmediato ante cualquier sospecha de compromiso (ej. un secreto
      expuesto accidentalmente en un log, un repositorio público, o un canal
      de soporte).
- [ ] Antes de rotar en producción, ten un plan de despliegue sin downtime: la
      clave anterior queda inválida apenas se genera la nueva, así que el
      cambio debe ser atómico en tu lado (no hay periodo de gracia con ambas
      claves activas simultáneamente en esta versión de la API).
- [ ] Rota también el `webhook_secret` si sospechas que un tercero pudo haber
      visto payloads de webhook sin autorización.

## Verificación de webhooks entrantes

- [ ] Verifica siempre la firma (`x-signature`) de cada webhook recibido antes
      de procesar el payload — no asumas que un POST a tu endpoint es legítimo
      solo porque llegó a la URL correcta.
- [ ] Valida también `x-timestamp` (ventana de ±5 minutos) en tu lado para
      rechazar reintentos de replay fuera de rango.
- [ ] Responde `2xx` solo después de validar la firma y de haber persistido el
      evento de forma idempotente — un evento puede reintentarse hasta 6 veces
      con backoff exponencial si tu endpoint no responde `2xx`.

## Acceso de red

- [ ] Restringe qué procesos/servidores de tu infraestructura tienen acceso al
      `hmac_secret` y pueden originar llamadas a la Partner API — minimiza la
      superficie, idealmente un único servicio backend, nunca un cliente
      móvil o web directamente.
- [ ] **Nota:** esta versión de la API no implementa allowlisting de IPs del
      lado de Bitalcer (cualquier IP con credenciales válidas puede llamar).
      Si tu modelo de seguridad requiere restricción por IP, impleméntala en
      tu propia infraestructura de salida (egress) — está en el roadmap como
      mejora futura del lado de Bitalcer, pero no debe asumirse como control
      ya activo.

## Separación sandbox / producción

- [ ] Usa credenciales de sandbox únicamente en entornos de desarrollo/QA —
      nunca reutilices una credencial de sandbox en producción ni viceversa
      (son pares completamente independientes, ligados a ambientes distintos).
- [ ] Verifica el campo `environment` en la respuesta de `GET /partner/v1/ping`
      antes de operar, como salvaguarda adicional contra apuntar accidentalmente
      al ambiente equivocado.

## Datos de tus usuarios finales (KYC delegado)

- [ ] Recuerda que el KYC del usuario final es **tu responsabilidad** (no de
      Bitalcer) — los Términos de Servicio de API delegan esa obligación
      contractualmente a tu empresa. Mantén tu propio proceso de verificación
      de identidad y debida diligencia AML acorde a tu jurisdicción.
- [ ] El `external_user_id` que envías a Bitalcer no debe contener información
      personal identificable directa (nombre completo, correo, documento de
      identidad) — usa un identificador interno opaco (UUID, ID de tu base de
      datos), igual que harías con cualquier proveedor externo.

## Monitoreo

- [ ] Revisa periódicamente la sección "Uso y facturación" de tu dashboard —
      picos inusuales en `request_count` o en comisiones acumuladas pueden ser
      indicio de un uso indebido de tus credenciales.
- [ ] Configura alertas propias sobre tasas de error elevadas (`4xx`/`5xx`)
      en tus llamadas — pueden señalar tanto un bug en tu integración como un
      intento de uso no autorizado.