> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entidades

Las entidades representan a las personas y empresas con las que tu organización trabaja en Syntage. Usa el ID de una entidad para solicitar datos, iniciar extracciones, gestionar identificadores, asignar etiquetas de entidad y revisar eventos para esa persona o empresa.

Una entidad se puede crear con un nombre, tipo, RFC opcional, identificadores opcionales y fuentes de datos opcionales para iniciar la extracción. Si falta información requerida, Syntage devuelve una URL de onboarding que puede usarse para recopilar la información faltante de la entidad.

## Favoritos personales

Cada usuario puede guardar su propia selección de entidades dentro de su organización. Otros usuarios, incluidos los administradores, tienen sus propios favoritos. Marcar una entidad como favorita no cambia sus etiquetas ni concede acceso: si pierdes acceso a una entidad, deja de aparecer en tus resultados.

### API de favoritos

Envía `POST /entities/favorites` para agregar uno o más favoritos o `DELETE /entities/favorites` para quitarlos. Ambos métodos aceptan el mismo cuerpo JSON con IRIs de entidades:

```json theme={null}
{"entities": ["/entities/91106968-1abd-4d64-85c1-4e73d96fb997"]}
```

Incluye entre 1 y 100 IRIs de entidades. Los IRIs repetidos se procesan una sola vez. Cada lote es atómico: si alguna entidad no existe o no es accesible, no se modifica ningún favorito. Las operaciones exitosas de agregar y quitar favoritos devuelven `204 No Content` sin cuerpo de respuesta. Repetir una operación es seguro; agregar un favorito existente conserva sus fechas.

Las respuestas GET de consulta individual y de listado incluyen `isFavorite` para el usuario autenticado de forma predeterminada. Si seleccionas los campos de respuesta con `properties[]`, incluye `properties[]=isFavorite` para recibirlo; las respuestas de creación y actualización no incluyen este campo. Usa `GET /entities?isFavorite=true` para consultar favoritos o `?isFavorite=false` para las demás entidades accesibles.

El usuario y la organización autenticados determinan los favoritos que se modifican; no se pueden seleccionar en la solicitud. Los usuarios de solo lectura pueden gestionar sus favoritos con autenticación JWT. Su restricción existente de autenticación mediante API key sigue vigente.

## Cuándo Syntage devuelve un `onboardingUrl`

La respuesta de `POST /entities` incluye `onboardingUrl` solo cuando Syntage todavía necesita información de la entidad para completar la configuración. El caso más común es cuando se omite el `rfc`. Si tu solicitud ya incluye un `rfc` válido (y cualquier otra información que Syntage necesite para resolver la entidad), la respuesta omite `onboardingUrl` o lo devuelve vacío porque no se requiere ningún paso de onboarding.

> [!NOTE]
>
> Las URLs de onboarding devueltas no caducan.

## Cómo se usan las entidades

1. Crea o recupera una entidad.
2. Almacena el ID de la entidad devuelto por Syntage.
3. Usa el ID de la entidad al solicitar registros de fuentes de datos, crear extracciones, listar eventos, asignar etiquetas o agregar identificadores.
4. Si Syntage devuelve un `onboardingUrl`, envía a la entidad a esa URL o incrusta la experiencia de onboarding en tu propio sitio.

El ID de la entidad es estable entre fuentes de datos. Una sola entidad puede conectarse a credenciales del SAT, datos del RPC, datos del RUG, reportes de Buró de Crédito, datos del Infonavit y más.

## IDs de entidad

Usa el ID de la entidad en nuevas integraciones:

```text theme={null}
/entities/{entityId}
/entities/{entityId}/tax-status
/entities/{entityId}/invoices
```

Algunos endpoints antiguos también aceptan URLs basadas en RFC por compatibilidad. Los nuevos endpoints y funcionalidades solo se agregan bajo URLs basadas en entidad.

Para detalles de endpoints, consulta la [Referencia de API de Entidades](https://docs.syntage.com/api-reference/entities/add-an-entity.md).

## Identificadores

Los identificadores almacenan valores específicos de cada país que pueden ser utilizados por las fuentes de datos y los flujos de trabajo del producto. México actualmente soporta:

| País | Identificador | Ejemplo |
| - | - | - |
| `mx` | `rfc` | `XAXX010101000` |
| `mx` | `curp` | `BADD110313HCMLNS09` |

Los identificadores pueden proporcionarse al crear una entidad o agregarse posteriormente con el endpoint de identificadores de entidad.

## Etiquetas de entidad

Las etiquetas de entidad son etiquetas definidas por la organización para agrupar y filtrar entidades. Son útiles cuando tu integración necesita tratar a un conjunto de entidades de la misma manera.

Casos de uso comunes:

| Caso de uso | Ejemplo |
| - | - |
| Planificadores de extracciones | Ejecutar una extracción diaria de facturas para cada entidad etiquetada con `Daily invoices`. |
| Monitoreo | Hacer seguimiento de entidades de alta prioridad por separado del resto de tu organización. |
| Filtrado en Syntage | Filtrar la lista de entidades en el dashboard de Syntage. |
| Segmentación en tu producto | Usar etiquetas para construir tus propios dashboards, colas de revisión o flujos de soporte alrededor de entidades etiquetadas. |

Primero crea las etiquetas de entidad y luego asígnalas a una entidad actualizando la colección `tags` de la entidad.

Al actualizar las etiquetas de una entidad, envía la lista completa de IRIs de etiquetas de entidad que debe tener la entidad. La lista enviada reemplaza las asignaciones anteriores.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.