# Inicio rápido

Crea una tienda, emite una factura y recibe el pago con la API REST de Invoise.

Source: https://docs.invoise.me/es/start/quickstart/

**Empieza más rápido con un agente**
Copia este prompt en tu agente para configurar una tienda y comprobar tu primera factura.

```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 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](https://docs.invoise.me/es/agents/sign-in/) 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](https://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](https://docs.invoise.me/es/payments/wallet/). 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](https://docs.invoise.me/es/payments/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:

```text
Authorization: Bearer ivk_...
```

La clave funciona solo para una tienda y no puede tocar tu cuenta ni tu equipo. Consulta
[Claves de API](https://docs.invoise.me/es/integration/api-keys/).

## 3. Elige una red y un token

```bash
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](https://docs.invoise.me/es/payments/networks/).

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

```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:?}\"}"
```

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](https://docs.invoise.me/es/payments/deposits-and-invoices/).

## 5. Espera la dirección

```bash
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](https://docs.invoise.me/es/payments/checkout/), 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:

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

1. Verifica `Invoise-Signature` con ese secreto y evita duplicados usando `Invoise-Event-ID`. Consulta el [ejemplo de verificación de firma](https://docs.invoise.me/es/integration/webhooks/#3-verificar-antes-de-procesar).
2. `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.
3. 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:

```bash
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:

```json
{
  "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](https://docs.invoise.me/es/payments/status/) 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](https://docs.invoise.me/es/integration/idempotency-and-errors/).