Facturación electrónica por HTTP

Una llamada con una llave de API produce un documento tributario electrónico firmado y sellado por el Ministerio de Hacienda. Usted describe la venta —quién compra, qué lleva y cuánto cuesta cada cosa—; el servidor se encarga de lo fiscal: el correlativo, los totales, el IVA, el monto en letras, la firma y la transmisión.

Estos son los documentos que la API emite hoy: factura (01), crédito fiscal (03), nota de crédito (05), nota de débito (06), exportación (11) y sujeto excluido (14). Todos por la misma ruta y con el mismo cuerpo; lo que cambia es el tipoDte y lo que ese tipo exige.

Tres formas de integrar

Las tres hablan con la misma URL y con las mismas cabeceras. Elija por el lenguaje que ya tiene, no por la que parezca más seria.

Su primera llamada

Hay una sola URL. La llave decide el ambiente: una que empieza con facta_test_ emite en pruebas contra el ambiente 00 del Ministerio, y una facta_live_ emite documentos fiscales reales en el 01. No hay una segunda URL para pruebas.

/v1/status es lo primero que conviene llamar: confirma que la llave sirve, dice para qué empresa emite, en qué ambiente y cuánto cupo le queda. No pide el segundo factor de firma y no exige ningún alcance.

curl https://hcnvknpsbadplnfcflxx.supabase.co/functions/v1/api-v1/v1/status \
  -H "X-Facta-Key: $FACTA_API_KEY"

Y esto es lo que contesta

{
  "ok": true,
  "version": "v1",
  "ambiente": "00",
  "emisor": {
    "nit": "06142803901121",
    "nombre": "MI EMPRESA, S.A. DE C.V.",
    "ambiente": "00"
  },
  "llave": {
    "keyId": "k_7f3a9c21",
    "label": "Caja 1 — punto de venta",
    "modo": "custodian",
    "alcances": ["issue", "query", "download"],
    "tiposDte": ["01", "03"],
    "venceEl": null
  },
  "firma": {
    "vaultDeFirma": true,
    "origenDeLaFirma": "vault",
    "cabecera": "x-facta-sign-key"
  },
  "limites": {
    "hora": { "limit": 60, "used": 3, "remaining": 57 },
    "dia": { "limit": 300, "used": 41, "remaining": 259 },
    "estado": { "limit": 240, "used": 1, "remaining": 239 },
    "montoMaximoPorDocumentoCentavos": 5000000
  }
}

Quién hace qué

Lo hace el servidor:

• El correlativo, reservado en una transacción, con su registro de huecos.
• Los totales, el IVA, las retenciones y el monto en letras.
• La validación contra el esquema oficial del Ministerio.
• La firma JWS RS512 con el certificado de la empresa emisora.
• La transmisión a Hacienda, y la contingencia cuando Hacienda no contesta.
• La representación gráfica en PDF, con el sello y el código QR.

Lo hace su sistema:

• Describir la venta: el tipo de documento, el receptor y las líneas.
• Elegir una Idempotency-Key por operación y reusarla en cada reintento.
• Guardar el jws que vuelve en la respuesta. Ese es el artefacto fiscal.
• Distinguir un rechazo de Hacienda de una caída, que no se arreglan igual.

Qué está publicado hoy

El detalle de cada fila, con lo que falta y por qué, está en Estado de publicación.

Por dónde seguir

De la cuenta a la primera factura de pruebas en Empezar, cada ruta con sus cabeceras y respuestas en la Referencia HTTP, y los casos que dan más dudas en las Guías. Si trabaja con un agente de código, la skill para agentes de IA le enseña a integrar la API sin adivinar.