Integra tus reportes de campo con tu ERP

ServiReports Connect es una API REST sobre HTTPS que responde en JSON. Con ella tu sistema puede buscar los reportes de tu organización, descargar su PDF, etiquetarlos con tu propio identificador y recibir avisos automáticos cuando ocurren eventos.

Al ser HTTP estándar, es compatible con cualquier lenguaje — JavaScript/Node, Python, PHP, Java, C#, Go, Ruby — o simplemente curl. No hay que instalar ningún SDK: usas el cliente HTTP que ya trae tu lenguaje.

Propósito. Automatizar tu operación: que un reporte foliado por tu técnico aparezca solo en tu ERP, ligado a tu orden de trabajo o factura, y obtener su PDF cuando lo necesites — sin que nadie entre al portal a copiar datos a mano.

Suscripción. El uso en producción requiere la suscripción de la API (una por organización). Puedes desarrollar y probar gratis en modo sandbox antes de activarla.

Toda llamada a la API se arma con cuatro piezas. Tomemos como ejemplo “buscar reportes”:

Así se ve completa, con las cuatro piezas juntas (misma llamada en 5 lenguajes):

curl -H "Authorization: Bearer TU_API_KEY" \
  "https://api.servireports.com/api/v1/reports?query=bomba&limit=20"

La API siempre responde con un código HTTP (200 = todo bien) y un cuerpo JSON. Mira la pestaña Respuesta arriba para ver exactamente qué te devuelve. En la sección Respuestas y diagnóstico explicamos cada código.

Las llaves que empiezan con dev_ son de sandbox. Funcionan gratis sobre los datos reales de tu organización, para que desarrolles y valides tu integración sin costo.

En sandbox, la descarga de PDF devuelve un PDF de prueba (con la leyenda “Prueba de descarga PDF”) y no consume cuota. Todo lo demás — búsqueda, referencia, registro de webhooks — se comporta igual que en producción, así tu código no cambia al pasar a vivo: solo cambias la llave.

Las llaves que empiezan con sr_live_ son de producción: entregan tus reportes reales y el PDF definitivo de cada uno. Requieren la suscripción de la API activa.

Si llamas con una llave de producción sin suscripción activa, la API responde 403 API_SUBSCRIPTION_REQUIRED. Actívala o renuévala desde la gestión de la suscripción.

Generar. En la pestaña Claves generas una llave sandbox o de producción. La llave completa se muestra una sola vez al crearla — guárdala en un lugar seguro (variable de entorno o gestor de secretos). Solo guardamos una huella; no podemos volver a mostrártela.

Usar. Envíala en el encabezado Authorization: Bearer TU_API_KEY en cada solicitud. Tu organización se identifica a partir de la propia llave — nunca la envías tú.

curl -H "Authorization: Bearer TU_API_KEY" "https://api.servireports.com/api/v1/usage"

¿Puedo tener varias? Sí. Crea las que necesites (por sistema, por ambiente). Todas comparten la misma cuota diaria de descargas de tu organización.

Eliminar. Revoca una llave desde la pestaña Claves; deja de funcionar de inmediato. Si sospechas que se filtró, revócala y genera otra.

• Las consultas son gratis y sin límite: buscar reportes, consultar uso, actualizar la referencia, gestionar webhooks.
• Solo las descargas de PDF consumen una cuota diaria por organización, compartida entre todas tus llaves.
• Al agotar la cuota del día, la descarga responde 429 API_RATE_LIMITED con el encabezado Retry-After (segundos hasta el reinicio). Respeta ese valor y reintenta.
• Consulta cuánto te queda cuando quieras con GET /usage.

Cada respuesta trae un código HTTP. Con él diagnosticas todo: si empieza en 2xx salió bien; 4xx es un problema de tu petición; 5xx es un error temporal del servidor.

• Los éxitos (2xx) devuelven el JSON del recurso (revisa la pestaña Respuesta en cada función).
• Los errores devuelven { "code": "...", "error": "..." }. Programa contra code (estable), no contra el texto.
• Toda respuesta trae el encabezado X-ServiReports-Mode: sandbox | production, para confirmar contra qué entorno hablas.

En la pestaña Actividad ves el uso por cada API key (última vez utilizada), para saber qué llaves están activas, detectar integraciones que dejaron de usarse y decidir cuáles conservar o revocar.

Para el estado de la cuota del día (límite, usado, restante) usa GET /usage desde tu integración — así tu propio sistema se monitorea y previene antes de una carga grande.

Un reporte es el documento de campo que tu técnico generó y folió desde la app: datos generales, secciones de contenido, fotos y firmas. Una vez foliado es definitivo (no cambia). Cada reporte tiene un folio único (ej. OYS2609-001) — es su identificador.

• Metadata (JSON) al buscarlo: folio, título, cliente, empresa, departamento, tipo de usuario, quién lo creó, fechas y tu referencia.
• Documento en PDF cuando lo descargas: el reporte completo, listo para archivar o imprimir. Para verlo, cualquier visor de PDF estándar.

La API no entrega las fotos/firmas sueltas; entrega el PDF final, que ya las incluye.

El índice es la lista de todos los reportes foliados de tu organización con su metadata. Es lo que consultas con GET /reports, con filtros y paginación.

Se entrega como JSON paginado: cada respuesta trae un arreglo reports, un count y un nextCursor. La primera vez (para llenar tu ERP con el histórico) recorres todo el índice pidiendo páginas con ?cursor=<nextCursor> hasta que nextCursor venga vacío — o, más simple, pides ?limit=-1 y te devolvemos todo de una vez. Después ya no re-lees todo: te mantienes al día con el webhook report.created.

Volcado completo (backfill inicial), en 5 lenguajes:

# El volcado completo se hace en bucle (pagina por pagina).
# Se implementa en tu lenguaje; el patron es: pedir 100, guardar,
# tomar nextCursor, repetir hasta que venga vacio. Ver otras pestanas.

Un webhook es al revés de una llamada normal: en vez de que tú preguntes, nosotros avisamos a tu servidor cuando pasa algo. Tú registras una URL https tuya y te mandamos un POST firmado cada vez que ocurre el evento.

Paso 1 — registrar tu URL y a qué eventos suscribirte:

curl -X POST \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tu-sistema.com/sr-hook","events":["report.created"]}' \
  "https://api.servireports.com/api/v1/webhooks"

Guarda el secret que te devuelve: lo necesitas para verificar que el aviso realmente vino de nosotros. Cada envío llega a tu URL con estos encabezados:

Paso 2 — verifica la firma antes de confiar en el aviso. Calculas el HMAC-SHA256 del cuerpo crudo (sin parsear) con tu secret y lo comparas con X-ServiReports-Signature:

# La verificacion de firma se hace en TU servidor (no con curl).
# Formula: sha256=HMAC_SHA256(cuerpo_crudo, tu_secret)
# Compara ese valor con el header X-ServiReports-Signature.
# Ver ejemplos en Node / Python / PHP / Java en las otras pestanas.

# Un receptor de webhook es un endpoint HTTP en TU servidor.
# No se implementa con curl. Elige tu lenguaje en las otras pestanas:
# el patron es SIEMPRE: (1) leer cuerpo crudo, (2) verificar firma,
# (3) responder 2xx rapido, (4) procesar de forma idempotente.

Los errores llegan con el código HTTP + un cuerpo { code, error }. Programa tu integración contra code (estable), no contra el texto (que puede cambiar).

Esta sección no son reglas, son ideas de implementación: cómo montar la API del lado de tu servidor para que rinda al máximo. Combínalas todas y tu integración prácticamente se auto-mantiene.

# El volcado completo se hace en bucle (pagina por pagina).
# Se implementa en tu lenguaje; el patron es: pedir 100, guardar,
# tomar nextCursor, repetir hasta que venga vacio. Ver otras pestanas.

# Patron conceptual (se implementa en tu servidor, no con curl):
# 1. Busca el reporte en TU base local.
# 2. Si esta -> lo devuelves (0 llamadas, 0 cuota).
# 3. Si NO esta -> lo pides a la API, lo guardas en tu base, y lo devuelves.
# Con el tiempo casi todo lo resuelves localmente.

# Flujo recomendado (pseudo-pasos, cada paso en tu lenguaje):
# 1. Registras UNA vez el webhook report.created.
# 2. Cada reporte nuevo llega solo a tu /sr-hook -> lo guardas en tu ERP.
# 3. Cuando un usuario abre la orden, bajas el PDF UNA vez y lo archivas.
# Asi no consultas en bucle y solo gastas cuota cuando de verdad ves el PDF.

Recordatorios rápidos:

• Respeta Retry-After en un 429 (espera creciente / backoff exponencial).
• Revisa /usage antes de una carga grande y actúa ante el webhook usage.threshold.
• Verifica siempre la firma del webhook y procesa idempotente con X-ServiReports-Delivery.