# Fluxo do agente

Da entrada por carteira até uma fatura paga, o caminho completo para um agente automatizado.

Source: https://docs.invoise.me/pt-br/agents/integration/

Este é o caminho de configuração para um agente com uma [sessão de carteira](https://docs.invoise.me/pt-br/agents/sign-in/). 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:

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

{"name":"My merchant","email":"owner@example.com"}
```

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

```http
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](https://docs.invoise.me/pt-br/payments/wallet/) 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](https://docs.invoise.me/pt-br/payments/solana-and-tron/).

## 3. Emita uma chave de API da loja

Use sua sessão para [criar uma chave](https://docs.invoise.me/pt-br/integration/api-keys/) 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](https://docs.invoise.me/pt-br/payments/deposits-and-invoices/#ofereça-vários-tokens-ou-redes).

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:

```bash
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](https://docs.invoise.me/pt-br/integration/webhooks/).

Leia [Status de fatura e depósito](https://docs.invoise.me/pt-br/payments/status/) 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](https://docs.invoise.me/llms.txt) para o índice de páginas e [OpenAPI](https://docs.invoise.me/openapi.json) para contratos estruturados. [Ferramentas de leitura](https://docs.invoise.me/pt-br/agents/reading/) lista exportações em Markdown e texto completo.