Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/eme2dev/Eme2App/llms.txt

Use this file to discover all available pages before exploring further.

The Invoices API is the core of Eme2App’s billing workflow. A factura moves through a lifecycle — borrador → confirmada → anulada — with strict transition rules. Confirming a factura automatically generates facturas_vencimientos (due-date instalments) derived from the assigned forma_pago. Voiding a confirmed invoice creates a mirror rectificativa with negative amounts. All endpoints require a Bearer token that contains a valid empresa_id. Base path: /api/facturas Authorization: Authorization: Bearer <token> with empresa_id embedded (call POST /api/auth/seleccionar-empresa first if needed).

​
Endpoint reference

MethodPathDescription
GET/api/facturasList invoices (paginated)
POST/api/facturasCreate invoice
GET/api/facturas/proximo-numeroNext available invoice number
GET/api/facturas/informe-cobrosCollections report
GET/api/facturas/:idGet invoice by ID
PUT/api/facturas/:idUpdate invoice
PUT/api/facturas/:id/estadoTransition invoice status
PATCH/api/facturas/:id/estado-emisionUpdate emission status
POST/api/facturas/:id/anularVoid a confirmed invoice
DELETE/api/facturas/:idDelete a draft invoice
POST/api/facturas/:id/enviar-emailSend PDF by email
POST/api/facturas/:id/cobrosRegister a collection against a vencimiento
GET/api/facturas/:id/cobrosList collections for an invoice
DELETE/api/facturas/:id/cobros/:cobro_idDelete cobro and revert vencimiento
PUT/api/facturas/cobros/:idUpdate a cobro
DELETE/api/facturas/cobros/:idDelete a cobro
GET/api/facturas/:id/vencimientosList all due dates
GET/api/facturas/:id/vencimientos-disponiblesList payable (pending/partial) due dates
POST/api/facturas/:id/vencimientosCreate a manual due date
PATCH/api/facturas/:id/vencimientos/:vencimiento_idUpdate a due date
DELETE/api/facturas/:id/vencimientos/:vencimiento_idDelete a due date
POST/api/facturas/:id/vencimientos/restaurarRestore due dates from forma_pago template
POST/api/facturas/:id/vencimientos/:vencimiento_id/revertir-cobroRevert all cobros on a due date

​
GET /api/facturas

Returns a paginated list of invoices belonging to the active company. Query parameters
ParameterTypeDescription
pageintegerPage number (default: 1)
pageSizeintegerResults per page (default: company setting)
Response 
{
  "datos": [
    {
      "id": "uuid",
      "numero": 42,
      "serie": "A",
      "fecha": "2024-03-15",
      "cliente_id": "uuid",
      "estado": "confirmada",
      "subtotal": "1000.00",
      "iva_monto": "210.00",
      "irpf_monto": "0.00",
      "total": "1210.00"
    }
  ],
  "paginacion": { "page": 1, "pageSize": 25, "total": 137 }
}

​
POST /api/facturas

Creates a new invoice in borrador status. Totals (subtotal, IVA, IRPF) are calculated server-side from the article catalogue; you do not send pre-computed tax amounts.
​
cliente_id
string (UUID)
required
ID of the client. Must belong to the active company.
​
numero
integer
required
Invoice number. Must be unique within the combination of empresa_id and serie. Use GET /api/facturas/proximo-numero to fetch the next available value.
​
fecha
string (YYYY-MM-DD)
required
Invoice date.
​
serie_id
string (UUID)
ID of the invoice series (series_facturas). Required when the company has usa_series = true.
​
serie
string
Series code (e.g. "A"). Alternative to serie_id; the server resolves the ID from the code.
​
forma_pago_id
string (UUID)
Payment terms. If omitted, the client’s forma_pago_defecto_id is used. Drives automatic vencimiento generation when the invoice is confirmed.
​
notas
string
Free-text notes printed on the invoice. Max 1000 characters.
​
detalles
array
required
Array of invoice line items. At least one line is required.
Response 
{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "mensaje": "Factura creada exitosamente"
}
The server rejects the request with 400 if numero is already used in the same empresa_id+serie scope, or if any articulo_id does not exist or is inactive.
curl example 
curl -s -X POST https://api.eme2app.com/api/facturas \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "cliente_id": "ccc11111-0000-0000-0000-000000000001",
    "numero": 43,
    "fecha": "2024-04-01",
    "serie_id": "sss00000-0000-0000-0000-000000000001",
    "forma_pago_id": "ppp00000-0000-0000-0000-000000000001",
    "notas": "Proyecto Q2",
    "detalles": [
      {
        "articulo_id": "aaa00000-0000-0000-0000-000000000001",
        "cantidad": 5,
        "precio_unitario": 200.00,
        "descripcion": "Horas de consultoría"
      }
    ]
  }'

​
GET /api/facturas/proximo-numero

Returns the next sequential invoice number for the given series. Query parameters
ParameterDescription
serie_idUUID of the series.
serieSeries code. Alternative to serie_id.
Response 
{ "proximo_numero": 44 }

​
GET /api/facturas/:id

Returns a single invoice with its header, line details, and totals.

​
PUT /api/facturas/:id

Full update of a borrador or confirmada invoice. The body mirrors POST /api/facturas. Existing line items are replaced entirely.
An invoice with registered cobros cannot be modified. Remove all cobros from the vencimientos panel before editing.

​
PUT /api/facturas/:id/estado

Transitions the invoice status.
​
estado
string
required
Target status. Allowed values: "borrador", "confirmada", "anulada".
Transition rules
FromToEffect
borradorconfirmadaGenerates vencimientos from forma_pago
confirmadaborradorDeletes vencimientos (only if none are cobrado/partial)
confirmadaanuladaUse POST /:id/anular instead
anuladaanyNot allowed

​
PATCH /api/facturas/:id/estado-emision

Updates the emission tracking state. Transitions are irreversible (one-way).
​
estado_emision
string
required
One of "sin_emitir", "pdf", "email". Can only progress forward.

​
POST /api/facturas/:id/anular

Voids a confirmed invoice by creating a rectificativa (mirror invoice with negative amounts). The original invoice is marked anulada.
​
serie_rectificativa
string
Code of the rectificative series to use. Required only when the company has more than one active rectificative series configured.
​
fecha_anulacion
string (YYYY-MM-DD)
Date of the void document. Defaults to today.
Response 
{
  "mensaje": "Factura 42 anulada. Se generó la factura 5 con serie R e importes en negativo.",
  "factura_anulada_id": "uuid-original",
  "factura_espejo_id": "uuid-rectificativa",
  "numero_factura_espejo": 5,
  "serie_factura_espejo": "R"
}
When the original invoice had cobros, the void operation creates corresponding negative cobros on the original invoice to zero out the accounting.

​
DELETE /api/facturas/:id

Permanently deletes a borrador invoice and its line items. If the invoice originated from a presupuesto and no other linked invoices remain, the presupuesto is restored to borrador.
Only draft invoices without registered cobros can be deleted. Confirmed invoices must be voided with POST /:id/anular first.

​
POST /api/facturas/:id/enviar-email

Sends the invoice PDF to a recipient. After a successful send, estado_emision is automatically updated to "email".
​
destino
string
required
Recipient email address.
​
pdf_base64
string
required
Base64-encoded PDF content generated client-side.
​
pdf_nombre
string
Attachment filename. Defaults to factura-{serie}-{numero}.pdf.
​
asunto
string
Email subject. Defaults to "Factura {serie}-{numero}".
​
texto
string
Email body text. Plain text, not HTML.
Only confirmed invoices (estado !== "borrador") can be sent. Draft invoices return 400.

​
GET /api/facturas/informe-cobros

Paginated report of all registered collections (cobros) for the active company.

​
POST /api/facturas/:id/cobros

Registers a collection against a specific vencimiento. Supports full and partial payment.
​
vencimiento_id
string (UUID)
required
The due-date instalment to pay.
​
importe
decimal
required
Amount collected. Must be > 0 and ≤ the vencimiento’s remaining balance.
​
fecha_pago
string (YYYY-MM-DD)
required
Date the payment was received.
​
instrumento_id
string (UUID)
required
Payment instrument (e.g. bank transfer, direct debit). Must be active.
​
notas
string
Optional internal note on the collection.
​
fecha_vencimiento_resto
string (YYYY-MM-DD)
Required for partial payments only. The due date for the remaining balance. Must be after fecha_pago.
Response (full payment) 
{
  "cobro": {
    "id": "uuid-cobro",
    "factura_id": "uuid-factura",
    "vencimiento_id": "uuid-vencimiento",
    "importe": 1210.00
  },
  "vencimiento_actualizado": { "id": "uuid-vencimiento", "estado": "cobrado" }
}
Response (partial payment) 
{
  "cobro": { "id": "uuid-cobro", "importe": 605.00 },
  "vencimiento_actualizado": { "id": "uuid-vencimiento", "estado": "partial", "importe": 605.00 },
  "vencimiento_nuevo": { "id": "uuid-resto", "importe": 605.00, "fecha_vencimiento": "2024-05-01", "estado": "pending" }
}

​
GET /api/facturas/:id/cobros

Returns all cobros for the invoice along with a payment summary. Response 
{
  "cobros": [
    {
      "id": "uuid",
      "importe": "1210.00",
      "fecha_pago": "2024-04-05",
      "instrumento_id": "uuid",
      "vencimiento_id": "uuid"
    }
  ],
  "resumen": {
    "total_factura": 1210.00,
    "total_cobrado": 1210.00,
    "pendiente": 0.00,
    "porcentaje_cobrado": 100
  }
}

​
DELETE /api/facturas/:id/cobros/:cobro_id

Deletes a cobro and reverts the associated vencimiento to pending. If the payment was partial and a rest vencimiento was created, that rest vencimiento is also removed. Response 
{ "mensaje": "Cobro eliminado exitosamente y vencimientos revertidos si fue necesario" }

​
PUT /api/facturas/cobros/:id

Updates metadata on a cobro (date, instrument, notes). The importe field cannot be changed for cobros linked to a vencimiento — delete and re-create the cobro instead.
​
fecha_pago
string (YYYY-MM-DD)
New payment date.
​
instrumento_id
string (UUID)
Replacement payment instrument.
​
referencia
string
External reference number.
​
notas
string
Internal note.

​
DELETE /api/facturas/cobros/:id

Deletes a cobro by its own ID and reverts the effect on its associated vencimiento (the vencimiento is restored to pending and any partial-payment rest vencimientos are removed). Functionally equivalent to DELETE /api/facturas/:id/cobros/:cobro_id but addressed directly by cobro ID, without needing the parent invoice ID. Path parameter
ParameterDescription
:idUUID of the cobro to delete.
Response 
{ "mensaje": "Cobro eliminado exitosamente" }
curl example 
curl -s -X DELETE https://api.eme2app.com/api/facturas/cobros/ccc00000-0000-0000-0000-000000000001 \
  -H "Authorization: Bearer $TOKEN"

​
GET /api/facturas/:id/vencimientos

Returns all due-date instalments for the invoice, including their current estado (pending, partial, cobrado, overdue).

​
GET /api/facturas/:id/vencimientos-disponibles

Returns only vencimientos with status pending or partial — i.e. those that can still receive a cobro.

​
POST /api/facturas/:id/vencimientos

Manually adds a new due-date instalment to a confirmed invoice.
​
numero_cuota
integer
required
Instalment sequence number. Must not duplicate an existing cuota on this invoice.
​
importe
decimal
required
Amount due on this instalment.
​
fecha_vencimiento
string (YYYY-MM-DD)
required
Due date.
​
instrumento_id
string (UUID)
Payment instrument. Falls back to the company’s default instrument.
​
notas
string
Optional note.

​
PATCH /api/facturas/:id/vencimientos/:vencimiento_id

Updates an existing vencimiento. If the vencimiento has a cobro, only fecha_vencimiento and notas can be changed (the importe is locked to the cobro amount).
​
importe
decimal
New instalment amount.
​
fecha_vencimiento
string (YYYY-MM-DD)
New due date.
​
instrumento_id
string (UUID)
Replacement instrument.
​
notas
string
Updated note.

​
DELETE /api/facturas/:id/vencimientos/:vencimiento_id

Removes a vencimiento. Blocked if the vencimiento has a cobro or is part of an agrupador.

​
POST /api/facturas/:id/vencimientos/restaurar

Regenerates the full vencimiento schedule from the invoice’s forma_pago template. Only available for confirmed invoices with no existing cobros.

​
POST /api/facturas/:id/vencimientos/:vencimiento_id/revertir-cobro

Reverts all cobros on a specific vencimiento, restoring it to pending. Any rest vencimientos created by partial payments are also removed. Use this to undo a collection entered in error. Response 
{
  "estado": "exito",
  "mensaje": "Vencimiento revertido: 1 cobro(s) eliminado(s)",
  "datos": {
    "id": "uuid",
    "estado": "pending",
    "importe": "1210.00",
    "fecha_vencimiento": "2024-04-30"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us