API de auditoría de facturas de MuninCloud

Cómo funciona

Cómo se usa, en cuatro pasos

1. Tras la compra recibes un enlace de recogida de un solo uso. Al abrirlo generas tu llave de administrar (mc_live_…), que se ve una vez. Nunca te la mandaremos por correo.
2. Con la llave de administrar creas una llave de procesar por cada empresa cuyas facturas vayas a enviar (POST /v1/llaves), indicando su NIF y su nombre o razón social (los dos obligatorios: con ellos el motor reconoce qué parte de la factura es tu empresa). Puedes limitar cada llave a unas IP.
3. Con una llave de procesar subes facturas (POST /v1/trabajos), diciendo en cada una si es una compra o una venta de esa empresa, y recibes un número de trabajo. El proceso es asíncrono: tarda de segundos a unos minutos.
4. Consultas el trabajo (GET /v1/trabajos/{trabajo}) hasta que esté terminado (con su documento v1) o rechazado (con su error). Respeta la cabecera Retry-After entre consultas.

Qué entra. Solo facturas, recibidas o emitidas: un PDF, JPEG o PNG de hasta 15 MB. Se leen como mucho 5 páginas. Un documento con varias facturas se rechaza (MULTIFACTURA): un proceso es una factura. Lo que no es una factura (un ticket, una nómina, un extracto, un acta…) se rechaza (NO_ES_FACTURA). Al subirla dices si es una compra (la empresa de la llave la recibe) o una venta (la emite): la factura se lee así y la respuesta lo repite en documento.direccion (RECIBIDA o EMITIDA). Si en el papel la empresa aparece en el lado contrario, se lee igual como dijiste y el documento lleva el aviso TIPO_DISCREPANTE.

Qué se cobra. Cada factura que se entrega terminada descuenta un proceso de tu pool. Un trabajo rechazado o fallido no descuenta.

Qué guardamos. Nada de la factura. El resultado se conserva 24 horas desde que termina, para que lo recojas; después, el trabajo ya no existe (NO_ENCONTRADO).

El documento v1 está descrito en respuesta.schema.json. Regla de v1: se pueden añadir campos, nunca quitarlos ni renombrarlos. Tu programa debe ignorar los campos que no conozca y tratar un código de aviso que no conozca como «revise el documento».

Los errores siempre llevan un codigo estable (el que debe mirar tu programa) y un mensaje para personas. Esta API no usa los códigos HTTP 400, 403 ni 404: una ráfaga de ellos hace que el cortafuegos de entrada bloquee tu IP durante horas. Los fallos de llave son 401; los de la pool, 402; los de ritmo, 429; los del documento, 413, 415 o 422; y si el motor de lectura no está disponible en ese momento, 503 con Retry-After (al subir y al consultar). La documentación trae la tabla de todos los errores, con un ejemplo de cada uno.

Cómo conseguir acceso

Acceso bajo solicitud

La API se activa con alta previa: escríbenos y te preparamos el acceso.

Escríbenos

Con el acceso preparado, el ciclo empieza por la recogida de tu llave: lo cuenta Las llaves.

Arranque rápido

Con curl

El guion entero: inicio_rapido.sh. Se lanza con MC_VALE=… MC_NIF=… MC_NOMBRE="…" MC_TIPO=compra bash inicio_rapido.sh factura.pdf: el NIF y el nombre son los de la empresa cuyas facturas vas a enviar, y MC_TIPO dice si esa factura es una compra o una venta de esa empresa (ver Las llaves).

Paso 0 · lo que usan los pasos: la dirección de la API, la factura, compra o venta, y un lector de JSON

API="${MC_API:-https://api.munincloud.com}"
FACTURA="${1:?uso: MC_VALE=… MC_NIF=… MC_NOMBRE=… MC_TIPO=compra|venta bash inicio_rapido.sh factura.pdf}"
TIPO="${MC_TIPO:?pon en MC_TIPO compra (la empresa recibe la factura) o venta (la emite)}"
case "$TIPO" in compra|venta) ;; *) echo "MC_TIPO tiene que ser compra o venta, no «$TIPO»" >&2; exit 2 ;; esac
campo() { python3 -c 'import json,sys; print(json.load(sys.stdin)[sys.argv[1]])' "$1"; }
umask 077   # los ficheros de las llaves nacen legibles solo por ti

Paso 1 · canjear el vale por la llave de administrar (una sola vez)

# El vale es lo que va detrás de «#vale=» en el enlace que recibes tras la compra. Sirve UNA vez.
curl -sS -X POST "$API/v1/recogida" \
  -H "Content-Type: application/json" \
  -d "{\"vale\": \"${MC_VALE:?pon en MC_VALE el vale de tu enlace}\"}" > recogida.json
campo llave < recogida.json > mc_llave_administrar   # sin «&&»: con set -e, un fallo aquí PARA el guion
rm recogida.json

Paso 2 · crear una llave de procesar para la empresa: su NIF y su nombre, los dos obligatorios

# El JSON lo escribe python3 para que un nombre con comillas o tildes vaya bien escrito.
: "${MC_NIF:?pon en MC_NIF el NIF de la empresa}" "${MC_NOMBRE:?pon en MC_NOMBRE el nombre o razón social de la empresa}"
python3 -c 'import json,os; print(json.dumps({"cif": os.environ["MC_NIF"], "nombre": os.environ["MC_NOMBRE"]}))' > llave_nueva.json
curl -sS -X POST "$API/v1/llaves" \
  -H "Authorization: Bearer $(cat mc_llave_administrar)" \
  -H "Content-Type: application/json" \
  -d @llave_nueva.json > llave.json
campo llave < llave.json > mc_llave_procesar
rm llave.json

Paso 3 · subir una factura diciendo si es compra o venta: la API contesta enseguida con un número de trabajo

curl -sS "$API/v1/trabajos" \
  -H "Authorization: Bearer $(cat mc_llave_procesar)" \
  -H "Idempotency-Key: $(basename "$FACTURA")-$TIPO-$(date +%Y%m%d)" \
  -F "tipo=$TIPO" \
  -F "factura=@$FACTURA" | tee trabajo.json
echo
TRABAJO=$(campo trabajo < trabajo.json)

Paso 4 · consultar el trabajo hasta que deje de estar «en_curso», respetando Retry-After

while :; do
  curl -sS -D cabeceras.txt "$API/v1/trabajos/$TRABAJO" \
    -H "Authorization: Bearer $(cat mc_llave_procesar)" > resultado.json
  [ "$(campo estado < resultado.json)" = "en_curso" ] || break
  ESPERA=$(sed -n 's/^[Rr]etry-[Aa]fter: *\([0-9]*\).*/\1/p' cabeceras.txt)
  sleep "${ESPERA:-5}"
done
cat resultado.json; echo

Paso 5 · ver lo que queda en la pool

curl -sS "$API/v1/pool" -H "Authorization: Bearer $(cat mc_llave_procesar)"
echo

Con Python

El guion entero: inicio_rapido.py (pip install requests; MC_LLAVE_PROCESAR=… python3 inicio_rapido.py factura.pdf compra).

Paso 0 · lo que usan los pasos

import json
import os
import sys
import time

import requests

API = os.environ.get("MC_API", "https://api.munincloud.com")


def error_de(r):
    """Los errores siempre traen un `codigo` estable (el que debe mirar tu programa) y un `mensaje` para personas."""
    try:
        return r.json()["error"]["codigo"]
    except (ValueError, KeyError):
        return f"HTTP {r.status_code}"

Paso 1 · la sesión, con la llave de procesar en la cabecera

sesion = requests.Session()
sesion.headers["Authorization"] = "Bearer " + os.environ["MC_LLAVE_PROCESAR"]

Paso 2 · subir la factura, diciendo si es compra o venta

if len(sys.argv) != 3 or sys.argv[2] not in ("compra", "venta"):
    sys.exit("uso: python3 inicio_rapido.py factura.pdf compra|venta")
ruta, tipo = sys.argv[1], sys.argv[2]
with open(ruta, "rb") as fh:
    r = sesion.post(f"{API}/v1/trabajos",
                    headers={"Idempotency-Key": f"{os.path.basename(ruta)}-{tipo}-{time.strftime('%Y%m%d')}"},
                    data={"tipo": tipo}, files={"factura": (os.path.basename(ruta), fh)}, timeout=60)
if r.status_code != 202:
    sys.exit(f"no se pudo subir: {error_de(r)}")
trabajo = r.json()["trabajo"]
print("trabajo:", trabajo)

Paso 3 · consultar hasta que deje de estar «en_curso», respetando Retry-After

while True:
    r = sesion.get(f"{API}/v1/trabajos/{trabajo}", timeout=30)
    if r.status_code in (429, 503) or (r.status_code == 200 and r.json()["estado"] == "en_curso"):
        time.sleep(int(r.headers.get("Retry-After", "5")))
        continue
    break
if r.status_code != 200:
    sys.exit(f"no se pudo consultar: {error_de(r)}")
resultado = r.json()
if resultado["estado"] == "terminado":
    documento = resultado["documento"]
    print(json.dumps(documento["factura"], ensure_ascii=False, indent=2))
    print("dirección:", documento["direccion"])     # RECIBIDA si dijiste compra, EMITIDA si dijiste venta
    print("avisos:", [a["codigo"] for a in documento.get("avisos", [])])
else:
    print("rechazado:", resultado["error"]["codigo"], "-", resultado["error"]["mensaje"])

Paso 4 · lo que queda en la pool

pool = sesion.get(f"{API}/v1/pool", timeout=30).json()
print("disponibles:", pool["disponibles"], "· estado:", pool["estado"])

Las llaves: quién paga, qué empresa se analiza, compra o venta

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 una llave de administrar, que sirve para crear, listar, limitar y anular las llaves de procesar y para ver la pool, pero no para subir facturas.
• 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 crea una llave por cliente; una empresa que se lleva su contabilidad crea una sola, con su propio NIF y nombre. Todas descuentan de la misma pool.

Compra o venta se dice en cada subida (tipo), siempre desde el punto de vista de la empresa de la llave: es una compra si esa empresa recibe la factura (aparece como cliente; un proveedor se la emite) y una venta si la emite (aparece como proveedor). La factura se lee como digas, y el documento lo repite en direccion (RECIBIDA o EMITIDA). Si en el papel la empresa aparece en el lado contrario, se lee igual como dijiste y llega con el aviso TIPO_DISCREPANTE (ver Avisos).

El ciclo de la llave

1. Recogida: tras la compra recibes un enlace de un solo uso (https://api.munincloud.com/v1/recogida#vale=…). Al abrirlo (o con POST /v1/recogida) obtienes la llave de administrar, que se ve una vez. Un vale usado, caducado o inexistente contesta 410 RECOGIDA_NO_VALIDA.
2. Administrar: con ella creas una llave de procesar por empresa (su NIF y su nombre), las listas, las limitas a unas IP y las anulas.
3. Procesar: con una llave de procesar subes facturas, consultas trabajos y ves la pool.

Errores

Cada error lleva un codigo estable, que es el que debe mirar tu programa, y un mensaje para personas. Esta tabla sale tal cual de los ejemplos del contrato (18 casos).

{
 "trabajo": "trb_01J9ZQ3K4T7W2B5N8C6D0F1G2K",
 "estado": "rechazado",
 "creado": "2026-10-02T16:20:00Z",
 "terminado": "2026-10-02T16:20:31Z",
 "error": {
  "codigo": "MULTIFACTURA",
  "mensaje": "El documento contiene más de una factura. Un proceso es una factura: súbalas por separado."
 },
 "pool": {
  "estado": "activa",
  "disponibles": 2412,
  "aviso_80": false
 }
}

{
 "trabajo": "trb_01J9ZQ3K4T7W2B5N8C6D0F1G2J",
 "estado": "rechazado",
 "creado": "2026-10-02T16:18:39Z",
 "terminado": "2026-10-02T16:18:41Z",
 "error": {
  "codigo": "NO_ES_FACTURA",
  "mensaje": "El documento no es una factura (recibida o emitida). Hoy solo se procesan facturas.",
  "tipo_detectado": null
 },
 "pool": {
  "estado": "activa",
  "disponibles": 2412,
  "aviso_80": false
 }
}

{
 "error": {
  "codigo": "IP_NO_PERMITIDA",
  "mensaje": "Esta llave no admite peticiones desde esta IP."
 }
}

{
 "error": {
  "codigo": "LLAVE_ANULADA",
  "mensaje": "Esta llave está anulada. Usa otra llave de la pool o crea una nueva."
 }
}

{
 "error": {
  "codigo": "LLAVE_INVALIDA",
  "mensaje": "Falta la llave o no es válida. Envíala como «Authorization: Bearer mc_live_…»."
 }
}

{
 "error": {
  "codigo": "LLAVE_SIN_PERMISO",
  "mensaje": "Esta llave no sirve para esta ruta (hace falta la de administrar o la de procesar)."
 }
}

{
 "error": {
  "codigo": "POOL_AGOTADA",
  "mensaje": "La pool está parada porque se han agotado el plan del mes y las recargas. Al recargarla, las mismas llaves vuelven a funcionar.",
  "recargar": "https://munincloud.com/api/recargar"
 }
}

{
 "error": {
  "codigo": "POOL_CERRADA",
  "mensaje": "La pool está cerrada y sus llaves anuladas. Hace falta una pool nueva."
 }
}

{
 "error": {
  "codigo": "NO_ENCONTRADO",
  "mensaje": "No existe, no es de esta llave o ya caducó (los resultados se guardan 24 horas)."
 }
}

{
 "error": {
  "codigo": "RECOGIDA_NO_VALIDA",
  "mensaje": "Este enlace ya se ha usado, ha caducado o no existe. Si no recogiste tu llave, escríbenos."
 }
}

{
 "error": {
  "codigo": "DOCUMENTO_NO_VALIDO",
  "mensaje": "El fichero pasa de 15 MB."
 }
}

{
 "error": {
  "codigo": "DOCUMENTO_NO_VALIDO",
  "mensaje": "El fichero no es PDF, JPEG ni PNG."
 }
}

{
 "error": {
  "codigo": "DOCUMENTO_NO_VALIDO",
  "mensaje": "Falta el campo «factura» o el fichero está vacío o roto."
 }
}

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

{
 "error": {
  "codigo": "RITMO_EXCEDIDO",
  "mensaje": "Demasiadas peticiones seguidas. Espera y reintenta.",
  "reintentar_en_s": 5
 }
}

{
 "error": {
  "codigo": "ERROR_INTERNO",
  "mensaje": "No se pudo completar la petición por un fallo nuestro. No se ha descontado nada; puedes reintentar."
 }
}

{
 "error": {
  "codigo": "ERROR_INTERNO",
  "mensaje": "El motor de lectura no está disponible ahora mismo. No se ha descontado nada.",
  "reintentar_en_s": 30
 }
}

{
 "error": {
  "codigo": "ERROR_INTERNO",
  "mensaje": "El resultado no se puede recoger ahora mismo. El trabajo sigue guardado: vuelve a consultarlo en unos segundos.",
  "reintentar_en_s": 30
 }
}

Avisos

Un aviso no rechaza la factura: el trabajo llega terminado, con su documento, y descuenta de la pool como cualquier otro; pero conviene revisarla antes de contabilizarla. Van en documento.avisos, cada uno con su codigo estable y un mensaje. La lista crece: un código que tu programa no conozca, trátalo como «revise el documento». Los de hoy (7):

Referencia

Referencia interactiva (Swagger UI 5.24.2, servido desde este sitio) · openapi.yaml · respuesta.schema.json (el documento v1).

Conectores

Código abierto (licencia MIT) para llevar el documento v1 a tu programa de contabilidad:

• munincloud-conector-csv — el documento v1 a CSV genérico.
• munincloud-conector-a3 — el documento v1 a a3 (Importador de Datos e Importia).
• munincloud-conector-erpnext — el documento v1 a ERPNext (Data Import de facturas de compra y venta).
• munincloud-conector-odoo — el documento v1 a Odoo (importación de facturas en account.move).
• munincloud-conector-contasol — el documento v1 a Contasol (ficheros IVS y APU de facturas recibidas).
• munincloud-conector-sage50 — el documento v1 a Sage 50 (importador de facturas en asientos).
• munincloud-conector-holded — el documento v1 a Holded (plantilla de compras).

a3® es una marca de Wolters Kluwer. MuninCloud no está asociado a, ni certificado por, Wolters Kluwer. a3ASESOR®, a3innuva® e Importia® también son marcas de Wolters Kluwer. ERPNext® es una marca de Frappe Technologies Pvt. Ltd. MuninCloud no está asociado a, ni certificado por, Frappe Technologies Pvt. Ltd. Frappe® también es una marca de Frappe Technologies Pvt. Ltd. Odoo® es una marca de Odoo S.A. MuninCloud no está asociado a, ni certificado por, Odoo S.A. Contasol® es una marca de Software DELSOL. MuninCloud no está asociado a, ni certificado por, Software DELSOL. Sage® es una marca de Sage Global Services Limited o sus licenciantes. MuninCloud no está asociado a, ni certificado por, Sage Global Services Limited o sus licenciantes. Holded® es una marca de Holded. MuninCloud no está asociado a, ni certificado por, Holded.