Faturas · Documentação

Endpoints disponíveis

GET /v1/invoices Listar faturas

POST /v1/invoices Criar fatura (com ou sem parcelas)

GET /v1/invoices/:id Obter fatura

PATCH /v1/invoices/:id Atualizar fatura

DELETE /v1/invoices/:id Excluir fatura

POST /v1/invoices/:id/payments Registrar um pagamento (amount, forma_pago SAT, payment_date)

POST /v1/invoices/:id/void Anular fatura

GET /v1/invoices/:id/installments Listar parcelas

PATCH /v1/invoices/:id/installments/:installment_id Atualizar parcela

Criar fatura

Cria uma fatura com itens e, opcionalmente, configura parcelas automáticas ou manuais.

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 das parcelas

Parâmetro	Tipo	Descrição
`has_installments`	boolean	Habilitar parcelas
`installment_count`	integer	Número de parcelas (2-48)
`installment_frequency`	string	`weekly`, `biweekly` o `monthly`
`first_installment_due_date`	date	Data de vencimento da primeira parcela
`late_fee_policy_id`	uuid	ID da política de juros de mora

Parcelas manuais

Para mais controle, você pode definir cada parcela manualmente com suas próprias datas, valores e status de pagamento. Útil para importar faturas existentes com pagamentos parciais.

Exemplo de parcelas manuais

{
  "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 fatura (Invoice)

Objeto fatura com parcelas

{
  "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"
}

Status das parcelas

Status	Descrição
pending	Pagamento pendente, não vencida
partial	Pagamento parcial recebido
paid	Totalmente paga
overdue	Vencida sem pagamento (pode gerar juros de mora)
cancelled	Cancelada (fatura anulada)

Juros de mora

As parcelas vencidas podem gerar juros de mora automaticamente conforme a política configurada. O campo late_fee_amount mostra os juros acumulados e é somado ao total_amount da parcela.

Importante: Os juros de mora são calculados sobre o saldo pendente do principal, não sobre juros anteriores (evita juros compostos indesejados).