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.
Crea una clave
Sección titulada «Crea una clave»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:
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.
Llama a la API
Sección titulada «Llama a la API»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.
Comprueba a qué pertenece una clave
Sección titulada «Comprueba a qué pertenece una clave»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.
Restringe el acceso por IP
Sección titulada «Restringe el acceso por IP»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.
Rota o revoca
Sección titulada «Rota o revoca»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.