SALTRA v4 API 集成指南：西班牙社保系统自动化操作（员工入职/离职/NSS查询）

saltra-integration by davidcastagnetoa/skills

1 周安装量

GitHub

安装命令

npx skills add https://github.com/davidcastagnetoa/skills --skill saltra-integration

自动化人力资源管理 API

🇨🇳中文介绍

SALTRA 集成技能

集成与 SALTRA v4 API（西班牙社会保障系统）的新操作。

何时激活

在社会保障系统中登记员工入职
登记员工离职
通过 DNI 查询 NSS（社会保障号码）
上传公司数字证书
与 SALTRA 进行的任何新操作

集成模式

令牌缓存（有效期内复用）

import axios from "axios";
import config from "../config/config.js";
import logger from "../utils/logger.js";

let saltraToken = null;
let tokenExpiry = 0;

const getSaltraToken = async () => {
  if (saltraToken && Date.now() < tokenExpiry) return saltraToken;

  const response = await axios.post(`${config.SALTRA_API_URL}/auth/login`, {
    email: config.SALTRA_EMAIL,
    password: config.SALTRA_PASSWORD,
  });

  saltraToken = response.data.access_token;
  tokenExpiry = Date.now() + (response.data.expires_in - 300) * 1000; // 5分钟安全边际
  return saltraToken;
};

通用操作

export const nuevaOperacionSaltra = async (datos, certSecret) => {
  const token = await getSaltraToken();

  const response = await axios.post(
    `${config.SALTRA_API_URL}/seg-social/operacion`,
    {
      ...datos,
      test: config.NODE_ENV !== "production" ? 1 : 0,
    },
    {
      headers: {
        Authorization: `Bearer ${token}`,
        "X-Cert-Secret": certSecret,
        "Content-Type": "application/json",
      },
    }
  );

  logger.debug({ request: datos, response: response.data }, "SALTRA operacion");
  return response.data;
};

🇺🇸English

SALTRA Integration Skill

Integra nuevas operaciones con la API SALTRA v4 (Seguridad Social espanola).

When to Activate

Registrar alta de un trabajador en la Seguridad Social
Registrar baja de un trabajador
Consultar NSS (Numero de la Seguridad Social) por DNI
Subir certificado digital de empresa
Cualquier nueva operacion con SALTRA

Patron de Integracion

Token Caching (Reutilizar mientras sea valido)

import axios from "axios";
import config from "../config/config.js";
import logger from "../utils/logger.js";

let saltraToken = null;
let tokenExpiry = 0;

const getSaltraToken = async () => {
  if (saltraToken && Date.now() < tokenExpiry) return saltraToken;

  const response = await axios.post(`${config.SALTRA_API_URL}/auth/login`, {
    email: config.SALTRA_EMAIL,
    password: config.SALTRA_PASSWORD,
  });

  saltraToken = response.data.access_token;
  tokenExpiry = Date.now() + (response.data.expires_in - 300) * 1000; // 5min safety margin
  return saltraToken;
};

Operacion Generica

export const nuevaOperacionSaltra = async (datos, certSecret) => {
  const token = await getSaltraToken();

  const response = await axios.post(
    `${config.SALTRA_API_URL}/seg-social/operacion`,
    {
      ...datos,
      test: config.NODE_ENV !== "production" ? 1 : 0,
    },
    {
      headers: {
        Authorization: `Bearer ${token}`,
        "X-Cert-Secret": certSecret,
        "Content-Type": "application/json",
      },
    }
  );

  logger.debug({ request: datos, response: response.data }, "SALTRA operacion");
  return response.data;
};

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

117,000 周安装

GitHub Actions 官方文档查询助手 - 精准解答 CI/CD 工作流问题

31,800 周安装

Skills CLI 使用指南：AI Agent 技能包管理器安装与管理教程

31,600 周安装

方法	路径	描述	状态
POST	`/auth/login`	获取访问令牌	已实现
POST	`/seg-social/alta`	登记员工入职	已实现
POST	`/seg-social/baja`	登记员工离职	已实现
GET	`/seg-social/nss-by-ipf`	通过 DNI + 姓氏查询 NSS	已实现
POST	`/certificate`	上传 p12/pfx 数字证书	已实现

{
  "naf": "123456789012",           // NSS (12位数字)
  "ipf": "12345678A",             // DNI/NIE
  "nombre": "Juan",
  "apellido1": "Garcia",
  "apellido2": "Lopez",
  "fecha_nacimiento": "1990-01-15",
  "sexo": "H",                    // H = 男性, M = 女性
  "regimen": "0111",              // 通用制度
  "ccc": "28123456789",           // 公司 CCC (11位数字)
  "grupo_cotizacion": "07",
  "fecha_alta": "2024-01-15",
  "cno": "5120",                  // 国家职业代码
  "tipo_contrato": "100",
  "coeficiente_jornada": "1000",  // 1000 = 全职
  "cert_secret": "xxx",           // 来自公司数字证书
  "test": 1                       // 1 = 测试模式, 0 = 生产模式
}

{
  "naf": "123456789012",           // NSS
  "ipf": "12345678A",             // DNI/NIE
  "fecha_baja": "2024-06-30",
  "causa_baja": "51",             // 原因代码 (51 = 自愿离职)
  "ccc": "28123456789",
  "cert_secret": "xxx",
  "test": 1
}

try {
  const result = await darAlta(datos, certSecret);
  return result;
} catch (error) {
  if (error.response?.data?.message) {
    // SALTRA 可读错误
    logger.error({ saltraError: error.response.data }, "Error SALTRA");
    throw new Error(`Error SALTRA: ${error.response.data.message}`);
  }
  throw error;
}

概念	约定
令牌缓存	始终在过期前5分钟复用
测试模式	在非生产环境中强制设置 `test=1`
cert_secret	从 `Company.saltra_cert_secret` 获取，上传证书时存储
错误	解析 `response.data.message` 以获取用户可读的错误信息
日志记录	在 `debug` 级别记录完整的请求和响应
配置	`config.js` 中的变量：`SALTRA_API_URL`, `SALTRA_EMAIL`, `SALTRA_PASSWORD`

令牌已缓存并复用
在非生产环境中激活测试模式 (test: 1)
cert_secret 从关联的 Company 获取
错误已解析并记录
数据在发送到 SALTRA 前已使用 Zod 验证
已使用结果创建/更新流程

Metodo	Ruta	Descripcion	Estado
POST	`/auth/login`	Obtener token de acceso	Implementado
POST	`/seg-social/alta`	Registrar alta de trabajador	Implementado
POST	`/seg-social/baja`	Registrar baja de trabajador	Implementado
GET	`/seg-social/nss-by-ipf`	Consultar NSS por DNI + apellidos	Implementado
POST	`/certificate`	Subir certificado digital p12/pfx	Implementado

Datos Requeridos para Alta

{
  naf: "123456789012",           // NSS (12 digitos)
  ipf: "12345678A",             // DNI/NIE
  nombre: "Juan",
  apellido1: "Garcia",
  apellido2: "Lopez",
  fecha_nacimiento: "1990-01-15",
  sexo: "H",                    // H = Hombre, M = Mujer
  regimen: "0111",              // Regimen general
  ccc: "28123456789",           // CCC empresa (11 digitos)
  grupo_cotizacion: "07",
  fecha_alta: "2024-01-15",
  cno: "5120",                  // Codigo Nacional de Ocupacion
  tipo_contrato: "100",
  coeficiente_jornada: "1000",  // 1000 = jornada completa
  cert_secret: "xxx",           // Del certificado digital de la empresa
  test: 1                       // 1 = modo prueba, 0 = produccion
}

Datos Requeridos para Baja

{
  naf: "123456789012",           // NSS
  ipf: "12345678A",             // DNI/NIE
  fecha_baja: "2024-06-30",
  causa_baja: "51",             // Codigo causa (51 = baja voluntaria)
  ccc: "28123456789",
  cert_secret: "xxx",
  test: 1
}

Manejo de Errores SALTRA

try {
  const result = await darAlta(datos, certSecret);
  return result;
} catch (error) {
  if (error.response?.data?.message) {
    // Error legible de SALTRA
    logger.error({ saltraError: error.response.data }, "Error SALTRA");
    throw new Error(`Error SALTRA: ${error.response.data.message}`);
  }
  throw error;
}

Concepto	Convencion
Token cache	Siempre reutilizar con margen de 5 minutos antes de expiracion
Modo test	Forzar `test=1` en entornos que NO sean produccion
cert_secret	Se obtiene de `Company.saltra_cert_secret`, se almacena al subir certificado
Errores	Parsear `response.data.message` para errores legibles al usuario
Logging	Loguear request y response completos en nivel `debug`
Config	Variables en `config.js`: `SALTRA_API_URL`, `SALTRA_EMAIL`, `SALTRA_PASSWORD`

Token cacheado y reutilizado
Modo test activo en no-produccion (test: 1)
cert_secret obtenido de la Company asociada
Errores parseados y logueados
Datos validados con Zod antes de enviar a SALTRA
Tramite creado/actualizado con el resultado

通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南

31,600 周安装

SALTRA v4 API 集成指南：西班牙社保系统自动化操作（员工入职/离职/NSS查询）

🇨🇳中文介绍

SALTRA 集成技能

何时激活

集成模式

令牌缓存（有效期内复用）

通用操作

🇺🇸English

SALTRA Integration Skill

When to Activate

Patron de Integracion

Token Caching (Reutilizar mientras sea valido)

Operacion Generica

相关 Skills

SALTRA v4 端点

入职所需数据

离职所需数据

SALTRA 错误处理

约定

检查清单

Endpoints SALTRA v4

Datos Requeridos para Alta

Datos Requeridos para Baja

Manejo de Errores SALTRA

Convenciones

Checklist

最新 Skills