GeneralInvoice

Una liquidación agrupada de comisiones y pagos entre la plataforma y un Provider, una Branch o una Account, por un período. Reúne una lista de GeneralInvoiceItem (una por orden / cargo pendiente) y define cuánto se le debe pagar (o cobrar) a ese destinatario.

Destinatario (related)

Relación polimórfica (related_type / related_id, ambos ocultos). related_type puede ser App\Provider, App\Branch o App\Account; en las rutas se usa el segmento providers, branches o accounts.

Estado (status)

  • pending — recién creada, todavía editable.
  • processing — conciliación en curso.
  • conciliated — cerrada: los montos quedaron firmes y se movió el balance correspondiente.

Flags (flags)

flags es un bitmask; los flags booleanos derivados se definen en onInitializeBitMaskBags(). Cubren dos ciclos paralelos:

  • Pago: is_payment_requested → is_payment_sent → is_payment_successful / is_payment_failed; payment_try_count cuenta los intentos y payment_index el número de pago.
  • Documento fiscal: is_invoice_doc_requested → is_invoice_doc_sent → is_invoice_doc_successful / is_invoice_doc_failed.
  • is_ignored_for_balance — la factura no impacta el balance del destinatario.

payment_status / payment_error / payment_via son la vista legible del ciclo de pago.

Ciclo de vida

conciliate cierra la factura (pasa a conciliated); luego send-payment (o batch-send-payments) dispara el pago al destinatario y set-paid lo marca pagado manualmente. PATCH solo aplica mientras está pending.

Montos

Cada monto tiene su versión formateada (string) y su versión _e2 (entero = monto × 100): subtotal (base de las órdenes), fee (comisión de la plataforma), discount (descuentos), delivery (envío) y total. total_to_pay_e2 es lo que finalmente se transfiere; fiscal_base_e2 la base imponible; branch_subtotal_e2 el subtotal de cara al comercio.

Estructura de Datos

Atributo Tipo Descripción
id int
number int Número correlativo de la factura
status string pending | processing | conciliated
count int Cantidad de ítems (órdenes) incluidos
total_e2 int Total de la factura (× 100)
subtotal string Subtotal formateado
fee string Comisión de la plataforma, formateada
total string Total formateado
related_type string Tipo del destinatario (App\Provider | App\Branch | App\Account) — oculto
related_id int Id del destinatario (oculto)
paid_at string\|null Momento en que se marcó pagada
notes string\|null Notas de la factura
created_at datetime\|null
updated_at datetime\|null
discount string Descuentos, formateados
flags int Bitmask del ciclo de pago y de documento fiscal (ver "Flags")
payment array\|null Datos del pago realizado al destinatario
config array Configuración de la factura (parámetros de generación / pago)
total_to_pay_e2 int\|null Monto que se transfiere efectivamente al destinatario (× 100)
company_id int\|null Company de la factura
payment_ref string\|null Referencia del pago
city_id int\|null Ciudad de la factura (para el balance de ciudad)
currency_conversion_factor float\|null Factor de conversión aplicado
currency_iso string\|null Moneda de la factura
delivery string\|null Montos de envío, formateados
delivery_base_e2 int\|null Base del envío (× 100)
delivery_discount_e2 int\|null Descuento del envío (× 100)
delivery_e2 int\|null Envío neto (× 100)
delivery_fee_e2 int\|null Comisión de envío (× 100)
discount_e2 int\|null Descuentos (× 100)
fee_e2 int\|null Comisión de la plataforma (× 100)
fiscal_base_e2 int\|null Base imponible (× 100)
subtotal_e2 int\|null Subtotal de las órdenes (× 100)
is_payment_requested bool BitMask (({@link self::flags} & 0x1) !== 0)
is_payment_sent bool BitMask (({@link self::flags} & 0x2) !== 0)
is_payment_successful bool BitMask (({@link self::flags} & 0x4) !== 0)
is_payment_failed bool BitMask (({@link self::flags} & 0x8) !== 0)
payment_try_count int BitMask (({@link self::flags} & 0xf0) >> 4)
payment_index int BitMask (({@link self::flags} & 0xf00) >> 8)
is_invoice_doc_requested bool BitMask (({@link self::flags} & 0x1000) !== 0)
is_invoice_doc_sent bool BitMask (({@link self::flags} & 0x2000) !== 0)
is_invoice_doc_successful bool BitMask (({@link self::flags} & 0x4000) !== 0)
is_invoice_doc_failed bool BitMask (({@link self::flags} & 0x8000) !== 0)
is_ignored_for_balance bool BitMask (({@link self::flags} & 0x10000) !== 0)
admin_url string
allLogs ApiLog>
balanceMovement BalanceMovement\|null Movimiento de balance generado al conciliar
branch_subtotal_e2 int\|null Subtotal de cara al comercio (× 100)
breakdown array\|null Desglose detallado de la factura
city City\|null
cityBalanceMovement BalanceMovement\|null Movimiento de balance de ciudad generado al conciliar
conciliations PendingFeeConciliation> Conciliaciones de cargos incluidas
currency Currency\|null
delivery_fee_commited_for_client_e2 int Envío comprometido a cubrir al cliente (× 100)
delivery_fee_paid_for_client_e2 int Envío efectivamente cubierto al cliente (× 100)
internal_ref string\|null Referencia interna de la factura
invoiceDocumentItem InvoiceDocumentItem\|null Ítem del documento fiscal asociado
items GeneralInvoiceItem> Ítems (una fila por orden / cargo)
logs ApiLog>
message_array array Mensaje de estado para mostrar
money Money\|null Total como objeto Money
payment_error string\|null Motivo del último fallo de pago
payment_object PayoutAccount\|null Cuenta de payout usada para el pago
payment_status string Estado legible del ciclo de pago
payment_via string\|null Medio por el que se pagó
payout_accounts array Cuentas de payout disponibles del destinatario
related Model\|Eloquent Destinatario de la factura ({@link Provider} / {@link Branch} / {@link Account})
subtotal_paid_for_client_e2 int Subtotal cubierto al cliente (× 100) 
{
    "id": 23,
    "number": 1,
    "status": "conciliated",
    "count": 7,
    "total_e2": 24792,
    "subtotal": "USD 271.56",
    "fee": "USD -23.64",
    "total": "USD 247.92",
    "paid_at": "2022-02-21 19:21:02",
    "notes": null,
    "created_at": "2022-02-21 19:05:18",
    "updated_at": "2025-04-10 16:47:23",
    "discount": "USD 0.00",
    "payment": null,
    "config": {
        "total_e2": 24792,
        "subtotal_e2": 27156,
        "fee_e2": -2364,
        "discount_e2": 0,
        "fiscal_base_e2": 34656
    },
    "total_to_pay_e2": 24792,
    "company_id": 116,
    "payment_ref": null,
    "city_id": 30,
    "is_payment_requested": false,
    "is_payment_sent": false,
    "is_payment_successful": false,
    "is_payment_failed": false,
    "payment_try_count": 0,
    "payment_index": 0,
    "is_invoice_doc_requested": false,
    "is_invoice_doc_sent": false,
    "is_invoice_doc_successful": false,
    "is_invoice_doc_failed": false,
    "is_ignored_for_balance": false,
    "payment_status": "not_available",
    "payment_error": null,
    "fiscal_base_e2": 34656,
    "subtotal_e2": 27156,
    "fee_e2": -2364,
    "branch_subtotal_e2": 27156,
    "discount_e2": 0,
    "delivery_base_e2": 0,
    "delivery_discount_e2": 0,
    "delivery_e2": 0,
    "delivery_fee_e2": 0,
    "breakdown": {
        "fiscal_tax_name": "IVA",
        "fiscal_tax_prc": 0.16,
        "total": {
            "amount_e2": 22270684,
            "currency_iso": "VES",
            "formatted_iso": "VES 222.706,84",
            "formatted": "222.706,84Bs"
        },
        "fiscal_base": {
            "amount_e2": 28421448,
            "currency_iso": "VES",
            "formatted_iso": "VES 284.214,48",
            "formatted": "284.214,48Bs"
        },
        "service_fee": {
            "amount_e2": 1671311,
            "currency_iso": "VES",
            "formatted_iso": "VES 16.713,11",
            "formatted": "16.713,11Bs"
        },
        "service_fee_taxes": {
            "amount_e2": 267410,
            "currency_iso": "VES",
            "formatted_iso": "VES 2.674,10",
            "formatted": "2.674,10Bs"
        },
        "service_fee_total": {
            "amount_e2": 1938721,
            "currency_iso": "VES",
            "formatted_iso": "VES 19.387,21",
            "formatted": "19.387,21Bs"
        },
        "total_to_pay": {
            "amount_e2": 20331964,
            "currency_iso": "VES",
            "formatted_iso": "VES 203.319,64",
            "formatted": "203.319,64Bs"
        },
        "currency_rate": 820.1018
    }
}

Endpoints

Insertar GeneralInvoice

Crear factura para un destinatario

Genera una GeneralInvoice en estado pending para el destinatario indicado por el prefijo {relatedType}/{relatedId} (providers, branches o accounts), con los cargos pendientes del período. Requiere el rol de gestión de facturas.

Método URI Cabeceras
POST /companies/{companyId}/{relatedType}/{relatedId}/general-invoices Authorization 
{
    "notes": "nullable|string",
    "order_ids": [
        "integer"
    ],
    "related_type": "string|in:providers,branches,accounts",
    "currency_conversion_factor": "nullable|numeric|min:0.000001"
}

Errores de negocio

Código HTTP Cuándo ocurre
ER404 404 El related_type indicado no es válido.
EF601 400 Ya existe una factura pendiente para ese destinatario; conciliarla o eliminarla primero.

Listar GeneralInvoice

{info} Soporta: Paginación Filters Carga dinámica

Listar facturas

Lista las GeneralInvoice de la company. Con el prefijo {relatedType}/{relatedId} (providers, branches o accounts) filtra por destinatario.

Método URI Cabeceras
GET /companies/{companyId}/{relatedType}/{relatedId}/general-invoices Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ER404 404 El related_type indicado no es válido.

Listar GeneralInvoice de Company

{info} Soporta: Paginación Filters Carga dinámica

Listar facturas

Lista las GeneralInvoice de la company. Con el prefijo {relatedType}/{relatedId} (providers, branches o accounts) filtra por destinatario.

Método URI Cabeceras
GET /companies/{companyId}/{relatedType}/{relatedId}/general-invoices Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ER404 404 El related_type indicado no es válido.

Mostrar GeneralInvoice

{info} Soporta: Paginación Filters Carga dinámica

Mostrar factura

Devuelve la GeneralInvoice por su id, con sus ítems, montos y estado de pago.

Método URI Cabeceras
GET /companies/{companyId}/general-invoices/{generalInvoiceId} Authorization

Actualizar GeneralInvoice

{info} Soporta: Paginación Filters Carga dinámica

Actualizar factura

Actualiza datos editables de una GeneralInvoice (notes, paid_at, currency_iso, currency_conversion_factor). Solo mientras está pending. Requiere el rol de gestión de facturas.

Método URI Cabeceras
PATCH /companies/{companyId}/general-invoices/{generalInvoiceId} Authorization 
{
    "notes": "nullable|string",
    "currency_conversion_factor": "nullable|numeric|min:0.000001"
}

Eliminar GeneralInvoice

Eliminar factura

Elimina una GeneralInvoice. Requiere el rol de gestión de facturas.

Método URI Cabeceras
DELETE /companies/{companyId}/general-invoices/{generalInvoiceId} Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EF600 400 La factura ya está conciliada y no se puede eliminar.
EF608 409 Ya se solicitó el documento fiscal de la factura.

Acciones de GeneralInvoice

Crear facturas en lote

Genera una GeneralInvoice pendiente para varios destinatarios a la vez (todos del tipo providers, branches o accounts). Requiere el rol de gestión de facturas.

Método URI Cabeceras
POST /companies/{companyId}/general-invoices Authorization 
{
    "notes": "nullable|string",
    "order_ids": [
        "integer"
    ],
    "related_type": "string|in:providers,branches,accounts",
    "currency_conversion_factor": "nullable|numeric|min:0.000001"
}

Errores de negocio

Código HTTP Cuándo ocurre
ER404 404 El related_type indicado no es válido.
EF601 400 Alguno de los destinatarios ya tiene una factura pendiente.

Previsualizar pagos de facturas en lote

{info} Soporta: Paginación Filters Carga dinámica

Devuelve, sin ejecutar nada, qué GeneralInvoice se pagarían y por cuánto con los filtros dados. Útil para revisar antes de disparar batch-send-payments.

Método URI Cabeceras
GET /companies/{companyId}/general-invoices/batch-send-payments Authorization 
{
    "type": "required|string|in:providers,branches,accounts",
    "mode": "required|string|in:pending,conciliated,failed,ids",
    "ids": [
        "integer|min:1"
    ],
    "date_beg": "date",
    "date_end": "date"
}

Enviar pagos de facturas en lote

{info} Soporta: Paginación Filters Carga dinámica

Dispara el pago automatizado de varias GeneralInvoice conciliadas a la vez (campo ids). Devuelve el resultado por factura.

Método URI Cabeceras
POST /companies/{companyId}/general-invoices/batch-send-payments Authorization 
{
    "type": "required|string|in:providers,branches,accounts",
    "mode": "required|string|in:pending,conciliated,failed,ids",
    "ids": [
        "integer|min:1"
    ],
    "date_beg": "date",
    "date_end": "date"
}

Errores de negocio

Código HTTP Cuándo ocurre
ER404 404 Alguno de los ids no corresponde a una factura de la company.

Realiza la concilicación de la factura (irreversible).

{info} Soporta: Paginación Filters Carga dinámica

Una vez conciliada una factura, ésta no puede ser modificada. Si se envía el parámetro send_payment = true, entonces se realizará un pago automatizado a los datos registrados del comercio o repartidor.

Método URI Cabeceras
POST /companies/{companyId}/general-invoices/{generalInvoiceId}/conciliate Authorization 
{
    "paid_at": "nullable|date",
    "notes": "nullable|string",
    "send_payment": "nullable|boolean",
    "payout_index": "nullable|integer"
}

Errores de negocio

Código HTTP Cuándo ocurre
EF600 400 La factura ya está conciliada.
EF607 400 El destinatario no tiene cuentas de payout configuradas (con send_payment).

Envía una solicitud de pago automatizado para la factura.

{info} Soporta: Paginación Filters Carga dinámica

Para usar este endpoint, la orden debe estar en status = conciliated y el payment_status debe ser not_available o failed.

El atributo payment_status revela información del estado actual de la solicitud de pago. Los valores posibles son:

  • not_available: Indica que no se ha solicitado un pago.
  • requested: La solicitud de pago ha sido enviada, pero aún no ha sido procesada por el sistema.
  • sent: La solicitud de pago ha sido procesada y enviada. En espera de confirmación.
  • failed: El pago ha fallado. La solicitud de pago ha terminado con un error.
  • successful: El pago ha sido procesado con éxito.
Método URI Cabeceras
POST /companies/{companyId}/general-invoices/{generalInvoiceId}/send-payment Authorization 
{
    "payout_index": "nullable|integer"
}

Errores de negocio

Código HTTP Cuándo ocurre
EF606 400 La factura no está conciliada.
EF603 409 El pago de la factura ya fue enviado.
EF604 409 La factura ya está pagada.
EF605 400 La conciliación de la factura venció; ya no se puede pagar.
EF607 400 El destinatario no tiene cuentas de payout configuradas.

Marca como pagada a una factura manualmente.

{info} Soporta: Paginación Filters Carga dinámica

Útil para que el sistema marque las facturas como pagadas cuando el API externo responde con algun error.

Método URI Cabeceras
POST /companies/{companyId}/general-invoices/{generalInvoiceId}/set-paid Authorization 
{
    "ref": "required|min:6|max:32"
}

Errores de negocio

Código HTTP Cuándo ocurre
EF606 400 La factura no está conciliada.
EF603 409 El pago de la factura ya fue enviado.
EF604 409 La factura ya está pagada.
EF613 409 El pago de la factura no está en estado fallido.

Eliminar facturas en lote

Elimina varias GeneralInvoice a la vez (campo ids). Cada una debe poder eliminarse (no conciliada, sin documento fiscal solicitado).

Método URI Cabeceras
DELETE /companies/{companyId}/general-invoices/batch-delete Authorization 
[
    "integer"
]

Relaciones