用途:该技能用于在项目中集成 SALTRA v4 API(西班牙社会保障),覆盖员工参保登记、退保、按 DNI 查询社会保障号(NSS)以及上传企业数字证书等操作,也适用于新增其他 SALTRA 操作。
主要能力与端点:POST /auth/login 获取访问令牌;POST /seg-social/alta 登记员工参保;POST /seg-social/baja 登记退保;GET /seg-social/nss-by-ipf 按 DNI 加姓氏查询 NSS;POST /certificate 上传 p12/pfx 数字证书。
使用方式:先通过 /auth/login 用邮箱和密码获取 access_token,并做令牌缓存(在过期前留 5 分钟安全余量复用)。调用业务接口时在请求头携带 Authorization: Bearer 令牌、X-Cert-Secret(来自企业数字证书)和 Content-Type: application/json。非生产环境强制 test=1,生产环境为 0。参保需提供 naf、ipf、姓名、出生日期、性别、regimen、ccc、grupo_cotizacion、fecha_alta、cno、tipo_contrato、coeficiente_jornada、cert_secret、test 等字段;退保需 naf、ipf、fecha_baja、causa_baja、ccc、cert_secret、test。
错误处理与约定:解析 response.data.message 生成可读错误并记录日志,debug 级别记录完整请求与响应;cert_secret 来自 Company.saltra_cert_secret,在上传证书时保存;配置项包括 SALTRA_API_URL、SALTRA_EMAIL、SALTRA_PASSWORD;建议发送前用 Zod 校验数据,并将结果写入相应流程记录。
限制:资料未提供速率限制、认证有效期具体数值、错误码清单及生产环境申请流程等信息,暂未提供。