factadesarrolladores API 0.1.0-esqueleto

Preparar un documento

POST /v1/dte/prepare

Alcance: issue. Aquí NO se abre el vault de firma, así que esta ruta no pide X-Facta-Sign-Key: reservar y construir es todo lo que un token robado puede hacer, y firmar no está entre esas dos cosas.

Alcance issueGasta correlativoIdempotency-Key obligatoria

Parámetros

NombreDóndeQué es
X-Facta-Keyrequerido cabecera

La llave de la API. Nunca en Authorization.

Idempotency-Keyrequerido cabecera

Un identificador por operación, elegido por usted. La misma en cada reintento.

X-Facta-Request-Fingerprintopcional cabecera

Opcional. SHA-256 en hexadecimal minúscula de la petición TAL COMO LA ESCRIBIÓ quien llama, antes de que ninguna biblioteca la complete. Solo se lee en POST /v1/dte y POST /v1/dte/prepare; en cualquier otra ruta se ignora. Con ella, la comparación de Idempotency-Key usa esta huella en lugar del cuerpo: un cliente que resuelve customerId o productId desde su copia del catálogo puede reintentar la misma venta después de que el catálogo cambió y obtiene la respuesta guardada, no un 422 idempotency_key_reuse. Una huella distinta con la misma llave sigue siendo 422, y una cabecera que no sea 64 caracteres hexadecimales en minúscula es 400 invalid_request. El alcance no cambia: (llave, Idempotency-Key). Si el primer intento no la mandó y el reintento sí, y el cuerpo del reintento es idéntico byte a byte al del primero, se trata como la misma petición (así una biblioteca que se actualiza a mitad de un reintento no recibe 422); si el cuerpo difiere, es 422. Si el primer intento la mandó y el reintento no, la respuesta es 422.

X-Facta-Debugopcional cabecera

Función de soporte, no de uso normal. Con X-Facta-Debug: timings, y solo si la llave está autorizada, la respuesta trae además un miembro debug con códigos de diagnóstico para el equipo de soporte de Facta, y la cabecera Server-Timing con el tiempo total.

``json "debug": { "ref": "k3q9m0x7ptd2", "t": "A1:12,V1:40,H4:812" } ``

  • Disponible para las llaves de pruebas (facta_test_) y para las llaves de producción que Facta haya habilitado. Con cualquier otra llave, o si la llave no es válida, la respuesta no cambia en un byte y la cabecera se ignora.
  • ref es una referencia aleatoria: dígasela a soporte junto con la hora de la petición.
  • t son pares código:milisegundos. El significado de cada código no es público y puede cambiar sin aviso; no construya lógica sobre él. Soporte lo interpreta con su propio catálogo.
  • Server-Timing lleva solo total;dur=<ms>.
  • Aplica a POST /v1/dte, POST /v1/dte/prepare, POST /v1/dte/sign, GET /v1/dte y a la descarga GET /v1/dte/{codigoGeneracion}/file (esta última solo con Server-Timing, porque la respuesta son los bytes del archivo). En otras rutas se ignora.
  • Una repetición por Idempotency-Key también lo acepta; el informe describe esa repetición y no se guarda.

Qué se manda

CampoTipoQué es
tipoDterequerido 01 · 03 · 04 · 05 · 06 · 07 · 11 · 14

01 factura · 03 crédito fiscal · 04 nota de remisión · 05 nota de crédito · 06 nota de débito · 07 comprobante de retención · 11 exportación · 14 sujeto excluido. Los demás del catálogo llegan con su tanda.

  • 04 nota de remisión: mueve mercadería sin venta de por medio (consignación, traslado entre establecimientos de la misma empresa, bienes en camino, depósito). Lleva el valor de los bienes pero no cobra nada. Requiere receptor.bienTitulo.
  • 07 comprobante de retención: lo emite solo un agente de retención designado por Hacienda cuando compra a un proveedor: retiene parte del IVA y le entrega este comprobante, que el proveedor usa para reclamar lo retenido. Sus «líneas» son retenciones, no mercadería. Una empresa que no es agente recibe 403 retention_agent_required antes de gastar correlativo.

La llave también tiene que llevar el tipo en tiposDte (403 dte_type_not_allowed si no): una llave acuñada antes de que existieran el 04 y el 07 lleva solo los seis anteriores y hay que acuñarla de nuevo con esos tipos marcados.

entregaopcional Entrega

receptoropcional Receptor o ReceptorExportacion o ReceptorSujetoExcluido o null

Su forma depende del tipo: Receptor para 01/03/04/05/06/07, ReceptorExportacion para el 11 y ReceptorSujetoExcluido para el 14. Una FE (01) puede no llevarlo — es el consumidor final anónimo.

itemsrequerido lista de Item

documentosRelacionadosopcional lista de DocumentoRelacionado

Obligatorio en 05 y 06, opcional en el 04 y prohibido en los demás. Qué documento sellado ajusta esta nota (o, en una remisión, a qué factura, crédito fiscal o exportación acompaña; una línea del 04 puede nombrar su documento con items[].numeroDocumento). Una nota puede ajustar un crédito fiscal (03) o un comprobante de retención (07). Cada entrada se escribe entera o se nombra por su codigoGeneracion, que el servidor completa desde el índice de SU empresa.

numPagoElectronicoopcional texto

Solo en la nota de débito (06). En otro tipo es 400.

exportacionopcional cualquiera

Obligatorio en el 11, y prohibido en los demás.

aplicarReteRentaopcional sí/no

Solo en el 14. Opcional: omitido o false deja la retención en cero; true aplica la tasa vigente de renta al subtotal completo de la FSE después de descuentos por línea (items[].montoDescu); la API no admite un descuento global para la FSE. No selecciona líneas por tipoItem: incluye bienes usados como insumos de un servicio. Una compra solo de bienes no queda sujeta automáticamente por no llevar IVA. Para retener solo sobre algunas líneas use incomeWithholding (modo per_line) con items[].applyIncomeWithholding; las dos formas se excluyen (fse_withholding_legacy_conflict). No es automática: la integración la solicita expresamente. Al combinarla con una línea exenta o no_sujeta se responde 422 retention_mixed_class_unsupported antes de reservar. Es un interruptor (sí o no), no un monto: Facta calcula la retención de renta del 10 % (con la tasa vigente) y la descuenta del total a pagar. El monto se lee en documento.resumen.reteRenta y en totales.reteRenta.

aplicarRetencionIvaopcional sí/no

Solo en el 01, 03, 05 y 06. Es un interruptor (sí o no), no un monto: Facta calcula el monto con la tasa vigente.

Retención de IVA del 1 % que le hace un cliente agente de retención (gran contribuyente), art. 162 del Código Tributario. Es el 1 % de la base neta gravada (después de descuentos), no del IVA. No cambia el IVA del 13 %: lo que cambia es el total a pagar, que baja en ese 1 %. Ejemplo: base neta $420.00, IVA $54.60, total $474.60; con aplicarRetencionIva: true la retención es $4.20 y el total a pagar queda en $470.40.

En el documento sellado el monto queda en resumen.ivaRete (en los cuatro tipos; la API de Facta lo repite en totales.ivaRete) y totalPagar ya lo descuenta.

Depende de quién es el comprador, algo que la API no puede ver, así que nunca es automática: se pide. En una nota de crédito (05) o de débito (06) revierte o repite la retención del documento que la nota corrige: la API no lo infiere (no puede leer el CCF cifrado) ni lo copia del documento relacionado; quien llama lo declara. La pantalla «Revisar y emitir» de Facta sí lo propone: si el borrador no trae la clave y el CCF relacionado llevó retención, la fila arranca activada con un aviso (un borrador que no permite cambios no se modifica; el aviso pide reenviarlo con aplicarRetencionIva: true). Un false explícito se respeta. Se anuncia con capabilities.retencionIvaNotas: true en GET /v1/status. En otro tipo es 400.

aplicarPercepcionIvaopcional sí/no

Solo en el 03. Es un interruptor (sí o no), no un monto: Facta calcula el monto con la tasa vigente.

Percepción de IVA del 1 % (art. 163 CT) que cobra usted, como emisor agente de percepción, sobre el monto neto gravado de las líneas de bienes (tipoItem 1) después de la parte proporcional del descuento global; los servicios no entran en la base. A diferencia de la retención, se suma al total a pagar (montoTotalOperacion + ivaPerci − ivaRete) y no forma parte de montoTotalOperacion. En el documento sellado queda en resumen.ivaPerci. Nunca es automática: se pide. En otro tipo es 400.

descuentoGlobalopcional objeto

Solo en 01, 03, 04, 11 y 14 (en el 04, el descuento del valor de los bienes remitidos: la Normativa v2.0 lista los descuentos globales por clase de venta como válidos para FE, CCF y NRE, y el esquema oficial del 04 los pide en resumen). El 07 lo ignora con una advertencia. El descuento de toda la venta, como lo escribe la app: un monto o un porcentaje. Se aplica después de los descuentos por línea (items[].montoDescu) y Facta lo reparte:

  • porcentaje: el mismo porcentaje sobre cada tipo de venta (gravada, exenta, no sujeta) y queda en resumen.porcentajeDescuento.
  • monto: en la misma base de IVA que precioUni de ese tipo (con IVA en el 01, sin IVA en el 03 y el 11). Si hay varios tipos de venta se reparte en proporción a cada uno y la suma cuadra al centavo; porcentajeDescuento queda en 0.
  • En el 11 todo cae en descuGravada; en el 14, en resumen.descu (el único descuento global de la FSE).

El resultado se lee en resumen.descuNoSuj, descuExenta, descuGravada (o descu en el 14) y totalDescu, y todo lo que sigue se calcula ya descontado: IVA, aplicarRetencionIva, aplicarPercepcionIva, aplicarReteRenta, totalPagar y la suma que tiene que dar pagos[].

Un descuento mayor que el subtotal es 400 invalid_request con details.field: "descuentoGlobal" y details.subtotal; un modo mal escrito, un valor fuera de rango o cualquier otra clave dentro del objeto es 400 sobre ese campo. En una nota de crédito (05) o de débito (06) es 400 global_discount_not_supported: sus montos salen del documento que corrigen. null es lo mismo que omitirlo. Ninguno de estos rechazos gasta correlativo. GET /v1/status confirma el soporte con capabilities.descuentoGlobal: true.

descuentoGlobal.modorequerido monto · porcentaje

«monto» en dólares, «porcentaje» en puntos (10 = 10 %). Obligatorio: no tiene valor por omisión.

descuentoGlobal.valorrequerido número

Mayor que cero, con dos decimales como máximo. Un porcentaje no pasa de 100.

incomeWithholdingopcional objeto

Solo en FSE (14). Retiene renta solo sobre las líneas con applyIncomeWithholding true: la tasa vigente sobre la suma de esas líneas después de sus descuentos. Excluyente con aplicarReteRenta; todas las líneas requieren applyIncomeWithholding booleano explícito. Disponible cuando GET /v1/status anuncia capabilities.fseIncomeWithholdingPerLine. El tratamiento de una compra de bienes independiente mezclada con servicios sigue pendiente de confirmación de la DGII.

incomeWithholding.moderequerido per_line

condicionOperacionopcional 1 · 2 · 3

1 contado

plazoopcional 01 · 02 · 03

CAT-018 — días, meses o años. Solo se escribe si la operación es a crédito.

periodoopcional entero

Cuántos de esos plazos. Solo con condicionOperacion 2.

formaPagoopcional 01 · 02 · 03 · 04 · 05 · 08 · 09 · 11 · 12 · 13 · 14 · 99 · null

Forma de pago, código de CAT-017: 01 billetes y monedas, 02 tarjeta de débito, 03 tarjeta de crédito, 04 cheque, 05 transferencia o depósito bancario, 08 dinero electrónico, 09 monedero electrónico, 11 bitcoin, 12 otras criptomonedas, 13 cuentas por pagar del receptor, 14 giro bancario, 99 otros. Sin él (u omitido o null) el servidor usa 01 (05 en la exportación). Un código que no es del catálogo es 422 validation_failed con details.field y details.supported, y no gasta correlativo: el esquema oficial solo acota el largo, así que antes se firmaba y Hacienda lo rechazaba en vuelo. En 05 y 06 no se usa. No se combina con pagos.

pagosopcional lista de Pago

Varias formas de pago para un mismo documento (01, 03, 11 y 14). Cada fila es { codigo, montoPago, referencia? } y la suma de montoPago tiene que igualar el total a pagar del documento, al centavo (422 validation_failed con details.totalPagar y details.sumaPagos si no, antes de reservar el correlativo). Sin pagos el documento lleva una sola fila por el total, como siempre.

Reglas: no se manda junto a formaPago (400); no existe en 05 ni 06, que no liquidan nada (400); y no se combina con una operación a crédito (condicionOperacion 2, 422): cómo se reparte el plazo entre varias formas de pago no está publicado por Hacienda, así que no se adivina. A crédito use formaPago con plazo y periodo (ver «Forma de pago, tipo por tipo» en SolicitudDte). Con condicionOperacion 3 (otro) sí se admite. Hasta 10 filas.

observacionesopcional texto

Texto libre del documento. Viaja dentro del DTE firmado, en resumen.observaciones, en los seis tipos que emite la API (01, 03, 05, 06, 11 y 14): es el lugar que definen los esquemas de la Normativa 2.0. La representación gráfica lo imprime como «Observaciones:» en todas las plantillas carta (las de ticket solo si la plantilla trae ese bloque).

Hasta 3000 caracteres. Los esquemas oficiales de 03, 05 y 06 escriben ese tope como maximum en lugar de maxLength, así que el validador del esquema no lo cuenta; en 05 y 06 Facta lo revisa antes de firmar. Si no hay nada que decir, omita el campo o mande null: los esquemas de 01, 03, 11 y 14 no admiten un texto vacío.

Un documento 1.x de otro sistema puede traer este texto en extension.observaciones; Facta lo lee de los dos lugares al dibujarlo, pero lo que la API firma va siempre en resumen.

apendiceopcional lista de FilaApendice

La sección Apéndice del propio documento: hasta 10 filas campo / etiqueta / valor que el esquema oficial admite en los seis tipos (01, 03, 05, 06, 11 y 14). Forma parte del DTE firmado y transmitido a Hacienda —por eso se valida contra el esquema antes de gastar un correlativo— y la hoja la imprime como «etiqueta: valor» bajo las observaciones. Úselo para lo que sí pertenece al documento (orden de compra, vendedor, referencia). Si lo que quiere es solo decorar la hoja, use representacion.

Una lista vacía es 400: omita el campo o mande null. Se aplican los mínimos más estrictos de los esquemas a todos los tipos (campo ≥ 2, etiqueta ≥ 3) para que una fila válida lo sea en cualquiera. Sin saltos de línea ni caracteres de control.

representacionopcional Representacion

Ejemplos

Solo la primera pestaña usa una librería de Facta; las demás son peticiones HTTP normales, porque no existe un cliente oficial para esos lenguajes.

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/prepare" \
  -H "X-Facta-Key: $FACTA_API_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
    }
  ]
}'

JavaScript

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,
  // 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/prepare", {
  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 (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));
}

TypeScript (SDK)

typescript
import { Facta, FactaError } from "@facta-dte/api";

const facta = new Facta({
  apiKey: process.env.FACTA_API_KEY!,
});

// Reserva el correlativo y devuelve el documento con sus totales, SIN firmar.
const preparado = await facta.prepare(
  {
  "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
    }
  ]
},
  // La misma Idempotency-Key que usaría un emitir directo: preparar YA
  // reserva el correlativo, así que también gasta uno.
  { idempotencyKey: pedidoId },
);

console.log(preparado.totales.totalPagar);   // ya calculado por el servidor
console.log(preparado.numeroControl);        // el número ya está reservado

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"],
    "Idempotency-Key": pedido_id,  # el mismo en cada reintento de esta operación
    "Content-Type": "application/json",
}

peticion = urllib.request.Request(
    base + "/v1/dte/prepare",
    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)
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"),
    "Idempotency-Key: " . $pedidoId,  // el mismo en cada reintento de esta operación
    "Content-Type: application/json",
];

$conexion = curl_init($base . "/v1/dte/prepare");
$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 (($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/prepare");
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("Idempotency-Key", pedidoId); // el mismo en cada reintento de esta operación

var respuesta = await cliente.SendAsync(peticion);
Console.WriteLine($"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 (raiz.TryGetProperty("error", out var error) && error.GetProperty("code").GetString() == "mh_rejected")
    Console.WriteLine($"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 Preparar {
  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/prepare"))
        .header("X-Facta-Key", System.getenv("FACTA_API_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 · 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/prepare", bytes.NewReader(cuerpo))
	peticion.Header.Set("Content-Type", "application/json")
	peticion.Header.Set("X-Facta-Key", os.Getenv("FACTA_API_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)
	default:
		fmt.Println("error:", datos["error"])
	}
}

Qué contesta

200

Correlativo reservado; el documento todavía no está firmado.

400

Cuerpo mal formado, de más de 1 MB, o falta Idempotency-Key.

401

unauthorized (no vino llave) o invalid_api_key (no sirve). Las dos tardan lo mismo, a propósito.

En las rutas que firman se suman las dos del segundo factor: sign_key_required (falta X-Facta-Sign-Key, o vino la de apertura por error) y sign_key_invalid (no abre el vault). details.intentosRestantes dice cuántos quedan antes de que la llave se suspenda sola.

403

La llave existe pero no puede: key_revoked, key_expired, key_inactive, forbidden_scope, dte_type_not_allowed, ip_not_allowed, environment_not_allowed, company_mismatch o sign_vault_locked (demasiados intentos fallidos de abrir el vault: esperar no lo arregla, hay que reactivar la llave desde la app).

409

idempotency_in_flight — la primera petición con esa llave todavía trabaja. details.enVueloSegundos dice desde cuándo.

Si esa primera petición ya había empezado algo que no se deshace —un correlativo reservado, o una anulación camino de Hacienda— el mensaje NOMBRA el documento (details.codigoGeneracion) para que se pueda preguntar GET /v1/dte/{codigoGeneracion} qué fue de él, en vez de esperar las 24 h del reclamo. Si no había llegado a eso, no pasó nada irreversible y el barrido de cinco minutos suelta el reclamo solo a la media hora (details.seLiberaSola).

422

validation_failed — no gasta correlativo.

429

rate_limited (por hora, por día, o la ventana propia de /v1/status) o amount_limit (el documento pasa del monto máximo de la llave). El de monto se comprueba ANTES de reservar: no gasta correlativo.

details.window dice cuál de las tres fue.

503

service_unavailable o correlative_unavailable — algo nuestro no está listo. correlative_unavailable trae Retry-After; si la base alcanzó a reservar el número cuando la petición ya había fallado, Facta lo devuelve antes de contestar, así que reintentar con la MISMA Idempotency-Key es seguro. Puede salir en CUALQUIER ruta, incluidas las de consulta: el registro de peticiones se escribe antes de trabajar y falla cerrado, así que si esa tabla no contesta, nada contesta.

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

↑ ↓ moverse Enter abrir Esc cerrar