Referencia de autenticación de agentes

Todas las rutas de abajo usan https://platform.invoise.me/api/v1. Envía JSON con Content-Type: application/json. Las solicitudes de inicio de sesión no necesitan una clave de idempotencia.

El inicio de sesión con billetera es solo para agentes. Una solicitud con cabecera Origin, como tiene toda solicitud de navegador, devuelve 403 wallet_sign_in_agents_only. Llama a estos endpoints desde un servidor o script.

POST /auth/wallet/challenge

Solicita un mensaje para firmar. No requiere credenciales.

Campo	Tipo	Valor
`address`	string, obligatorio	Tu dirección de billetera EVM.
`chain_id`	integer, obligatorio	Un ID de red EVM disponible, obtenido de la API.

Respuesta 200: challenge_id (string) y message (string).

Firma el mensaje devuelto exactamente tal como se recibió, usando la firma de mensaje personal EIP-191. Nunca envíes la clave privada. Un desafío caducado o ya usado requiere una nueva solicitud.

POST /auth/wallet/verify

Intercambia un desafío firmado por una sesión. No requiere token bearer.

Campo	Tipo	Valor
`challenge_id`	string, obligatorio	ID devuelto por la solicitud de desafío.
`signature`	string, obligatorio	Firma hexadecimal del mensaje original exacto.

{"challenge_id":"<challenge-id>","signature":"<0x-signature>"}

Respuesta 200 (valores de ejemplo):

{
  "token": "<session-token>",
  "expires_at": "2026-09-21T10:00:00Z",
  "user": {
    "user_id": "<user-id>",
    "onboarding_required": true,
    "mfa_required": false
  }
}

Envía token en Authorization: Bearer <session-token>. Usa expires_at para controlar la caducidad. No se establece ninguna cookie, así que las llamadas con bearer no necesitan cabecera CSRF.

Las pruebas no válidas o ya consumidas pueden devolver 401 unauthorized. Si la solicitud agota el tiempo de espera después de que una prueba de un solo uso pudiera haberse consumido, inicia un desafío nuevo en lugar de reenviar la firma repetidamente.

MFA, cuando está activado

El inicio de sesión con billetera no evita el segundo factor de la cuenta. Si user.mfa_required es true, usa el factor configurado con esta sesión antes de las llamadas de negocio.

Para una cuenta con TOTP, envía:

POST /api/v1/auth/totp/verify
Authorization: Bearer <session-token>
Content-Type: application/json

{"code":"<current-code>"}

Los cambios sensibles protegidos por MFA también pueden devolver 403 mfa_required cuando se necesita una confirmación reciente. Los códigos de recuperación requieren la sesión principal; no son un método de inicio de sesión independiente. Los demás factores de la cuenta se describen en Inicio de sesión de cuenta.

POST /onboarding

Cuando user.onboarding_required es true, crea el primer comercio. Una cuenta que solo inició sesión con una billetera debe enviar el correo del propietario humano junto a name, así que pídeselo antes a tu humano:

{"name":"My merchant","email":"[email protected]"}

Envíalo con la sesión bearer y una Idempotency-Key. El correo se convierte en un método de inicio de sesión de esta misma cuenta. Invoise le envía a la persona un aviso: abre el panel, inicia sesión con ese correo usando un código de un solo uso y llega a la cuenta que creó el agente.

Error	Significado
`400 email_required`	Falta `email`. Pídeselo a tu humano.
`400 invalid_email`	La dirección tiene un formato incorrecto.
`400 disposable_email`	No se aceptan direcciones de correo desechables. Usa una dirección permanente.
`400 identity_already_linked`	El correo ya pertenece a otra cuenta. Pide uno distinto.

Consulta Flujo del agente para ver los siguientes pasos.

POST /auth/logout

Termina la sesión actual. Envía su token bearer. Una solicitud exitosa devuelve 200; las llamadas futuras con la sesión revocada se rechazan.

Para el trabajo de pagos continuo, usa una clave de API de tienda. Para la configuración tras iniciar sesión, sigue el flujo del agente.