Autenticación
Su llave de API, en Authorization: Bearer <llave>: tuc_live_… en producción, tuc_test_… en el sandbox (https://api.tucapi.app/sandbox).
| Alcance | Permite |
|---|---|
payins:crear |
crear, confirmar y pedir código |
payouts:crear |
crear pagos |
operaciones:leer |
consultar operaciones y eventos |
saldos:leer |
GET /v2/balances |
webhooks:configurar |
registrar la url de avisos |
El catálogo (capabilities, methods, banks) lo lee cualquier llave válida.
Alcances
Sección titulada «Alcances»Cada ruta exige un alcance, o cualquier llave válida para el catálogo:
| Alcance | Rutas |
|---|---|
operaciones:leer |
GET /v2/events, GET /v2/payins/{id}, GET /v2/payouts/{id}, GET /v2/transactions/{id} |
payins:crear |
POST /v2/payins, POST /v2/payins/{id}/cancel, POST /v2/payins/{id}/confirm, POST /v2/payins/{id}/resend-code |
payouts:crear |
POST /v2/payouts, POST /v2/payouts/{id}/cancel |
saldos:leer |
GET /v2/balances |
webhooks:configurar |
POST /v2/webhook-endpoints |
| cualquier llave válida | GET /v2/banks, GET /v2/capabilities, GET /v2/methods |
Una llave sin el alcance recibe 403 scope_missing. Una llave ausente o
inválida, 401 unauthorized. Los dos son errores de configuración, no de
red: no los reintente.
Sandbox y producción
Sección titulada «Sandbox y producción»| URL base | Llave | |
|---|---|---|
| Producción | https://api.tucapi.app |
tuc_live_… |
| Sandbox | https://api.tucapi.app/sandbox |
tuc_test_… |
El mismo contrato sirve en los dos ambientes: cambian la llave y la URL base,
y nada más. Una llave de prueba contra producción, o una de producción contra
el sandbox, recibe 401 unauthorized. En los SDK la URL base es una opción
del cliente (baseUrl, base_url, WithBaseURL); en el servidor MCP, la
variable TUCAPI_API_URL.
En el sandbox nada mueve dinero: los proveedores son dobles que responden como los reales, con los mismos estados, códigos de fallo, tiempos, webhooks firmados y eventos. El desenlace de cada operación lo decide el documento del pagador o del beneficiario:
document.number |
Desenlace |
|---|---|
00000001 |
failed, failure.code de cuenta inválida |
00000002 |
pending al crear; confirmed en la primera consulta |
00000004 |
failed por fondos insuficientes del pagador |
00000022 |
failed por falta de domiciliación (sólo direct_debit) |
| cualquier otro | confirmed |
En un cobro con código (debit_otp) el código válido es siempre 123456;
cualquier otro deja el cobro en failed con failure.code = code_rejected,
igual que en producción, y para volver a probar se crea otro cobro. Las
referencias del banco son correlativas de 8 dígitos, como las de producción. Las llaves de prueba
las emite TuCapi junto con las de producción, con los mismos alcances.