Autenticación

Envía estas dos cabeceras en cada solicitud, incluido /ping:

Cabecera	Contenido
X-Api-Key	Identificador de la credencial.
X-Api-Secret	Secret asociado a esa credencial.
Accept	application/json, para solicitar respuestas JSON.
Content-Type	application/json, al enviar un cuerpo JSON.

La credencial determina la empresa con la que trabajas. No necesitas enviar un identificador de empresa en la URL ni en una cabecera adicional.

Guarda el secret en las variables de entorno de tu servidor. No lo incluyas en aplicaciones de navegador, URLs ni repositorios.

Validaciones de acceso

La API verifica que la credencial exista, esté activa, admita la IP de origen, tenga el secret correcto y pertenezca a una empresa activa.

• 401: faltan credenciales o no son válidas.
• 403: la credencial está desactivada, la IP no está permitida o la empresa está inactiva.

Permisos de la credencial

Cada API key tiene scopes explícitos, asignados desde Configuración → API Keys:

Scope	Operación
sales.orders:read	Listar ventas.
sales.orders:write	Crear ventas en borrador con precios de catálogo.
sales.orders:assign-seller	Asignar opcionalmente un vendedor al crear una venta.

Una credencial sin scopes no tiene acceso a esas operaciones. /ping requiere únicamente autenticación. Los permisos nuevos no se conceden automáticamente.

Una solicitud válida sin el scope requerido recibe 403. El middleware de rutas incluye el scope faltante en required_scope.

Identidad y trazabilidad

La API registra automáticamente el creador como API · nombre de la integración, a partir de la credencial autenticada. No hace falta crear un usuario humano llamado API ni configurar un vendedor en la credencial.

Opcionalmente puedes enviar:

X-External-Actor-Id: usuario-123

Este valor es una referencia declarada por tu integración, no un usuario autenticado de Simple. Solo se usa para auditoría: no cambia permisos, no inicia una sesión y no asigna un vendedor. Admite hasta 255 caracteres y no permite caracteres de control; un valor inválido responde 422. Evita incluir datos personales innecesarios.

La respuesta de creación incluye created_by, con el tipo de actor, identificador, nombre de la integración, etiqueta y referencia externa opcional. La identidad histórica se conserva aunque la credencial sea renombrada o revocada.

El vendedor es un dato de negocio diferente del creador. En ventas puedes enviar seller_id en el JSON si la key tiene también sales.orders:assign-seller; debe ser un miembro activo de la misma empresa. Si no lo envías, la venta queda sin vendedor asignado y conserva su creador API.