Conectá tu sistema a fluxa.

El reparto

Quién hace qué.

Autenticación

Una credencial, en cada pedido.

fct_…

La credencial arranca con un prefijo reconocible y dice en su propio texto si es de producción o de prueba. Eso la hace fácil de detectar con un escáner de secretos si alguna vez se te escapa a un repositorio.

Se muestra una sola vez

El secreto se ve en claro cuando se emite y no hay forma de recuperarlo después: en la base queda sólo su hash SHA-256, que es contra lo que se verifica cada request.

Producción y prueba

Las credenciales de prueba son de sólo lectura por diseño. Si intentás cualquier escritura con una, la respuesta es 403 CREDENCIAL_TEST_SOLO_LECTURA — no depende de que te hayas olvidado un permiso.

GET /api/v1/ping

Confirma que tu credencial es válida y que la plataforma responde, sin tocar datos de ninguna empresa. Sirve como chequeo de arranque de tu integración.

GET /api/v1/empresas
Authorization: Bearer fct_live_…

200 OK
{
  "data": [
    {
      "empresa_id": "9f1c8b0e-…",
      "ruc": "219900450019",
      "razon_social": "Ferretería Aguiar",
      "scopes": ["empresa:read", "cfe:read", "catalogos:read"]
    }
  ]
}

Permisos

El permiso vive en la conexión, no en la credencial.

• usuarios y contadores de la empresa;
• la configuración del emisor;
• el panel de administración.

Lectura

Qué podés leer.

• Tus empresas.GET /api/v1/empresas devuelve las empresas que tu credencial puede operar, cada una con su RUT, su razón social y los permisos concedidos. No hace falta cablear nada a mano.
• La identidad del emisor. Antes de facturar contra una empresa podés pedir/api/v1/empresas/{empresaId} y comparar RUT y razón social con lo que tenés cargado de tu lado. Es un chequeo barato contra el error de conectar la empresa equivocada.
• El listado de comprobantes./api/v1/empresas/{empresaId}/cfe filtra por estado, tipo, cliente, moneda, serie, número y rango de fechas, y puede traer las líneas embebidas en la misma respuesta.
• El detalle./api/v1/empresas/{empresaId}/cfe/{cfeId} da líneas, receptor, montos, moneda, la referencia al comprobante original cuando es una nota de crédito o débito, y el bloque de retención cuando es un resguardo. Es una vista curada: no expone plomería interna ni datos del proveedor.
• Los catálogos./api/v1/empresas/{empresaId}/articulos con código interno, GTIN, unidad y precio; /api/v1/empresas/{empresaId}/clientes con documento, nombre y contacto. Y podés resolver de a uno: el artículo por su código interno exacto, el cliente por tipo y número de documento.

Sincronización

Cómo te enterás de que DGI respondió.

GET /api/v1/empresas/9f1c8b0e-…/cfe/eventos?desde_seq=4187&limit=50
Authorization: Bearer fct_live_…

200 OK
{
  "data": [
    {
      "seq": 4187,
      "tipo": "ACEPTADO_DGI",
      "cfe_id": "3ac07d92-…",
      "estado_anterior": "ENVIADO_PROVEEDOR",
      "estado_nuevo": "ACEPTADO_DGI",
      "cfe": {
        "tipo": "E_TICKET",
        "serie": "A",
        "numero": 1204,
        "fecha_emision": "2026-07-29",
        "moneda": "UYU",
        "monto_total": "12480.00",
        "receptor": null
      },
      "created_at": "2026-07-29T14:02:11.318Z"
    }
  ],
  "pagination": { "next_seq": 4188, "has_more": false }
}

• El evento no miente. Se escribe en la misma transacción que el cambio de estado que lo produjo. Si el cambio no quedó firme, el evento no existe: no vas a recibir avisos de cosas que no pasaron.
• Entrega al-menos-una-vez. Podés recibir el mismo evento dos veces y tenés que descartar duplicados por su seq. A cambio, no se pierde nada si tu proceso se cae en el medio.
• Viene con el resumen adentro. Cada evento trae tipo, serie, número, fecha, moneda, monto total, receptor, referencia y retención, para que no tengas que pedir el detalle de a uno detrás de cada aviso.
• Retardo deliberado. El feed sirve los eventos unos diez segundos después: es para no saltearse un evento que confirma un instante más tarde. Preferimos que llegue completo y ordenado antes que instantáneo.

Escritura

Preparar y emitir son dos pasos.

1. Resolvés catálogos. Buscás el artículo por su código interno exacto y te quedás con su identificador.
2. Das de alta el receptor, si hace falta./api/v1/empresas/{empresaId}/clientes crea o recupera por RUT en una sola llamada: si no existe lo creamos (201,created: true) y si ya existía te devolvemos el que hay (200,created: false), sin pisarle el nombre ni el contacto aunque los mandes distintos. El RUT se valida y se normaliza con las mismas reglas que la pantalla de clientes: si el dígito verificador no cierra, la respuesta es400 CLIENTE_RUC_INVALIDO antes de crear nada.
3. Creás el borrador con una Idempotency-Key. Mandás el artículo y la cantidad, y fluxa congela descripción, precio, IVA, código y unidad desde la ficha. Vos no mandás importes ni tasas. Cada línea lleva una referencia_externa tuya, obligatoria: un texto corto con el que identificás esa línea en tu sistema, que vuelve tal cual en las lecturas.
4. Revisás lo que quedó armado: montos, receptor y líneas ya vienen en la respuesta.
5. Ordenás la emisión./api/v1/empresas/{empresaId}/cfe/{cfeId}/emitir no lleva cuerpo ni key, y sólo aplica a un borrador creado por tu propia aplicación. Te respondemos 202 con el comprobante y un identificador de trabajo; el resultado fiscal llega después por el feed.

POST /api/v1/empresas/9f1c8b0e-…/cfe
Authorization: Bearer fct_live_…
Idempotency-Key: 6b3f2d10-8e5a-4c77-9d21-0f4b8e2a1c33
Content-Type: application/json

{
  "tipo": "E_TICKET",
  "fecha_emision": "2026-07-29",
  "moneda": "UYU",
  "forma_pago": "CONTADO",
  "lineas": [
    {
      "articulo_id": "b21e4f6a-…",
      "cantidad": "2",
      "referencia_externa": "venta-8841-linea-1"
    }
  ]
}

201 Created
{
  "data": {
    "cfe": {
      "id": "3ac07d92-…",
      "estado": "BORRADOR",
      "moneda": "UYU",
      "monto_neto": "10229.51",
      "monto_iva": "2250.49",
      "monto_total": "12480.00"
    },
    "idempotency_replayed": false
  }
}

POST /api/v1/empresas/9f1c8b0e-…/cfe/3ac07d92-…/emitir
Authorization: Bearer fct_live_…

202 Accepted
{
  "data": {
    "cfe": { "id": "3ac07d92-…", "estado": "EN_COLA" },
    "job_id": "emision-3ac07d92-…"
  }
}

Errores

Un código estable por cada decisión.

403 Forbidden
{
  "error": {
    "code": "EMPRESA_SUSPENDIDA",
    "message": "La empresa está suspendida.",
    "requestId": "01J8Q…"
  }
}

Seguridad

Si te roban la credencial.

• Una aplicación puede tener varias credenciales activas a la vez. Eso es lo que te permite rotar sin cortar servicio: emitís la nueva, convivís unos días con las dos, y recién ahí revocás la vieja.
• Revocar corta el acceso en el siguiente request. No hay ventana de gracia por token vigente, porque la credencial se verifica en cada llamada.
• El corte puede ser total o quirúrgico. La revocación de la aplicación devuelve401 en todas las empresas a la vez; si una sola empresa revoca su conexión, recibís403 nada más que con esa y seguís funcionando normal con las demás.
• Hay aviso por correo. Cuando se conecta una aplicación a una empresa, el administrador de esa empresa recibe la novedad con la aplicación y los permisos concedidos; al rotar una credencial se avisa al contacto técnico de cada empresa vinculada.
• Cada escritura queda atribuida a tu aplicación como autor, nunca a un usuario prestado. El alta de conexiones, los cambios de permisos y las revocaciones también quedan registrados.

El contrato

Sólo se suma.

Pedir acceso

Contanos qué querés conectar.