Create a Boleto Charge batch

POST

https://tenant.api.corpx.com/v1/accounts/:accountId/boleto/charge/batches

POST

/v1/accounts/:accountId/boleto/charge/batches

curl -X POST https://tenant.api.corpx.com/v1/accounts/accountId/boleto/charge/batches \
     -H "Idempotency-Key: Idempotency-Key" \
     -H "X-Tenant-Id: X-Tenant-Id" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Cobranças de setembro"
}'

{
  "batchId": "string",
  "name": "string",
  "status": "DRAFT",
  "totalItems": 1,
  "quotaReserved": 1,
  "statistics": {
    "generation": {
      "total": 1,
      "pending": 1,
      "processing": 1,
      "issued": 1,
      "failed": 1,
      "progressPercentage": 1.1
    },
    "payment": {
      "issued": 1,
      "paid": 1,
      "unpaid": 1,
      "overdue": 1,
      "paidAmount": 1.1,
      "conversionRate": 1.1
    }
  },
  "createdAt": "2024-01-15T09:30:00Z",
  "updatedAt": "2024-01-15T09:30:00Z",
  "items": [
    {
      "itemId": "string",
      "position": 1,
      "identifier": "string",
      "status": "ISSUED",
      "request": {
        "identifier": "string",
        "dueDate": "2023-01-15",
        "amount": {
          "nominal": 150.75,
          "currency": "BRL"
        },
        "payer": {
          "name": "Maria da Silva",
          "personType": "person",
          "taxNumber": "52998224725",
          "email": "string",
          "addressStreet": "string",
          "addressNumber": "string",
          "addressComplement": "string",
          "addressDistrict": "string",
          "addressCity": "string",
          "addressState": "SP",
          "addressZipCode": "01310100"
        },
        "issueDate": "2023-01-15",
        "interest": {
          "calculationModel": "string",
          "typeId": 1,
          "typeKey": "string",
          "value": 1.1,
          "startDate": "2023-01-15"
        },
        "fine": {
          "calculationModel": "string",
          "typeId": 1,
          "typeKey": "string",
          "value": 1.1,
          "startDate": "2023-01-15"
        },
        "discount": {
          "calculationModel": "string",
          "groups": [
            {
              "sequence": 1,
              "typeId": 1,
              "typeKey": "string",
              "value": 1.1,
              "limitDate": "2023-01-15"
            }
          ]
        },
        "abatement": {
          "amount": 1.1
        },
        "allowPartialPayment": true,
        "allowDivergentPayment": true,
        "divergentPaymentMode": "anyValue",
        "minPaymentAmount": 1.1,
        "maxPaymentAmount": 1.1,
        "expirationPolicy": {
          "allowPaymentAfterDueDate": true,
          "paymentLimitDate": "2023-01-15",
          "blockPaymentAfterLimit": true,
          "decursoGraceDays": 1
        }
      },
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z",
      "error": {
        "errorCode": "string",
        "message": "string"
      },
      "charge": {
        "chargeId": "string",
        "identifier": "string",
        "status": "string",
        "registrationCondition": "string",
        "barcode": "string",
        "digitableLine": "string",
        "ourNumber": "string",
        "amount": {
          "nominal": 1.1,
          "updatedAmount": 1.1,
          "paid": 1.1,
          "currency": "string"
        },
        "updatedAt": "2024-01-15T09:30:00Z"
      }
    }
  ],
  "page": 1,
  "pageSize": 1,
  "totalPages": 1,
  "hasNext": true,
  "dispatchedAt": "2024-01-15T09:30:00Z",
  "completedAt": "2024-01-15T09:30:00Z"
}

Creates an empty DRAFT batch for this account. Scope boleto_charge.manage; BaaS only. Add items in atomic chunks with PUT .../items, then dispatch once. Creating a draft consumes no issuance quota. Idempotency-Key is required; an exact retry returns the existing batch.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired

Account identifier.

Request

This endpoint expects an object.

namestringOptional<=120 characters

Optional operator-facing batch name.

Response

Idempotent retry; returns the existing batch

batchIdstring

Batch identifier.

namestring

Optional operator-facing name; empty when omitted.

statusenum

Batch lifecycle. Only DRAFT is editable. COMPLETED, PARTIAL_FAILED, and FAILED are terminal for issuance attempts; individual boleto registration and payment continue afterwards.

totalItemsinteger0-5000

Number of staged items.

quotaReservedinteger0-5000

Slots permanently reserved when dispatch was admitted.

statisticsobject

Current generation progress and payment conversion.

createdAtdatetime

Draft creation instant, in UTC.

updatedAtdatetime

Last persisted batch/statistics update, in UTC.

itemslist of objects

Current page of staged items and issuance results.

pageinteger

Current item page.

pageSizeinteger

Requested item page size.

totalPagesinteger

Number of item pages.

hasNextboolean

Whether another item page exists.

dispatchedAtdatetime or nullOptional

Instant quota was reserved and the batch was queued.

completedAtdatetime or nullOptional

Instant every issuance attempt reached an outcome.

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

Authentication

Path parameters

Headers

Request

Response

Errors