Subalans API

Introducción

Cada servicio vive bajo un mismo dominio y expone un único endpoint POST /api/v1 (más un GET /health). Todas las peticiones se autentican con un Bearer token y envían las credenciales del contribuyente en el cuerpo JSON. Las APIs son stateless: hacen login en cada llamada, no guardan credenciales ni archivos, y no registran datos sensibles.

Autenticación

Manda tu token en el header Authorization con el esquema Bearer. Todas las peticiones usan Content-Type: application/json.

curl -X POST https://subalans.com/api/v1/constancia \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "rfc": "XAXX010101000", "ciec": "TU_CIEC" }'

Un token ausente devuelve 401 { "error": "Falta el header Authorization: Bearer <token>." }; una llave inválida o revocada devuelve 401 { "error": "API key inválida o revocada." }. Los 401 traen solo error (sin ok).

Permisos y vigencia de las llaves

Desde el dashboard de desarrolladores cada llave puede configurarse con:

• Permisos por servicio — restringe la llave a ciertos servicios (p. ej. sólo EFOS y CFDI). Llamar a un servicio no permitido devuelve 403 code: "key_scope_denied" con la lista allowed_services en el cuerpo.
• Vigencia — 7 días, 30 días, 90 días, 1 año o sin expiración. Una llave vencida (expires_at) responde 401 igual que una revocada.

Credenciales del contribuyente

Cada documento se obtiene autenticándose ante el portal del gobierno con las credenciales del contribuyente. Hay dos métodos; cada servicio acepta uno o ambos:

Método CIEC

Método e.firma (FIEL)

const fs = require("fs");
const payload = {
  rfc: "ACE180101AA1",
  cer_b64: fs.readFileSync("cert.cer").toString("base64"),
  key_b64: fs.readFileSync("private.key").toString("base64"),
  password: "TU_PASSWORD_EFIRMA",
};

Formato de petición y respuesta

Toda petición es un POST con cuerpo JSON al endpoint /api/v1 del servicio. La forma del 200 depende del servicio:

• Endpoints de PDF (/constancia, /opinion, /opinion-imss, /infonavit): el cuerpo de la respuesta es el PDF binario (Content-Type: application/pdf + Content-Disposition). Guárdalo a disco o súbelo a tu storage tal cual.
• CFDI y Buzón: JSON con "ok": true y los datos; los archivos van en Base64.

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="constancia.pdf"

%PDF-1.7 … (bytes del PDF)

const r = await fetch("https://subalans.com/api/v1/constancia", {
  method: "POST",
  headers: { Authorization: "Bearer " + token, "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
if (!r.ok) throw new Error((await r.json()).error);  // los errores sí son JSON
const pdf = Buffer.from(await r.arrayBuffer());  // el 200 es binario
fs.writeFileSync("constancia.pdf", pdf);           // o súbelo a tu storage

Manejo de errores

Las respuestas de error siempre son JSON con "ok": false, un error legible (en español, listo para mostrar al usuario) y, cuando aplica, un code semántico para tu lógica. El código HTTP te dice de quién es el problema:

Campo code (taxonomía)

{
  "ok": false,
  "code": "credencial",
  "error": "La CIEC es incorrecta: el RFC o la contraseña CIEC no son válidos en el SAT."
}

Reintentos y timeouts

Los documentos que requieren navegar portales del gobierno (IMSS, Infonavit, Opinión SAT) tienen latencia variable porque dependen de servicios externos (validación OCSP del SAT, anti-bots, etc.). Diseña tu cliente para tolerarlo:

• Timeout del cliente ≥ 180 s para IMSS e Infonavit (no cortes a los 90 s — matarías corridas válidas).
• Reintenta sólo 5xx (502/504, code: "tecnico"/"timeout") con backoff exponencial. No reintentes 4xx — son del lado del usuario.
• Latencia típica por servicio:

Modo asíncrono y webhooks

Los documentos que dependen de portales del gobierno pueden tardar de segundos a minutos. En vez de mantener la conexión abierta, agrega "async": true al cuerpo de cualquier endpoint de documento (/constancia, /opinion, /opinion-imss, /infonavit, /buzon, /cfdi) y la API responde de inmediato con un job_id:

curl -X POST https://subalans.com/api/v1/opinion \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "rfc": "XAXX010101000", "ciec": "TU_CIEC", "async": true }'

{
  "ok": true,
  "job_id": "job_a1b2c3d4e5f6a7b8c9d0",
  "status": "queued",
  "poll": "/api/v1/jobs/job_a1b2c3d4e5f6a7b8c9d0"
}

Consultar el resultado (polling)

GET /api/v1/jobs/{job_id} es la fuente de verdad y funciona en todos los planes. Estados: queued → running → done | failed. En done, el campo result trae la misma respuesta que el modo síncrono (en los endpoints de PDF, el documento viene en result.pdf_base64). Los resultados viven 24 horas.

{
  "ok": true,
  "job_id": "job_a1b2c3d4e5f6a7b8c9d0",
  "status": "done",
  "result": { "ok": true, "pdf_base64": "JVBERi0…", "sentido": "positiva" }
}

Si el trámite falla, status es failed y error trae el mensaje (mismo texto y semántica que los errores síncronos). Los fallos técnicos del portal se reintentan solos con backoff antes de darse por vencidos; los de credencial fallan a la primera (no tiene caso reintentar una CIEC incorrecta).

Webhooks (planes Pro y Scale)

Configura tu URL en el panel (sección Webhooks) o mándala por petición en webhook_url. Al terminar el job te enviamos un POST firmado:

POST https://tuservidor.com/hooks/subalans
X-Subalans-Signature: t=1780000000,v1=5f8a…
X-Subalans-Event-Id: evt_job_a1b2c3d4e5f6a7b8c9d0_done

{
  "event": "job.completed",   // o "job.failed"
  "job_id": "job_a1b2c3d4e5f6a7b8c9d0",
  "type": "ocsat",
  "status": "done",
  "result": { … },
  "event_id": "evt_job_a1b2c3d4e5f6a7b8c9d0_done"
}

Verificar la firma

El header X-Subalans-Signature es t=<epoch>,v1=<hex> donde v1 = HMAC-SHA256(secreto, t + "." + cuerpoCrudo). Rechaza cualquier webhook cuya firma no coincida — sin esto, cualquiera podría inyectarte resultados falsos.

const crypto = require("node:crypto");
function verificar(sigHeader, cuerpoCrudo, secreto) {
  const [, t, v1] = /t=(\d+),v1=([0-9a-f]+)/.exec(sigHeader) ?? [];
  if (!t) return false;
  const esperado = crypto.createHmac("sha256", secreto).update(t + "." + cuerpoCrudo).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1));
}

• Reintentos: si tu servidor no responde 2xx, reintentamos a 1 s, 10 s, 1 min y 10 min. Después de eso, recupera el resultado con GET /api/v1/jobs/{id}.
• Idempotencia: deduplica con event_id — un mismo evento puede llegar más de una vez.
• Responde rápido: regresa el 200 de inmediato y procesa después; cortamos la conexión a los 10 s.

Modo prueba (sandbox) Disponible

El modo prueba te permite construir tu integración sin credenciales reales del contribuyente y sin tocar los portales del gobierno: con una llave sk_test_…, ciertos RFCs de prueba devuelven respuestas predefinidas — al instante y de forma determinista — para que puedas probar todos los caminos (éxito y cada error) antes de pasar a producción.