Facturación por API

Con Bigu Facturas, 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 Tu negocio › Facturación. El consumo diario puede ser sólo por API. En Facturas, las emisiones API quedan en el registro fiscal del servicio sin crear ventas, caja ni stock; el ERP conserva el registro comercial. En Integra, cada e-Ticket o e-Factura pedido por API crea su venta en Bigu y emite desde ella. La respuesta conserva el estado fiscal, CAE, serie, número y archivos, y suma sale_id para consultar la venta.

Si buscás el recorrido de pantalla, seguí Preparar, revisar y emitir un comprobante. Esta referencia describe la integración para quienes desarrollan el sistema que llama a Bigu.

Primeros pasos

1. Creá la clave

Abrí Tu negocio › Facturación. En la tarjeta Conectá tu sistema, elegí la fila API de facturación para abrir su modal. Quien administra la facturación del negocio puede crear la clave con el permiso Administrar facturación electrónica (fiscal.manage): no depende sólo de ser propietario.

Escribí el Nombre de la integración, dejá Consultar comprobantes y archivos marcado y marcá Emitir comprobantes. Si querés probar sin emitir, marcá también Preparar borradores, clientes y conceptos. Después elegí Crear clave. Al crearla, Bigu muestra la clave una sola vez y el aviso Guardá esta clave en tu servidor. Se muestra una sola vez. Guardala antes de cerrar con Ya la guardé.

Configurá BIGU_API_KEY como variable de entorno del servidor de tu integración. Los comandos siguientes leen esa variable; no escribas la clave en el comando, en el navegador ni en el repositorio.

2. Emití un comprobante

Antes de enviar, completá el alta fiscal y reemplazá la fecha, el receptor, los conceptos y los importes del ejemplo por los del comprobante real. Cada emisión se transmite a DGI. Elegí un external_id por comprobante y conservá el mismo pedido para recuperarlo.

Este pedido emite un comprobante real en producción. Consume numeración y cupo. Para anular el comprobante emitido, tenés que emitir una nota de crédito, que también consume numeración y cupo.

Como primera prueba segura, guardá un borrador con POST /api/v1/fiscal/borradores y validá su revisión con POST /api/v1/fiscal/borradores/validar. Ambas operaciones requieren fiscal:prepare; no emiten, no reservan numeración ni consumen cupo. Seguí Borradores y revisión fiscal para preparar el UUID, el documento y la revisión.

: "${BIGU_API_KEY:?Configurá BIGU_API_KEY en tu servidor}"
curl --include --request POST 'https://bigu.ai/api/v1/facturas' \
  --header "Authorization: Bearer $BIGU_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "external_id": "venta-2026-001",
  "tipo_cfe": 111,
  "fecha": "2026-10-06",
  "contado": true,
  "moneda": "UYU",
  "receptor": {
    "tipo_documento": 2,
    "documento": "214844360018",
    "razon_social": "Receptor de ejemplo",
    "direccion": "Domicilio del receptor",
    "ciudad": "Montevideo"
  },
  "lineas": [
    {
      "nombre": "Servicio",
      "cantidad": 1,
      "unidad_medida": "un",
      "precio_unitario": 100000,
      "categoria_iva": "tasa_basica"
    }
  ]
}
JSON

La respuesta de ejemplo es HTTP 202. Confirma que se encoló el pedido; todavía no significa aceptación de DGI. nueva distingue un envío nuevo de un reintento.

{
  "external_id": "venta-2026-001",
  "estado": "pendiente",
  "nueva": true
}

3. Consultá el estado

Usá el mismo identificador y la misma clave para consultar:

curl --include 'https://bigu.ai/api/v1/facturas/venta-2026-001' \
  --header "Authorization: Bearer $BIGU_API_KEY"

Esta es una respuesta de ejemplo HTTP 200 cuando DGI ya aceptó el comprobante. serie y numero los asigna el motor fiscal; no los elegís al emitir. Una consulta devuelve nueva: false.

{
  "external_id": "venta-2026-001",
  "estado": "aceptada",
  "nueva": false,
  "serie": "A",
  "numero": 123
}

Mientras esté pendiente, firmada o enviada, consultá cada cinco segundos y después con espera creciente. Revisá motivo cuando haya observaciones o un rechazo; un estado en_duda requiere conciliación antes de repetir o entregar el comprobante.

Planes y límites

La API está incluida junto con la web en Bigu Facturas, sin un adicional por usar ambos canales. La oferta estándar no tiene límite de comprobantes; la tarifa profesional incluye hasta cinco por mes calendario, compartidos con la web, el asistente y las tareas programadas. Consultá las condiciones y precios vigentes.

En Integra, cada nuevo e-Ticket o e-Factura pedido por API genera una venta y se emite desde ella, también si sólo incluye servicios. La emisión y su consulta devuelven además sale_id: abrí esa venta en Bigu para consultar su cuenta, cobros y comprobante. El mismo external_id conserva una sola venta y un solo comprobante, incluso si DGI falla o rechaza el envío. En Factura, siguen siendo comprobantes sueltos.

Con contado: true, la venta cobra sólo en UYU, con el medio de pago y la caja o cuenta por defecto de Nueva venta, si ese medio está habilitado. Si no puede registrar el cobro —otra moneda, efectivo con la caja sin su primera apertura o un cheque sin sus datos— queda a cobrar. Con contado: false, queda a cobrar en la cuenta del cliente. Si no hay cobro y falta el receptor, responde 409 sale_credit_customer_required sin guardar la venta ni el comprobante. Un e-Ticket sin receptor se admite cuando queda totalmente cobrado.

El receptor se busca por RUT o CI; si no existe, se crea. Si su nombre ya corresponde a otro cliente sin teléfono, se distingue con el documento, por ejemplo María Rodríguez · CI 12345678. Si ese nombre completo también está ocupado, devuelve 409 customer_name_already_exists: revisá la ficha existente.

Las notas de crédito y débito por API quedan como comprobantes sueltos en Integra, incluidos los originales históricos y las facturas externas. Si referencias[0] apunta a un comprobante que tiene venta, devuelve 409 sale_required: corregí desde esa venta para mantener sus saldos y stock. Al anular un comprobante suelto histórico, su nota conserva la sucursal fiscal del original. Las facturas programadas requieren receptor y generan una venta por fecha, sin registrar un cobro.

Si efactura falla después de guardar la venta, la emisión responde 503, con retryable: true, el código del servicio y sale_id. La venta y su posible cobro ya existen: reintentá con el mismo external_id y contenido. Cambiar la identidad puede duplicar la operación. Si falta numeración, resolvé el CAE antes de reintentar. El GET de un CFE todavía sin transmitir responde 200 desde el espejo, con estado: pendiente, sale_id y el motivo; ese estado no confirma que efactura lo haya recibido.

El reintento sólo transmite un comprobante en borrador cuya venta sigue confirmada; los otros estados se devuelven desde el espejo. Si anulaste la venta, responde 409 venta_anulada, con sale_id y retryable: false, sin llamar a efactura. Consultá la venta de origen: cargar un CAE o recuperar el servicio no habilita su emisión.

fecha define la fecha del CFE y el cálculo de los plazos. La venta y el cobro se registran con la hora real; una fecha fiscal de ayer no modifica la caja de ayer.

En otra moneda, el comprobante conserva su moneda y cotización y la venta registra sus importes en UYU. Las correcciones parciales y los comprobantes fiscales de cobranza sobre esas facturas todavía no están disponibles; los cobros comerciales siguen registrándose en la venta.

Cupo de la tarifa profesional

409 fiscal_monthly_limit_reached indica que el negocio alcanzó los cinco comprobantes del mes calendario en su zona horaria. El sexto envío nuevo queda bloqueado antes de transmitir y no cambia la tarifa ni genera un cobro. La persona dueña puede revisar el uso en Ventas y confirmar el cambio a Facturas sin límite desde Suscripción.

El cupo incluye notas de crédito y débito y se comparte entre todos los canales. Los borradores y las vistas previas no consumen cupo; los envíos pendientes reservan su lugar. Un reintento con el mismo identificador y contenido conserva su lugar original. Este cupo comercial es distinto del límite técnico de solicitudes por minuto: una consulta de estado no consume un comprobante.

Acceso

El endpoint de emisión es https://bigu.ai/api/v1/facturas. Consultá el OpenAPI para ver todos los campos y operaciones. El acceso al endpoint no reemplaza el alta fiscal ni los permisos de emisión del negocio.

Abrí Tu negocio › Facturación. En la tarjeta Conectá tu sistema, elegí la fila API de facturación para abrir su modal. Quien administra la facturación del negocio crea la clave allí. La clave se muestra una vez, se almacena como hash y vence a los 90 días. Se envía únicamente como Authorization: Bearer $BIGU_API_KEY. No la incluyas en URLs, código del navegador ni repositorios. Creá una segunda clave antes de revocar la anterior para rotar sin interrupciones. 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 el modal API de facturación, que abrís desde la tarjeta Conectá 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 el modal API de facturación, que abrís desde la tarjeta Conectá 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. Quien administra la facturación puede revocar la clave incluso cuando se restringe el acceso operativo del negocio.

Emitir

Los importes son enteros en centésimos y los precios incluyen IVA: 100000 = $1.000, salvo con precios_sin_iva (más abajo). 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 RUT, 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.

Código del catálogo y sucursal opcionales

El contrato OpenAPI 1.5.0, bajo las mismas rutas /api/v1, conserva estos campos opcionales y agrega sale_id a los errores de transmisión de una venta registrada:

Por ejemplo, podés sumar "codigo": "SKU-001" a una línea y "sucursal": "UUID_DE_TU_SUCURSAL" al documento. Conservá ambos campos al reintentar; cambiar cualquiera con el mismo external_id devuelve 409 idempotency_conflict.

Precios sin IVA

El contrato OpenAPI 1.6.0 agrega precios_sin_iva, opcional. Con "precios_sin_iva": true, precio_unitario y descuento de cada línea van sin IVA y el comprobante suma el IVA de cada tasa, calculado una sola vez sobre la suma de sus líneas y redondeado al centésimo. El comprobante muestra tu precio sin IVA y el IVA aparte. Sin el campo, los precios llevan el IVA adentro, como siempre, aunque en Bigu hayas elegido Mis precios son sin IVA. En Integra, la venta que se registra guarda esos precios sin IVA y su total incluye el IVA sumado. Conservá el campo al reintentar: cambiarlo con el mismo external_id devuelve 409 idempotency_conflict.

Reintentos sin duplicados

Si se pierde la respuesta del pedido venta-2026-001, conservá ese identificador y el mismo contenido. Cambiar a venta-2026-002 sería otro pedido, no la recuperación del primero.

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. En Integra también contiene sale_id, la venta generada por ese pedido. 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. Cobros, saldos, entregas y exportación por esta API admiten sólo el estado aceptada. Un comprobante observada queda fuera de esas operaciones y no cambia esperando: revisá el motivo y conciliá la corrección necesaria. Un estado en_duda requiere conciliación antes de entregar o repetir el envío. 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.

Errores

Las respuestas de error usan este formato. Por ejemplo, cambiar el contenido de un pedido reservado devuelve HTTP 409:

{
  "ok": false,
  "error": {
    "code": "idempotency_conflict",
    "message": "Ese external_id ya pertenece a otro contenido. Reintentá el pedido original o usá uno nuevo.",
    "retryable": false,
    "reference": "solicitud-001"
  }
}

retryable: true indica que podés reintentar la misma solicitud con espera creciente, conservando la identidad y el contenido. Un 429 incluye Retry-After: 60: esperá ese tiempo. retryable: false exige revisar la causa antes de volver a enviar; esperar por sí solo no corrige los datos, el permiso ni el plan. Si estás esperando la firma o aceptación, consultá el estado antes de repetir la operación.

La tabla reúne los códigos de la API y los que conserva del servicio fiscal y de los controles compartidos. El HTTP es el que recibe tu integración; un problema de autorización entre Bigu y el servicio fiscal se informa como 503, aunque tu clave sea válida.

Cuando falla la transmisión de una venta ya guardada, el mismo código fiscal puede llegar con 503, retryable: true y sale_id. Antes de que exista la venta, conserva su HTTP de validación. Guiate por el HTTP y retryable de esa respuesta y recuperá siempre la misma identidad.

Al emitir con POST /api/v1/facturas, un RUT inválido devuelve 400 invalid_request. 422 invalid_customer_rut corresponde a la preparación de clientes o reglas fiscales, no a esa emisión directa.

Guardá x-request-id y error.reference para soporte. No registres la clave ni datos fiscales en logs públicos. Si recibís un código más específico del servicio fiscal, conservá también el HTTP, message y retryable al consultar a soporte.

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.

Al crear o editar un cliente sin teléfono, un email repetido devuelve customer_email_already_exists sin guardar el cambio: revisá la ficha existente o usá otro email. Si esa ficha está archivada, reactivala antes de elegirla. Esta regla corresponde al alta y la edición; el traspaso de planillas y otros sistemas conserva sus propias reglas de conciliación.

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.

En Integra, la regla exige receptor. Las reglas antiguas activas con fechas vencidas quedan pausadas en este despliegue y sus ocurrencias pendientes anteriores quedan omitidas, con motivo. Reanudar lleva la próxima fecha a hoy o después, respetando la frecuencia y la última fecha: no emite esos períodos atrasados. Factura conserva su recorrido anterior.

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.