Flujo del agente

Este es el camino de configuración para un agente con una sesión de billetera. 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:

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

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

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

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 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.

3. Emite una clave de API de tienda

Usa tu sesión para crear una clave 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.

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:

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.

Consulta Estado de facturas y depósitos 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 para el índice de páginas y OpenAPI para contratos estructurados. Herramientas de lectura lista las exportaciones en Markdown y de texto completo.