Inicio rápido

Copia este prompt en tu agente para configurar una tienda y comprobar tu primera factura.

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 es la forma habitual de integrar Invoise en un sitio o un backend: inicia sesión como persona, configura la tienda en el panel y deja que tu servidor llame a la API con una clave.

¿Vas a crear un agente autónomo sin navegador ni correo? Ve a Inicio de sesión de agentes en su lugar. Esta página asume que la configuración la hace una persona.

1. Inicia sesión y crea una tienda

Abre platform.invoise.me e inicia sesión con un código por correo o con Google. En el primer inicio de sesión creas un comercio; un comercio nuevo aún no tiene tiendas, así que crea una.

Una tienda necesita un destinatario —la billetera que recibe tu dinero— o paga a tu billetera de Invoise. Puedes cambiar el destinatario y el delegado opcional más adelante; las facturas y direcciones ya creadas conservan los que tenían al crearse.

Crea una tienda sandbox si quieres practicar sin fondos reales. Consulta Sandbox.

2. Crea una clave de API

En la tienda, crea una clave con los permisos read y write. Empieza con ivk_ y se muestra una sola vez, así que guárdala de inmediato.

Tu servidor la envía en cada solicitud:

Authorization: Bearer ivk_...

La clave funciona solo para una tienda y no puede tocar tu cuenta ni tu equipo. Consulta Claves de API.

3. Elige una red y un token

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

Toma chain_id, la dirección del token y decimals de la respuesta. Elige una red habilitada para tu comercio y un token disponible. Los activos disponibles cambian; no fijes su lista en el código. Consulta Redes y tokens.

4. Emite una factura

Los importes son cadenas de enteros en las unidades más pequeñas del token. Con 6 decimales, 10000000 son 10 tokens.

Define estas variables de entorno antes de la solicitud:

Variable	Valor
`CHAIN_ID`	El `chain_id` de la red elegida, obtenido de la API.
`TOKEN_ADDRESS`	El `tokens[].address` del token elegido en esa red.
`AMOUNT`	Importe de la factura en las unidades más pequeñas, calculado con `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:?}\"}"

Sustituye {shop_id} por el ID de tu tienda. Genera y guarda una Idempotency-Key única para esta factura; la clave de ejemplo es solo ilustrativa.

La respuesta es 202 Accepted: guarda su id como issuance_id. 202 significa que la creación se aceptó, no que el cliente haya pagado.

¿Quieres una dirección de recarga reutilizable sin importe fijo? Llama a /deposits en su lugar. Consulta Depósitos y facturas.

5. Espera la dirección

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

Haz sondeos hasta que llegue una dirección y luego envía al pagador al payment_url de esa respuesta. Esa es la página de pago alojada, con la dirección, un código QR y el estado en vivo ya integrados.

6. Comprueba si está pagada

Una factura está pagada cuando su status es funded o settled. funded significa que se confirmó el importe requerido; settled significa que la factura se cerró en la cadena. Consulta el estado mediante la API y recibe notificaciones de cambios mediante webhooks.

Mediante un webhook

Antes de tu primer pago, registra el endpoint de tu 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"]}'

Sustituye la URL por tu endpoint HTTPS público y guarda secret de la respuesta.

Verifica Invoise-Signature con ese secreto y evita duplicados usando Invoise-Event-ID. Consulta el ejemplo de verificación de firma.
transfer.confirmed informa de una transferencia entrante confirmada. Toma data.issuance_id y consulta la factura mediante el GET de abajo: una sola transferencia puede cubrir solo una parte del importe.
Si status es funded o settled y cancelled_at es null, marca el pedido como pagado una sola vez. Por separado, payout.confirmed confirma la liquidación completa correspondiente al pago al destinatario.

Mediante la API

Consulta la factura desde tu backend:

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

Campos relevantes de la respuesta tras el pago:

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

El importe completo de la factura está confirmado. Marca el pedido como pagado; otro GET o webhook no debe acreditarlo dos veces.

Con open, sigue esperando: el pago completo aún no ha llegado. Puedes sondear cada 3–5 segundos y espaciar más los sondeos si la espera se alarga. registering y reconciling tampoco significan éxito. Si cancelled_at está definido, gestiona por separado el pedido pagado y cancelado.

Consulta Estado de facturas y depósitos para ver todos los estados y el comportamiento específico de los depósitos.

Una regla que recordar

Crear una factura o un depósito requiere Idempotency-Key. Conserva la clave: si una solicitud agota el tiempo de espera y no sabes si funcionó, envía la misma solicitud con la misma clave otra vez. Obtendrás el resultado original en lugar de una segunda factura. Consulta Idempotencia y errores.