FSV1 — Estandar de Identidad Fiscal Digital

Resumen

Campos

Como generar un QR FSV1

1. Construir objeto JSON con campos requeridos + opcionales
2. Minificar JSON (sin espacios)
3. Codificar en base64url
4. Prepend FSV1:
5. Generar codigo QR con el string resultante

Como leer un QR FSV1

1. Escanear QR y obtener string
2. Verificar que empieza con FSV1:
3. Remover el prefijo y decodificar base64url
4. Parsear como JSON UTF-8
5. Validar campos requeridos: v, tipo_doc, nit, nombre

Ejemplos de codigo

Python

import json, base64

def decode_fsv1(qr_string: str) -> dict:
    """Decodifica un QR fiscal FSV1."""
    assert qr_string.startswith("FSV1:"), "No es FSV1"
    b64 = qr_string[5:]
    json_str = base64.urlsafe_b64decode(b64).decode("utf-8")
    return json.loads(json_str)

def encode_fsv1(data: dict) -> str:
    """Codifica datos fiscales a FSV1."""
    json_str = json.dumps(data, ensure_ascii=False, separators=(',',':'))
    b64 = base64.urlsafe_b64encode(json_str.encode("utf-8")).decode()
    return f"FSV1:{b64}"

# Ejemplo
fiscal = {
    "v": 1,
    "tipo_doc": "36",
    "nit": "06140101901023",
    "nombre": "Empresa Ejemplo S.A."
}
qr = encode_fsv1(fiscal)
print(qr)  # FSV1:eyJ2IjoxLC...
print(decode_fsv1(qr))  # {v: 1, tipo_doc: "36", ...}

JavaScript

function decodeFSV1(qrString) {
  if (!qrString.startsWith("FSV1:")) throw new Error("No es FSV1");
  const b64 = qrString.slice(5);
  // base64url → base64
  const base64 = b64.replace(/-/g, '+').replace(/_/g, '/');
  const json = atob(base64);
  return JSON.parse(json);
}

function encodeFSV1(data) {
  const json = JSON.stringify(data);
  const b64 = btoa(json)
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
  return "FSV1:" + b64;
}

// Ejemplo
const fiscal = {
  v: 1, tipo_doc: "36",
  nit: "06140101901023",
  nombre: "Empresa Ejemplo S.A."
};
const qr = encodeFSV1(fiscal);
console.log(decodeFSV1(qr));

cURL — API de consulta

# Buscar por NIT
curl "https://factura-sv-api-production.up.railway.app/api/v1/fiscal-id/lookup?nit=06140101901023"

# Decodificar QR
curl -X POST "https://factura-sv-api-production.up.railway.app/api/v1/fiscal-id/decode" \
  -H "Content-Type: application/json" \
  -d '{"qr_string": "FSV1:eyJ2IjoxLC..."}'

# Generar tarjeta
curl -X POST "https://factura-sv-api-production.up.railway.app/api/v1/fiscal-id/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "nit": "06140101901023",
    "nombre": "Empresa Ejemplo S.A.",
    "tipo_documento": "36"
  }'

# Especificacion completa
curl "https://factura-sv-api-production.up.railway.app/api/v1/fiscal-id/spec"

API Endpoints