<!-- GENERADO POR scripts/generar_docs_v2.go DESDE api/openapi-v2.json Y docs/v2/fuentes/ — NO EDITAR A MANO. -->

# Empezar

La API v2 le permite **cobrarle a una persona** (pay-ins) y **pagarle a una
persona** (payouts) con una sola integración: país, moneda y método viajan en
el cuerpo del pedido, y lo que se puede hacer hoy lo dice
`GET /v2/capabilities`. Usted no elige proveedor ni banco de salida: la API
enruta cada operación por el mejor riel disponible.

## En cinco pasos

1. **Pida sus llaves.** TuCapi le entrega dos: `tuc_live_…` para producción
   (`https://api.tucapi.app`) y `tuc_test_…` para probar sin mover dinero en
   el sandbox (`https://api.tucapi.app/sandbox`), con los alcances que
   necesite (`payins:crear`, `payouts:crear`, `operaciones:leer`,
   `saldos:leer`, `webhooks:configurar`). Ver [Autenticación](autenticacion.md).
2. **Lea el catálogo.** `GET /v2/capabilities` le dice qué países, monedas y
   métodos tiene su llave, con los campos que cada método exige. Ver
   [Catálogo](catalogo.md).
3. **Registre su webhook.** `POST /v2/webhook-endpoints` con su url https;
   guarde el secreto, se muestra una sola vez. Ver [Webhooks](webhooks.md).
4. **Cree su primera operación** con un SDK o con `curl`, siempre con
   `Idempotency-Key`. Ver [Cobros](cobros.md) y [Pagos](pagos.md).
5. **Reciba el desenlace** por webhook (`payout.confirmed`, `payout.failed`,
   `payin.confirmed`, `payin.failed`) o consúltelo con
   `GET /v2/transactions/{id}`.

## Las tres reglas que conviene entender antes de escribir código

- **`Idempotency-Key` es obligatoria y es su red.** Reenviar el mismo pedido
  con la misma clave devuelve LA MISMA operación. Es lo que hace seguro
  reintentar. Ver [Idempotencia y reintentos](idempotencia-y-reintentos.md).
- **Los estados públicos son tres:** `pending`, `confirmed` y `failed`. Un
  `failed` siempre trae `failure.code`, un valor cerrado sobre el que puede
  hacer un `switch`. Un `201` no significa "cobrado": mire `status`.
- **Los importes son texto** con punto decimal (`"1500.50"`), nunca números
  JSON.

## Un pago en tres líneas

**`POST /v2/payouts`**

```bash
curl -X POST https://api.tucapi.app/v2/payouts \
  -H "Authorization: Bearer $LLAVE" \
  -H "Idempotency-Key: orden-4821" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1500.50",
    "beneficiary": {
      "account_number": "04121234567",
      "bank_code": "0102",
      "document": {
        "number": "12345678",
        "type": "V"
      },
      "name": "Nombre Apellido"
    },
    "country": "VE",
    "currency": "VES",
    "metadata": {
      "orden": "B-2"
    },
    "method": "mobile_payment",
    "purpose": "remittance",
    "reference": "remesa 456"
  }'
```

Respuesta `201`:

```json
{
  "amount": "1500.50",
  "bank_reference": null,
  "country": "VE",
  "created_at": "2026-09-23T14:59:05Z",
  "created_by": "company",
  "currency": "VES",
  "failure": null,
  "id": "6f1c2a9e-3b4d-4c5e-8f70-1a2b3c4d5e6f",
  "metadata": {
    "orden": "A-1"
  },
  "method": "mobile_payment",
  "pending_reason": "processing",
  "purpose": "remittance",
  "reference": "factura 123",
  "status": "pending",
  "type": "payout",
  "updated_at": "2026-09-23T14:59:05Z"
}
```


## Dónde está todo

- [Empezar](empezar.md): Qué es la API v2, cómo funciona un cobro y un pago, y los cinco pasos para la primera integración.
- [Autenticación](autenticacion.md): La llave de API, los alcances y el ambiente sandbox.
- [Idempotencia y reintentos](idempotencia-y-reintentos.md): Cómo reintentar sin pagar dos veces; qué se reintenta y qué no.
- [Cobros (pay-ins)](cobros.md): Cobrarle a una persona con código de un solo uso, por débito domiciliado, o esperar el Pago Móvil o la transferencia que ella manda.
- [Pagos (payouts)](pagos.md): Pagarle a una persona por pago móvil o transferencia, el saldo, y la cancelación.
- [Webhooks y eventos](webhooks.md): Cómo recibir el desenlace de cada operación, verificar la firma y consultar los eventos.
- [Errores y fallos](errores.md): El sobre de error, los códigos de error de la API y los códigos de fallo de una operación.
- [Catálogo](catalogo.md): Países, monedas, métodos con sus campos y límites, bancos y disponibilidad.
- [Los SDK](sdks.md): Los clientes oficiales de Go, Node y Python: qué resuelven y cómo se usan.
- [Servidor MCP](mcp.md): Cómo conectar un asistente de IA (Claude, ChatGPT, Gemini, Codex) a su cuenta por MCP, sólo lectura.