# Flujo del agente

Desde el inicio de sesión con billetera hasta una factura pagada, el camino completo para un agente automatizado.

Source: https://docs.invoise.me/es/agents/integration/

Este es el camino de configuración para un agente con una [sesión de billetera](https://docs.invoise.me/es/agents/sign-in/). Si ya tienes un ID de tienda y una clave de API, ve directamente al paso 4.

Todas las escrituras JSON de abajo necesitan `Content-Type: application/json`, tu token bearer de sesión y una `Idempotency-Key` guardada única para la acción.

## 1. Elige un comercio

Consulta `GET /api/v1/me`. Si `user.onboarding_required` es true, pídele antes a tu humano su dirección de correo y luego completa la configuración:

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

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

Una cuenta que solo inició sesión con una billetera debe enviar `email`; sin él, la respuesta es `400 email_required`. Una dirección con formato incorrecto devuelve `invalid_email`, una desechable `disposable_email`, y un correo que ya pertenece a otra cuenta `identity_already_linked`. El correo se convierte en un método de inicio de sesión de esta misma cuenta. Invoise le envía a la persona un aviso: abre el panel, inicia sesión con ese correo usando un código de un solo uso y llega a la cuenta que creaste.

Esto devuelve `{"completed":true}`, no el ID del comercio. A continuación llama a `GET /api/v1/merchants` y guarda el `id` del comercio que buscas.

Una cuenta que ya existía puede pertenecer a varios comercios. Elige explícitamente; no uses en silencio la primera entrada. No uses `POST /merchants` para la incorporación: devuelve `forbidden`.

## 2. Crea una tienda

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

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

Guarda el `id` devuelto como `shop_id`. Empieza en sandbox para una prueba; crea una tienda de producción aparte con `sandbox: false` después.

El `delegate` EVM opcional es una billetera de liquidación que controlas. Configúralo solo si lo necesitas. Nunca uses una dirección de depósito de un exchange para ese rol.

Puedes cambiar el destinatario y el delegado más adelante con `PATCH /api/v1/shops/{shop_id}`. Las facturas y direcciones ya creadas conservan los que tenían al crearse.

Una tienda de producción puede en su lugar pagar a la [billetera de Invoise](https://docs.invoise.me/es/payments/wallet/) de la cuenta: envía `"payout_target":"wallet"` sin `recipient`. Tu humano configura esa billetera en el panel; hasta entonces, crear una factura devuelve `400 wallet_not_ready`. Solana y Tron necesitan su propio destinatario; consulta [Solana y Tron](https://docs.invoise.me/es/payments/solana-and-tron/).

## 3. Emite una clave de API de tienda

Usa tu sesión para [crear una clave](https://docs.invoise.me/es/integration/api-keys/) con `read` y `write`. Guarda el token `ivk_` devuelto en tu almacén de secretos y úsalo luego para las siguientes llamadas de pago.

## 4. Crea una factura

1. Consulta `GET /api/v1/networks`. Usa una red habilitada y un token disponible, con su dirección y decimales reales.
2. Guarda una clave de idempotencia junto con la factura en tu sistema antes de enviar la solicitud.
3. Llama a `POST /api/v1/shops/{shop_id}/invoices`:

| Campo | Valor |
| --- | --- |
| `chain_id` | ID de la red elegida, obtenido de la API; un entero. |
| `token` | Dirección del token elegido, obtenida de la API. |
| `amount` | Importe de la factura en las unidades más pequeñas del token; una cadena de enteros. |
| `external_id` | Referencia opcional a un registro de tu sistema. |

Para una dirección de recarga reutilizable, llama a `/deposits` sin `amount`. Para dejar que el pagador elija entre varios tokens o redes, envía `assets` en lugar de `chain_id` y `token`; consulta [Depósitos y facturas](https://docs.invoise.me/es/payments/deposits-and-invoices/#ofrece-varios-tokens-o-redes).

Tras un tiempo de espera agotado, reintenta la misma solicitud con la misma clave. `external_id` por sí solo no evita duplicados.

## 5. Espera la dirección y luego el pago

Guarda `id` de la respuesta `202`. Sondea:

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

Espera a que `address` no esté vacío y luego comparte `payment_url`. Sigue sondeando este mismo endpoint para `status` y `received`. Recibe notificaciones de cambios mediante [webhooks](https://docs.invoise.me/es/integration/webhooks/).

Consulta [Estado de facturas y depósitos](https://docs.invoise.me/es/payments/status/) antes de registrar el pago de la factura: `funded`, `settled`, la cancelación y los depósitos reutilizables tienen significados distintos. Persiste cada actualización de negocio una sola vez.

## Consulta la documentación sin navegador

Empieza en [llms.txt](https://docs.invoise.me/llms.txt) para el índice de páginas y [OpenAPI](https://docs.invoise.me/openapi.json) para contratos estructurados. [Herramientas de lectura](https://docs.invoise.me/es/agents/reading/) lista las exportaciones en Markdown y de texto completo.