#Extractores

Conectar un RFC descargaba todo su histórico. Un extractor convierte eso en una decisión: qué fuentes de datos traer, cuánto hacia atrás y con qué disparador.

Dos reglas definen el recurso:

• Un extractor pertenece a la organización y aplica a todos los RFCs que tenga conectados. No hay cadencia por RFC.
• Tu plan limita cuántos extractores puedes configurar, nunca su frecuencia.

#Límite por plan

Los extractores deshabilitados también cuentan: son configuración que conservas. Al llegar al tope, POST /extractors responde 409 con un mensaje que dice cuántos permite tu plan y cuántos tienes, para que elijas entre borrar uno y subir de plan.

#El objeto Extractor

#Disparadores

#Alcance

scope decide el rango de fechas fiscales (issued_at) que se descarga cada vez que el extractor corre. El rango siempre termina hoy.

#Cadencia

schedule_kind y schedule_spec solo aplican con trigger_kind: schedule; con los otros disparadores schedule_kind debe ir en null. La timezone del extractor es la que decide en qué día cae la cadencia.

Cada cadencia se ejecuta a la medianoche de la zona horaria del extractor. Un mes sin la N-ésima ocurrencia se salta: {"weekday": 0, "nth": 5} no corre en los meses que solo tienen cuatro lunes.

Al guardar un extractor programado no se descarga nada en ese momento: se calcula su próxima corrida. Si configuras "primer lunes" un miércoles, la primera extracción es el lunes siguiente, no ese mismo miércoles.

#Fuentes de datos

data_source_keys es la lista de fuentes que el extractor trae. Un extractor no puede traer lo que la conexión del RFC no tenga habilitado: se descarga la intersección entre ambas.

#Fuentes obligatorias

GET /fiscal-entities/data-sources marca cada fuente con is_mandatory. Hoy la única es sat_miinformacion, y no es opcional: trae los datos de registro del propio contribuyente —régimen, obligaciones, medios de contacto— que el resto de la plataforma da por hechos al calcular alertas, contactos y la CSF.

Se agrega del lado del servidor, así que:

• El extractor que te devolvemos puede traer más claves de las que enviaste. No es un error: no la pediste y ahí está.
• Quitarla con PATCH no la quita. Un data_source_keys que la omita reemplaza el resto de la lista y la conserva a ella.
• Lo mismo al conectar un RFC: una lista explícita en POST /fiscal-entities restringe lo demás, pero la obligatoria queda habilitada igual. Si no fuera así, la intersección entre extractor y conexión la dejaría fuera.

Fíltrala de cualquier selector que construyas, usando is_mandatory y no una lista fija de claves: ofrecer una casilla para algo que siempre vuelve marcado es peor que no ofrecerla.

#La ventana de visibilidad

Un mismo RFC puede estar conectado por varias organizaciones y se descarga una sola vez (conexiones virtuales). Lo que separa a cada organización no es lo que existe, sino lo que cada una puede leer: un techo lógico sobre issued_at.

• Techo — no puedes leer CFDIs con issued_at más nuevo que tu última extracción, aunque el dato ya exista porque otra organización lo descargó.
• Piso — un extractor de 3 meses no te muestra los 8 años que otra organización ya descargó del mismo RFC.
• La ventana solo se abre: una extracción la ensancha y nada la encoge, así que lo que veías ayer no desaparece hoy.

#Dónde aplica

La ventana aplica a toda lectura de datos fiscales, no solo al listado de CFDIs:

Esto significa que un sumario mensual puede no cuadrar con el mismo mes visto por otra organización conectada al mismo RFC: cada una ve su propia ventana. Si necesitas el mes completo, amplía la extracción del RFC.

#Lista tus extractores

Devuelve los extractores de tu organización, del más antiguo al más reciente. Es un arreglo directo, sin envelope de paginación.

#Ejemplo

curl https://api.clarisfy.com/v1/extractors \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

Respuesta 200 OK:

[
  {
    "extractor_id": "ext_01jtvm3qbwfr8at3kbq72yaeb1",
    "name": "CFDIs al día",
    "is_enabled": true,
    "trigger_kind": "schedule",
    "schedule_kind": "every_n_days",
    "schedule_spec": { "n": 7 },
    "timezone": "America/Mexico_City",
    "scope": "since_watermark",
    "scope_months": null,
    "data_source_keys": ["sat_cfdi_issued", "sat_cfdi_received"],
    "created_at": "2026-08-01T18:24:11Z"
  }
]

#Crea un extractor

#Cuerpo de la petición

#Ejemplo

curl -X POST https://api.clarisfy.com/v1/extractors \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Alta de RFC: último año",
        "trigger_kind": "connection_created",
        "scope": "last_n_months",
        "scope_months": 12,
        "data_source_keys": ["sat_cfdi_issued", "sat_cfdi_received"]
      }'

Respuesta 201 Created — el extractor creado:

{
  "extractor_id": "ext_01jtvm3qbwfr8at3kbq72yaeb1",
  "name": "Alta de RFC: último año",
  "is_enabled": true,
  "trigger_kind": "connection_created",
  "schedule_kind": null,
  "schedule_spec": {},
  "timezone": "America/Mexico_City",
  "scope": "last_n_months",
  "scope_months": 12,
  "data_source_keys": ["sat_cfdi_issued", "sat_cfdi_received"],
  "created_at": "2026-08-01T18:24:11Z"
}

#Errores

#Actualiza un extractor

Actualización parcial: solo se escriben los campos presentes en el cuerpo, así que un PATCH con únicamente is_enabled no borra la cadencia.

#Campos dependientes

Dos pares de campos van amarrados: un disparador schedule exige schedule_kind (y cualquier otro disparador exige que no lo haya), y el alcance last_n_months exige scope_months (y cualquier otro alcance exige que no lo haya).

Al actualizar, la mitad que deja de aplicar se limpia sola. Para volver schedule un extractor por evento basta con mandar el disparador:

# la cadencia guardada se borra sola — no mandes schedule_kind: null
-d '{"trigger_kind": "connection_created"}'

La dirección contraria no se adivina: pasar a schedule sin schedule_kind, o a last_n_months sin scope_months, responde 422. Elegir una cadencia por ti significaría empezar a consultar al SAT con un ritmo que nunca pediste.

#Parámetros de ruta

#Ejemplo

curl -X PATCH https://api.clarisfy.com/v1/extractors/ext_01jtvm3qbwfr8at3kbq72yaeb1 \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe" \
  -H "Content-Type: application/json" \
  -d '{"is_enabled": false}'

Respuesta 200 OK — el extractor actualizado, con la misma forma que en la creación.

#Errores

El límite del plan no se revalida al actualizar: un PATCH nunca crea un extractor, así que no puede rebasar tu cuota.

#Ejecuta un extractor ahora

Corre el extractor de inmediato para todos los RFCs activos de tu organización, sin esperar su cadencia ni una reconexión. Útil justo después de crearlo: un extractor diario configurado al mediodía no haría nada visible hasta la medianoche.

No mueve el calendario. El siguiente disparo programado sigue donde estaba, así que esto no es una forma de adelantar la cadencia.

curl -X POST https://api.clarisfy.com/v1/extractors/ext_01jtvm3qbwfr8at3kbq72yaeb1/run \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

#Respuesta

{
  "status": "dispatched",
  "connections": 3,
  "dispatched": 2
}

#Errores

#Elimina un extractor

Elimina el extractor y libera su lugar en el plan. Responde 204 No Content, sin cuerpo.

curl -X DELETE https://api.clarisfy.com/v1/extractors/ext_01jtvm3qbwfr8at3kbq72yaeb1 \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

#Errores