/ Comprobantes

Facturas

Emite facturas electrónicas (tipo 01) a clientes con RUC, consulta su estado y descarga XML, CDR y PDF.

Crear factura

POST/facturas

Crea la factura, calcula IGV y totales, genera y firma el XML y la encola para enviarla a SUNAT. La serie debe empezar con F (por ejemplo F001).

Campos principales

seriestringObligatorio: 4 caracteres.
fecha_emisiondateObligatorio: yyyy-mm-dd.
sucursal_idinteger: Sucursal que emite. Si no se envía, no se asocia a ninguna.
cod_localstring: Código de local anexo (4 caracteres). Por defecto el de la sucursal principal.
tipo_monedastring: PEN (por defecto), USD o EUR.
forma_pagostring: Contado (por defecto) o Credito.
fecha_vencimientodate: Obligatoria si forma_pago es Credito.
tipo_operacionstring: Catálogo 51. Por defecto 0101 (venta interna).
observacionstring: Máx. 500.
leyendastring: Leyenda personalizada (máx. 500).
pagosarray: Pagos asociados: [{ "metodo": "yape", "monto": 118.00 }].

Cliente

cliente.tipo_docstringObligatorio: Catálogo 06. En factura normalmente 6 (RUC).
cliente.num_docstringObligatorio: Máx. 15. El RUC lleva 11 dígitos y empieza con 10, 15, 17 o 20.
cliente.razon_socialstringObligatorio: Máx. 1500.
cliente.direccionstring: Máx. 500.
cliente.emailstring: Para enviar el comprobante.
cliente.telefonostring: Teléfono de contacto.

Ítems (items[])

descripcionstringObligatorio: Máximo 500 caracteres.
unidadstringObligatorio: Unidad de medida UN/CEFACT: NIU (unidad), ZZ (servicio), KGM, BG, etc.
cantidadnumberObligatorio: Mayor que 0.
precio_unitarionumberObligatorio: Precio unitario con IGV incluido.
codigostring: Código interno del producto (máx. 30).
cod_producto_sunatstring: Código UNSPSC de 8 dígitos. Será obligatorio desde 01/01/2027 si tu RUC está en el padrón de SUNAT.
tip_afe_igvstring: Afectación del IGV (catálogo 07). Por defecto 10 (gravado). 20 exonerado, 30 inafecto, 40 exportación, 15 gratuito.
porcentaje_igvnumber: Por defecto 18.
descuentosarray: Descuentos por ítem: [{ "cod_tipo": "00", "monto": 4.00 }] o con porcentaje.

Envía precio_unitario con IGV incluido: la API separa la base imponible y el impuesto. Para una factura de S/ 118.00 obtienes base 100.00 e IGV 18.00.

curl -X POST "https://apifact.gavi-cloud.com/api/v1/facturas" \
  -H "X-Api-Key: TU_API_KEY" \
  -H "X-Api-Secret: TU_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "serie": "F001",
    "fecha_emision": "2026-10-02",
    "tipo_moneda": "PEN",
    "forma_pago": "Contado",
    "cliente": {
      "tipo_doc": "6",
      "num_doc": "20555666777",
      "razon_social": "ACME CORP SAC",
      "direccion": "JR. ACME 456 - LIMA",
      "email": "facturas@acme.com"
    },
    "items": [
      {
        "codigo": "P001",
        "descripcion": "LAPTOP HP PAVILION 15",
        "unidad": "NIU",
        "cantidad": 2,
        "precio_unitario": 2950,
        "tip_afe_igv": "10"
      }
    ],
    "observacion": "Pedido #12345"
  }'

Respuesta201 Created

{
  "estado": "exito",
  "mensaje": "Factura creada y encolada para envío a SUNAT.",
  "datos": {
    "id": 123,
    "tipo_documento": "01",
    "serie": "F001",
    "correlativo": "00000123",
    "numero_completo": "F001-123",
    "fecha_emision": "2026-10-02",
    "mto_oper_gravadas": "5000.00",
    "mto_igv": "900.00",
    "mto_imp_venta": "5900.00",
    "leyenda": "SON CINCO MIL NOVECIENTOS CON 00/100 SOLES",
    "sunat_status": "pendiente",
    "sunat_code": null,
    "sunat_description": null
  }
}

Operaciones especiales

Cambia tip_afe_igv por ítem para operaciones no gravadas, y tipo_operacion / tipo_moneda para exportaciones.

Caso	Cómo enviarlo
Exonerada	`tip_afe_igv: "20"`
Inafecta	`tip_afe_igv: "30"`
Gratuita (bonificación)	`tip_afe_igv: "15"`
Exportación	`tipo_operacion: "0200"`, `tipo_moneda: "USD"`, `tip_afe_igv: "40"`
Bolsa plástica (ICBPER)	`icbper` y `factor_icbper` en el ítem
Venta al crédito	`forma_pago: "Credito"` y `fecha_vencimiento`

Listar facturas

GET/facturas

Devuelve los comprobantes de tu empresa, paginados y filtrables.

Parámetros de consulta

searchstring: Búsqueda libre: razón social, documento, serie o correlativo.
seriestring: Serie exacta (F001) o con comodín (F0%).
client_num_docstring: RUC o DNI exacto del cliente.
sunat_statusstring: pendiente, enviado, aceptado, rechazado o anulado. Acepta varios separados por coma.
fecha_desdedate: Fecha de emisión mínima (yyyy-mm-dd).
fecha_hastadate: Fecha de emisión máxima.
monto_minnumber: Total mínimo.
monto_maxnumber: Total máximo.
sucursal_idinteger: Filtra por sucursal.
constring: Relaciones a incluir: items, payments.
ordenar_porstring: fecha_emision, correlativo, mto_imp_venta, created_at (por defecto).
ordenstring: desc (por defecto) o asc.
por_paginainteger: Por defecto 15, máximo 100.

curl "https://apifact.gavi-cloud.com/api/v1/facturas?sunat_status=aceptado&fecha_desde=2026-10-01&fecha_hasta=2026-10-31" \
  -H "X-Api-Key: TU_API_KEY" \
  -H "X-Api-Secret: TU_API_SECRET"

Respuesta200 OK

{
  "estado": "exito",
  "datos": {
    "datos": [
      "..."
    ],
    "paginacion": {
      "pagina_actual": 1,
      "ultima_pagina": 8,
      "por_pagina": 15,
      "total": 112
    }
  }
}

Ver factura

GET/facturas/{id}

Devuelve el comprobante con sus ítems, pagos, estado SUNAT y, si ya fue rechazado, el código y descripción del error.

curl "https://apifact.gavi-cloud.com/api/v1/facturas/123" \
  -H "X-Api-Key: TU_API_KEY" \
  -H "X-Api-Secret: TU_API_SECRET"

Actualizar factura

PUT/facturas/{id}

Solo puedes modificar una factura que no haya sido aceptada por SUNAT; por ejemplo, para corregir una rechazada y reenviarla. Una factura aceptada se corrige con una nota de crédito.

curl -X PUT "https://apifact.gavi-cloud.com/api/v1/facturas/123" \
  -H "X-Api-Key: TU_API_KEY" \
  -H "X-Api-Secret: TU_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente": {
      "razon_social": "ACME CORP S.A.C."
    }
  }'

XML, CDR y PDF

Con el id de la factura descargas cada archivo. El PDF admite formato A4, A5 o ticket. El CDR está disponible cuando SUNAT aceptó el comprobante.

Método	Ruta	Devuelve
GET	/facturas/{id}/xml	XML firmado
GET	/facturas/{id}/cdr	CDR de SUNAT
GET	/facturas/{id}/pdf	Representación impresa
POST	/facturas/{id}/reenviar	Reenvía a SUNAT un comprobante pendiente o rechazado

curl "https://apifact.gavi-cloud.com/api/v1/facturas/123/pdf" \
  -H "X-Api-Key: TU_API_KEY" \
  -H "X-Api-Secret: TU_API_SECRET"