Ir al contenido

Claves de API

Una clave de API le permite a tu backend trabajar con una tienda. Créala en el panel, guárdala en tu servidor y envíala como token bearer.

En la tienda, crea una clave con los permisos read y write. El token ivk_ se muestra una sola vez; guárdalo de inmediato. Una tienda puede tener hasta 10 claves no revocadas; consulta Límites.

Un agente puede crear la misma clave usando su sesión de inicio de sesión:

Ventana de terminal
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/keys' \
-H 'Authorization: Bearer <session-token>' \
-H 'Idempotency-Key: <saved-unique-key>' \
-H 'Content-Type: application/json' \
-d '{"name":"backend","scopes":["read","write"]}'

Usa una sesión para crear o cambiar claves. Una clave de API no puede crear otra clave. Si la cuenta tiene MFA, gestionar claves puede requerir un segundo factor reciente.

Ventana de terminal
curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/payments?limit=50' \
-H 'Authorization: Bearer ivk_...'
Permiso Propósito
read permite leer facturas y depósitos, además de las comisiones y las redes activadas del comercio.
write permite todo en la tienda: crear, cancelar y desactivar facturas y depósitos, webhooks, el nombre y la identidad visual de la tienda.

Solicita ambos permisos para un backend que crea pagos y los comprueba. No asumas que write incluye read automáticamente.

La clave trabaja solo con su propia tienda, pero con toda ella. Solo adónde paga la tienda (destinatario, delegado, destino de pago), el archivado y el reinicio del sandbox requieren una sesión iniciada. Con read también lee las comisiones y las redes activadas de su comercio (GET /api/v1/merchants/{merchant_id}/tariffs y /networks). Todo lo demás sobre la cuenta y el comercio —inicio de sesión, perfil, equipo, otras tiendas, el resumen del comercio, claves de API, la billetera y la tarjeta— requiere una sesión iniciada; una clave recibe 403 api_key_not_allowed o 401. Nunca la pongas en código de navegador, una URL de pago o un chat compartido.

Archivar la tienda deshabilita todas sus claves.

GET /api/v1/me con la clave devuelve la clave y a qué pertenece:

{"user_id":"…","onboarding_required":false,"mfa_required":false,"key_id":"…","key_name":"backend","scopes":["read","write"],"shop_id":"…","shop_name":"Main shop","sandbox":false,"merchant_id":"…","merchant_name":"Acme"}

Usa shop_id en las rutas de la tienda; no hace falta listar comercios.

Opcionalmente, incluye allowed_ips al crear o editar una clave:

{"allowed_ips":["203.0.113.10","2001:db8::/32"]}

Estas son direcciones de ejemplo. Sustitúyelas por las direcciones de salida reales de tu backend. Se permiten hasta 10 IP o rangos CIDR por clave; más devuelve 400 too_many_allowed_ips. Una lista vacía elimina la restricción.

Crea una clave de reemplazo, actualiza tu backend y luego revoca la clave antigua con DELETE /api/v1/shops/{shop_id}/keys/{key_id}.

PATCH en la misma ruta puede cambiar name, enabled, scopes o allowed_ips. Los campos omitidos no cambian. Editar no revela ni rota el token.

Las claves funcionan hasta que se deshabilitan o revocan, sujetas al acceso de la cuenta y la tienda. No son una promesa de acceso permanente. Consulta la referencia de la API para ver los detalles de las solicitudes.