# Criar uma instrução de coleta

Create a collection instruction for a user's Link. While an item's collection window is open, Belvo checks the balances of the user's accounts several times a day. When one account has at least the item's amount plus BRL 0.01, Belvo sets the item to CHARGE_SETTLED and sends you the item_ready_to_charge webhook. You then create the Charge yourself, using Payments (Brazil). For every item status and the webhook payload, see the Smart Collections statuses and webhooks article.

Before you send the request, check that:

  - The link_id is an active, confirmed Link of your organization, with exactly one data consent.
  - Every item has at least one collection window that ends in the future. If one item doesn't, Belvo rejects the whole request.
  - Each policy amount is the same as its item's amount. Belvo doesn't use the policy amount yet.

This request is not idempotent, and external_id is not checked for uniqueness. If you retry after a timeout, first list your collection instructions to check whether the first request created one.

Errors: Belvo returns a 400 error only for problems with link_id or a body that is not valid JSON. Any other problem returns a 500 error, including a body that doesn't match the schema, an item with no window that ends in the future, a Link that doesn't have exactly one data consent, and a failure to read the Link's accounts.

Endpoint: POST /api/collection-instructions/
Version: 1.223.0
Security: basicAuth

## Request fields (application/json):

  - `link_id` (string, required)
    The link.id of the user's Open Finance Data Aggregation Link. Belvo reads the balances of the accounts shared through this Link.

The Link must belong to your organization, be active, and be confirmed. It must also have exactly one data consent.
    Example: "3b979abb-fd60-4d15-a655-8f462ca4ea8f"

  - `items` (array, required)
    The amounts you want to collect. Belvo monitors each item separately and sends a separate webhook for each one.

  - `items.amount` (string, required)
    The amount to collect, in BRL, as a decimal string.

Belvo considers an account ready to charge when its balance is at least this amount plus BRL 0.01. Belvo checks each account on its own and does not add balances across accounts.
    Example: "150.00"

  - `items.external_id` (string,null)
    Your own reference for this item, such as an invoice or installment number. Belvo returns it in the item_ready_to_charge webhook.

Belvo does not check that this value is unique, and it is not an idempotency key: if you send the same request twice, Belvo creates two instructions. Send null or omit the field if you don't need it.
    Example: "invoice-2026-11-0042"

  - `items.collection_policies` (array, required)
    The collection windows for this item. Belvo checks balances only while a window is open.

At least one window must end in the future when you create the instruction.

  - `items.collection_policies.start_date` (string, required)
    The first day of the window (YYYY-MM-DD). The window opens at 00:00 UTC on this date.
    Example: "2026-11-05"

  - `items.collection_policies.end_date` (string, required)
    The last day of the window (YYYY-MM-DD), inclusive. The window closes at the end of this date, in UTC.
    Example: "2026-11-10"

  - `items.collection_policies.amount` (string, required)
    The amount for this window, in BRL, as a decimal string.

Note: Belvo stores this value but does not use it yet. The balance check always uses the item's amount, so set this field to the same value as the item's amount.
    Example: "150.00"

## Response 201 fields (application/json):

  - `id` (string, required)
    The unique identifier of the collection instruction. Use it to get or cancel the instruction.
    Example: "c2a6f1d4-7b3e-4f5a-9c8d-1e2f3a4b5c6d"

  - `link_id` (string, required)
    The link.id whose accounts Belvo monitors for this instruction.
    Example: "3b979abb-fd60-4d15-a655-8f462ca4ea8f"

  - `status` (string, required)
    The status of the collection instruction. Can be one of:

  - PROCESSING: The instruction was created. It stays in this status until you cancel it, even after every item has reached a final status. Check each item's status to see how monitoring ended.
  - COMPLETED: Reserved for future use. Belvo does not currently set this status.
  - CANCELLED: You cancelled the instruction. Any items that were still PENDING or PROCESSING were cancelled too.
    Enum: "PROCESSING", "COMPLETED", "CANCELLED"

  - `created_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when Belvo created the instruction.
    Example: "2026-11-04T14:30:12.418230Z"

  - `updated_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when the instruction's status last changed.
    Example: "2026-11-04T14:30:12.418230Z"

  - `items` (array, required)
    The items of this instruction. The order of the items is not guaranteed.

  - `items.id` (string, required)
    The unique identifier of the item. Belvo sends it in the item_ready_to_charge webhook, and you use it to cancel the item or mark it as complete.
    Example: "8f14e45f-ceea-4e67-a3f2-2a1b9c3d7e10"

  - `items.amount` (string, required)
    The amount to collect, in BRL, as a decimal string with two decimal places.
    Example: "150.00"

  - `items.external_id` (string,null, required)
    The reference you sent when you created the item. null if you didn't send one.
    Example: "invoice-2026-11-0042"

  - `items.status` (string, required)
    The status of the collection instruction item. Can be one of:

  - PENDING: The item is waiting for its next scheduled balance check. Every new item starts in this status.
  - PROCESSING: A balance check for the item is in progress. After the check, the item returns to PENDING if no account had enough balance and a collection window is still open.
  - CHARGE_SETTLED: One of the user's accounts had enough balance, and Belvo sent you the item_ready_to_charge webhook. Monitoring stops. This status does not mean that a payment was made: you create the Charge yourself, using Payments (Brazil). If Belvo can't deliver the webhook, the item still moves to this status, so also check the instruction's details regularly.
  - POLICY_EXPIRED: All of the item's collection windows ended before any account had enough balance. Belvo does not send a webhook for this status.
  - CHARGE_REJECTED: Belvo could not read the balance of any of the user's accounts (for example, because the data consent is no longer valid). Belvo does not send a webhook for this status.
  - FAILED: An internal error stopped monitoring. Belvo does not send a webhook for this status.
  - COMPLETED: You marked the item as complete (for example, because you collected the amount outside Belvo), so Belvo stopped monitoring it.
  - CANCELLED: You cancelled the item, or the whole collection instruction.

CHARGE_SETTLED, POLICY_EXPIRED, CHARGE_REJECTED, FAILED, COMPLETED, and CANCELLED are final statuses.
    Enum: "PENDING", "PROCESSING", "CHARGE_SETTLED", "POLICY_EXPIRED", "CHARGE_REJECTED", "FAILED", "COMPLETED", "CANCELLED"

  - `items.created_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when Belvo created the item.
    Example: "2026-11-04T14:30:12.418230Z"

  - `items.updated_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when Belvo last updated the item. Belvo updates the item at every balance check, so for a PENDING item this is usually the time of its last check.
    Example: "2026-11-04T14:30:12.418230Z"

  - `items.collection_policies` (array, required)
    The collection windows of the item.

  - `items.collection_policies.id` (string, required)
    The unique identifier of the collection window.
    Example: "5d41402a-bc4b-4a76-b971-9d911017c592"

  - `items.collection_policies.start_date` (string, required)
    The first day of the window (YYYY-MM-DD). The window opens at 00:00 UTC on this date.
    Example: "2026-11-05"

  - `items.collection_policies.end_date` (string, required)
    The last day of the window (YYYY-MM-DD), inclusive. The window closes at the end of this date, in UTC.
    Example: "2026-11-10"

  - `items.collection_policies.amount` (string, required)
    The amount you sent for this window, in BRL, as a decimal string. Belvo does not use this value yet; the balance check uses the item's amount.
    Example: "150.00"

  - `items.collection_policies.created_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when Belvo created the window.
    Example: "2026-11-04T14:30:12.418230Z"

## Response 400 fields (application/json):

  - `code` (string)
    A unique error code that allows you to classify and handle the error programmatically. Can be one of:

  - required: link_id is missing from the request body.
  - invalid: link_id is not a UUID, or it is not an active and confirmed Link of your organization.
  - null: link_id is null.
  - parse_error: the request body is not valid JSON.
    Example: "invalid"

  - `message` (string)
    A short description of the error. For example:

  - This field is required.
  - Object with pk=3b979abb-fd60-4d15-a655-8f462ca4ea8f does not exist.
  - Must be a valid UUID.
    Example: "Object with pk=3b979abb-fd60-4d15-a655-8f462ca4ea8f does not exist."

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `field` (string,null)
    The name of the field where the error was encountered. For link_id errors, the value is link_id.
    Example: "link_id"

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (permission_denied) that allows you to classify and handle the error programmatically.
    Example: "permission_denied"

  - `message` (string)
    A short description of the error. For permission_denied errors, the description is:

  - You do not have permission to perform this action.
    Example: "You do not have permission to perform this action."

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    Um código de erro único (request_timeout) que permite classificar e lidar com o erro programaticamente.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 408 request_timeout.
    Example: "request_timeout"

  - `message` (string)
    Uma breve descrição do erro.

Para erros de request_timeout, a descrição é:

  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (server_error) that allows you to classify and handle the error programmatically.
    Example: "server_error"

  - `message` (string)
    A short description of the error. For server_error errors, the description is:

  - Server error (500)
    Example: "Server error (500)"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"