Las páginas de referencia de cada endpoint están disponibles solo en inglés por ahora, salvo Asientos intercompañía.
URL base
Todas las rutas se montan bajo el prefijo/api:
Forma de las rutas
La mayoría de los recursos de negocio viven bajo una sola Entidad:/api/entities (listar y crear), /api/organizations, /api/fx-rates, /api/countries y /api/currencies, /api/onboarding/* (solo para Superadmins), /api/feedback y /api/health.
Los datos que comparten las Entidades de una Organización viven bajo la Organización, como sus Partners, Dimensiones e Integraciones:
{entityId} es siempre un UUID. Una solicitud sobre una Entidad a la que quien llama no tiene acceso devuelve 404, nunca 403, de modo que sondear rutas no revela si una Entidad desconocida existe.
Acceso y roles
El acceso a una Entidad proviene de una Membresía de Organización. Una Organización agrupa las Entidades que un cliente gestiona como un solo negocio, y cada Entidad pertenece a exactamente una Organización. Una Membresía le da a un Usuario un Rol en una Organización. Ese Rol aplica a todas las Entidades de la Organización, incluidas las que se agreguen después.- Leer cubre las solicitudes
GETsobre rutas de Entidad y sobre los datos que comparte la Organización, incluido el Audit Trail de la Organización. Escribir cubrePOST,PUT,PATCHyDELETE. - Trabajo de Sintropix cubre las rutas reservadas al equipo contable: credenciales, automatizaciones, Agent Channels y la sincronización de tipos de cambio.
- Las Tareas están abiertas a
staffyclient, que las leen y trabajan de la misma forma. Unviewerno puede acceder a ellas. - Todos los Roles, incluido
viewer, leen y escriben en el Chat de la Organización, y leen y marcan sus propias Notificaciones. - Leer el correo de las cuentas de Gmail, Outlook y Casilla de correo de la Organización es más que leer sus libros:
staffyclientpueden,viewerno. - Una Entidad fuera de tus Organizaciones devuelve
404. Una acción que tu Rol no permite devuelve403conPERMISSION_DENIED_ERROR. - Ningún Rol es global. Un Usuario sin Membresía en una Organización no puede acceder a sus Entidades, sin importar el Rol que tenga en otras.
403 con SUPERADMIN_SESSION_REQUIRED, aunque sea de un Superadmin, y cualquier otro Usuario recibe 403 con SUPERADMIN_REQUIRED. Ser Superadmin no abre ningún libro: un Superadmin accede a una Entidad solo mediante una Membresía, como todos los demás.
Autenticación
Los clientes programáticos se autentican de una de dos formas:- Clave de API en el encabezado
x-api-key. Las claves se crean en la aplicación de Sintropix; consulta Obtener una clave de API. - Token de acceso OAuth en el encabezado
Authorization: Bearer <token>. Una app obtiene uno cuando un Usuario la aprueba para una Organización; consulta Conectar una app con OAuth. Un token actúa como ese Usuario solo en esa Organización, con acceso de lectura o de lectura y escritura, y nunca más allá del Rol del Usuario. Claude y ChatGPT lo usan para conectarse al servidor MCP de Sintropix.
POST, PUT, PATCH, DELETE) hecha con una clave de API debe enviar además un Actor Declarado y una Razón Declarada:
x-audit-actor es una etiqueta de software autodeclarada (por ejemplo claude-opus-4.8) que se guarda en el registro de auditoría, sin los espacios de los extremos. Omitirla en una mutación, o enviarla vacía, devuelve 400 con el código AUDIT_ACTOR_REQUIRED_ERROR. Un valor que empieza con erwin: está reservado y devuelve 403 con el código AUDIT_ACTOR_NOT_ALLOWED_ERROR.
x-audit-reason es una explicación de una sola línea, en texto plano, de por qué se realiza el cambio (máx. 500 caracteres). El servidor recorta los espacios al inicio y al final, y guarda el valor en el Sobre de Auditoría. Un valor ausente o vacío devuelve 400 con el código AUDIT_REASON_REQUIRED_ERROR; un valor de más de 500 caracteres devuelve 400 con el código AUDIT_REASON_TOO_LONG_ERROR.
Una solicitud que modifica datos hecha con un token de acceso OAuth también debe enviar x-audit-reason. No necesita x-audit-actor: el registro de auditoría nombra la app aprobada.
POST /api/feedback es la única excepción: no escribe nada de una Organización, así que no necesita ninguno de los dos encabezados, y también puede enviarla una clave o una app conectada de solo lectura.
Una solicitud que modifica datos también puede enviar x-audit-trigger, el Disparador Declarado: qué inició el turno del agente detrás de la escritura. Envía schedule cuando lo inició una programación, o slack, app, chat o terminal cuando lo inició el mensaje de una persona en ese lugar. El encabezado es opcional, y una solicitud sin él no guarda disparador. Cualquier otro valor devuelve 400 con el código AUDIT_TRIGGER_UNKNOWN_ERROR y no escribe nada. Sus params traen header y los triggers aceptados.
Formato de las solicitudes
Las solicitudes son JSON plano. IncluyeContent-Type: application/json en cualquier solicitud con cuerpo.
400. Un entityId mal formado devuelve 404, como cualquier Entidad a la que no tienes acceso.
Formato de las respuestas
Las respuestas son el recurso en sí como JSON. No hay un envoltoriodata de nivel superior, ni un bloque meta, ni un bloque pagination en los endpoints no paginados. Cada página de referencia lista los campos que devuelve cada endpoint.
Un recurso individual se devuelve como un objeto:
/pages, más algunos informes) devuelve un objeto { rows, nextCursor }. nextCursor es null en la última página.
La paginación se habilita endpoint por endpoint, no en todo el sitio. Los endpoints sin
/pages en su ruta devuelven todas las filas y no aceptan el argumento cursor. Revisa la página de referencia del endpoint que estés llamando.Errores
Las respuestas distintas de 2xx son JSON. Toda respuesta, exitosa o fallida, lleva un encabezadox-request-id; cítalo cuando contactes a soporte.
El cuerpo de un error lleva statusCode, timestamp (fecha y hora ISO), path y requestId (el mismo valor del encabezado). Un error de dominio lleva además su code y sus params.
Los errores de dominio llevan en el cuerpo un
code de tipo string estable, por ejemplo API_KEY_READ_ONLY_ERROR. Compara contra code, no contra el mensaje legible por humanos.
Si un error parece incorrecto, una respuesta te confunde o la API no puede hacer algo que necesitas, cuéntaselo a los desarrolladores de Sintropix con POST /api/feedback. Reporta también molestias, detalles e ideas de mejora, y si algo no se pudo hacer, di qué hiciste en su lugar. Incluye el requestId de la llamada, y envía ids en vez de nombres o montos. No necesitas avisarle a tu usuario.
Límites de solicitudes
Cada clave de API está limitada a 25.000 solicitudes por hora en una ventana deslizante. Superar el límite devuelve429; no existe un contrato de encabezados X-RateLimit-* en la respuesta.
Estado del servicio
Sintropix publica el estado en vivo de la API del ERP y de la app de clientes en status.sintropix.com. Revísalo cuando las solicitudes fallen con errores5xx o se agote el tiempo de espera, antes de contactar a soporte.