API de Sereno Fiscal

Una API es una puerta para que tus programas hablen con Sereno sin que nadie abra la pantalla. Esta es de solo lectura: consulta y avisa, pero nunca presenta nada ante el SAT ni toca tu e.firma.

Para quién es

• Quien tiene un ERP, un sistema de compras o de contabilidad y quiere validar a cada proveedor contra las listas antes de pagarle.
• Quien arma automatizaciones en Zapier o Make y quiere que una alerta de Sereno cree una tarea o mande un mensaje.
• Los despachos contables que quieren ver el semáforo de todos sus clientes en su propio tablero.

Cómo obtener tu llave

1. Entra a Sereno con una cuenta de administrador y abre Mi cuenta, pestaña API. (En un despacho, la crea el dueño.)
2. Elige Crear llave, ponle un nombre que la distinga, marca los permisos que necesita y, si quieres, las empresas y una fecha de vencimiento.
3. Copia la llave en cuanto aparezca: se muestra una sola vez. Guárdala en el gestor de contraseñas o en la configuración segura de tu sistema.

La API viene incluida en los paquetes Pro, Max y Corporativo, y se puede añadir al paquete Plus con el complemento de API. Los despachos tienen su propia llave, que crea el dueño del despacho. Si tu paquete no la incluye, la pestaña te lo avisa.

Seguridad

• La llave se ve una sola vez. Sereno solo guarda una huella de ella, así que no podemos mostrártela después. Si la pierdes, rótala o crea otra.
• Da alcances mínimos. Una llave que solo valida proveedores necesita únicamente listas. Si se filtra, el daño es menor.
• Úsala solo desde tu servidor. La API no acepta llamadas desde un navegador a propósito: una llave dentro de una página web quedaría a la vista de cualquiera.
• Hay límites diarios y por minuto por llave (ver Límites) y un tope por dirección de internet para frenar intentos con llaves falsas.
• Rota con calma. Al rotar una llave, la anterior sigue sirviendo 7 días para que cambies tus sistemas sin cortes.
• Revoca sin dudar. Una llave revocada deja de servir en segundos. Sereno te avisa por correo si una llave lleva 90 días sin usarse.

Tu primera consulta

La dirección base es https://api.serenofiscal.mx/v1. Con tu llave en la variable SERENO_LLAVE:

curl "https://api.serenofiscal.mx/v1/listas/DEL120301AB3" \
  -H "Authorization: Bearer $SERENO_LLAVE"

Manda la llave en el encabezado Authorization de cada petición, con la palabra Bearer y un espacio antes. Una llave tiene esta forma: srn_live_ seguido de 43 letras, números, guiones o guiones bajos.

Authorization: Bearer srn_live_…

Para comprobar que tu llave funciona sin gastar cuota, pide el estado. Con llave, además de la salud del servicio verás tu plan, tus límites y lo que llevas gastado hoy:

curl "https://api.serenofiscal.mx/v1/estado" \
  -H "Authorization: Bearer $SERENO_LLAVE"

Una llave que falta, mal escrita, inexistente, revocada o vencida responde siempre el mismo 401 (llave_invalida). Los permisos de la llave se llaman alcances:

Si la llave se limitó a ciertas empresas, solo ve esas. Pedir una empresa que no ve da el mismo 404 que una que no existe. Las empresas que el equipo de Sereno tenga suspendidas no aparecen en la API, y si la cuenta fue cerrada recibirás 403 cuenta_suspendida. La API es de servidor a servidor: no admite llamadas desde un navegador (no tiene CORS), para que tu llave nunca viva en una página web.

• Formato. Todo es JSON en UTF-8. Las rutas y los campos están en español (razon_social, fecha_limite) y las listas cerradas de valores van sin acento (ambar, critica).
• Versión. Va en la ruta (/v1). Agregar campos nuevos no rompe nada: ignora los que no conozcas. Un cambio que rompe sería /v2.
• Fechas. Los instantes van en ISO 8601 y en UTC (2026-10-19T14:03:00Z); las fechas, como 2026-10-19; los periodos, como 2026-09. Los cortes de día y de mes se hacen en hora de la Ciudad de México.
• Dinero. Siempre como texto decimal con dos decimales ("1250300.00") y su moneda, nunca como número flotante. Lo que viene en otra moneda se convierte a pesos con el tipo de cambio de la factura.
• RFC. Se aceptan en minúsculas y con espacios en los bordes; se devuelven en mayúsculas.
• Paginación por cursor. Las listas aceptan ?limite=100 (de 1 a 200) y ?cursor=…. La respuesta trae {"datos": [...], "siguiente_cursor": null}: mientras siguiente_cursor no sea null, pídelo como cursor con los mismos filtros. El cursor es opaco; no lo armes ni lo interpretes.
• Idempotency-Key. POST /listas/lote y POST /webhooks/{id}/probar aceptan este encabezado (hasta 64 caracteres). Repetir la misma petición con la misma clave devuelve la misma respuesta sin volver a gastar cuota; la misma clave con otro cuerpo da 409. Se guarda 24 horas.
• Encabezados de respuesta. X-Id-Peticion (el id que verás también en los errores), X-Limite-Dia y X-Restante-Dia (tu cuota del día), Retry-After en los 429 e Idempotent-Replayed cuando se repite una respuesta guardada.
• Tiempos. Espera hasta 15 segundos antes de dar por perdida una petición.

Son 20 endpoints. Cada uno indica su alcance, qué cuenta contra tu cuota, sus parámetros, un ejemplo con curl y la respuesta. Todos los datos de los ejemplos son inventados. La misma referencia, para herramientas, está en openapi.json.

Un webhook es una dirección de tu sistema a la que Sereno le manda un aviso cuando ocurre algo, para que no tengas que preguntar una y otra vez. Los creas en Cuenta > API o con POST /webhooks. Al crearlo recibes un secreto (whsec_…) que se muestra una sola vez. Para eventos que no sean ping, la llave que lo crea debe tener los alcances webhooks y empresas.

Eventos

Forma del aviso

Cada aviso es una petición POST con el evento en JSON:

{
  "id": "evt_261019140211a1b2c3d4e5f6",
  "tipo": "alerta.creada",
  "creado": "2026-10-19T14:02:11Z",
  "empresa_rfc": "ABC010101AB1",
  "datos": {
    "alerta_id": "3f2e8c1a-5b7d-4e90-a1c2-9d4f6b8e0a12",
    "severidad": "alta",
    "regla": "L-02",
    "titulo": "Proveedor en lista 69-B",
    "rfc_contraparte": "DEL120301AB3",
    "fecha_limite": null
  },
  "url": "/v1/empresas/ABC010101AB1/alertas?id=3f2e8c1a-5b7d-4e90-a1c2-9d4f6b8e0a12"
}

id identifica el evento, creado es cuándo ocurrió y url es la ruta de esta API donde ver el detalle. Los mismos eventos de los últimos 30 días están en GET /eventos, útil para recuperar avisos que tu servidor se perdió.

Encabezados

• Sereno-Evento-Id: el id del evento (igual que id en el cuerpo).
• Sereno-Firma: t=1760882580,v1=<hex>, donde t es la hora en segundos desde 1970 y v1 es la firma. Durante la rotación del secreto trae dos v1.

Cómo verificar la firma

La firma es un código HMAC-SHA256 (un código que solo Sereno y tú pueden calcular porque ambos conocen el secreto) de la hora, un punto y el cuerpo exacto: HMAC-SHA256(secreto, t + "." + cuerpo), en hexadecimal. Usa el secreto completo, con su prefijo whsec_, como llave. Para estar seguro de que el aviso viene de Sereno:

1. Lee el cuerpo tal como llegó, como texto. Si lo conviertes a objeto y lo vuelves a escribir, la firma ya no coincide.
2. Rechaza el aviso si t tiene más de 5 minutos de diferencia con tu reloj (evita que alguien repita un aviso viejo).
3. Calcula la firma esperada y compárala con cada v1 con una comparación de tiempo constante (timingSafeEqual en Node, compare_digest en Python), nunca con ==.

import crypto from "node:crypto";

// secreto: el whsec_… completo que se mostró al crear el webhook.
// cuerpoCrudo: el cuerpo EXACTO que llegó, como texto (sin volver a serializarlo).
export function verificarFirma(secreto, encabezado, cuerpoCrudo, ahoraS = Math.floor(Date.now() / 1000)) {
  const partes = encabezado.split(",").map((p) => p.trim().split("="));
  const t = Number(partes.find(([k]) => k === "t")?.[1]);
  const firmas = partes.filter(([k]) => k === "v1").map(([, v]) => v);
  if (!Number.isFinite(t) || firmas.length === 0) return false;
  if (Math.abs(ahoraS - t) > 300) return false; // más de 5 minutos: rechazar
  const esperada = crypto.createHmac("sha256", secreto).update(`${t}.${cuerpoCrudo}`).digest("hex");
  return firmas.some(
    (f) => f.length === esperada.length && crypto.timingSafeEqual(Buffer.from(f), Buffer.from(esperada)),
  );
}

import express from "express";
import { verificarFirma } from "./verificar-firma.js";

const app = express();
const yaProcesados = new Set(); // en producción, una tabla o Redis con los ids de evento

// Importante: leer el cuerpo SIN convertirlo a objeto antes de verificar la firma.
app.post("/sereno", express.raw({ type: "application/json" }), (req, res) => {
  const cuerpo = req.body.toString("utf8");
  if (!verificarFirma(process.env.SERENO_SECRETO, req.get("Sereno-Firma") ?? "", cuerpo)) {
    return res.sendStatus(400);
  }
  const evento = JSON.parse(cuerpo);
  if (yaProcesados.has(evento.id)) return res.sendStatus(200); // repetido: ya lo atendiste
  yaProcesados.add(evento.id);
  console.log(evento.tipo, evento.empresa_rfc);
  res.sendStatus(200); // responde 2xx en menos de 10 segundos
});

app.listen(3000);

import hashlib
import hmac
import time


def verificar_firma(secreto: str, encabezado: str, cuerpo: bytes, tolerancia_s: int = 300) -> bool:
    """secreto: el whsec_… completo. cuerpo: los bytes EXACTOS que llegaron."""
    partes = [p.strip().split("=", 1) for p in encabezado.split(",") if "=" in p]
    t = next((v for k, v in partes if k == "t"), None)
    firmas = [v for k, v in partes if k == "v1"]
    if t is None or not t.isdigit() or not firmas:
        return False
    if abs(time.time() - int(t)) > tolerancia_s:  # más de 5 minutos: rechazar
        return False
    esperada = hmac.new(secreto.encode(), t.encode() + b"." + cuerpo, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(f, esperada) for f in firmas)

import os

from flask import Flask, request

from verificar_firma import verificar_firma

app = Flask(__name__)
ya_procesados = set()  # en producción, una tabla o Redis con los ids de evento


@app.post("/sereno")
def recibir():
    cuerpo = request.get_data()  # bytes sin tocar
    if not verificar_firma(os.environ["SERENO_SECRETO"], request.headers.get("Sereno-Firma", ""), cuerpo):
        return "", 400
    evento = request.get_json()
    if evento["id"] in ya_procesados:
        return "", 200  # repetido: ya lo atendiste
    ya_procesados.add(evento["id"])
    print(evento["tipo"], evento["empresa_rfc"])
    return "", 200  # responde 2xx en menos de 10 segundos

Entrega, reintentos y pausa

• Al menos una vez. Un aviso puede llegar repetido: guarda los id que ya atendiste y descarta los repetidos. No hay garantía de orden; usa creado para ordenar.
• Éxito es una respuesta 2xx en menos de 10 segundos. Responde rápido y procesa después.
• Reintentos si falla: a 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 24 horas (7 intentos en total). Si todos fallan, la entrega queda como fallida y el evento sigue disponible en GET /eventos. Puedes reintentar a mano desde Cuenta > API.
• Pausa. Tras 20 entregas fallidas seguidas, el webhook se pausa y avisamos por correo al administrador. Cuando tu servidor vuelva a responder, reanúdalo desde Cuenta > API.
• Destino. Solo https en el puerto 443, sin usuario ni contraseña y sin redirecciones (una respuesta 3xx cuenta como falla). La dirección se resuelve al enviar y se rechazan las redes privadas, locales y de metadatos, para que nadie use a Sereno contra redes internas.
• Rotar el secreto. Al rotarlo, durante 24 horas cada aviso trae dos firmas (la del secreto nuevo y la del anterior). Acepta cualquiera y cambia el secreto en tu sistema con calma.

Cuando algo sale mal, la respuesta trae el código HTTP y un cuerpo con esta forma, siempre con el id_peticion (que también viaja en el encabezado X-Id-Peticion; menciónalo si nos escribes):

{
  "error": {
    "codigo": "limite_diario",
    "mensaje": "Llegaste a 1,000 consultas de listas hoy; se reinicia a las 00:00 (hora de México).",
    "id_peticion": "req_8f2c1a9e04",
    "reintentar_en": 5400
  }
}

El mensaje está en español y se puede mostrar tal cual. Programa contra el codigo, que no cambia. reintentar_en (segundos) solo viene en los 429, igual que el encabezado Retry-After.

Un RFC de otra cuenta responde exactamente igual que uno que no existe (404 no_encontrado): así la API no revela quién es cliente de Sereno.

Hay dos cuotas diarias que se reinician a las 00:00, hora de la Ciudad de México: las consultas de listas (cada RFC que revisas cuenta una, también dentro de un lote) y las lecturas (cualquier otra petición cuenta una). Los límites se cuentan por llave. Además hay un tope de peticiones por minuto, que es un freno y puede variar un poco.GET /estado no gasta cuota. Un lote que no cabe completo en lo que te queda se rechaza completo.

• Un lote lleva hasta 500 RFC por petición.
• Los paquetes que no aparecen en la tabla no incluyen la API.
• Si llegas al límite diario recibes 429 limite_diario con Retry-After; si pasas el de minuto, 429 limite_minuto. Reintenta después de ese tiempo, no antes.
• También hay un tope por dirección de internet: 300 peticiones por minuto y 60 intentos con llave inválida en 10 minutos.
• Tu consumo del día está en el panel (Cuenta > API) y en GET /estado.

¿Dudas o algo que no funciona como aquí se dice? Escríbenos a hola@serenofiscal.mx con el id_peticion.