Autenticación con API keys - Guía de usuarios de Tero

Qué es

Las API keys permiten que un script, una integración o una carga inicial hablen con la API de administración de una empresa. No reemplazan el ingreso al back office: sirven para automatizar tareas como listar productos, importar un CSV o actualizar medios de pago. Cada clave pertenece a un solo comercio. Tero guarda un hash y un prefijo visible; la clave completa se muestra una sola vez al crearla.

Dónde está

La URL base de la API es:

https://pos-api.terominds.com/api

En staging:

https://pos-api.stg.terominds.com/api

Llamá a pos-api en forma directa. El sitio teropos.com.ar (antes pos.terominds.com) es el back office y no acepta estas claves en el navegador. Creá y revocá las claves en Back office → Configuración → Equipo → API keys. El procedimiento está en Crear y revocar API keys.

Cómo se usa

Enviá la clave en el encabezado Authorization como Bearer. El formato es tero_live_<prefijo>_<secreto>.

export TERO_API_KEY='tero_live_aabbccdd_xxxxxxxx'
export TERO_TENANT_ID='00000000-0000-0000-0000-000000000001'
export TERO_API='https://pos-api.terominds.com/api'

curl -sS "$TERO_API/admin/tenants/$TERO_TENANT_ID/catalog" \
  -H "Authorization: Bearer $TERO_API_KEY" \
  -H "Accept: application/json"

El tenantId es el identificador de la empresa. Lo ves en la URL del back office: /admin/tenants/<tenantId>/....

Creá una clave

En Configuración → Equipo → API keys elegí el alcance y copiá la clave completa.

Guardala fuera del repositorio

Usá una variable de entorno o un gestor de secretos. No la subas a git ni la pegues en un chat.

Llamá a pos-api

Usá https://pos-api.terominds.com/api y el encabezado Authorization: Bearer ….

Configuración

Encabezado	Valor
`Authorization`	`Bearer tero_live_<prefijo>_<secreto>`
`Accept`	`application/json`
`Content-Type`	`application/json` en POST y PUT

No hace falta X-Tero-Origin-Secret. Ese encabezado lo envía solo el back office para las sesiones del navegador. Una API key con el formato correcto alcanza para entrar a pos-api. Una sesión de cookies no alcanza para llamar a pos-api en forma directa. Eso evita que una cookie robada se use fuera del sitio.

Errores

Código	`error`	Qué significa
401	`unauthorized`	Falta autenticación (no hay clave ni sesión).
401	`invalid_api_key`	La clave no existe o el secreto no coincide.
401	`api_key_revoked`	La clave fue revocada.
401	`api_key_expired`	La clave venció.
403	`insufficient_scope`	Una clave de solo lectura intentó un método que no es GET.
403	`forbidden`	La clave no corresponde a esa empresa, o el endpoint es solo de plataforma.
429	`rate_limited`	Demasiadas llamadas. Esperá un minuto y reintentá.

La API de administración está acotada a la empresa de la clave. Los endpoints de superadmin (crear empresas, flota global, releases) no aceptan API keys.

Tips y advertencias

La clave completa se muestra una sola vez. Si la perdés, revocala y creá otra. Tero nunca vuelve a mostrar el secreto.

Preferí una clave de solo lectura si el script no necesita cambiar datos.
Si una automatización deja de usarse, revocala.
El tenantId de la URL tiene que ser el de la empresa dueña de la clave.

Relacionado

Alcances

Lectura o lectura y escritura.

Crear y revocar

Desde el back office.

Ejemplos

Productos, CSV, fotos y cobros.

​Qué es

​Dónde está

​Cómo se usa

​Configuración

​Errores

​Tips y advertencias

​Relacionado

Alcances

Crear y revocar

Ejemplos

Qué es

Dónde está

Cómo se usa

Configuración

Errores

Tips y advertencias

Relacionado