API de Timbrado CFDI 4.0

curl -X POST https://v2.facter.com.mx/api/ext/v1/cfdis \
  -H "Authorization: Bearer fct_live_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"emisor_rfc":"EKU9003173C9","external_ref":"REF-FAC-000123","fecha_emision":null,"cfdi":{"Version":"4.0","Serie":"A","Folio":"123","FormaPago":"01","MetodoPago":"PUE","CondicionesDePago":null,"SubTotal":"1000.00","Descuento":null,"Moneda":"MXN","Total":"1160.00","TipoDeComprobante":"I","Exportacion":"01","LugarExpedicion":"64000","Emisor":{"Rfc":"EKU9003173C9","Nombre":"ESCUELA KEMPER URGATE","RegimenFiscal":"601"},"Receptor":{"Rfc":"XAXX010101000","Nombre":"PUBLICO EN GENERAL","DomicilioFiscalReceptor":"64000","RegimenFiscalReceptor":"616","UsoCFDI":"S01"},"Conceptos":[{"ClaveProdServ":"01010101","NoIdentificacion":"SKU-01","Cantidad":"1.000000","ClaveUnidad":"H87","Unidad":"Pieza","Descripcion":"Producto de prueba","ValorUnitario":"1000.00","Importe":"1000.00","Descuento":null,"ObjetoImp":"02","Impuestos":{"Traslados":[{"Base":"1000.00","Impuesto":"002","TipoFactor":"Tasa","TasaOCuota":"0.160000","Importe":"160.00"}],"Retenciones":[]}}],"Impuestos":{"TotalImpuestosTrasladados":"160.00","Traslados":[{"Base":"1000.00","Impuesto":"002","TipoFactor":"Tasa","TasaOCuota":"0.160000","Importe":"160.00"}]},"CfdiRelacionados":null,"Complemento":null,"InformacionGlobal":null}}'

<?php
$payload = {
    "emisor_rfc": "EKU9003173C9",
    "external_ref": "REF-FAC-000123",
    "fecha_emision": null,
    "cfdi": {
        "Version": "4.0",
        "Serie": "A",
        "Folio": "123",
        "FormaPago": "01",
        "MetodoPago": "PUE",
        "CondicionesDePago": null,
        "SubTotal": "1000.00",
        "Descuento": null,
        "Moneda": "MXN",
        "Total": "1160.00",
        "TipoDeComprobante": "I",
        "Exportacion": "01",
        "LugarExpedicion": "64000",
        "Emisor": {
            "Rfc": "EKU9003173C9",
            "Nombre": "ESCUELA KEMPER URGATE",
            "RegimenFiscal": "601"
        },
        "Receptor": {
            "Rfc": "XAXX010101000",
            "Nombre": "PUBLICO EN GENERAL",
            "DomicilioFiscalReceptor": "64000",
            "RegimenFiscalReceptor": "616",
            "UsoCFDI": "S01"
        },
        "Conceptos": [
            {
                "ClaveProdServ": "01010101",
                "NoIdentificacion": "SKU-01",
                "Cantidad": "1.000000",
                "ClaveUnidad": "H87",
                "Unidad": "Pieza",
                "Descripcion": "Producto de prueba",
                "ValorUnitario": "1000.00",
                "Importe": "1000.00",
                "Descuento": null,
                "ObjetoImp": "02",
                "Impuestos": {
                    "Traslados": [
                        {
                            "Base": "1000.00",
                            "Impuesto": "002",
                            "TipoFactor": "Tasa",
                            "TasaOCuota": "0.160000",
                            "Importe": "160.00"
                        }
                    ],
                    "Retenciones": []
                }
            }
        ],
        "Impuestos": {
            "TotalImpuestosTrasladados": "160.00",
            "Traslados": [
                {
                    "Base": "1000.00",
                    "Impuesto": "002",
                    "TipoFactor": "Tasa",
                    "TasaOCuota": "0.160000",
                    "Importe": "160.00"
                }
            ]
        },
        "CfdiRelacionados": null,
        "Complemento": null,
        "InformacionGlobal": null
    }
};

$ch = curl_init("https://v2.facter.com.mx/api/ext/v1/cfdis");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("FACTER_API_KEY"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$reqId  = null;
curl_close($ch);

$res = json_decode($body, true);
if ($status === 201) {
    echo "Timbrado UUID: " . $res["data"]["uuid"] . PHP_EOL;
} else {
    // NUNCA reintentes un 422 (validación). Sí reintenta timeouts/5xx con la MISMA key.
    echo "Error {$res['code']}: {$res['message']}" . PHP_EOL;
}

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("FACTER_API_KEY"));

var json = """
{
    "emisor_rfc": "EKU9003173C9",
    "external_ref": "REF-FAC-000123",
    "fecha_emision": null,
    "cfdi": {
        "Version": "4.0",
        "Serie": "A",
        "Folio": "123",
        "FormaPago": "01",
        "MetodoPago": "PUE",
        "CondicionesDePago": null,
        "SubTotal": "1000.00",
        "Descuento": null,
        "Moneda": "MXN",
        "Total": "1160.00",
        "TipoDeComprobante": "I",
        "Exportacion": "01",
        "LugarExpedicion": "64000",
        "Emisor": {
            "Rfc": "EKU9003173C9",
            "Nombre": "ESCUELA KEMPER URGATE",
            "RegimenFiscal": "601"
        },
        "Receptor": {
            "Rfc": "XAXX010101000",
            "Nombre": "PUBLICO EN GENERAL",
            "DomicilioFiscalReceptor": "64000",
            "RegimenFiscalReceptor": "616",
            "UsoCFDI": "S01"
        },
        "Conceptos": [
            {
                "ClaveProdServ": "01010101",
                "NoIdentificacion": "SKU-01",
                "Cantidad": "1.000000",
                "ClaveUnidad": "H87",
                "Unidad": "Pieza",
                "Descripcion": "Producto de prueba",
                "ValorUnitario": "1000.00",
                "Importe": "1000.00",
                "Descuento": null,
                "ObjetoImp": "02",
                "Impuestos": {
                    "Traslados": [
                        {
                            "Base": "1000.00",
                            "Impuesto": "002",
                            "TipoFactor": "Tasa",
                            "TasaOCuota": "0.160000",
                            "Importe": "160.00"
                        }
                    ],
                    "Retenciones": []
                }
            }
        ],
        "Impuestos": {
            "TotalImpuestosTrasladados": "160.00",
            "Traslados": [
                {
                    "Base": "1000.00",
                    "Impuesto": "002",
                    "TipoFactor": "Tasa",
                    "TasaOCuota": "0.160000",
                    "Importe": "160.00"
                }
            ]
        },
        "CfdiRelacionados": null,
        "Complemento": null,
        "InformacionGlobal": null
    }
}
""";

var req = new HttpRequestMessage(HttpMethod.Post, "https://v2.facter.com.mx/api/ext/v1/cfdis");
req.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
req.Content = new StringContent(json, Encoding.UTF8, "application/json");

var res  = await http.SendAsync(req);
var body = await res.Content.ReadAsStringAsync();

if ((int)res.StatusCode == 201)
    Console.WriteLine("Timbrado: " + body);
else
    // No reintentes 4xx; sí timeout/5xx con la MISMA key.
    Console.Error.WriteLine($"Error {(int)res.StatusCode}: {body}");

import { randomUUID } from "node:crypto";

const payload = {"emisor_rfc":"EKU9003173C9","external_ref":"REF-FAC-000123","fecha_emision":null,"cfdi":{"Version":"4.0","Serie":"A","Folio":"123","FormaPago":"01","MetodoPago":"PUE","CondicionesDePago":null,"SubTotal":"1000.00","Descuento":null,"Moneda":"MXN","Total":"1160.00","TipoDeComprobante":"I","Exportacion":"01","LugarExpedicion":"64000","Emisor":{"Rfc":"EKU9003173C9","Nombre":"ESCUELA KEMPER URGATE","RegimenFiscal":"601"},"Receptor":{"Rfc":"XAXX010101000","Nombre":"PUBLICO EN GENERAL","DomicilioFiscalReceptor":"64000","RegimenFiscalReceptor":"616","UsoCFDI":"S01"},"Conceptos":[{"ClaveProdServ":"01010101","NoIdentificacion":"SKU-01","Cantidad":"1.000000","ClaveUnidad":"H87","Unidad":"Pieza","Descripcion":"Producto de prueba","ValorUnitario":"1000.00","Importe":"1000.00","Descuento":null,"ObjetoImp":"02","Impuestos":{"Traslados":[{"Base":"1000.00","Impuesto":"002","TipoFactor":"Tasa","TasaOCuota":"0.160000","Importe":"160.00"}],"Retenciones":[]}}],"Impuestos":{"TotalImpuestosTrasladados":"160.00","Traslados":[{"Base":"1000.00","Impuesto":"002","TipoFactor":"Tasa","TasaOCuota":"0.160000","Importe":"160.00"}]},"CfdiRelacionados":null,"Complemento":null,"InformacionGlobal":null}};

const res = await fetch("https://v2.facter.com.mx/api/ext/v1/cfdis", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.FACTER_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const data = await res.json();
if (res.status === 201) {
  console.log("Timbrado UUID:", data.data.uuid);
} else {
  // No reintentes 4xx; sí reintenta timeout/5xx con la MISMA Idempotency-Key.
  console.error(`Error ${data.code}: ${data.message}`);
}

curl -X POST https://v2.facter.com.mx/api/ext/v1/cfdis/validate \
  -H "Authorization: Bearer fct_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"emisor_rfc":"EKU9003173C9","external_ref":"REF-FAC-000123","fecha_emision":null,"cfdi":{"Version":"4.0","Serie":"A","Folio":"123","FormaPago":"01","MetodoPago":"PUE","CondicionesDePago":null,"SubTotal":"1000.00","Descuento":null,"Moneda":"MXN","Total":"1160.00","TipoDeComprobante":"I","Exportacion":"01","LugarExpedicion":"64000","Emisor":{"Rfc":"EKU9003173C9","Nombre":"ESCUELA KEMPER URGATE","RegimenFiscal":"601"},"Receptor":{"Rfc":"XAXX010101000","Nombre":"PUBLICO EN GENERAL","DomicilioFiscalReceptor":"64000","RegimenFiscalReceptor":"616","UsoCFDI":"S01"},"Conceptos":[{"ClaveProdServ":"01010101","NoIdentificacion":"SKU-01","Cantidad":"1.000000","ClaveUnidad":"H87","Unidad":"Pieza","Descripcion":"Producto de prueba","ValorUnitario":"1000.00","Importe":"1000.00","Descuento":null,"ObjetoImp":"02","Impuestos":{"Traslados":[{"Base":"1000.00","Impuesto":"002","TipoFactor":"Tasa","TasaOCuota":"0.160000","Importe":"160.00"}],"Retenciones":[]}}],"Impuestos":{"TotalImpuestosTrasladados":"160.00","Traslados":[{"Base":"1000.00","Impuesto":"002","TipoFactor":"Tasa","TasaOCuota":"0.160000","Importe":"160.00"}]},"CfdiRelacionados":null,"Complemento":null,"InformacionGlobal":null}}'

<?php
// Verificación de firma del webhook (HMAC-SHA256, comparación en tiempo constante).
$raw    = file_get_contents("php://input");
$header = $_SERVER["HTTP_X_FACTER_SIGNATURE"] ?? "";      // "sha256=...."
$secret = getenv("FACTER_WEBHOOK_SECRET");

$expected = "sha256=" . hash_hmac("sha256", $raw, $secret);

if (!hash_equals($expected, $header)) {
    http_response_code(401);
    exit("firma inválida");
}

$event = json_decode($raw, true);
// Idempotencia: deduplica por $event["data"]["uuid"] + $event["event"].
http_response_code(200);   // responde 2xx rápido; procesa en segundo plano.

using System.Security.Cryptography;
using System.Text;

// En tu endpoint, lee el cuerpo CRUDO (no deserializado) para el HMAC.
string raw    = await new StreamReader(Request.Body).ReadToEndAsync();
string header = Request.Headers["X-Facter-Signature"]; // "sha256=...."
string secret = Environment.GetEnvironmentVariable("FACTER_WEBHOOK_SECRET")!;

using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
string expected = "sha256=" +
    Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(raw))).ToLowerInvariant();

bool ok = CryptographicOperations.FixedTimeEquals(
    Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(header));
if (!ok) return Unauthorized("firma inválida");
// Deduplica por data.uuid + event. Responde 200 rápido.

import crypto from "node:crypto";
import express from "express";

const app = express();
// Necesitas el cuerpo CRUDO para el HMAC:
app.use("/facter/webhook", express.raw({ type: "*/*" }));

app.post("/facter/webhook", (req, res) => {
  const sig = req.get("X-Facter-Signature") || "";
  const expected = "sha256=" +
    crypto.createHmac("sha256", process.env.FACTER_WEBHOOK_SECRET)
          .update(req.body)           // Buffer crudo
          .digest("hex");

  const ok = sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) return res.status(401).send("firma inválida");

  const event = JSON.parse(req.body.toString("utf8"));
  // Deduplica por event.data.uuid + event.event.
  res.sendStatus(200);
});

# El webhook llega como POST a tu URL con el header:
#   X-Facter-Signature: sha256=<hmac>
# Verifica recomputando el HMAC del cuerpo CRUDO con tu webhook_secret.

import { randomUUID } from "node:crypto";

// Genera la Idempotency-Key UNA vez por intento lógico de timbrado.
// Reintenta SOLO ante timeout / 5xx, SIEMPRE con la misma key.
async function stampWithRetry(payload, apiKey, maxRetries = 4) {
  const key = randomUUID();
  let delay = 1000;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const res = await fetch("https://v2.facter.com.mx/api/ext/v1/cfdis", {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Idempotency-Key": key,         // ← MISMA key en cada reintento
          "Content-Type": "application/json",
        },
        body: JSON.stringify(payload),
      });

      if (res.status < 500) return res;   // 2xx/4xx → resultado definitivo, NO reintentar
    } catch (_) { /* error de red → reintentar */ }

    await new Promise(r => setTimeout(r, delay));
    delay *= 2;                           // backoff exponencial
  }
  throw new Error("timbrado no confirmado tras reintentos");
}