Integraciones y entrada de documentos Útil

Crear una clave de API

3:00 Tutorial 3.5

Una clave de API permite que un programa externo consulte o cree datos de la gestoría. Cada clave lleva permisos y clientes autorizados, y se muestra una sola vez.

Antes de empezar

  • Plan que incluya la API. El plan Gratuito no la incluye. Máximo de claves activas por plan: Starter 1, Professional 5 y Enterprise 20.
  • Rol de titular o administrador del equipo. El resto de miembros no ve el submenú de API ni puede crear, rotar o revocar claves.
  • Clientes dados de alta en la cartera. Una clave sin clientes marcados no lee nada.
  • Con la API desactivada en el sistema, la pantalla lo indica: las claves y sus permisos quedan guardados y funcionan al activarse.

Paso 1. Abrir las claves de API

En el menú lateral, Integraciones > API y desarrolladores > Claves de API.

  1. Las pestañas son Claves, Webhooks, Consumo y Registro de llamadas.
  2. Localizar Crear clave (1) y el recuento «N de M claves del plan» (2).
Pantalla API y desarrolladores con las pestañas, el botón Crear clave (1) y el recuento de claves del plan (2).
Nota. Con el máximo del plan alcanzado, el botón desaparece y el recuento indica «revocar alguna para crear otra».

Paso 2. Identificar la integración

Pulsar Crear clave y completar el primer panel:

  1. Nombre de la integración (1): de 3 a 120 caracteres. Solo identifica la clave en el listado.
  2. Entorno (2): Pruebas (`cg_test_`) lee datos reales y no escribe. Producción (`cg_live_`) accede a los datos fiscales de los clientes.
  3. Para qué se va a usar (3): obligatorio en producción, de 20 a 1000 caracteres. Queda como justificación del uso.
Formulario Crear clave con Nombre de la integración (1), Entorno (2) y Para qué se va a usar (3).
Nota. Una clave de pruebas hace todas las lecturas salvo exportar el histórico completo de un cliente. En el entorno sandbox, la única opción es Sandbox (`cg_sbx_`), con datos ficticios.

Paso 3. Elegir lo que puede hacer

En el Candado 1, Qué puede hacer, marcar solo los permisos que la integración necesita (1). La primera carga propone tres de lectura: clientes, facturas y documentos.

Candado 1 Qué puede hacer con la lista de permisos y la etiqueta Escribe datos (1).
Nota. Los permisos que modifican datos llevan la etiqueta Escribe datos. Los que el plan no concede salen deshabilitados con No incluido en el plan.
Importante. Exportar el histórico de un cliente y borrar su rastro requiere un permiso aparte, `clientes:derechos`. Las escrituras exigen además la cabecera `Idempotency-Key`.
Importante. Presentar modelos ante la AEAT no se hace por la API: por ella se generan borradores y se descarga el justificante de lo ya presentado.

Paso 4. Elegir sobre quién

En el Candado 2, Sobre quién, buscar con Buscar por nombre o NIF… (1) y marcar los clientes que la clave podrá ver (2).

Candado 2 Sobre quién con el buscador (1) y la lista de clientes con casillas (2).
Atención. Sin ningún cliente marcado, la clave se crea pero no puede leer nada. Una clave de producción admite como máximo 25 clientes al crearla.
Nota. Cada cliente marcado queda autorizado con su consentimiento registrado. El techo de 25 se amplía después desde la pantalla Clientes de la clave.

Paso 5. Limitar el origen y la vigencia

Solo en los planes con configuración avanzada, el Candado 3 ofrece Direcciones IP permitidas (1) y Caduca el (2). Ambos son opcionales.

Candado 3 Desde dónde y hasta cuándo con Direcciones IP permitidas (1) y Caduca el (2).
Nota. Una dirección o un rango por línea (IPv4 o IPv6), hasta 20. La fecha de caducidad es posterior a hoy y de dos años como máximo. Vacíos, la clave funciona desde cualquier IP y no caduca.

Paso 6. Crear y copiar la clave

  1. Pulsar Crear clave. Aparece «Clave creada. Copiarla ahora: no se puede volver a ver.»
  2. En el recuadro Copiar ahora figura la clave completa (1). Pulsar Copiar (2) y guardarla.
Listado de claves con el recuadro Copiar ahora, la clave (1) y el botón Copiar (2).
Importante. Es la única vez que se muestra. Solo se guarda una huella: si se pierde, no se recupera. Hay que crear otra y revocar la anterior.
Nota. Si el navegador no permite copiar, la clave queda seleccionada y aparece «No se ha podido copiar: queda seleccionada, copiar con Ctrl+C (o Cmd+C).»

Paso 7. Entregar la clave al integrador

  1. Cada llamada lleva `Authorization: Bearer` con la clave y `X-CG-Client` con el cliente sobre el que actúa.
  2. Las escrituras añaden `Idempotency-Key`, para que un reintento no duplique una factura.
  3. La referencia técnica está en Documentación, en el mismo submenú.
Nota. Permisos y clientes se comprueban en cada llamada. Cambiarlos más tarde, con Permisos y Clientes en la ficha de la clave, no invalida la clave.

Resultado

La clave figura en el listado con el prefijo del entorno y una cadena de candados: Plan, Permisos, Clientes, Desde y Vigencia. Cada llamada de la integración queda en Registro de llamadas.

Campos del formulario

Campo Qué admite Obligatorio Efecto
Nombre de la integración Texto de 3 a 120 caracteres Sí Nombre de la clave en el listado.
Entorno Pruebas (cg_test_) o Producción (cg_live_); en el sandbox, Sandbox (cg_sbx_) Sí Prefijo de la clave. Pruebas no escribe.
Para qué se va a usar Texto de 20 a 1000 caracteres Sí, en Producción Justificación del acceso a los datos de los clientes.
Permisos (Qué puede hacer) Casillas del catálogo, salvo las que el plan no incluye Sí, al menos uno Concede el primer candado.
Clientes (Sobre quién) Clientes de la cartera; hasta 25 en una clave de producción No Autoriza y registra el consentimiento de cada cliente marcado.
Direcciones IP permitidas Una IP o rango por línea, hasta 20 No Limita desde dónde funciona la clave.
Caduca el Fecha posterior a hoy, hasta dos años No La clave se apaga sola ese día.

Problemas frecuentes

«Solo quien lleva la cuenta puede crear o revocar claves de API. Una clave da acceso a los datos de los clientes desde fuera del panel.»
Error de acceso 403. Solo el titular o un administrador del equipo gestiona claves.
«Máximo de {n} claves activas del plan alcanzado. Revocar alguna antes de crear otra.»
Revocar una clave en desuso o pasar a un plan con más claves.
«El plan no incluye la API pública.» / «El plan no incluye claves de API.»
El plan actual no contempla la API. Cambiar de plan desde la suscripción.
«Marcar al menos un permiso: una clave sin permisos no puede hacer nada.»
Marcar al menos un permiso en el Candado 1.
«Ninguno de los permisos marcados está incluido en el plan.»
Marcar permisos sin la etiqueta No incluido en el plan.
«Una clave de producción accede a los datos fiscales de los clientes desde fuera del panel. Explicar en una línea para qué se va a usar: …»
Completar Para qué se va a usar con un mínimo de 20 caracteres.
«Una clave de producción nace con un máximo de 25 clientes autorizados, y hay marcados {n}. …»
Marcar 25 o menos y ampliar el techo después, cuando la integración ya haya hecho su primera llamada.
La clave muestra Clientes: «No lee nada»
No hay ningún cliente autorizado. Marcarlos con Clientes en la ficha de la clave.
La clave muestra Plan: «Fuera»
Hay más claves activas que las que admite el plan. La API rechaza las más recientes hasta revocar alguna.

Continuar con

Consejo
Crear una clave por integración permite revocar la de un proveedor sin dejar sin servicio a las demás.
Anterior Activar el buzón de correo de un cliente Siguiente Cambiar los permisos y los clientes de una clave de API

Prueba CopilotGestoria gratis

30 días gratis. Sube tu primera factura en 2 minutos.

Crear cuenta gratis