Una llave de procesar por cada empresa | Desarrolladores

Quién paga y qué empresa se analiza

En la API hay dos papeles, y pueden ser la misma empresa o no:

Quien paga: la empresa (o la gestoría) que compra el plan. Tiene la pool (el saldo de procesos del mes) y la llave de administrar.
La empresa cuyas facturas se analizan: cada llave de procesar es de una empresa, con su NIF y su nombre o razón social, los dos obligatorios. Con ellos el motor reconoce qué parte de cada factura es esa empresa.

🗂️

Una gestoría con varios clientes

Crea una llave de procesar por cliente, cada una con el NIF y el nombre de ese cliente. Todas descuentan de la misma pool.

🏠

Una empresa que lleva lo suyo

Crea una sola llave de procesar, con su propio NIF y su nombre.

Todas las operaciones de esta guía piden la llave de administrar (la de la guía anterior).

Crea la llave de procesar: NIF y nombre

POST /v1/llaves con el NIF (cif) y el nombre (nombre) de la empresa:

curl -sS https://api.munincloud.com/v1/llaves \
  -H "Authorization: Bearer $MC_LLAVE_ADMINISTRAR" \
  -H "Content-Type: application/json" \
  -d '{"cif": "B00000018", "nombre": "TEST SL"}'

cif: el NIF de la empresa cuyas facturas subirá esta llave, sin espacios ni guiones (9 caracteres, letras y números). Se comprueba su forma; la AEAT, no.
nombre: el nombre o razón social, como aparece en sus facturas (p. ej. TEST SL). De 1 a 100 caracteres, sin saltos de línea ni tabuladores, sin caracteres invisibles de formato y sin espacios al principio ni al final.

Si el nombre lleva comillas o tildes, que el JSON lo escriba un programa y no tú a mano. El arranque rápido lo hace con python3:

python3 -c 'import json,os; print(json.dumps({"cif": os.environ["MC_NIF"], "nombre": os.environ["MC_NOMBRE"]}))' > llave_nueva.json

La respuesta es un 201 con la llave completa en llave (el secreto de este ejemplo es ilustrativo):

{
  "id": "k7Q2mX9pL4sA",
  "tipo": "procesar",
  "cif": "B00000018",
  "nombre": "TEST SL",
  "ips_permitidas": ["203.0.113.10"],
  "creada": "2026-10-02T09:05:00Z",
  "anulada": null,
  "ultimo_uso": null,
  "llave": "mc_live_k7Q2mX9pL4sA_EJEMPLOxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

La llave completa se devuelve una sola vez, en esta respuesta: guárdala. El id (los 12 caracteres tras mc_live_) es su nombre público: es el que usarás para limitarla o anularla.

⚠️

El NIF y el nombre no se cambian

Se fijan al crear la llave. Para otra empresa, otra llave.

Si la petición está mal formada, la respuesta es un 422:

{
  "error": {
    "codigo": "PETICION_NO_VALIDA",
    "mensaje": "El campo «cif» no tiene forma de NIF (9 caracteres, letras y números)."
  }
}

Y una pool cerrada no emite llaves: 402 con POOL_CERRADA.

Limítala a unas IP (si quieres)

Puedes dar la lista al crearla (ips_permitidas en el mismo POST /v1/llaves) o cambiarla después con PATCH /v1/llaves/{llave}, usando el id público, no la llave entera:

curl -sS -X PATCH https://api.munincloud.com/v1/llaves/k7Q2mX9pL4sA \
  -H "Authorization: Bearer $MC_LLAVE_ADMINISTRAR" \
  -H "Content-Type: application/json" \
  -d '{"ips_permitidas": ["203.0.113.10"]}'

Cada elemento es una IPv4/IPv6 o un rango CIDR (198.51.100.0/24), hasta 20. Lista vacía = sin límite. Vale para las de procesar y para la propia de administrar. Desde una IP que no está en la lista, la llave contesta 401 con IP_NO_PERMITIDA.

Lista las llaves de la pool

GET /v1/llaves devuelve todas, vivas y anuladas. Nunca el secreto.

curl -sS https://api.munincloud.com/v1/llaves \
  -H "Authorization: Bearer $MC_LLAVE_ADMINISTRAR"

{
  "llaves": [
    {"id": "a1B2c3D4e5F6", "tipo": "administrar", "cif": null, "nombre": null, "ips_permitidas": [], "creada": "2026-10-02T09:00:00Z", "anulada": null, "ultimo_uso": "2026-10-02T16:00:00Z"},
    {"id": "k7Q2mX9pL4sA", "tipo": "procesar", "cif": "B00000018", "nombre": "TEST SL", "ips_permitidas": ["203.0.113.10"], "creada": "2026-10-02T09:05:00Z", "anulada": null, "ultimo_uso": "2026-10-02T16:18:24Z"}
  ]
}

ultimo_uso te dice si una llave se sigue usando antes de anularla.

Anula la que ya no sirva

DELETE /v1/llaves/{llave} anula una llave de procesar. Es definitivo: desde ese momento contesta LLAVE_ANULADA. Las demás llaves siguen funcionando.

curl -sS -X DELETE https://api.munincloud.com/v1/llaves/k7Q2mX9pL4sA \
  -H "Authorization: Bearer $MC_LLAVE_ADMINISTRAR"

La respuesta es la llave, con la fecha en anulada.

✅

Cambiar una llave sin corte

Crea la nueva, ponla en tu programa, comprueba que entra y anula la vieja.

Lo siguiente

Con una llave de procesar ya puedes subir facturas de esa empresa: Subir una factura y recoger el resultado.