curl
HTTP directo · para probar, no para producción
La forma más rápida de ver la API funcionar es desde la terminal. Todos los ejemplos de esta documentación tienen una pestaña de curl; esta página junta el flujo completo de emitir en un solo guion, con jq para leer las respuestas.
Requisitos
- curl 7.76 o superior (por
--fail-with-body) y jq 1.6 o superior para leer el JSON. - Una llave de API con el alcance
issue, y su llave de firma. - Un destino de almacenamiento conectado en la app — sin él la emisión se detiene con
422 no_storage_destinationantes de reservar correlativo.
https://hcnvknpsbadplnfcflxx.supabase.co/functions/v1/api-v1Variables de entorno
# Las tres cadenas se muestran UNA sola vez, al acuñar la llave.
FACTA_API_KEY=facta_test_k7f3a9c21.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FACTA_SIGN_KEY=factask_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Esta tercera NO se le pasa a Facta ni al cliente: abre sus credenciales
# de almacenamiento en SU servidor.
FACTA_UNLOCK_KEY=factauk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxRegión de la API
GET /v1/status contesta region (por ejemplo us-west-2): la región de la base de datos de su ambiente. Si envía x-region: <region> en cada petición, la función corre junto a los datos y una Factura tarda cerca de la mitad (4,3 s contra 7,2 s en la medición del 6 de octubre de 2026). Léala una vez, con la misma llave, y reúsela:
FACTA_REGION=$(curl -s -H "X-Facta-Key: $FACTA_API_KEY" "$FACTA_API/v1/status" | jq -r '.region // empty')
# luego, en cada llamada: ${FACTA_REGION:+-H "x-region: $FACTA_REGION"}Si region viene vacía, no envíe la cabecera.
Hacienda bloquea por dirección IP de origen algunas regiones de AWS (responde un 403 HTML en vez de su respuesta normal). Desde el 12 de noviembre de 2026 el servidor fija su propia región: si una petición llega sin x-region y cae en otra región, la reenvía a la configurada antes de hacer nada. Enviar el encabezado sigue siendo lo mejor, porque evita ese salto extra. Si aun así Hacienda rechaza la conexión, la API responde 502 mh_network_blocked con details.servedRegion: las credenciales no son el problema; reintente con x-region.
n8n y otras herramientas sin código
En el nodo HTTP Request de n8n abra Send Headers y agregue x-region con el valor us-west-2 (o la region que devuelva GET /v1/status), junto con X-Facta-Key, X-Facta-Sign-Key e Idempotency-Key. Haga lo mismo en Make, Zapier o Postman.
El guion completo
#!/usr/bin/env bash
# Emitir un DTE contra la API de Facta con curl y jq.
#
# Objetivo: curl 7.76 o superior (por --fail-with-body) y jq 1.6 o superior.
# No hay librería de Facta para shell — esto es HTTP directo, no un cliente
# oficial.
#
# FACTA_API_BASE_URL=https://hcnvknpsbadplnfcflxx.supabase.co/functions/v1/api-v1 \
# FACTA_API_KEY=facta_test_... FACTA_SIGN_KEY=factask_... \
# PEDIDO_ID=pedido-00417 ./emitir.sh
#
# Lo que cubre: estado antes de emitir, una Idempotency-Key que su sistema
# posee (no una al azar por intento), 200 / 202 / 422 distintos, timeout de
# 60 s, lectura de RateLimit-Remaining y descarga del JSON firmado byte a
# byte. Nunca usa FACTA_UNLOCK_KEY — esa cadena abre SU almacenamiento, no
# esta API.
set -euo pipefail
base="${FACTA_API_BASE_URL%/}"
# El identificador de ESTA venta — en un sistema real viene de su propio
# pedido o ticket, persistido antes de la primera llamada, para que un
# reintento use el mismo valor en vez de uno nuevo por intento.
pedido_id="${PEDIDO_ID:-pedido-00417}"
# 1) El estado primero: confirma que la llave sirve y cuánto cupo queda. No
# pide X-Facta-Sign-Key y no gasta el cupo de emitir.
# Supabase ejecuta la función en la región más cercana a quien llama, y
# Hacienda bloquea algunas regiones. El servidor ya reenvía por sí mismo, pero
# enviar x-region en cada llamada evita ese salto extra.
estado_json=$(curl --fail-with-body -sS "$base/v1/status" \
-H "X-Facta-Key: $FACTA_API_KEY")
region=$(echo "$estado_json" | jq -r '.region // empty')
echo "ambiente: $(echo "$estado_json" | jq -r .ambiente) · cupo por hora restante: $(echo "$estado_json" | jq -r .limites.hora.remaining)"
# 2) Emitir. Una factura (01) a consumidor final: el IVA va INCLUIDO en
# precioUni, como exige el esquema oficial de este tipo de documento.
respuesta_archivo=$(mktemp)
cabeceras_archivo=$(mktemp)
trap 'rm -f "$respuesta_archivo" "$cabeceras_archivo"' EXIT
estado_http=$(curl -sS -o "$respuesta_archivo" -D "$cabeceras_archivo" -w '%{http_code}' \
-X POST "$base/v1/dte" \
-H "X-Facta-Key: $FACTA_API_KEY" \
-H "X-Facta-Sign-Key: $FACTA_SIGN_KEY" \
${region:+-H "x-region: $region"} \
-H "Idempotency-Key: $pedido_id" \
-H "Content-Type: application/json" \
--max-time 60 \
-d '{
"tipoDte": "01",
"items": [
{ "descripcion": "Café", "cantidad": 2, "precioUni": 1.5 }
]
}')
echo "cupo restante: $(grep -i '^ratelimit-remaining:' "$cabeceras_archivo" | cut -d' ' -f2 | tr -d '\r')"
cuerpo=$(cat "$respuesta_archivo")
case "$estado_http" in
200)
echo "sellado: $(echo "$cuerpo" | jq -r .numeroControl) $(echo "$cuerpo" | jq -r .selloRecibido)"
;;
202)
# Firmado, sin respuesta del Ministerio todavía. El documento EXISTE y se
# le debe a Hacienda: NO se reintenta esta llamada.
echo "en contingencia: $(echo "$cuerpo" | jq -r .numeroControl) — $(echo "$cuerpo" | jq -r .detalle)"
;;
422)
codigo_error=$(echo "$cuerpo" | jq -r .error.code)
if [ "$codigo_error" = "mh_rejected" ]; then
echo "rechazado: $(echo "$cuerpo" | jq -r .error.message)" >&2
echo "número ya gastado: $(echo "$cuerpo" | jq -r .error.details.numeroControl)" >&2
else
echo "no se pudo emitir: $codigo_error $(echo "$cuerpo" | jq -r .error.message)" >&2
fi
exit 1
;;
*)
echo "error inesperado: $estado_http $cuerpo" >&2
exit 1
;;
esac
# 3) Descargar los bytes EXACTOS del JSON firmado — nunca se vuelven a
# serializar, porque eso no reproduciría los bytes que Hacienda validó.
codigo=$(echo "$cuerpo" | jq -r .codigoGeneracion)
curl --fail-with-body -sS "$base/v1/dte/$codigo/file?kind=json" \
-H "X-Facta-Key: $FACTA_API_KEY" \
${region:+-H "x-region: $region"} \
--max-time 60 \
-o "$codigo.json"
echo "archivado: $codigo.json"
Lo que este guion no hace
Los demás lenguajes
El mismo documento, en un lenguaje de programación de verdad. Cambia la sintaxis; no cambian las cabeceras, ni los códigos, ni las reglas.
JavaScript
// JavaScript puro, sin ninguna librería de Facta. Node 22 o 24; fetch es global.
const base = process.env.FACTA_API_BASE_URL;
const headers = {
"X-Facta-Key": process.env.FACTA_API_KEY,
"X-Facta-Sign-Key": process.env.FACTA_SIGN_KEY,
// Un identificador que USTED elige y REUTILIZA en cada reintento de
// esta misma operación — su número de pedido, su ticket de caja.
"Idempotency-Key": pedidoId,
"Content-Type": "application/json",
};
const controlador = new AbortController();
const plazo = setTimeout(() => controlador.abort(), 60_000);
const respuesta = await fetch(base + "/v1/dte", {
method: "POST",
headers,
body: JSON.stringify({
"tipoDte": "03",
"receptor": {
"customerId": "374114b6-e957-4c7a-8911-dd6381b1e0ea"
},
"items": [
{
"descripcion": "Integración de la API de facturación electrónica",
"cantidad": 1,
"precioUni": 25
}
]
}),
signal: controlador.signal,
}).finally(() => clearTimeout(plazo));
console.log("cupo restante:", respuesta.headers.get("RateLimit-Remaining"));
const cuerpo = await respuesta.json();
if (respuesta.status === 200) {
// Resultado correcto.
console.log(cuerpo);
}
else if (respuesta.status === 202) {
// 202: firmado, sin respuesta del Ministerio todavía. NO lo reintente.
console.log("en contingencia:", cuerpo.numeroControl);
}
else if (cuerpo.error?.code === "mh_rejected") {
console.error("rechazado:", cuerpo.error.message, "· número gastado:", cuerpo.error.details.numeroControl);
}
else {
throw new Error(cuerpo.error?.code ?? String(respuesta.status));
}
Python
import json
import os
import urllib.error
import urllib.request
base = os.environ["FACTA_API_BASE_URL"]
cabeceras = {
"X-Facta-Key": os.environ["FACTA_API_KEY"],
"X-Facta-Sign-Key": os.environ["FACTA_SIGN_KEY"],
"Idempotency-Key": pedido_id, # el mismo en cada reintento de esta operación
"Content-Type": "application/json",
}
peticion = urllib.request.Request(
base + "/v1/dte",
data=json.dumps({
"tipoDte": "03",
"receptor": {
"customerId": "374114b6-e957-4c7a-8911-dd6381b1e0ea"
},
"items": [
{
"descripcion": "Integración de la API de facturación electrónica",
"cantidad": 1,
"precioUni": 25
}
]
}).encode("utf-8"),
method="POST",
headers=cabeceras,
)
try:
# El Ministerio puede tardar unos cuarenta segundos en contestar.
with urllib.request.urlopen(peticion, timeout=60) as respuesta:
print("cupo restante:", respuesta.headers.get("RateLimit-Remaining"))
cuerpo = json.load(respuesta)
if respuesta.status == 200:
print(cuerpo)
elif respuesta.status == 202:
# Firmado, sin respuesta del Ministerio todavía. NO lo reintente.
print("en contingencia:", cuerpo["numeroControl"])
except urllib.error.HTTPError as fallo:
error = json.load(fallo).get("error", {})
if error.get("code") == "mh_rejected":
detalle = error.get("details", {})
print("rechazado:", error.get("message"), "· número gastado:", detalle.get("numeroControl"))
else:
raise
PHP
<?php
// PHP 8 con la extensión cURL. No hay librería de Facta para PHP.
$base = getenv("FACTA_API_BASE_URL");
$cabeceras = [
"X-Facta-Key: " . getenv("FACTA_API_KEY"),
"X-Facta-Sign-Key: " . getenv("FACTA_SIGN_KEY"),
"Idempotency-Key: " . $pedidoId, // el mismo en cada reintento de esta operación
"Content-Type: application/json",
];
$conexion = curl_init($base . "/v1/dte");
$cuerpo = json_encode([
"tipoDte" => "03",
"receptor" => [
"customerId" => "374114b6-e957-4c7a-8911-dd6381b1e0ea",
],
"items" => [
[
"descripcion" => "Integración de la API de facturación electrónica",
"cantidad" => 1,
"precioUni" => 25,
],
],
], JSON_UNESCAPED_UNICODE);
curl_setopt_array($conexion, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => true,
CURLOPT_TIMEOUT => 60,
CURLOPT_HTTPHEADER => $cabeceras,
CURLOPT_POSTFIELDS => $cuerpo,
]);
$crudo = curl_exec($conexion);
$estado = curl_getinfo($conexion, CURLINFO_RESPONSE_CODE);
$tamCabeceras = curl_getinfo($conexion, CURLINFO_HEADER_SIZE);
curl_close($conexion);
$cabecerasRespuesta = substr($crudo, 0, $tamCabeceras);
echo "cupo restante: " . (preg_match("/RateLimit-Remaining: (\d+)/i", $cabecerasRespuesta, $m) ? $m[1] : "?") . "\n";
$datos = json_decode(substr($crudo, $tamCabeceras), true);
if ($estado === 200) {
echo json_encode($datos) . "\n";
}
elseif ($estado === 202) {
// Firmado, sin respuesta del Ministerio todavía. NO lo reintente.
echo "en contingencia: {$datos['numeroControl']}\n";
}
elseif (($datos['error']['code'] ?? null) === 'mh_rejected') {
echo "rechazado: {$datos['error']['message']}\n";
echo "número gastado: {$datos['error']['details']['numeroControl']}\n";
} else {
throw new RuntimeException($datos['error']['code'] ?? "HTTP $estado");
}
C#
// .NET 8 con HttpClient. No hay librería de Facta para C#.
using System.Net.Http.Json;
using System.Text.Json;
var base_ = Environment.GetEnvironmentVariable("FACTA_API_BASE_URL");
using var cliente = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
var peticion = new HttpRequestMessage(HttpMethod.Post, base_ + "/v1/dte");
peticion.Content = JsonContent.Create(new { tipoDte = "03", receptor = new { customerId = "374114b6-e957-4c7a-8911-dd6381b1e0ea" }, items = new[] { new { descripcion = "Integración de la API de facturación electrónica", cantidad = 1, precioUni = 25 } } });
peticion.Headers.Add("X-Facta-Key", Environment.GetEnvironmentVariable("FACTA_API_KEY"));
peticion.Headers.Add("X-Facta-Sign-Key", Environment.GetEnvironmentVariable("FACTA_SIGN_KEY"));
peticion.Headers.Add("Idempotency-Key", pedidoId); // el mismo en cada reintento de esta operación
var respuesta = await cliente.SendAsync(peticion);
Console.WriteLine({{OTROS}}
quot;cupo restante: {respuesta.Headers.GetValues("RateLimit-Remaining").FirstOrDefault()}");
using var datos = JsonDocument.Parse(await respuesta.Content.ReadAsStringAsync());
var raiz = datos.RootElement;
if ((int)respuesta.StatusCode == 200)
Console.WriteLine(raiz);
else if ((int)respuesta.StatusCode == 202)
// Firmado, sin respuesta del Ministerio todavía. NO lo reintente.
Console.WriteLine({{OTROS}}
quot;en contingencia: {raiz.GetProperty("numeroControl")}");
else if (raiz.TryGetProperty("error", out var error) && error.GetProperty("code").GetString() == "mh_rejected")
Console.WriteLine({{OTROS}}
quot;rechazado: {error.GetProperty("message")} · gastó {error.GetProperty("details").GetProperty("numeroControl")}");
else
throw new InvalidOperationException(respuesta.StatusCode.ToString());
Java
// JDK 17 o superior, con java.net.http. No hay librería de Facta para Java.
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
public final class Emitir {
public static void main(String[] args) throws Exception {
var base = System.getenv("FACTA_API_BASE_URL");
var constructor = HttpRequest.newBuilder(URI.create(base + "/v1/dte"))
.header("X-Facta-Key", System.getenv("FACTA_API_KEY"))
.header("X-Facta-Sign-Key", System.getenv("FACTA_SIGN_KEY"))
// El mismo pedidoId en cada reintento de esta operación.
.header("Idempotency-Key", pedidoId)
.timeout(Duration.ofSeconds(60))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("""
{
"tipoDte": "03",
"receptor": {
"customerId": "374114b6-e957-4c7a-8911-dd6381b1e0ea"
},
"items": [
{
"descripcion": "Integración de la API de facturación electrónica",
"cantidad": 1,
"precioUni": 25
}
]
}
"""));
var peticion = constructor.build();
var respuesta = HttpClient.newHttpClient().send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println("cupo restante: " + respuesta.headers().firstValue("RateLimit-Remaining").orElse("?"));
// Estados: 200 correcto · 202 correcto (el 202 queda firmado, en contingencia — no se reintenta) · 422 con "mh_rejected" si Hacienda lo negó.
System.out.println(respuesta.statusCode());
System.out.println(respuesta.body());
}
}
Go
// Go 1.22 con net/http. No hay librería de Facta para Go.
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
func main() {
base := os.Getenv("FACTA_API_BASE_URL")
cuerpo, _ := json.Marshal(map[string]any{"tipoDte": "03", "receptor": map[string]any{"customerId": "374114b6-e957-4c7a-8911-dd6381b1e0ea"}, "items": []any{map[string]any{"descripcion": "Integración de la API de facturación electrónica", "cantidad": 1, "precioUni": 25}}})
peticion, _ := http.NewRequest("POST", base+"/v1/dte", bytes.NewReader(cuerpo))
peticion.Header.Set("Content-Type", "application/json")
peticion.Header.Set("X-Facta-Key", os.Getenv("FACTA_API_KEY"))
peticion.Header.Set("X-Facta-Sign-Key", os.Getenv("FACTA_SIGN_KEY"))
// El mismo pedidoId en cada reintento de esta operación.
peticion.Header.Set("Idempotency-Key", pedidoId)
cliente := &http.Client{Timeout: 60 * time.Second}
respuesta, err := cliente.Do(peticion)
if err != nil {
panic(err)
}
defer respuesta.Body.Close()
fmt.Println("cupo restante:", respuesta.Header.Get("RateLimit-Remaining"))
var datos map[string]any
json.NewDecoder(respuesta.Body).Decode(&datos)
switch respuesta.StatusCode {
case 200:
fmt.Println(datos)
case 202:
// Firmado, sin respuesta del Ministerio todavía. No reintentar.
fmt.Println(datos)
default:
fmt.Println("error:", datos["error"])
}
}