Factura Nextfacturanext

API REST · versión 1

Conecta tus herramientas con Factura Next

La API permite a integraciones autorizadas consultar los datos del negocio y crear clientes, proveedores, facturas internas, gastos y pagos. La clave la crea el titular desde su cuenta y queda ligada a un solo negocio.

Descargar contrato OpenAPI 3.1
Antes de empezar
Necesitas un plan activo (Plan Adaptativo o Plan Illimitado) y el complemento API.

El titular genera una clave Test o Production en menú lateral → API. La clave completa se muestra una sola vez.

Envía la clave como Authorization: Bearer …. Guárdala en el servidor de tu integración. No la incluyas en navegadores, aplicaciones móviles, URLs, registros ni repositorios.

Las claves Test solo funcionan en entornos locales y de vista previa. Las claves Production solo funcionan en el despliegue de producción. Cada solicitud se limita a un negocio y a los permisos de la clave.

Solicitud y reintentos
JSON sobre HTTPS, con límites para proteger tus datos.

Usa Content-Type: application/json. El cuerpo máximo es 64 KB. Las listas aceptan limit (1–100) y offset (0–10000).

El límite es 120 solicitudes por minuto por clave. Una respuesta 429 incluye Retry-After. Las creaciones de facturas, gastos, pagos, devoluciones y anulaciones exigen Idempotency-Key; repite la misma clave después de un timeout.

Envía importes como enteros en unidades menores de la moneda e incluye el código de moneda. Las fechas de negocio son YYYY-MM-DD y se interpretan en la zona America/Montevideo.

Autenticación

curl "$FACTURA_NEXT_API_URL/api/v1/business" \
  -H "Authorization: Bearer $FACTURA_NEXT_API_KEY" \
  -H "Accept: application/json"

Define la URL base y la clave como secretos del servidor. Nunca uses una clave Supabase ni el rol service_role en una integración.

Crear una factura

curl -X POST "$FACTURA_NEXT_API_URL/api/v1/invoices" \
  -H "Authorization: Bearer $FACTURA_NEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-92831-invoice" \
  -d '{
    "client_id": "00000000-0000-4000-8000-000000000001",
    "issue_date": "2026-09-27",
    "payment_method": "contado",
    "currency": "UYU",
    "items": [{
      "description": "Servicio mensual",
      "quantity": 1,
      "unit_price_minor_units": 125000,
      "tax_type": "basica"
    }]
  }'

Rutas disponibles

Todas las rutas comienzan con /api/v1. Los identificadores siempre se resuelven dentro del negocio asociado a la clave.

Negocio y referencias

GET/business

Perfil seguro del negocio.

GET/plan/usage

Plan actual, complemento API, cuota anual y reinicio.

GET/reference/tax-types

Tipos de IVA aceptados.

Clientes y proveedores

GET / POST/clients

Consultar o crear clientes.

GET / PATCH/clients/{clientId}

Consultar o editar un cliente propio.

POST/clients/{clientId}/archive|restore

Archivar o restaurar un cliente.

GET / POST/suppliers

Consultar o crear proveedores.

GET / PATCH/suppliers/{supplierId}

Consultar o editar un proveedor propio.

POST/suppliers/{supplierId}/archive|restore

Archivar o restaurar un proveedor.

Facturas, gastos, pagos y devoluciones

GET / POST/invoices

Consultar facturas internas o crear una nueva factura.

GET/invoices/{invoiceId}

Consultar una factura propia y sus líneas.

POST/invoices/{invoiceId}/void

Anular una factura permitida; requiere Idempotency-Key.

GET / POST/invoices/{invoiceId}/returns

Consultar devoluciones o crear una devolución y su reembolso.

GET / POST/expenses

Consultar gastos o crear un gasto para un proveedor existente.

GET/expenses/{expenseId}

Consultar un gasto propio y sus líneas.

GET / POST/payments

Consultar pagos o registrar un pago para una factura.

GET/payments/{paymentId}

Consultar un pago propio.

GET/receipts

Consultar comprobantes de pago registrados.

GET/receipts/{receiptId}

Consultar un recibo y su factura relacionada.

GET/returns/{returnId}

Consultar una devolución propia y sus líneas.

Planes y límite anual

El Plan Adaptativo permite crear 60 facturas por año, desde la fecha en que el negocio activa por primera vez su plan base. La factura 60 se guarda y la respuesta incluye limit_reached: true.

La factura 61 responde HTTP 409 con upgrade_required y no se guarda. La clave API no puede aceptar cargos. El titular debe aceptar el Plan Illimitado en Factura Next; luego la integración puede repetir la solicitud con la misma clave de idempotencia.

El Plan Illimitado no tiene límite de facturas. En el aniversario, el plan base vuelve al Plan Adaptativo y el complemento API conserva su estado. Consulta GET /plan/usage para la cuota y la fecha siguiente. La respuesta conserva base_plan como código estable (basic/pro) e incluye base_plan_name con el nombre visible del plan.

Errores

Los errores usan { "error": { "code", "message", "request_id" } }. Los campos inválidos incluyen una lista fields.

400 solicitud o clave de idempotencia inválida · 401 clave ausente, inválida, vencida o revocada, o complemento inactivo · 403 alcance insuficiente o plan no disponible · 404 registro no disponible para este negocio.

409 conflicto, límite del Plan Adaptativo o clave de idempotencia reutilizada con otros datos · 413 cuerpo demasiado grande · 415 contenido incorrecto · 422 validación · 429 límite de solicitudes · 500 error temporal. Cada respuesta contiene X-Request-Id.