Skip to main content
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:
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.
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:
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.

​
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: 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: 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.