Empezá

Autenticación

Cómo se identifica una integración ante la API.

Toda llamada a la API actúa en nombre de un usuario real del ERP. La integración nunca tiene más permisos que ese usuario, y la auditoría registra cada operación como hecha por la API.

Sesión de un usuario

Hoy una integración entra con el correo y la contraseña de un usuario creado para ella, y manda la cookie de sesión que recibe en cada llamada. Es lo que usan los ejemplos de la referencia.

Creá un usuario para la integración, con un rol que tenga sólo los permisos que necesita.

Iniciá la sesión y guardá la cookie en sesion.txt:

curl -c sesion.txt -X POST "$ERP_URL/api/auth/sign-in/email" \
  -H "Content-Type: application/json" \
  -d '{"email": "integracion@tuempresa.com.ar", "password": "…"}'

Elegí la empresa activa de esa sesión (Elegir la empresa activa):

curl -b sesion.txt -X POST "$ERP_URL/api/v1/companies/select-active" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"companyId\": \"$ERP_EMPRESA\"}"

Mandá la cookie en cada llamada:

curl -b sesion.txt "$ERP_URL/api/v1/items/list" \
  -H "X-Expected-Company: $ERP_EMPRESA"

Desde código, la cookie va en el encabezado Cookie. En los ejemplos de TypeScript está en la variable ERP_SESION, con su nombre y su valor: __Secure-erp.session_token=….

Una llamada sin sesión, o con la sesión vencida, responde 401 con el código session.required.

Clave API

La clave API va a ser una credencial que un usuario crea desde su ficha para una integración: elige la empresa, qué permisos suyos le delega y hasta cuándo vale (90 días como máximo, según la política de la empresa). Se va a mandar como Authorization: Bearer <clave> en lugar de la cookie, y el usuario la va a poder revocar cuando quiera.