WooCommerce: de la comanda pagada a la factura emesa

<?php
/**
 * Plugin Name: Cairos para WooCommerce
 */

define("CAIROS_BASE", "https://erp.cairos.es/api/v1");

function cairos_llamar($ruta, $cuerpo = null, $llave = null) {
    $cabeceras = [
        "Authorization" => "Bearer " . getenv("CAIROS_CLAVE"),
        "Content-Type"  => "application/json",
    ];
    if ($llave) {
        $cabeceras["Idempotency-Key"] = $llave;
    }

    $r = wp_remote_post(CAIROS_BASE . $ruta, [
        "headers" => $cabeceras,
        "body"    => $cuerpo ? wp_json_encode($cuerpo) : null,
        "timeout" => 20,
    ]);

    if (is_wp_error($r)) {
        throw new Exception($r->get_error_message());
    }

    $estado = wp_remote_retrieve_response_code($r);
    $datos  = json_decode(wp_remote_retrieve_body($r), true);

    if ($estado >= 400) {
        $codigo = $datos["error"]["codigo"] ?? "desconocido";
        throw new Exception("Cairos " . $estado . ": " . $codigo);
    }

    return $datos;
}

add_action("woocommerce_payment_complete", "cairos_facturar_pedido");

function cairos_facturar_pedido($id_pedido) {
    $pedido = wc_get_order($id_pedido);

    // 1 · Si ya lo facturamos, no hay nada que hacer. Esta línea
    //     vale más que todo el resto del fichero.
    if ($pedido->get_meta("_cairos_factura_id")) {
        return;
    }

    $llave = "wc-" . $id_pedido;

    try {
        // 2 · Contacto. El NIF sale del campo que añadiste al
        //     proceso de compra.
        $contacto = cairos_llamar("/contactos/upsert", [
            "nombre"     => trim($pedido->get_billing_company()
                ?: $pedido->get_formatted_billing_full_name()),
            "nif"        => $pedido->get_meta("_billing_nif"),
            "email"      => $pedido->get_billing_email(),
            // "customer" o "supplier": el enumerado esta en
            // ingles y un "cliente" devuelve 422.
            "tipo"       => "customer",
            "buscar_por" => "email",
        ], $llave . "-contacto");

        // 3 · Líneas. get_subtotal() es SIN impuestos, que es lo
        //     que espera la API por defecto. El campo del texto
        //     es "descripcion" y el del impuesto "tipo_iva":
        //     "concepto" e "iva" no existen y dan 422.
        $lineas = [];
        foreach ($pedido->get_items() as $item) {
            $cantidad = $item->get_quantity();
            $lineas[] = [
                "descripcion" => $item->get_name(),
                "cantidad"    => $cantidad,
                "precio"      => round($item->get_subtotal() / max(1, $cantidad), 2),
                "tipo_iva"    => 21,
            ];
        }

        // 4 · Borrador. La fecha es "fecha_emision".
        $factura = cairos_llamar("/facturas", [
            "contacto_id"   => $contacto["id"],
            "serie"         => "WEB",
            "fecha_emision" => $pedido->get_date_paid()->date("Y-m-d"),
            "lineas"        => $lineas,
        ], $llave);

        // 5 · Guardamos ANTES de emitir. Si algo falla después,
        //     al menos sabemos que este pedido ya tiene factura.
        $pedido->update_meta_data("_cairos_factura_id", $factura["id"]);
        $pedido->save();

        // 6 · Emitir: aquí es donde toma número de serie.
        $emitida = cairos_llamar(
            "/facturas/" . $factura["id"] . "/emitir",
            null,
            $llave . "-emitir"
        );

        // 7 · Y el cobro, que en una tienda ya ha ocurrido.
        //     "metodo" es un enumerado cerrado: transfer, cash,
        //     card, direct_debit u other. El nombre bonito de la
        //     pasarela va en "notas", que es texto libre.
        cairos_llamar("/cobros", [
            "factura_id" => $factura["id"],
            "fecha"      => $pedido->get_date_paid()->date("Y-m-d"),
            "importe"    => (float) $pedido->get_total(),
            "metodo"     => "card",
            "notas"      => $pedido->get_payment_method_title(),
        ], $llave . "-cobro");

        // "referencia" es lo que sale impreso ("WEB-0042").
        // "numero" es un entero y por si solo no dice la serie.
        $pedido->update_meta_data("_cairos_factura_ref", $emitida["referencia"]);
        $pedido->add_order_note("Factura " . $emitida["referencia"]);
        $pedido->save();

    } catch (Exception $e) {
        // Ni una excepción sin registrar: un fallo silencioso aquí
        // se descubre en el cierre del trimestre.
        $pedido->add_order_note("Cairos: " . $e->getMessage());
        error_log("Cairos: " . $e->getMessage());
    }
}