Facturas

REST API — Todos los endpoints requieren autenticación mediante Bearer token. Incluye Authorization: Bearer {token} en cada solicitud. Los tokens se gestionan en Configuración de GitScrum → API. Base URL: https://services.gitscrum.com — Todas las rutas de solicitud en esta documentación son relativas a esta URL base.

Crea, gestiona y realiza seguimiento de facturas durante todo su ciclo de vida: borrador, emisión, envío y pago.

Listar facturas

GET /company-invoices?company_slug={slug}

Devuelve todas las facturas del workspace.

Parámetros de query

Respuesta

{
  "data": [
    {
      "uuid": "inv-abc-123",
      "title": "January 2026 Services",
      "status": "sent",
      "client": {
        "uuid": "client-abc-123",
        "name": "Acme Corp"
      },
      "due_date": "2026-02-28",
      "currency": "USD",
      "subtotal": 8500,
      "tax": 0,
      "total": 8500,
      "issued_at": "2026-02-01T10:00:00Z",
      "paid_at": null,
      "created_at": "2026-01-28T09:00:00Z"
    }
  ]
}

Obtener factura

GET /company-invoices/{uuid}?company_slug={slug}

Devuelve los detalles completos de la factura incluyendo líneas de detalle.

Parámetros de ruta

Respuesta

{
  "data": {
    "uuid": "inv-abc-123",
    "title": "January 2026 Services",
    "status": "sent",
    "client": {
      "uuid": "client-abc-123",
      "name": "Acme Corp"
    },
    "due_date": "2026-02-28",
    "currency": "USD",
    "subtotal": 8500,
    "tax": 0,
    "total": 8500,
    "items": [
      {
        "description": "Frontend development",
        "quantity": 40,
        "unit_price": 150,
        "total": 6000
      },
      {
        "description": "Code review & QA",
        "quantity": 10,
        "unit_price": 250,
        "total": 2500
      }
    ],
    "issued_at": "2026-02-01T10:00:00Z",
    "paid_at": null,
    "created_at": "2026-01-28T09:00:00Z"
  }
}

Crear factura

POST /company-invoices

Crea una nueva factura en estado de borrador.

Cuerpo de la solicitud

Cada elemento en el array items:

Ejemplo

curl -X POST https://services.gitscrum.com/company-invoices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "company_slug": "acme",
    "contact_company_uuid": "client-abc-123",
    "title": "February 2026 Services",
    "due_date": "2026-03-31",
    "currency": "USD",
    "items": [
      {
        "description": "Development hours",
        "quantity": 60,
        "unit_price": 150
      }
    ]
  }'

Actualizar factura

PUT /company-invoices/{uuid}

Actualiza una factura existente. Acepta los mismos campos opcionales que crear más company_slug.

Parámetros de ruta

Emitir factura

POST /company-invoices/{uuid}/issue?company_slug={slug}

Cambia el estado de la factura de draft a issued.

Parámetros de ruta

Enviar factura

POST /company-invoices/{uuid}/send?company_slug={slug}

Envía la factura al cliente por email.

Parámetros de ruta

Marcar como pagada

POST /company-invoices/{uuid}/paid?company_slug={slug}

Marca la factura como pagada.

Parámetros de ruta

Respuesta

{
  "data": {
    "uuid": "inv-abc-123",
    "status": "paid",
    "paid_at": "2026-02-07T14:00:00Z"
  }
}

Eliminar factura

DELETE /company-invoices/{uuid}?company_slug={slug}

Elimina permanentemente una factura.

Parámetros de ruta

Estadísticas de facturas

GET /company-invoices/stats?company_slug={slug}

Devuelve estadísticas de facturas del workspace.

Respuesta

{
  "data": {
    "total": 45,
    "draft": 3,
    "issued": 2,
    "sent": 8,
    "paid": 32,
    "total_value": 185000,
    "paid_value": 142000
  }
}

Agregar línea de detalle

POST /company-invoices/{uuid}/item?company_slug={slug}

Agrega una línea de detalle a una factura.

Parámetros de ruta

Cuerpo de la solicitud

Listar líneas de detalle

GET /company-invoices/{uuid}/items?company_slug={slug}

Devuelve todas las líneas de detalle de una factura.

Parámetros de ruta

Eliminar línea de detalle

DELETE /company-invoices/{uuid}/item/{id}?company_slug={slug}

Elimina una línea de detalle de una factura.

Parámetros de ruta

Marcar como reembolsada

POST /company-invoices/{uuid}/refunded?company_slug={slug}

Marca la factura como reembolsada.

Parámetros de ruta

Ciclo de vida de la factura

draft → issued → sent → paid

1. Crear — la factura inicia como draft
2. Emitir — bloquea la factura, cambia estado a issued
3. Enviar — se entrega al cliente, cambia estado a sent
4. Marcar como pagada — registra el pago, cambia estado a paid

Referencia de campos