Entrada do agente

Já tem uma chave de API da loja? Pule a entrada e use a API de pagamento. Um agente só precisa da entrada por carteira quando tem que configurar ou administrar uma conta.

A entrada por carteira é exclusiva para agentes. Envie estas requisições a partir de um servidor ou script: uma requisição com cabeçalho Origin, que todo navegador adiciona, é recusada com 403 wallet_sign_in_agents_only. O painel não oferece entrada por carteira nem vinculação de carteira.

1. Solicite uma mensagem

Use uma carteira EVM que você controla. A chave privada dela fica com sua ferramenta de assinatura e nunca é enviada ao Invoise.

curl -X POST 'https://platform.invoise.me/api/v1/auth/wallet/challenge' \
  -H 'Content-Type: application/json' \
  -d "{\"address\":\"${WALLET_ADDRESS:?}\",\"chain_id\":${CHAIN_ID:?}}"

Defina WALLET_ADDRESS com seu endereço EVM e CHAIN_ID com um ID de rede EVM disponível, obtido na API. A resposta contém challenge_id e message.

2. Assine a mensagem retornada

Use o método de assinatura de mensagem pessoal EIP-191 da sua carteira. Assine message exatamente como recebida, incluindo espaços em branco. Esta é uma assinatura de mensagem, não uma transação.

O desafio tem vida curta e uso único. Se expirar ou for consumido, solicite um novo.

3. Troque a assinatura por uma sessão

curl -X POST 'https://platform.invoise.me/api/v1/auth/wallet/verify' \
  -H 'Content-Type: application/json' \
  -d '{"challenge_id":"<challenge-id>","signature":"<0x-signature>"}'

Salve token com segurança e verifique expires_at, user.mfa_required e user.onboarding_required na resposta.

O Invoise não define nenhum cookie. Envie a sessão em Authorization: Bearer <token>; ela não precisa de cabeçalho CSRF.

4. Conclua a configuração

Condição	Próximo passo
user.mfa_required: true	Complete o segundo fator configurado antes das requisições de negócio. A entrada por carteira não contorna o MFA.
user.onboarding_required: true	Peça o e-mail ao seu humano e depois crie o primeiro lojista por /onboarding com name e email. Sem o e-mail, a resposta é 400 email_required; um endereço descartável retorna 400 disposable_email.
Entrada concluída	Continue com Fluxo do agente para escolher um lojista, criar uma loja e emitir uma chave de API da loja.

Use a sessão para a configuração e a chave de API com escopo para o trabalho de pagamento. Se uma sessão expirar, autentique novamente. Veja Referência de autenticação para os campos de requisição e resposta.