# SLA — GeoEvidence Public API

> **Tier:** POC-ready (best-effort). SLA contractual en ship-ready.
> **Versión actual:** `2026-09-01`
> **Tickets relacionados:** [#16](https://github.com/mandres9/GeoEvidence/issues/16) (meta endpoints), [`readiness-table-v1.md`](./readiness-table-v1.md) (umbrales del eje Soporte).

## Disponibilidad

| Métrica | Target POC-ready | Target ship-ready |
|---|---|---|
| Uptime mensual | best-effort (~99% esperado) | 99.5%+ contractual |
| Mantenimiento programado | aviso 24h por email + status page | aviso 7 días por email + status page |
| Degradación aceptable | rate limit reducido (de 1000/h a 200/h) | sin degradación; failover a read-only |

Durante POC-ready, los incidentes pueden causar downtime no programado. Reportamos cada incidente post-mortem.

## Tiempos de respuesta de soporte

| Severidad | Definición | Target POC-ready | Target ship-ready |
|---|---|---|---|
| **Crítica** | API inaccesible para todos los integradores | 4h hábiles | 1h hábiles (24/7) |
| **Alta** | Funcionalidad degradada (ej: rate-limit agresivo, latency > 5s) | 8h hábiles | 4h hábiles |
| **Normal** | Bug específico, pregunta de uso | 24h hábiles | 8h hábiles |

**Hábiles**: lunes a viernes 9:00-18:00 ART (UTC-3). Fuera de horario, los tickets se acusan recibo pero la resolución puede esperar al siguiente día hábil.

## Canales de soporte

- **Email** (POC-ready): `equipo@geoevidence.com` — canal primario, mejor para issues no-urgentes.
- **Status page**: `/api/v1/health` y `/api/v1/version` (POC-ready); statuspage.io o equivalente (ship-ready).
- **Escalación** (ship-ready): Slack compartido con integradores activos.

## Correlación de incidentes

Cada response del API incluye el header `X-Request-Id` (UUID v4). Cuando reportes un incidente, **incluí este ID** — corresponde 1-a-1 con la fila en `access_log` y nos permite reconstruir exactamente qué pasó.

Si el cliente envía `X-Request-Id` propio, lo respetamos. Si no, generamos uno nuevo. Ambos casos quedan logueados.

## Notificación de breaking changes

Per [`readiness-table-v1.md`](./readiness-table-v1.md) §Política de deprecation, **6 meses de aviso previo** a cualquier breaking change.

Canales de notificación:
1. Entrada en [`CHANGELOG.md`](./CHANGELOG.md) con la fecha de deprecation marcada.
2. Header `GeoEvidence-Deprecation-Notice` en responses de endpoints afectados durante la ventana.
3. Email directo a todos los integradores activos (con `partner_id` lookup en `api_keys.last_used_at`).
4. Anuncio en `developers.geoevidence.com/api-spec.yaml` (nueva entrada en `info.version`).

Qué cuenta como **breaking**: eliminar endpoint/field, cambiar tipo, cambiar success status code, cambiar auth scheme, cambiar HMAC payload format.
Qué **NO** cuenta: añadir field opcional, añadir endpoint, añadir header, alargar string, añadir enum value.

## Data residency (POC-ready)

Deploy único en región US (Railway default). Para integradores europeos con requisito GDPR, esto es un blocker — manejado en mapa A de certificaciones y roadmap ship-ready (regions EU/US).

PII mínima expuesta: el `evidence_id` (md5 del server_hash) y metadata de captura (lat/lon, timestamp). Sin nombres, emails, ni PII directa del usuario final.

## Rate limit (per partner)

| Tier | Límite | Ventana |
|---|---|---|
| Default (POC-ready) | 1000 req/partner/h | sliding window 1h |
| Test mode (POC-ready) | 100 req/partner/h, expira en 7 días | sliding window 1h |
| Enterprise (ship-ready) | negociable | negociable |

Headers en cada response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. En 429: `Retry-After` con segundos hasta el próximo slot.

## Compromisos que NO asumimos (POC-ready)

- **99.9%+ uptime contractual** — eso es ship-ready.
- **Latency SLA** (< 200ms p99) — eso es ship-ready.
- **Multi-region failover** — eso es ship-ready.
- **24/7 soporte humano** — eso es ship-ready.
- **Compliance certifications** (ISO 27001, SOC 2) — vive en mapa A.

## Cómo escalar a ship-ready

Si necesitás un SLA más estricto para un pilot formal:
1. Email a `equipo@geoevidence.com` con tu caso de uso y volumen estimado.
2. Acordamos un tier custom (rate limit + SLA).
3. Firmamos amendment al agreement con los nuevos términos.
4. Migramos tu `api_keys.scopes` a un scope dedicado y `last_used_at` se trackea con más detalle.

Para ship-ready formal (no custom), esperar al mapa A de certificaciones + roadmap de multi-region.