# TuCapi — API de cobros y pagos, versión 2

> Cobros (pay-ins) y pagos (payouts) por país y moneda, con una sola integración. Contrato v2.8.0. Importes en texto con punto decimal; una sola integración para cobros (pay-ins) y pagos (payouts).

La API v2 cobra y paga a personas por país, moneda y método; el catálogo
(`GET /v2/capabilities`) dice qué se puede hacer hoy. Toda creación lleva
`Idempotency-Key`; el desenlace llega por webhook firmado o por `GET /v2/events`.
Cada página de abajo existe en Markdown en `https://api.tucapi.app/v2/docs/<página>.md` y, para leerla en el navegador, en `https://api.tucapi.app/v2/docs/<página>`.

## Documentación

- [Empezar](https://api.tucapi.app/v2/docs/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](https://api.tucapi.app/v2/docs/autenticacion.md): La llave de API, los alcances y el ambiente sandbox.
- [Idempotencia y reintentos](https://api.tucapi.app/v2/docs/idempotencia-y-reintentos.md): Cómo reintentar sin pagar dos veces; qué se reintenta y qué no.
- [Cobros (pay-ins)](https://api.tucapi.app/v2/docs/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)](https://api.tucapi.app/v2/docs/pagos.md): Pagarle a una persona por pago móvil o transferencia, el saldo, y la cancelación.
- [Webhooks y eventos](https://api.tucapi.app/v2/docs/webhooks.md): Cómo recibir el desenlace de cada operación, verificar la firma y consultar los eventos.
- [Errores y fallos](https://api.tucapi.app/v2/docs/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](https://api.tucapi.app/v2/docs/catalogo.md): Países, monedas, métodos con sus campos y límites, bancos y disponibilidad.
- [Los SDK](https://api.tucapi.app/v2/docs/sdks.md): Los clientes oficiales de Go, Node y Python: qué resuelven y cómo se usan.
- [Servidor MCP](https://api.tucapi.app/v2/docs/mcp.md): Cómo conectar un asistente de IA (Claude, ChatGPT, Gemini, Codex) a su cuenta por MCP, sólo lectura.

## Contrato

- [OpenAPI 3.1](https://api.tucapi.app/v2/openapi.json): la fuente de verdad, servida por la API sin autenticación. Todo lo demás se genera de acá.

## Reglas que un asistente tiene que saber antes de escribir código

- `Idempotency-Key` es obligatoria en `POST /v2/payins` y `POST /v2/payouts`; la misma clave devuelve la misma operación. Nunca reintente con una clave nueva.
- Los estados públicos son `pending`, `confirmed` y `failed`; un `failed` trae `failure.code` (valor cerrado). Un `201` no es "cobrado".
- Los errores llegan como `{"error": {"code", "message", "details"}}`. Compare `code`.
- `confirm`, `resend-code`, `cancel` y `webhook-endpoints` no se reintentan a ciegas: consulte con `GET` y decida.
- El webhook se verifica con HMAC-SHA256 sobre `X-Timestamp + "." + cuerpo crudo`, en tiempo constante, con ventana de 5 minutos; puede traer dos firmas durante una rotación.
- Los importes son texto (`"1500.50"`), nunca números JSON.

## Optional

- [Toda la documentación en un archivo](https://api.tucapi.app/v2/llms-full.txt): las páginas de arriba concatenadas.