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": "********" }'

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).

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: "••••••••",
};

Formato de petición y respuesta

Toda petición es un POST con cuerpo JSON al endpoint /api/v1 del servicio. Una respuesta exitosa siempre incluye "ok": true y el documento (o los datos) solicitados.

{
  "ok": true,
  "rfc": "ACE180101AA1",
  "pdf_base64": "JVBERi0xLjQKJ..."   // el documento, codificado en Base64
}

const r = await fetch("https://subalans.com/api/v1/constancia", {
  method: "POST",
  headers: { Authorization: "Bearer " + token, "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
const data = await r.json();
if (data.ok) fs.writeFileSync("constancia.pdf", Buffer.from(data.pdf_base64, "base64"));

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 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.