Facturas — API Reference

Listar Facturas


GET /api/v1/invoices



Scope requerido:

invoices:read



Parámetros de query

Parámetro Tipo Descripción
page integer Página (default: 1)
per_page integer Resultados por página (default: 25, max: 100)
status string Filtrar por estado: draft, posted, paid, cancelled, annulled
since string Facturas desde esta fecha (YYYY-MM-DD)
until string Facturas hasta esta fecha (YYYY-MM-DD)
q string Buscar por nombre de cliente o número de factura
Ejemplo

Parámetro	Tipo	Descripción
page	integer	Página (default: 1)
per_page	integer	Resultados por página (default: 25, max: 100)
status	string	Filtrar por estado: draft`,` posted`,` paid`,` cancelled`,` annulled
since	string	Facturas desde esta fecha (YYYY-MM-DD)
until	string	Facturas hasta esta fecha (YYYY-MM-DD)
q	string	Buscar por nombre de cliente o número de factura

bash
curl -X GET "https://vertex.app/api/v1/invoices?status=posted&per_page=10" \
  -H "Authorization: Bearer vtx_tu_key"



Respuesta

json
{
  "data": [
    {
      "id": "uuid",
      "internal_number": "FEL-2026-000042",
      "status": "posted",
      "invoice_date": "2026-02-15",
      "due_date": "2026-03-15",
      "customer": {
        "name": "Empresa Demo S.A.",
        "tax_id": "12345678",
        "email": "contacto@empresa.com"
      },
      "currency": "GTQ",
      "subtotal": 1000.00,
      "tax_amount": 120.00,
      "total_amount": 1120.00,
      "fel": {
        "uuid": "FEL-UUID",
        "series": "A",
        "number": "123456",
        "status": "certified"
      },
      "created_at": "2026-02-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 42,
    "total_pages": 5
  }
}





Obtener Factura


GET /api/v1/invoices/:id



Scope requerido:

invoices:read



Ejemplo

bash
curl -X GET "https://vertex.app/api/v1/invoices/uuid-de-la-factura" \
  -H "Authorization: Bearer vtx_tu_key"



Respuesta

Igual que un item de la lista, pero incluye el detalle de

items

json
{
  "data": {
    "id": "uuid",
    "internal_number": "FEL-2026-000042",
    "status": "posted",
    "items": [
      {
        "id": "uuid",
        "description": "Servicio de consultoría",
        "quantity": 2,
        "unit_price": 500.00,
        "total": 1000.00
      }
    ]
  }
}





Anular Factura


POST /api/v1/invoices/:id/void



Scope requerido:

invoices:void



Body

json
{
  "reason": "Cliente solicitó cancelación"
}

reason (string, requerido): Motivo de la anulación (mínimo 3 caracteres).


Respuesta

json
{
  "data": {
    "credit_note_id": "uuid-nota-de-credito",
    "credit_note_number": "NC-2026-000001",
    "original_invoice_id": "uuid",
    "status": "voided",
    "fel": {
      "uuid": "FEL-UUID-NC",
      "status": "certified"
    }
  }
}

Notas importantes

Solo se pueden anular facturas del mismo día (regla fiscal Guatemala)
La anulación genera automáticamente una Nota de Crédito
Si la factura tiene certificación FEL, la nota de crédito también se certifica
El inventario se revierte automáticamente si aplica