Saltar al contenido principal
Borrador: especificación en curso. Los endpoints y campos pueden cambiar.

Claves de API

Cada clave pertenece a una organización y es creada en el panel por un administrador. La clave completa se muestra una sola vez, al momento de crearla. La clave va en el encabezado Authorization de cada solicitud:
La clave de API autentica la integración ante TESA. No firma transacciones ni da acceso a las claves de las billeteras, que permanecen con la empresa o con su custodio.

Alcances

Cada clave recibe uno o más alcances. Una llamada fuera del alcance de la clave devuelve 403. Recomendamos separar funciones: la integración con el ERP usa read y propose, y la aprobación queda con una clave admin guardada en un entorno restringido, o solo en el panel.

Rotación

  • Una organización puede tener más de una clave activa a la vez, lo que permite rotar sin ventana de interrupción.
  • El flujo sugerido es crear la nueva clave, actualizar la integración y revocar la anterior.
  • Las claves revocadas dejan de funcionar de inmediato. Cada clave registra su fecha de creación, último uso y autor.

Lista de IP permitidas

Las claves de producción pueden restringirse a una lista de IP o bloques CIDR. Las solicitudes desde fuera de la lista devuelven 403 con el código ip_nao_autorizado. La propuesta es que la lista de IP permitidas sea obligatoria para las claves con alcance admin.

Firma de solicitudes (HMAC)

Además de la clave, las solicitudes que cambian estado (POST, PUT) pueden firmarse con un secreto HMAC de la organización, separado de la clave de API. La propuesta es que la firma sea obligatoria para las claves con alcance admin. El mensaje canónico une, separados por saltos de línea: la marca de tiempo, el método, la ruta con la cadena de consulta y el cuerpo bruto de la solicitud.
Las solicitudes con una marca de tiempo fuera de una ventana de 5 minutos se rechazan con 401, lo que impide la repetición de una solicitud capturada.

Idempotencia

Toda solicitud POST acepta el encabezado Idempotency-Key, con un valor único generado por la integración (un UUID, por ejemplo).
  • Repetir la misma clave con el mismo cuerpo devuelve la respuesta original, sin crear una segunda operación.
  • Repetir la misma clave con un cuerpo distinto devuelve 409 con el código conflito_idempotencia.
  • Las claves se almacenan durante 24 horas.
Para rescates y aprobaciones, Idempotency-Key es obligatoria. Una falla de red no debe crear dos solicitudes de rescate.

Límites de tasa

Los límites se aplican por clave y se detallan en Errores y límites. El volumen de llamadas es además la base de la factura de uso del plan: vea Precios y uso. Toda respuesta incluye los encabezados RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset.