Recaudo Docs
Crear cuenta

Pagos y clientes

Facturas

Las facturas permiten gestionar cobros con soporte completo para parcialidades (pagos en cuotas), políticas de moratorios y seguimiento detallado de pagos. Ideal para colegiaturas, créditos y servicios recurrentes.

Endpoints disponibles

GET /v1/invoices Listar facturas
POST /v1/invoices Crear factura (con o sin parcialidades)
GET /v1/invoices/:id Obtener factura
PATCH /v1/invoices/:id Actualizar factura
DELETE /v1/invoices/:id Eliminar factura
POST /v1/invoices/:id/payments Registrar un pago (amount, forma_pago SAT, payment_date)
POST /v1/invoices/:id/void Anular factura
GET /v1/invoices/:id/installments Listar parcialidades
PATCH /v1/invoices/:id/installments/:installment_id Actualizar parcialidad

Crear factura

Crea una factura con items y opcionalmente configura parcialidades automáticas o manuales.

curl -X POST https://recaudo.app/api/v1/invoices \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8e250c25-9d84-4892-98ec-d71fc1fcd3c7",
    "document_date": "2024-01-15",
    "items": [
      {
        "description": "Colegiatura Enero 2024",
        "quantity": 1,
        "unit_price": 5000.00
      }
    ],
    "has_installments": true,
    "installment_count": 3,
    "installment_frequency": "monthly",
    "first_installment_due_date": "2024-01-20"
  }'
$response = $client->post('https://recaudo.app/api/v1/invoices', [
    'headers' => [
        'Authorization' => 'Bearer sk_live_tu_secret_key',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'customer_id' => '8e250c25-9d84-4892-98ec-d71fc1fcd3c7',
        'document_date' => '2024-01-15',
        'items' => [
[
    'description' => 'Colegiatura Enero 2024',
    'quantity' => 1,
    'unit_price' => 5000.00,
]
        ],
        'has_installments' => true,
        'installment_count' => 3,
        'installment_frequency' => 'monthly',
        'first_installment_due_date' => '2024-01-20',
    ]
]);
const response = await fetch('https://recaudo.app/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_tu_secret_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customer_id: '8e250c25-9d84-4892-98ec-d71fc1fcd3c7',
    document_date: '2024-01-15',
    items: [
      {
        description: 'Colegiatura Enero 2024',
        quantity: 1,
        unit_price: 5000.00
      }
    ],
    has_installments: true,
    installment_count: 3,
    installment_frequency: 'monthly',
    first_installment_due_date: '2024-01-20'
  })
});
response = requests.post(
    'https://recaudo.app/api/v1/invoices',
    headers={
        'Authorization': 'Bearer sk_live_tu_secret_key',
        'Content-Type': 'application/json',
    },
    json={
        'customer_id': '8e250c25-9d84-4892-98ec-d71fc1fcd3c7',
        'document_date': '2024-01-15',
        'items': [
{
    'description': 'Colegiatura Enero 2024',
    'quantity': 1,
    'unit_price': 5000.00
}
        ],
        'has_installments': True,
        'installment_count': 3,
        'installment_frequency': 'monthly',
        'first_installment_due_date': '2024-01-20'
    }
)

Parámetros de parcialidades

Parámetro Tipo Descripción
has_installments boolean Habilitar parcialidades
installment_count integer Número de parcialidades (2-48)
installment_frequency string weekly, biweekly o monthly
first_installment_due_date date Fecha de vencimiento de la primera parcialidad
late_fee_policy_id uuid ID de política de moratorios

Parcialidades manuales

Para mayor control, puedes definir cada parcialidad manualmente con sus propias fechas, montos y estado de pago. Útil para importar facturas existentes con pagos parciales.

Ejemplo de parcialidades manuales 
{
  "customer_id": "8e250c25-9d84-4892-98ec-d71fc1fcd3c7",
  "items": [
    { "description": "Servicio anual", "quantity": 1, "unit_price": 12000.00 }
  ],
  "installments": [
    {
      "due_date": "2024-01-15",
      "amount": 4000.00,
      "external_id": "FACT-001-P1",
      "is_paid": true,
      "amount_paid": 4000.00,
      "paid_at": "2024-01-10"
    },
    {
      "due_date": "2024-02-15",
      "amount": 4000.00,
      "external_id": "FACT-001-P2",
      "is_paid": false
    },
    {
      "due_date": "2024-03-15",
      "amount": 4000.00,
      "external_id": "FACT-001-P3",
      "is_paid": false
    }
  ]
}

Objeto factura (Invoice)

Objeto factura con parcialidades 
{
  "id": "263bb741-94bf-4aa5-9f47-6e64b82ba7e9",
  "object": "invoice",
  "invoice_number": "INV-2024-0001",
  "external_id": "FACT-001",
  "status": "partial",
  "customer_id": "8e250c25-9d84-4892-98ec-d71fc1fcd3c7",
  "currency": "MXN",
  "subtotal": 5000.00,
  "tax_amount": 0,
  "total": 5000.00,
  "amount_paid": 1666.67,
  "amount_due": 3333.33,
  "document_date": "2024-01-15",
  "due_date": "2024-03-20",
  "has_installments": true,
  "installment_count": 3,
  "installment_frequency": "monthly",
  "items": [
    {
      "id": "ii_xyz789",
      "description": "Colegiatura Enero 2024",
      "quantity": 1,
      "unit_price": 5000.00,
      "total": 5000.00
    }
  ],
  "installments": [
    {
      "id": "inst_001",
      "installment_number": 1,
      "status": "paid",
      "principal_amount": 1666.67,
      "late_fee_amount": 0,
      "total_amount": 1666.67,
      "amount_paid": 1666.67,
      "amount_due": 0,
      "due_date": "2024-01-20",
      "paid_at": "2024-01-18T14:30:00Z",
      "days_overdue": 0,
      "external_id": null
    },
    {
      "id": "inst_002",
      "installment_number": 2,
      "status": "pending",
      "principal_amount": 1666.67,
      "late_fee_amount": 0,
      "total_amount": 1666.67,
      "amount_paid": 0,
      "amount_due": 1666.67,
      "due_date": "2024-02-20",
      "paid_at": null,
      "days_overdue": 0,
      "external_id": null
    },
    {
      "id": "inst_003",
      "installment_number": 3,
      "status": "pending",
      "principal_amount": 1666.66,
      "late_fee_amount": 0,
      "total_amount": 1666.66,
      "amount_paid": 0,
      "amount_due": 1666.66,
      "due_date": "2024-03-20",
      "paid_at": null,
      "days_overdue": 0,
      "external_id": null
    }
  ],
  "created_at": "2024-01-15T00:00:00Z"
}

Estados de las parcialidades

Estado Descripción
pending Pendiente de pago, no vencida
partial Pago parcial recibido
paid Completamente pagada
overdue Vencida sin pagar (puede generar moratorios)
cancelled Cancelada (factura anulada)

Moratorios

Las parcialidades vencidas pueden generar moratorios automáticamente según la política configurada. El campo late_fee_amount muestra el moratorio acumulado y se suma al total_amount de la parcialidad.

Importante: Los moratorios se calculan sobre el saldo pendiente del principal, no sobre moratorios previos (evita interés compuesto no deseado).

¿Te sirvió esta página? Gracias por avisarnos.
Esc