Facturación por API

Conectá tu ERP o tienda sin registrar cada venta en la interfaz de Bigu. El alta del negocio, certificado, numeración y habilitación fiscal se completan una vez en Perfil del negocio › Facturación. El consumo diario puede ser sólo por API. Las emisiones API quedan en el registro fiscal del servicio; no crean ventas, movimientos de caja ni stock en Bigu. El ERP conserva el registro comercial.

Acceso

En Facturación, comprobá el entorno de la conexión antes de copiar su URL y crear la clave. La disponibilidad del endpoint no reemplaza el alta fiscal ni los permisos de emisión del negocio.

El propietario crea una clave en Perfil del negocio › Facturación. La clave se muestra una vez, se almacena como hash y vence a los 90 días. Se envía únicamente como Authorization: Bearer CLAVE. No la incluyas en URLs, código del navegador ni repositorios. Creá una segunda clave antes de revocar la anterior para rotar sin interrupciones. Las claves de dev no sirven en producción. Cada clave accede sólo a su negocio; no se admite business_id en el cuerpo. Límite: 120 solicitudes/minuto por clave, compartido por todas las réplicas. Un 429 incluye Retry-After. Las respuestas no se cachean.

Elegí los permisos de la clave

En Facturá desde tu sistema, escribí el Nombre de la integración y revisá Permisos de esta conexión antes de elegir Crear clave. Una clave nueva empieza con consulta: para emitir, también tenés que marcar Emitir comprobantes. Guardá la clave en tu servidor antes de cerrar el aviso con Ya la guardé.

Elegí los permisos que requiere esa integración. Si recibís 403 insufficient_scope, revisá qué operación está intentando; no se corrige repitiendo la misma solicitud. Creá una clave con el alcance necesario, actualizá la integración y después revocá la anterior.

Revocar o rotar una clave

En Facturá desde tu sistema, localizá la integración por su nombre, prefijo y vencimiento. Elegí Revocar para quitarle acceso y comprobá Clave revocada. Esa integración ya no puede acceder. No es necesario esperar a que venza: las solicitudes siguientes dejan de estar autorizadas.

Para rotar sin interrumpir tu sistema, creá otra clave con sus permisos, guardala donde corre la integración, comprobá la conexión y recién después revocá la anterior. Una clave guardada no vuelve a mostrarse; si perdiste el secreto, necesitás crear otra. La revocación sigue siendo posible para el propietario cuando se restringe el acceso operativo del negocio.

Emitir

POST /api/v1/facturas
Content-Type: application/json
Authorization: Bearer CLAVE

{
  "external_id": "venta-2026-001",
  "tipo_cfe": 111,
  "fecha": "2026-09-05",
  "contado": true,
  "moneda": "UYU",
  "receptor": {
    "tipo_documento": 2,
    "documento": "214844360018",
    "razon_social": "Receptor de prueba DGI",
    "direccion": "Domicilio de prueba",
    "ciudad": "Montevideo"
  },
  "lineas": [
    {
      "nombre": "Servicio de prueba",
      "cantidad": 1,
      "unidad_medida": "un",
      "precio_unitario": 100000,
      "categoria_iva": "tasa_basica"
    }
  ]
}

El receptor anterior es de prueba. Usá datos reales sólo en el ambiente adecuado. Los importes son enteros en centésimos y los precios incluyen IVA: 100000 = $1.000. Las cantidades admiten hasta tres decimales. Máximo 200 líneas y 256 KiB por solicitud. Tipos: 101 e-Ticket; 111 e-Factura; 102/112 notas de crédito; 103/113 notas de débito. En e-Factura y sus notas son obligatorios el RUC, razón social, dirección y ciudad del receptor. Las notas usan una referencia con tipo_cfe, serie, numero, fecha y razon del original. El original debe estar aceptado en este negocio y tener la misma moneda y familia. El crédito acumulado, incluidas notas pendientes, no puede superar su importe. Las referencias globales no están disponibles en esta API. El motor valida las reglas fiscales; la API no permite elegir serie, número ni firma. Categorías IVA: tasa_basica, tasa_minima, exento, no_facturable, exportacion. Monedas: UYU, USD, EUR, ARS, BRL. Fuera de UYU enviá tipo_cambio como string decimal (por ejemplo "40.500"), la cotización fiscal en pesos por unidad, con hasta tres decimales. Consultá el esquema OpenAPI para los campos opcionales.

Reintentos sin duplicados

external_id es obligatorio: 1–80 letras, números, guiones o guiones bajos. Conservá un identificador por comprobante, incluso si rotás la clave. La primera solicitud válida reserva el identificador y congela su contenido. Repetir el mismo pedido devuelve la misma emisión; cambiar el contenido devuelve 409 idempotency_conflict. Si la red falla o devuelve 503, reintentá el MISMO pedido. No generes un external_id nuevo para resolver un timeout: duplicaría la operación. Si corregís datos de un pedido reservado que nunca se emitió, usá una identidad nueva sólo después de conciliar su estado. Una fecha omitida se resuelve cuando el motor acepta el pedido; enviá fecha explícita para preservar la fecha comercial.

Consultar y descargar

202 significa encolado, NO aceptado por DGI. La respuesta contiene external_id, estado, nueva y, cuando existen, serie, numero y motivo. Consultá GET /api/v1/facturas/EXTERNAL_ID cada 5 segundos y luego con espera creciente. Estados en curso: pendiente, firmada, enviada. Otros estados: aceptada, observada, rechazada, invalida, en_duda. No entregues como aceptado un comprobante pendiente, rechazado o en_duda. Los estados observada y en_duda requieren revisión del motivo y conciliación. No hay webhooks en v1; la integración consulta el estado.

GET /api/v1/facturas/EXTERNAL_ID/pdf descarga la representación impresa. GET /api/v1/facturas/EXTERNAL_ID/xml descarga los bytes exactos del XML firmado. Ambas rutas exigen la misma autenticación. Antes de firmar devuelven 409. El XML puede descargarse para diagnóstico aunque DGI lo rechace: disponer del archivo no demuestra aceptación. El PDF conserva el logo y presentación del negocio. En dev los PDF se identifican SIN VALIDEZ FISCAL.

Errores

El cuerpo es { "ok": false, "error": { "code": "...", "message": "...", "retryable": false, "reference": "..." } }. 400: JSON o campos inválidos. 401: clave inválida, vencida o revocada. 403: permiso insuficiente en la clave, o una operación no habilitada por el plan o estado del negocio. 404: comprobante inexistente para este negocio. 409: conflicto o requisito fiscal pendiente. 413: cuerpo demasiado grande. 429: límite de solicitudes. 503: servicio no disponible. Guardá x-request-id para soporte; nunca la clave ni datos fiscales en logs públicos.

Descubrir y recuperar

GET /api/v1/fiscal/capacidades informa los permisos de la clave y las operaciones disponibles. GET /api/v1/fiscal/emisor consulta la habilitación actual, certificado y requisitos por tipo de comprobante. Un fallo del servicio se informa como error; nunca se interpreta como habilitación.

GET /api/v1/facturas?query=CLIENTE&limit=20 busca por identificador externo, documento o razón social. La respuesta contiene items y next_cursor. Pasá el cursor en la consulta siguiente conservando los filtros. from es la fecha de registro inclusiva y to exclusiva, ambas ISO 8601 con zona horaria. El listado incluye pedidos conservados antes de transmitir: consultá su status_url para conocer el resultado fiscal. La presencia en el listado no demuestra emisión ni aceptación.

Las claves anteriores conservan consulta y emisión. Una clave restringida a fiscal:read puede consultar y descargar, pero una emisión devuelve 403 insufficient_scope sin reservar el pedido.

Borradores y revisión fiscal

Los borradores se comparten entre la web, la API y el MCP del mismo negocio. Guardar no emite ni reserva numeración. Podés guardar contenido incompleto; validar exige todos los datos fiscales y fecha explícita en formato YYYY-MM-DD. fecha_vencimiento es opcional y no puede ser anterior a la emisión.

1. Generá un UUID y conservá ese id antes de llamar a POST /api/v1/fiscal/borradores. Enviá { "id": "UUID", "revision": 0, "document": { ... } }. El documento usa los campos del pedido de emisión; Bigu asigna external_id como draft_UUID.
2. Para editar, enviá el mismo id y la última revision devuelta. Cada guardado aumenta la revisión e invalida la revisión fiscal anterior.
3. Llamá a POST /api/v1/fiscal/borradores/validar con id y revision. Obtendrás bases, IVA y total en centésimos, calculados por el motor fiscal real. Esta respuesta no significa emisión ni aceptación de DGI.
4. Emití con POST /api/v1/fiscal/borradores/emitir, usando el mismo id y revision. El contenido queda congelado antes del envío al servicio fiscal.
5. Confirmá el resultado en GET /api/v1/facturas/draft_UUID. Ante una interrupción, consultá y reintentá la misma identidad; no crees otro borrador para repetir el envío.

GET /api/v1/fiscal/borradores lista borradores con limit y cursor; continuá con next_cursor para recuperar todos. GET /api/v1/fiscal/borradores/UUID recupera el contenido y la revisión actual. Un 409 draft_revision_conflict exige volver a consultar: puede haber una edición concurrente, una revisión sin validar o una emisión ya iniciada. Un borrador enviado no se edita.

Guardar y validar requieren fiscal:prepare; emitir requiere fiscal:issue; consultar requiere fiscal:read. Las claves anteriores conservan sus permisos originales de consulta y emisión; creá una nueva clave con preparación para usar borradores.

Observaciones y vencimiento

nota permite hasta 1000 caracteres de observaciones comerciales por comprobante. Queda congelada al emitir y aparece en el PDF; no forma parte del XML fiscal ni cambia los impuestos. La nota general del negocio se configura por separado en la presentación del emisor.

fecha_vencimiento se conserva en el CFE y se muestra en su PDF. Tanto la fecha como las observaciones se revisan antes de emitir; editar un borrador invalida su revisión anterior.

Clientes y conceptos

La API permite buscar y mantener los clientes y conceptos del negocio con permisos de preparación fiscal. Reutiliza el catálogo y las identidades existentes sin conceder stock ni gestión general.

GET y POST /api/v1/fiscal/clientes consultan o guardan destinatarios; GET y POST /api/v1/fiscal/conceptos hacen lo mismo con los conceptos. Para recuperar una escritura consultá el mismo id; para recorrer una búsqueda, conservá sus filtros y continuá hasta agotar next_cursor. El detalle de campos, actualización parcial y permisos está en la guía enlazada.

Entrega, cobros y resúmenes

La guía de cobros y entrega cubre el formato y la recuperación de estas operaciones:

Cada efecto requiere su scope específico y un identificador estable. Un correo recibido por el proveedor todavía no equivale a entrega confirmada. Registrar un pago anota dinero que ya recibiste y no ejecuta una cobranza.

Reglas y ocurrencias automáticas

Con fiscal:rules, POST /api/v1/fiscal/reglas guarda una plantilla y autoriza su calendario semanal o mensual. Conservá un UUID por regla y revisá los campos de fecha, zona horaria, vencimiento y correo en Facturación automática antes de activarla.

POST /api/v1/fiscal/reglas/estado recibe el id y status: paused o active para pausar o reanudar. Pausar impide trabajo nuevo; una ocurrencia ya iniciada puede terminar. Revocar la clave que creó la regla no la pausa.

GET /api/v1/fiscal/reglas permite listar o recuperar por id. GET /api/v1/fiscal/reglas/ocurrencias consulta el progreso de las fechas y acepta id para filtrar una regla. Ambas consultas usan limit, cursor y next_cursor. Agotá las páginas y consultá el comprobante de cada ocurrencia antes de darla por emitida o aceptada. Las consultas requieren fiscal:read.