#REPSE (STPS)

Devuelve el estado de una Fiscal Entity en el REPSE (Registro de Prestadoras de Servicios Especializados u Obras Especializadas), el padrón público de la STPS (Secretaría del Trabajo y Previsión Social): si el RFC aparece registrado, su folio, razón social, ubicación, vigencia y las actividades que amparaba el registro.

Cuelga de https://api.clarisfy.com/v1/fiscal-entities/ y es tenant-gated: tu organización debe tener una conexión activa al RFC, o el endpoint responde 404.

#Estado REPSE del RFC

#Parámetros de ruta

curl "https://api.clarisfy.com/v1/fiscal-entities/fe_9a1c2b3d4e5f6071/repse" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "rfc": "NAS210518XY0",
  "is_registered": true,
  "is_stale": false,
  "checked_at": "2026-07-30T12:00:00+00:00",
  "folio": "128149",
  "razon_social": "NARA ASSESSMENTS SC",
  "entidad": "Ciudad de México",
  "municipio": "Benito Juárez",
  "num_aviso": null,
  "fecha_aviso": null,
  "vigencia_hasta": "2027-05-18",
  "is_expired": false,
  "days_to_expiry": 292,
  "actividades": [
    {
      "descripcion": "Servicios de consultoría en administración",
      "folio": "128149"
    }
  ]
}

#Campos

#202: el RFC nunca se ha consultado

Si es la primera vez que se pide este RFC, la respuesta es 202 con el header Retry-After y este cuerpo, y la consulta a la STPS queda encolada:

{
  "status": "checking",
  "rfc": "NAS210518XY0",
  "retry_after_seconds": 15
}

Reintenta el GET después de retry_after_seconds. No trates un 202 como "no registrado" (ver la nota de los tres estados arriba).

#Errores

#Actualizar el estado REPSE

Encola una consulta al padrón de la STPS para el RFC y devuelve 202 de inmediato. El resultado se lee después en GET /fiscal-entities/{fiscal_entity_id}/repse: este endpoint no devuelve el registro.

#Parámetros de ruta

curl -X POST "https://api.clarisfy.com/v1/fiscal-entities/fe_9a1c2b3d4e5f6071/repse/refresh" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

202 Accepted:

{
  "status": "queued",
  "rfc": "NAS210518XY0"
}

#Cooldown de 1 hora por RFC

Hay un cooldown de 1 hora por RFC. Dentro de esa ventana el endpoint responde 429 con el header Retry-After y los segundos restantes anidados dentro de detail:

{
  "detail": {
    "message": "Ya solicitaste esta actualización hace poco. Intenta más tarde.",
    "retry_after_seconds": 2480
  }
}

La STPS es un sitio público sin contrato de rate-limit publicado, y un registro REPSE cambia en escala de meses: una actualización por hora ya es mucho más frecuente de lo que se mueve el dato. Como la caché es por RFC, el cooldown también lo es — lo comparten todas las organizaciones conectadas a ese RFC.

#Errores

#Vigencia: refresco y alertas automáticas

No necesitas orquestar el refresco de los RFCs que administras:

• Un proceso diario vuelve a consultar los RFCs con conexión activa cuya consulta está vencida o nunca se hizo, en lotes acotados y en serie (es un sitio público, se consulta con moderación).
• Ese mismo paso levanta una alerta por organización cuando la vigencia de un registro vence dentro de 60 días o ya venció: critical cuando ya venció, warning mientras solo se aproxima. La alerta está deduplicada por (RFC, vigencia), así que el proceso diario no repite el mismo aviso; solo una nueva vigencia (re-registro) abre una alerta nueva.

La alerta enuncia el hecho y la fecha. No concluye nada sobre deducibilidad ni sobre qué hacer: esa decisión es de tu contador.

#Proveedores cruzados contra el REPSE

Cruza los emisores de los CFDIs recibidos de un RFC contra el padrón, y reporta cuánto dinero está facturado por proveedores sin registro, con registro vencido o todavía sin verificar. Es la contraparte del endpoint anterior: ahí consultas tu propio registro, aquí el de quienes te facturan.

#Parámetros

#Campos

status de cada proveedor es uno de registered, not_registered, expired o unknown.

Los montos son NUMERIC serializados como string: parséalos con un tipo decimal, no con un float.

curl "https://api.clarisfy.com/v1/cfdi/repse-suppliers?fiscalEntityId=fe_9a1c2b3d4e5f6071&months=12&limit=50" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"