API del facturador

Para empezar

1. 1En el facturador, entrá a Ajustes › Integraciones y creá una clave de prueba con permiso de facturar.
2. 2Probá con el ejemplo de Crear una factura: sale en el ambiente de prueba de ARCA, sin validez fiscal.
3. 3Cuando todo ande, conectá tu certificado de ARCA (guía), pasá el facturador a producción y creá una clave de producción.

Autenticación

Cada pedido lleva la clave en el encabezado Authorization.

Authorization: Bearer art_test_xxxxxxxxxxxxxxxxxxxxxxxx

• Ambiente: las claves art_test_ funcionan solo con el facturador en modo de prueba, y las art_live_ solo en producción. Una prueba nunca sale como factura real.
• Permiso: "Solo leer" consulta; "Facturar" además crea facturas y notas de crédito.
• Guardá la clave en tu servidor, nunca en una página web ni en una app del celular. Si se filtra, revocala en Ajustes y creá otra.

Crear una factura

Con el encabezado Idempotency-Key: un identificador único de la venta en tu sistema, por ejemplo el número de pedido (8 a 120 caracteres). Si repetís el pedido con el mismo valor, devuelve la misma factura y no emite otra.

curl https://facturador.mitrastienda.com.ar/v1/comprobantes \
  -H "Authorization: Bearer art_test_..." \
  -H "Idempotency-Key: pedido-10457" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente": { "nombre": "Consumidor final" },
    "items": [
      { "descripcion": "Auriculares bluetooth", "cantidad": 1, "precioUnitario": 48900, "iva": 21 },
      { "descripcion": "Envío", "cantidad": 1, "precioUnitario": 6500, "iva": 21 }
    ]
  }'

Campos

La letra (A, B o C) sale de tu condición frente al IVA y la del comprador. El punto de venta es el predeterminado del ambiente.

Respuesta

{
  "id": "cm2x...",
  "tipo": "factura",
  "estado": "emitiendo",
  "ambiente": "prueba",
  "letra": "B",
  "puntoDeVenta": 3,
  "numero": null,
  "cae": null,
  "total": 55400,
  "referencia": "pedido-10457",
  "mensaje": null
  // ...
}

El CAE llega en segundos: consultá GET /v1/comprobantes/{id} hasta que el estado sea autorizada o rechazada, o recibilo con los avisos a tu sistema.

Estados

Todos los pedidos

Avisos a tu sistema

En Ajustes › Integraciones › Avisos a tu sistema cargás una dirección https://. Cuando un comprobante se autoriza o se rechaza, le mandamos un POST:

{
  "evento": "comprobante.autorizado",
  "creado": "2026-10-12T15:04:05.000Z",
  "comprobante": { "id": "cm2x...", "estado": "autorizada", "numero": 128, "cae": "76412589031524", "referencia": "pedido-10457" /* ... */ }
}

• Eventos: comprobante.autorizado y comprobante.rechazado. El botón Probar manda uno de tipo prueba.
• Respondé con un 2xx en menos de 10 segundos. Si no, reintentamos con espera creciente, hasta 8 veces.
• Puede llegar más de una vez: usá comprobante.id para no procesarlo dos veces.

Verificar la firma

Cada aviso trae Artic-Signature: t=<segundos>,v1=<firma>. La firma es un HMAC-SHA256 en hexadecimal de t + "." + cuerpo con el secreto que te mostramos al cargar la dirección.

import { createHmac, timingSafeEqual } from "node:crypto";

function avisoValido(cuerpo, encabezado, secreto) {
  const { t, v1 } = Object.fromEntries(encabezado.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // más de 5 minutos: se descarta
  const esperada = createHmac("sha256", secreto).update(`${t}.${cuerpo}`).digest("hex");
  return timingSafeEqual(Buffer.from(esperada), Buffer.from(v1));
}

Errores

Responden con un código HTTP y este formato:

{ "error": { "codigo": "idempotency_key", "mensaje": "Mandá el encabezado Idempotency-Key..." } }