Respuesta técnica para RFPs · API e integraciones de Pitflo
Versión del 19 ago 2026
Este documento resume, con sus decisiones fechadas, cómo Pitflo expone datos a sistemas externos y qué garantías ofrece. Está pensado para el equipo de integraciones y el jurídico de una cadena: cada afirmación existe como decisión versionada en el producto, no como promesa comercial.
Alcance: solo lectura (decisión I6, 2026-08-07)
La API pública /v1 es de SOLO LECTURA. La escritura por API no existe en v1 y ningún token puede alterar datos de la empresa. Un cambio incompatible del contrato estrena /v2 — el consumidor de /v1 no se rompe en silencio.
Bajas: lápidas donde las hay, y dicho de frente dónde no
Los borrados lógicos no salen por las LECTURAS de la API: la fila dada de baja deja de listarse. Por webhook, los recursos con lápida avisan la baja — customer.deleted, vehicle.deleted y service.deleted entregan { id, deleted: true } para que el sistema del cliente quite esa fila (service.restored la devuelve viva). En los recursos SIN evento de baja, una baja en Pitflo no llega sola: la empresa es responsable de lo que copie a su sistema, incluidas esas bajas — lo decimos en la pantalla de Integraciones y aquí.
Mitigación práctica donde no hay lápida: re-lecturas completas periódicas del recurso, o conciliación por updated_since + inventario de ids.
Control de datos: allowlist con marca pii, negado por omisión
Cada empresa decide qué recursos y qué CAMPOS expone su token; nada nace expuesto. Los campos que identifican personas llevan la marca pii en el propio OpenAPI (x-pii) y la pantalla los agrupa bajo advertencia. internalNotes no es elegible para nadie, nunca. Una columna nueva del esquema NO nace expuesta: una prueba de CI obliga a clasificarla a mano.
Webhooks firmados y anti-SSRF
Cada entrega viaja firmada (Pitflo-Firma: HMAC-SHA256 con epoch dentro de lo firmado; verificación documentada: ventana de 5 minutos, comparación en tiempo constante, dedupe por id estable entre reintentos).
Anti-SSRF en CADA entrega: solo https puerto 443, se resuelven todas las IPs del host y se conecta a la IP validada (pinning contra DNS rebinding); vetados loopback, rangos privados, link-local y multicast. El cuerpo de la respuesta del destino no se guarda.
Las entregas se conservan 30 días (solo metadatos; el payload se borra al entregarse o morir).
Límites de servicio (catálogo público co-probado en CI)
600 peticiones/minuto por token; superficies públicas a 10/minuto por IP; límite global por sesión 120/minuto. Cupos: 10 integraciones activas por empresa, 3 webhooks por integración, limit 100 por página. Los números viven en un catálogo único publicado en /limits y el CI truena si divergen de las constantes reales.
Aislamiento y autenticación
El token es opaco (pfk_ + 32 bytes aleatorios), se enseña una vez y en base solo vive su sha256. Toda consulta deriva la empresa DEL TOKEN, jamás de un parámetro; el id de otra empresa responde el mismo 404 que un id inexistente. Una cookie de sesión sobre /v1 es 403 estructural. La fuerza bruta de tokens paga 429 por IP antes de tocar la base.
Documentos legales y niveles de servicio
Términos de servicio, políticas de seguridad y el DPA (Pitflo encargado / la empresa responsable, LFPDPPP) son documentos versionados públicos — se leen DENTRO de este portal, en la columna de la izquierda. El anexo de niveles de servicio (SLA) es el documento hermano de esta respuesta: versión pública con fecha, medido por la página de estado.