factadesarrolladores API 0.1.0-esqueleto

JavaScript

HTTP directo · no hay librería de Facta para JavaScript sin tipos

Si su proyecto es JavaScript puro —sin TypeScript—, esta página es la suya: fetch es global desde Node 18 y no hace falta ninguna dependencia. Si en cambio puede usar TypeScript, el SDK oficial también funciona en JavaScript puro y añade tipos, reintentos y errores sobre los que se puede hacer switch.

Requisitos

  • Node 22 o 24. fetch y AbortSignal.timeout son globales; no hace falta ninguna dependencia.
  • 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_destination antes de reservar correlativo.
URL basehttps://hcnvknpsbadplnfcflxx.supabase.co/functions/v1/api-v1

Variables de entorno

sh
# 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

El ejemplo completo

javascriptarchivo real · sdks/javascript/examples/emitir.mjs
#!/usr/bin/env node
// Emitir un DTE contra la API de Facta con fetch, sin ninguna librería.
//
// Objetivo: Node 22 o 24 — fetch y AbortSignal.timeout son globales. No hay
// librería de Facta para JavaScript sin el SDK oficial de TypeScript; esto es
// HTTP directo.
//
//   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 node emitir.mjs
//
// 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.
import { writeFile } from 'node:fs/promises';

const base = process.env.FACTA_API_BASE_URL.replace(/\/+$/, '');
const apiKey = process.env.FACTA_API_KEY;
const signKey = process.env.FACTA_SIGN_KEY;
// El identificador de ESTA venta — en un sistema real viene de su propia base
// de datos y se persiste antes de la primera llamada, para que un reintento
// use el mismo valor en vez de uno nuevo por intento.
const pedidoId = process.env.PEDIDO_ID ?? 'pedido-00417';

async function peticion(method, path, { firma = false, body } = {}) {
  const headers = { 'X-Facta-Key': apiKey };
  if (firma) headers['X-Facta-Sign-Key'] = signKey;
  if (body !== undefined) {
    headers['Content-Type'] = 'application/json';
    headers['Idempotency-Key'] = pedidoId;
  }
  const respuesta = await fetch(base + path, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(60_000),
  });
  return respuesta;
}

// 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.
const estadoRespuesta = await peticion('GET', '/v1/status');
if (estadoRespuesta.status !== 200) {
  console.error('no se pudo leer el estado de la llave:', await estadoRespuesta.text());
  process.exit(1);
}
const info = await estadoRespuesta.json();
console.log(`ambiente: ${info.ambiente} · cupo por hora restante: ${info.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.
const emitirRespuesta = await peticion('POST', '/v1/dte', {
  firma: true,
  body: {
    tipoDte: '01',
    items: [{ descripcion: 'Café', cantidad: 2, precioUni: 1.5 }],
  },
});

console.log('cupo restante:', emitirRespuesta.headers.get('RateLimit-Remaining'));

const datos = await emitirRespuesta.json();
if (emitirRespuesta.status === 200) {
  console.log('sellado:', datos.numeroControl, datos.selloRecibido);
} else if (emitirRespuesta.status === 202) {
  // Firmado, sin respuesta del Ministerio todavía. El documento EXISTE y se
  // le debe a Hacienda: NO se reintenta esta llamada.
  console.log('en contingencia:', datos.numeroControl, '—', datos.detalle);
} else if (emitirRespuesta.status === 422) {
  if (datos.error?.code === 'mh_rejected') {
    console.error('rechazado:', datos.error.message);
    console.error('número ya gastado:', datos.error.details.numeroControl);
  } else {
    console.error('no se pudo emitir:', datos.error?.code, datos.error?.message);
  }
  process.exit(1);
} else {
  console.error('error inesperado:', emitirRespuesta.status, datos);
  process.exit(1);
}

// 3) Descargar los bytes EXACTOS del JSON firmado — nunca se vuelven a
//    serializar, porque eso no reproduciría los bytes que Hacienda validó.
const archivoRespuesta = await peticion('GET', `/v1/dte/${datos.codigoGeneracion}/file?kind=json`);
if (archivoRespuesta.status === 200) {
  const bytes = new Uint8Array(await archivoRespuesta.arrayBuffer());
  const nombre = `${datos.codigoGeneracion}.json`;
  await writeFile(nombre, bytes);
  console.log('archivado:', nombre);
}

Lo que este ejemplo no hace

Los demás lenguajes

El mismo documento, en los otros seis. Cambia la sintaxis; no cambian las cabeceras, ni los códigos, ni las reglas.

curl

curl
# -D - vuelca las cabeceras de la respuesta, con RateLimit-Remaining (y, si aplica, Retry-After).
curl --fail-with-body -X POST "$FACTA_API_BASE_URL/v1/dte" \
  -H "X-Facta-Key: $FACTA_API_KEY" \
  -H "X-Facta-Sign-Key: $FACTA_SIGN_KEY" \
  -H "Idempotency-Key: $PEDIDO_ID" \
  -H "Content-Type: application/json" \
  -D - \
  --max-time 60 \
  -d '{
  "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
    }
  ]
}'

Python

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
// 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#

csharp
// .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

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
// 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"])
	}
}

Escriba para buscar Por ejemplo: idempotencia, contingencia, 422, emitir.

↑ ↓ moverse Enter abrir Esc cerrar