Invoices

Las Invoices permiten emitir, enviar y gestionar facturas de clientes de forma programática. Cada factura genera un enlace de pago alojado y puede enviarse automáticamente por correo electrónico. Está vinculada a un Customer y puede contener una o varias líneas de productos.

El flujo estándar es: crear una factura (draft) → finalizar → enviar por correo electrónico → esperar el pago (paid).

Ciclo de vida

draft→open→paid / void / uncollectible

Estado	Significado	Acción disponible
`draft`	Borrador: modificable, no enviada.	`/finalize/` para pasar a open.
`open`	Finalizada: enlace de pago activo.	`/send/`, `/pay/`, `/void/`.
`paid`	Pagada: pago recibido.	Ninguna acción posible.
`void`	Anulada: enlace desactivado.	Crear una nueva Invoice.
`uncollectible`	Declarada incobrable.	Solo acción manual.

Endpoints

Méthode	Endpoint	Description
POST	`/invoices/`	Crear una factura (estado draft)
GET	`/invoices/`	Listar las facturas
GET	`/invoices/{id}/`	Recuperar una factura
PATCH	`/invoices/{id}/`	Modificar una factura draft
POST	`/invoices/{id}/finalize/`	Finalizar (draft → open)
POST	`/invoices/{id}/send/`	Enviar por correo electrónico al Customer
POST	`/invoices/{id}/void/`	Anular una factura open
POST	`/invoices/{id}/pay/`	Marcar como pagada manualmente

¿Está clara esta introducción?

Esquema del objeto

ResponseObjeto Invoice

json

{
  "id": "inv_xxxxxxxxxxxx",
  "object": "invoice",
  "invoice_number": "2026-0042",
  "status": "open",
  "customer": "cust_xxxxxxxx",
  "customer_email": "client@email.com",
  "currency": "XAF",
  "subtotal": 50000,
  "tax_amount": 0,
  "discount_amount": 0,
  "total": 50000,
  "amount_paid": 0,
  "amount_remaining": 50000,
  "due_date": "2026-04-01",
  "description": "Facture de conseil — Mars 2026",
  "footer": "Merci de votre confiance.",
  "payment_url": "https://pay.sangho.ga/i/inv_xxxx",
  "pdf_url": "https://api.sangho.ga/v1/invoices/inv_xxxx/pdf/",
  "line_items": [
    {
      "product": "prod_xxx",
      "description": "Conseil stratégique",
      "quantity": 2,
      "unit_amount": 25000,
      "amount": 50000
    }
  ],
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Crear una Invoice

Crea una factura en estado draft. En esta fase es totalmente modificable. No se envía ningún correo electrónico y no hay ningún enlace de pago activo.

POSTCuerpo de la solicitud

customerRequis

stringcust_...

ID del Customer destinatario de la factura. El correo electrónico y el nombre del Customer se utilizarán en la factura en PDF y en el correo de envío.

line_itemsRequis

array[object]

Líneas de facturación. Cada línea contiene un producto o un importe libre, una cantidad y un precio.

Cada elemento debe contener: product (ID de un Product existente) o bien description + unit_amount para una línea libre. quantity es un entero positivo (por defecto: 1). El IVA se calcula automáticamente según la configuración de su App.

currencyOptionnel

stringISO 4217défaut :moneda de la App

Código de moneda de la factura. Por defecto, se utiliza la moneda principal de su App.

due_dateOptionnel

stringYYYY-MM-DDdéfaut :D+30ex :2026-04-01

Fecha de vencimiento del pago. Se muestra en la factura en PDF y en el correo de envío.

Si no se indica, el vencimiento se fija 30 días después de la fecha de finalización (no de creación). Pasado el vencimiento, la factura sigue en open: Sangho no envía recordatorios automáticos. Puede implementar recordatorios mediante los webhooks invoice.payment_overdue.

descriptionOptionnel

string

Asunto o descripción de la factura. Aparece en el encabezado de la factura en PDF y en el correo.

footerOptionnel

string

Texto del pie de página de la factura en PDF. Útil para los avisos legales, el IBAN y las condiciones de pago.

Máx. 500 caracteres. Solo se muestra en el PDF, no en la página de pago en línea.

metadataOptionnel

object

Datos libres: referencia de orden de compra, número de contrato, etc.

Finalizar, Enviar, Anular

Finalizar (/finalize/): bloquea la factura y genera el enlace de pago. La factura pasa a open. Las líneas y el importe ya no se pueden modificar.

Enviar (/send/): envía la factura por correo electrónico al Customer con el enlace de pago y el PDF adjunto. Se puede llamar varias veces (recordatorio manual).

Finalizar + Enviar en una sola operación

Puede llamar a /finalize/ y después a /send/ inmediatamente a continuación. O bien pasar auto_send: true en el cuerpo de /finalize/ para activar el envío automáticamente al finalizar.

Anular (/void/): invalida definitivamente la factura. El enlace de pago se desactiva. Es irreversible: cree una nueva Invoice si es necesario.

¿Está claro el ciclo de vida de las Invoices?

Crear y enviar una factura

bash

# 1. Créer (draft)
curl -X POST https://api.sangho.ga/v1/invoices/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cust_xxxxxxxx",
    "currency": "XAF",
    "due_date": "2026-04-15",
    "description": "Prestation de conseil — Avril 2026",
    "footer": "Règlement sous 30 jours. IBAN : GA00 0000 0000.",
    "line_items": [
      { "product": "prod_xxx", "quantity": 2 },
      { "description": "Frais de déplacement", "unit_amount": 5000, "quantity": 1 }
    ]
  }'


# 2. Finaliser
curl -X POST https://api.sangho.ga/v1/invoices/inv_xxx/finalize/ \
  -H "Authorization: Bearer sk_prod_xxxx"


# 3. Envoyer par email
curl -X POST https://api.sangho.ga/v1/invoices/inv_xxx/send/ \
  -H "Authorization: Bearer sk_prod_xxxx"

Response201 Created — Draft

La factura se crea en draft. No se envía ningún correo ni hay ningún enlace activo. Se puede modificar mediante PATCH.

json

{
  "id": "inv_xxxxxxxxxxxx",
  "object": "invoice",
  "invoice_number": "2026-0042",
  "status": "draft",
  "customer": "cust_xxxxxxxx",
  "total": 55000,
  "currency": "XAF",
  "due_date": "2026-04-15",
  "payment_url": null,
  "pdf_url": null,
  "created_at": "2026-03-15T09:00:00Z"
}

Response200 OK — Finalizada (open)

La factura queda bloqueada. El enlace de pago está activo. Envíe /send/ para notificar al cliente.

Una vez finalizada, los line_items y el importe total ya no se pueden modificar. Cree una nueva Invoice en caso de error.

json

{
  "id": "inv_xxxxxxxxxxxx",
  "status": "open",
  "total": 55000,
  "payment_url": "https://pay.sangho.ga/i/inv_xxxx",
  "pdf_url": "https://api.sangho.ga/v1/invoices/inv_xxxx/pdf/",
  "updated_at": "2026-03-15T09:05:00Z"
}