Criar cobranças em lote

Quando você precisa gerar várias cobranças de uma só vez — por exemplo, mensalidades de um grupo de clientes ou cobranças recorrentes do mês — utilize o endpoint de criação em lote.

Em uma única requisição é possível enviar até 50 clientes, cada um com seu próprio valor e dados. A Az.pague gera uma cobrança (link de pagamento) individual para cada um deles.

Endpoint

POST /api/v1/payment-link-bulk

O processamento do lote é assíncrono: a requisição retorna imediatamente com o token do lote e o status inicial. Você pode acompanhar o progresso pelo endpoint de status.

Exemplo de requisição

Exemplo de criação em lote

curl --request POST \
  --url https://sandbox.azpag.dev/api/v1/payment-link-bulk \
  --header 'Authorization: Bearer {token}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Cobranças Maio/2025",
    "title": "Mensalidade",
    "description": "Mensalidade do plano Premium",
    "enable_pix": true,
    "enable_credit": true,
    "installments": 3,
    "fee_mode": "customer_pay_fee",
    "expired_at": "2025-06-30",
    "expire_after_payment": true,
    "customers": [
      {
        "name": "Maria Souza",
        "email": "maria@exemplo.com",
        "phone": "51999990000",
        "document": "12345678901",
        "amount": 99.90,
        "reference": "INV-2025-05-001"
      },
      {
        "name": "João Lima",
        "email": "joao@exemplo.com",
        "phone": "51988887777",
        "document": "09876543210",
        "amount": 149.90,
        "reference": "INV-2025-05-002"
      }
    ]
  }'

Atributos do lote

Os atributos abaixo são aplicados a todas as cobranças geradas no lote, exceto quando sobrescritos individualmente pelo cliente.

Atributo	Tipo	Obrigatório	Descrição
name	Texto	Não	Nome interno do lote, utilizado para identificação no painel. Limite de 150 caracteres.
title	Texto	Não	Título padrão exibido na página de cobrança.
description	Texto	Não	Texto auxiliar padrão das cobranças. Limite de 1000 caracteres.
amount	Decimal	Não	Valor padrão da cobrança. Caso omitido, é obrigatório informar o valor em cada cliente.
additional_amount	Decimal	Não	Valor adicional opcional somado a cada cobrança.
bg_color	Texto	Não	Cor de fundo da página em formato hexadecimal.
show_company_logo	Boolean	Não	Exibe o logo da empresa na página de cobrança.
expired_at	Data	Não	Data de expiração padrão no formato YYYY-MM-DD.
expire_after_payment	Boolean	Não	Invalida a cobrança após o primeiro pagamento confirmado.
enable_pix	Boolean	Não	Habilita o Pix em todas as cobranças.
enable_credit	Boolean	Não	Habilita o cartão de crédito.
enable_bank_slip	Boolean	Não	Habilita o boleto bancário.
installments	Inteiro	Não	Número máximo de parcelas no cartão (1 a 12).
fee_mode	Texto	Não	Define o modo de juros aplicado às cobranças: none, interest ou customer_pay_fee.
hide_customer_fields	Boolean	Não	Oculta os campos de dados do cliente na página de cobrança.
payment_link_rule_token	Texto	Não	Token da régua de cobrança aplicada a todas as cobranças do lote.
customers	Array	Sim	Lista de clientes que receberão uma cobrança. Mínimo de 1 e máximo de 50 clientes por requisição.

Modo de juros (fee_mode)

Campo único na API. Use fee_mode para definir como as taxas serão aplicadas na cobrança.

fee_mode	enable_fee	customer_pay_fee	cash_discount	Significado
none	false	false	false	Empresa absorve todas as taxas
interest	true	false	true	Juros incidem na parcela; à vista com desconto
customer_pay_fee	true	true	true	Repasse das taxas ao comprador

Atributos de cada cliente (customers[])

Atributo	Tipo	Obrigatório	Descrição
amount	Decimal	Sim	Valor cobrado desse cliente. Ex: 99.90
title	Texto	Não	Sobrescreve o título do lote para esse cliente específico.
description	Texto	Não	Sobrescreve a descrição do lote.
name	Texto	Não	Nome do cliente.
email	Texto	Não	E-mail do cliente.
phone	Texto	Não	Telefone do cliente, com DDD.
document	Texto	Não	CPF ou CNPJ do cliente, sem formatação.
cep	Texto	Não	CEP do cliente. O sistema carrega automaticamente o endereço com base nos dados atualizados dos Correios. Se o CEP informado for inválido ou incorreto, o cliente deverá preencher o campo manualmente no momento do pagamento.
number	Texto	Não	Número do endereço. Caso não informado, o cliente deverá preencher o campo no momento do pagamento.
reference	Texto	Não	Referência externa para identificar essa cobrança na sua aplicação.

Respostas

202: Accepted

{
  "data": {
    "token": "bulk_3kd0192",
    "name": "Cobranças Maio/2025",
    "status": "pending",
    "total": 2,
    "processed": 0,
    "percent": 0.00,
    "created_at": "2025-05-30 10:00:00",
    "updated_at": "2025-05-30 10:00:00"
  }
}

422: Unprocessable Entity

{
  "hasError": true,
  "response": {
    "customers": [
      "Adicione ao menos um cliente."
    ],
    "customers.0.amount": [
      "O valor de cobrança do cliente 1 é obrigatório."
    ]
  }
}

429: Too Many Requests

{
  "hasError": true,
  "response": "Too many requests."
}

500: Internal Server Error

{
  "hasError": true,
  "response": "Error on server, try again."
}

Acompanhando o progresso do lote

Após criar o lote, você pode acompanhar o processamento consultando:

Endpoint

GET /api/v1/payment-link-bulk/{token}/status

A resposta retorna o total de links a serem gerados, quantos já foram processados e o percentual concluído:

Exemplo de resposta de status

{
  "data": {
    "token": "bulk_3kd0192",
    "status": "processing",
    "total": 50,
    "processed": 32,
    "percent": 64.00
  }
}

Status possíveis do lote

Status	Descrição
pending	Lote criado, aguardando início do processamento.
processing	Geração dos links em andamento.
completed	Todas as cobranças foram geradas com sucesso.
partial_failure	Lote finalizado, mas algum cliente falhou na geração.
canceled	Lote interrompido pelo cancelamento manual.

Recomendamos consultar o status em intervalos de 5 a 10 segundos e parar quando receber um status final (completed, partial_failure ou canceled).

Consultando as cobranças geradas

Para obter a lista completa de cobranças geradas pelo lote, com a URL pública de cada uma:

Endpoint

GET /api/v1/payment-link-bulk/{token}

A resposta inclui o array payment_links com cada cobrança gerada, no mesmo formato retornado pelo endpoint de criação avulsa.

Adicionando mais clientes ao lote

Caso esteja construindo a lista em partes, é possível adicionar novos clientes a um lote existente:

Endpoint

POST /api/v1/payment-link-bulk/{token}/customers

A requisição aceita o mesmo array customers da criação, com o mesmo limite de 50 clientes por requisição.

Cancelando um lote

Para interromper um lote em processamento:

Endpoint

POST /api/v1/payment-link-bulk/{token}/cancel

As cobranças que ainda não foram geradas deixam de ser processadas. Cobranças já geradas e ainda não pagas podem ser canceladas individualmente através de DELETE /api/v1/payment-link/{slug}.