Subir una factura y recoger el resultado

POST /v1/trabajos, en multipart/form-data, con la llave de procesar, el tipo y el fichero en factura:

curl -sS https://api.munincloud.com/v1/trabajos \
  -H "Authorization: Bearer $MC_LLAVE_PROCESAR" \
  -H "Idempotency-Key: 7f6c1b0e-factura-0001" \
  -F "tipo=compra" \
  -F "factura=@factura.pdf;type=application/pdf"

La API contesta enseguida con un 202 y un número de trabajo:

{
  "trabajo": "trb_01J9ZQ3K4T7W2B5N8C6D0F1G2H",
  "estado": "en_curso",
  "creado": "2026-10-02T16:18:24Z",
  "pool": {"estado": "activa", "disponibles": 2412, "aviso_80": false}
}

Con las cabeceras Location (la URL del trabajo), Retry-After (los segundos que conviene esperar antes de preguntar) y X-Pool-Disponibles / X-Pool-Estado (lo que le queda a la pool).

El proceso es asíncrono: tarda de segundos a unos minutos. GET /v1/trabajos/{trabajo} devuelve el trabajo siempre con 200 mientras exista, en uno de tres estados:

• en_curso: vuelve a preguntar tras los segundos de Retry-After;
• terminado: documento trae la factura auditada v1, con sus avisos;
• rechazado: error dice por qué.

El bucle del arranque rápido, con curl:

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

Y con Python, que además espera ante un 429 o un 503:

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

campo, $API, sesion y API son los del paso 0 de cada guion: los dos enteros están en la documentación.

Un trabajo terminado trae el documento v1: cómo leerlo lo cuenta la guía siguiente. Un trabajo rechazado trae el error, y no descuenta de la pool:

{
  "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}
}

En NO_ES_FACTURA, error.tipo_detectado dice qué se reconoció (TICKET, NOMINA, ONBOARDING o bancos), o null si no se sabe.