Fluxo do agente

Este é o caminho de configuração para um agente com uma sessão de carteira. Se você já tem um ID de loja e uma chave de API, vá direto para a etapa 4.

Todas as escritas JSON abaixo precisam de Content-Type: application/json, do token bearer da sua sessão e de uma Idempotency-Key salva e exclusiva para a ação.

1. Selecione um lojista

Leia GET /api/v1/me. Se user.onboarding_required for verdadeiro, peça primeiro o endereço de e-mail do seu humano e depois conclua a configuração:

POST /api/v1/onboarding
Content-Type: application/json

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

Uma conta que entrou apenas com uma carteira deve enviar email; sem ele, a resposta é 400 email_required. Um endereço malformado retorna invalid_email, um descartável retorna disposable_email, e um e-mail que já pertence a outra conta retorna identity_already_linked. O e-mail se torna um método de entrada dessa mesma conta. O Invoise envia um aviso à pessoa: ela abre o painel, entra com esse e-mail usando um código de uso único e chega à conta que você criou.

Isso retorna {"completed":true}, não o ID do lojista. Chame em seguida GET /api/v1/merchants e salve o id do lojista pretendido.

Uma conta que já existia pode pertencer a vários lojistas. Escolha explicitamente; não use silenciosamente a primeira entrada. Não use POST /merchants para o onboarding — ele retorna forbidden.

2. Crie uma loja

POST /api/v1/merchants/{merchant_id}/shops
Content-Type: application/json

{
  "name": "Agent payments",
  "sandbox": true,
  "recipient": "<your-payout-address>"
}

Salve o id retornado como shop_id. Comece no sandbox para um teste; crie uma loja real separada com sandbox: false depois.

O delegate EVM opcional é uma carteira de liquidação que você controla. Defina-o apenas se precisar de um. Nunca use um endereço de depósito de corretora para essa função.

Você pode alterar o destinatário e o delegado depois com PATCH /api/v1/shops/{shop_id}. Faturas e endereços já criados mantêm os que tinham na criação.

Uma loja real pode, em vez disso, pagar na carteira Invoise da conta: envie "payout_target":"wallet" sem recipient. Seu humano configura essa carteira no painel; até lá, criar uma fatura retorna 400 wallet_not_ready. Solana e Tron precisam de seu próprio destinatário; veja Solana e Tron.

3. Emita uma chave de API da loja

Use sua sessão para criar uma chave com read e write. Salve o token ivk_ retornado no seu cofre de segredos e use-o para as chamadas de pagamento a seguir.

4. Crie uma fatura

1. Leia GET /api/v1/networks. Use uma rede habilitada e um token pronto, com seu endereço e casas decimais reais.
2. Salve uma chave de idempotência com a fatura no seu sistema antes de enviar a requisição.
3. Chame POST /api/v1/shops/{shop_id}/invoices:

Campo	Valor
chain_id	ID da rede selecionada, obtido na API; um inteiro.
token	Endereço do token selecionado, obtido na API.
amount	Valor da fatura nas menores unidades do token; uma string de inteiro.
external_id	Referência opcional a um registro no seu sistema.

Para um endereço de recarga reutilizável, chame /deposits sem amount. Para deixar o pagador escolher entre vários tokens ou redes, envie assets em vez de chain_id e token; veja Depósitos e faturas.

Após um timeout, repita a mesma requisição com a mesma chave. external_id sozinho não evita duplicatas.

5. Aguarde o endereço e depois o pagamento

Salve id da resposta 202. Consulte repetidamente:

curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id}' \
  -H 'Authorization: Bearer ivk_...'

Aguarde um address não vazio e depois compartilhe payment_url. Continue consultando esse mesmo endpoint para status e received. Receba notificações de mudança por webhooks.

Leia Status de fatura e depósito antes de registrar o pagamento de uma fatura: funded, settled, cancelamento e depósitos reutilizáveis têm significados diferentes. Persista cada atualização de negócio uma única vez.

Leia a documentação sem navegador

Comece em llms.txt para o índice de páginas e OpenAPI para contratos estruturados. Ferramentas de leitura lista exportações em Markdown e texto completo.