# Início rápido Crie uma loja, emita uma fatura e receba o pagamento com a API REST do Invoise. Source: https://docs.invoise.me/pt-br/start/quickstart/ **Comece mais rápido com um agente** Copie este prompt no seu agente para configurar uma loja e verificar sua primeira fatura. ```text wrap 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](https://docs.invoise.me/pt-br/agents/sign-in/) 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](https://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](https://docs.invoise.me/pt-br/payments/wallet/). 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](https://docs.invoise.me/pt-br/payments/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: ```text Authorization: Bearer ivk_... ``` A chave funciona para apenas uma loja e não pode acessar sua conta ou sua equipe. Veja [Chaves de API](https://docs.invoise.me/pt-br/integration/api-keys/). ## 3. Escolha uma rede e um token ```bash 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](https://docs.invoise.me/pt-br/payments/networks/). ## 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`. | ```bash 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](https://docs.invoise.me/pt-br/payments/deposits-and-invoices/). ## 5. Aguarde o endereço ```bash 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](https://docs.invoise.me/pt-br/payments/checkout/), 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: ```bash curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \ -H 'Authorization: Bearer ivk_...' \ -H 'Idempotency-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. 1. Verifique `Invoise-Signature` com esse segredo e deduplique por `Invoise-Event-ID`. Veja o [exemplo de verificação de assinatura](https://docs.invoise.me/pt-br/integration/webhooks/#3-verifique-antes-de-processar). 2. `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. 3. 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: ```bash 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: ```json { "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](https://docs.invoise.me/pt-br/payments/status/) 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](https://docs.invoise.me/pt-br/integration/idempotency-and-errors/).