Início rápido

Copie este prompt no seu agente para configurar uma loja e verificar sua primeira fatura.

Help me integrate Invoise into my project. Read https://docs.invoise.me/llms.txt, https://docs.invoise.me/openapi.json and https://docs.invoise.me/agents/integration.md.

Use my existing access or help me sign in and create a merchant, shop and API key. If you sign in with a wallet, ask me for my email before creating the merchant. Ask me for the recipient address before creating the shop. Read available networks, tokens, decimals and fees from the API.

Start in Sandbox: create an invoice, get payment_url, connect webhooks with signature verification and deduplication, and check payment through GET. Save Idempotency-Key before sending requests. Finish with the test result and what is needed to accept real payments.

Esta é a forma normal de integrar o Invoise a um site ou back-end: entre como uma pessoa, configure a loja no painel e deixe seu servidor chamar a API com uma chave.

Está construindo um agente autônomo sem navegador e sem e-mail? Acesse Entrada do agente em vez disso. Esta página pressupõe que uma pessoa faz a configuração.

1. Entre e crie uma loja

Abra platform.invoise.me e entre com um código por e-mail ou com o Google. Na primeira entrada você cria um lojista; um lojista novo ainda não tem lojas, então crie uma.

Uma loja precisa de um destinatário — a carteira que recebe seu dinheiro — ou paga na sua carteira Invoise. Você pode alterar o destinatário e o delegado opcional depois; faturas e endereços já criados mantêm os que tinham na criação.

Crie uma loja sandbox se quiser testar sem fundos reais. Veja Sandbox.

2. Crie uma chave de API

Na loja, crie uma chave com os escopos read e write. Ela começa com ivk_ e é exibida uma única vez, então salve-a imediatamente.

Seu servidor a envia em cada requisição:

Authorization: Bearer ivk_...

A chave funciona para apenas uma loja e não pode acessar sua conta ou sua equipe. Veja Chaves de API.

3. Escolha uma rede e um token

curl https://platform.invoise.me/api/v1/networks

Pegue chain_id, o endereço do token e decimals na resposta. Escolha uma rede habilitada para o seu lojista e um token pronto. Os ativos disponíveis mudam; não fixe a lista deles no código. Veja Redes e tokens.

4. Emita uma fatura

Os valores são strings de números inteiros nas menores unidades do token. Com 6 casas decimais, 10000000 equivale a 10 tokens.

Defina estas variáveis de ambiente antes da requisição:

Variável	Valor
`CHAIN_ID`	O `chain_id` da rede selecionada, obtido na API.
`TOKEN_ADDRESS`	O `tokens[].address` do token selecionado nessa rede.
`AMOUNT`	Valor da fatura nas menores unidades, calculado usando `tokens[].decimals`.

curl -X POST https://platform.invoise.me/api/v1/shops/{shop_id}/invoices \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 2a8b1f47-6d0c-4a1f-8f0b-4f2c9f3a77d2' \
  -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"amount\":\"${AMOUNT:?}\"}"

Substitua {shop_id} pelo ID da sua loja. Gere e salve uma Idempotency-Key exclusiva para esta fatura; a chave do exemplo é apenas ilustrativa.

A resposta é 202 Accepted: salve o id dela como issuance_id. 202 significa que a criação foi aceita, não que o cliente pagou.

Quer um endereço de recarga reutilizável sem valor fixo? Chame /deposits em vez disso. Veja Depósitos e faturas.

5. Aguarde o endereço

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

Consulte repetidamente até que um endereço seja retornado e envie o pagador para o payment_url dessa resposta. Essa é a página de pagamento hospedada, com o endereço, um QR code e o status em tempo real já prontos.

6. Verifique se foi pago

Uma fatura está paga quando seu status é funded ou settled. funded significa que o valor exigido foi confirmado; settled significa que a fatura foi fechada na blockchain. Leia o status pela API e receba notificações de mudança por webhooks.

Por webhook

Antes do seu primeiro pagamento, registre o endpoint do seu servidor:

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-webhook-key>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'

Substitua a URL pelo endpoint HTTPS público do seu servidor e salve o secret da resposta.

Verifique Invoise-Signature com esse segredo e deduplique por Invoise-Event-ID. Veja o exemplo de verificação de assinatura.
transfer.confirmed informa uma transferência recebida confirmada. Pegue data.issuance_id e leia a fatura pelo GET abaixo: uma única transferência pode cobrir apenas parte do valor.
Se status for funded ou settled e cancelled_at for null, marque o pedido como pago uma única vez. Separadamente, payout.confirmed confirma a contabilização completa da liquidação do repasse ao destinatário.

Pela API

Leia a fatura a partir do seu back-end:

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

Campos relevantes da resposta após o pagamento:

{
  "status": "funded",
  "amount": "10000000",
  "received": "10000000",
  "cancelled_at": null
}

O valor total da fatura está confirmado. Marque o pedido como pago; outro GET ou webhook não deve creditá-lo duas vezes.

Para open, continue aguardando: o pagamento completo ainda não chegou. Você pode consultar a cada 3–5 segundos e reduzir a frequência em esperas longas. registering e reconciling também não significam sucesso. Se cancelled_at estiver definido, trate o pedido pago e cancelado separadamente.

Veja Status de fatura e depósito para todos os estados e o comportamento específico dos depósitos.

Uma regra para lembrar

Criar uma fatura ou depósito exige Idempotency-Key. Guarde a chave: se uma requisição expirar e você não tiver certeza se funcionou, envie a mesma requisição com a mesma chave novamente. Você receberá o resultado original em vez de uma segunda fatura. Veja Idempotência e erros.