#Fiscal Entities

Una FiscalEntity es un RFC con sus datos fiscales normalizados. Estos endpoints permiten conectar un RFC, listar los que administras y consultar el detalle de uno.

#El objeto FiscalEntity

Campo	Tipo	Descripción
`id`	string	Identificador único de la entidad (`fe_…`).
`rfc`	string	RFC del contribuyente (12 = moral, 13 = física).
`legal_name`	string \| null	Razón social o nombre legal.
`person_type`	string	`natural` (persona física) o `legal` (persona moral).
`regimen_code`	string \| null	Clave del régimen fiscal SAT (p. ej. `626`).
`regimen_label`	string \| null	Nombre del régimen fiscal.
`connection_status`	string	Estado de la conexión: `active`, `draft`, `invalid_ciec`, `suspended`, `deleted`.
`ciec_status`	string	Salud de la CIEC: `valid`, `expired_password`, `mfa_required`, `account_locked`, `unknown`.
`nickname`	string \| null	Apodo que tu organización le dio al RFC.
`last_synced_at`	string \| null	Última sincronización con el SAT (ISO 8601).
`invoice_backfill_completed_at`	string \| null	Cuándo terminó la carga histórica de CFDIs (ISO 8601).

#Conecta un RFC

POST/fiscal-entities

Crea una conexión entre tu organización y un RFC. Hay dos formas, según tengas o no la CIEC a la mano:

Con CIEC — la validamos contra el SAT y, si es correcta, la conexión queda active, ciframos la CIEC at-rest y empezamos a descargar los datos del RFC.
Sin CIEC — la conexión queda en draft y devolvemos un onboarding_token (una sola vez) para que el contribuyente capture su CIEC desde un link.

#Cuerpo de la petición

Campo	Tipo	Descripción
`rfc`	string	Requerido. RFC a conectar.
`ciec`	string \| null	CIEC del contribuyente. Omítela para generar un link de onboarding.
`nickname`	string \| null	Apodo opcional para identificar el RFC (máx. 200).
`data_source_keys`	string[]	Opcional. Fuentes a habilitar. Si se omite, se habilitan todas las activas.

#Ejemplo — con CIEC

curl -X POST https://api.clarisfy.com/api/v1/fiscal-entities \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe" \
  -H "Content-Type: application/json" \
  -d '{"rfc": "GACJ850315AB1", "ciec": "MiCiecSecreta", "nickname": "Mi empresa"}'

Respuesta 201 Created. El id es el de la conexión (cnx_…); la entidad va anidada en fiscal_entity:

{
  "id": "cnx_01jtvm3qbwfr8at3kbq72yaeb1",
  "fiscal_entity": {
    "id": "fe_9a1c2b3d4e5f6071",
    "rfc": "GACJ850315AB1",
    "legal_name": "Juan García Cruz",
    "person_type": "natural",
    "regimen_code": "626",
    "regimen_label": "Régimen Simplificado de Confianza",
    "connection_status": "active",
    "ciec_status": "valid",
    "nickname": "Mi empresa",
    "last_synced_at": null,
    "invoice_backfill_completed_at": null
  },
  "onboarding_token": null
}

#Sin CIEC — invitación por link

Omite ciec para crear la conexión en draft y recibir un onboarding_token (se devuelve una sola vez). Con él se arma el link https://app.clarisfy.com/onboarding/ciec/{onboarding_token} para que el contribuyente capture su CIEC:

{
  "id": "cnx_01jtvm3qbwfr8at3kbq72yaeb1",
  "fiscal_entity": {
    "id": "fe_9a1c2b3d4e5f6071",
    "rfc": "GACJ850315AB1",
    "connection_status": "draft",
    "ciec_status": "unknown",
    "last_synced_at": null,
    "invoice_backfill_completed_at": null
  },
  "onboarding_token": "obt_2b7f9c1a4d8e6f30a1b2c3d4"
}

#Errores

Código HTTP	Causa
`422`	RFC con formato inválido, o CIEC malformada.
`409`	Tu organización ya tiene una conexión activa a ese RFC.
`503`	No se pudo validar la CIEC con el SAT (SAT/servicio no disponible). No se creó la conexión; reintenta.

#Lista de Fiscal Entities

GET/fiscal-entities

Devuelve todas las conexiones de tu organización (active, draft e invalid_ciec) como un arreglo JSON. No tiene paginación: el volumen es el de los RFCs que administras.

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

[
  {
    "id": "fe_9a1c2b3d4e5f6071",
    "rfc": "GACJ850315AB1",
    "legal_name": "Juan García Cruz",
    "person_type": "natural",
    "regimen_code": "626",
    "regimen_label": "Régimen Simplificado de Confianza",
    "connection_status": "active",
    "ciec_status": "valid",
    "nickname": "Mi empresa",
    "last_synced_at": "2026-07-25T04:00:00Z",
    "invoice_backfill_completed_at": "2026-06-02T11:30:00Z"
  }
]

#Detalle de una Fiscal Entity

GET/fiscal-entities/{id}

#Parámetros de ruta

Parámetro	Tipo	Descripción
`id`	string	Identificador de la `FiscalEntity` (`fe_…`).

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

{
  "id": "fe_9a1c2b3d4e5f6071",
  "rfc": "GACJ850315AB1",
  "legal_name": "Juan García Cruz",
  "person_type": "natural",
  "regimen_code": "626",
  "regimen_label": "Régimen Simplificado de Confianza",
  "connection_status": "active",
  "ciec_status": "valid",
  "nickname": "Mi empresa",
  "last_synced_at": "2026-07-25T04:00:00Z",
  "invoice_backfill_completed_at": "2026-06-02T11:30:00Z"
}

400 invalid fiscal entity id si el id no tiene el formato fe_….
404 not found si el RFC no existe o tu organización no tiene una conexión a él (no se revela su existencia entre organizaciones).