CompanyInvoiceDelivery

Apply one operation to a set of invoices

Applies one operation to a set of invoices of this company and reports, invoice by invoice, which succeeded and which failed.

  • Operations: ISSUE issues the draft invoices; STATUS moves them to the new_status given in the body.
  • Limit: up to 50 invoices per request (invoice_ids).
  • Not atomic: each invoice is processed on its own, and since issuing is irreversible, the ones already issued stay issued if a later one fails.
  • Related: downloading PDFs, sending email and exporting are not operations of this batch — use …/invoices/pdf-archive, …/invoices/deliveries and …/invoices/exports.
post/v1/companies/{company_id}/invoices/batches

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/invoices/batches
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

operation'ISSUE' | 'STATUS' required
  • ISSUE: issue the draft invoices, each one assigned its definitive number.
  • STATUS: change the status of the invoices; requires new_status.
invoice_idsUUID[] required
new_status'SENT' | 'PAID'

Target status. Required when operation is STATUS.

payment_datestring date

Payment date. Required when new_status is PAID.

Example request

{
  "invoice_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "payment_date": "2025-01-15"
}

Response

Batch completed (may include partial failures)

successboolean required

Example response

{
  "success": true,
  "data": {
    "total": 5,
    "successful": 4,
    "failed": 1,
    "failures": [
      {
        "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
        "reason": "Only draft invoices can be issued"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.