Cobranças

Cadastrar cobrança

Crie uma nova cobrança via Pix ou Boleto. Suporta cobranças únicas, parceladas, recorrentes e assinaturas, com notificações automáticas ao pagador e webhooks personalizados para cada evento.

Endpoint

POST

/invoices/applications/invoices

Content-Type: application/json
Authorization: Basic {token}

Headers

Campos da requisição

Envie no body da requisição um JSON com os campos abaixo. Os campos customerId, externalId, dueDate, paymentTypes, installmentCount e price são obrigatórios — os demais são opcionais.

Campo	Tipo	Obrigatório	Descrição
dueDate	ISO date	Obrigatório	Data de vencimento da cobrança no formato YYYY-MM-DD (ex: 2026-06-30).
paymentTypes	array	Obrigatório	Tipos de pagamento aceitos. Pelo menos um valor obrigatório. Valores aceitos: PIX, BOLETO.
installmentCount	number	Obrigatório	Número de parcelas da cobrança. Para cobranças únicas (SINGLE) envie 1; para parceladas (INSTALLMENT) envie o número total de parcelas.
price	number	Obrigatório	Valor da cobrança em reais. Mínimo de R$5,00. Pode ser omitido apenas se priceByCustomer for true.
customerId	UUID	Obrigatório	ID do cliente associado à cobrança. Toda cobrança precisa estar vinculada a um cliente já cadastrado (ver Cadastrar cliente).
externalId	string	Obrigatório	Identificador externo do seu sistema, usado para reconciliação. Aparece em todos os payloads de webhook, permitindo amarrar o evento ao registro correspondente no seu banco.
description	string	Opcional	Descrição da cobrança, exibida ao pagador. Máximo de 350 caracteres.
invoiceType	enum	Opcional	Tipo da cobrança: SINGLE, INSTALLMENT, RECURRING ou SUBSCRIPTION. Default: SINGLE.
frequency	enum	Opcional	Frequência da recorrência. Usado quando invoiceType é RECURRING ou SUBSCRIPTION.
endDate	ISO date	Opcional	Data limite para encerrar uma cobrança recorrente ou assinatura.
endInstallment	number	Opcional	Número da parcela em que a cobrança recorrente deve encerrar.
endSubscription	string	Opcional	Critério de fim de assinatura (usado em SUBSCRIPTION).
notifications	array	Opcional	Configuração de notificações ao pagador via Email, WhatsApp ou SMS (ver tabela Notifications abaixo).
webhooks	array	Opcional	Webhooks específicos desta cobrança que sobrescrevem os webhooks da aplicação (ver tabela Webhooks abaixo).
redirectTo	URL	Opcional	URL para a qual o pagador será redirecionado após concluir o pagamento.
priceByCustomer	boolean	Opcional	Quando true, permite que o pagador defina o valor da cobrança (price é ignorado).

Notifications

Opcional

O campo notifications é opcional. Porém, se enviado, deve ser um array onde cada objeto do array precisa respeitar as regras abaixo (type e channel são obrigatórios em cada item):

Campo	Tipo	Obrigatório	Descrição
type	enum	Obrigatório	Tipo do evento que dispara a notificação. Veja Valores aceitos abaixo.
channel	enum	Obrigatório	Canal de envio: Email, WhatsApp ou SMS.
period	number	Opcional	Quantidade de dias antes/depois do evento para enviar a notificação. Mínimo de 5 dias. Usado em SEND_INVOICE_REMINDER e INVOICE_RESEND.

Webhooks

Opcional

O campo webhooks é opcional. Porém, se enviado, deve ser um array onde cada objeto do array precisa conter os dois campos abaixo (ambos obrigatórios). Webhook por cobrança tem prioridade sobre webhook configurado no nível da aplicação. Veja os payloads de cada evento em Eventos e payloads.

Campo	Tipo	Obrigatório	Descrição
hookType	enum	Obrigatório	Tipo do evento que dispara o webhook. Veja eventos disponíveis em Eventos e payloads.
url	URL	Obrigatório	URL do seu endpoint HTTPS que receberá a notificação.

Valores aceitos

Os campos abaixo aceitam apenas valores específicos. Enviar valores fora desta lista resulta em erro de validação.

invoiceType

SINGLE

INSTALLMENT

RECURRING

SUBSCRIPTION

SINGLE: cobrança única. INSTALLMENT: parcelada em N parcelas. RECURRING: recorrência com data de término. SUBSCRIPTION: assinatura contínua.

paymentTypes (cada item)

PIX

BOLETO

Métodos de pagamento que serão oferecidos ao pagador.

frequency

WEEKLY

FORTWEEKLY

MONTHLY

BIMONTHLY

QUARTERLY

SEMESTER

YEARLY

Periodicidade das cobranças recorrentes/assinaturas.

notifications.type

SEND_FIRST_INVOICE_BY

INVOICE_GENERATED

INVOICE_CHANGED

SEND_INVOICE_REMINDER

SEND_INVOICE_AT_DAY

SEND_INVOICE_CODE_AT_DAY

INVOICE_FAIL

INVOICE_RESEND

INVOICE_CONFIRM_PAYMENT

Eventos que disparam o envio de uma notificação ao pagador.

notifications.channel

SMS

Canal por onde a notificação será enviada.

webhooks.hookType

INVOICE_CREATED

INVOICE_DELETED

PAYMENT_GENERATED

PAYMENT_CONFIRMED

Eventos que disparam um webhook para sua URL. Apenas estes quatro são efetivamente enviados pela API.

Exemplo de requisição

Exemplo com os principais campos preenchidos. Substitua $TOKEN pelo seu token Base64 e {{customerId}} pelo id real do cliente (veja Detalhe do cliente):

curl -X POST https://api.az.center/invoices/applications/invoices \
  -H "Authorization: Basic $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "{{customerId}}",
  "description": "Mensalidade junho/2026",
  "dueDate": "2026-06-30",
  "installmentCount": 1,
  "invoiceType": "SINGLE",
  "price": 150,
  "externalId": "ORDER-1234",
  "paymentTypes": ["PIX", "BOLETO"],
  "notifications": [
    { "type": "INVOICE_GENERATED", "channel": "Email" },
    { "type": "SEND_INVOICE_REMINDER", "channel": "Email", "period": 5 },
    { "type": "INVOICE_CONFIRM_PAYMENT", "channel": "Email" },
    { "type": "INVOICE_GENERATED", "channel": "WhatsApp" }
  ],
  "redirectTo": "https://seusite.com.br/obrigado",
  "webhooks": [
    { "hookType": "INVOICE_CREATED", "url": "https://seusite.com.br/webhooks/created" },
    { "hookType": "PAYMENT_GENERATED", "url": "https://seusite.com.br/webhooks/generated" },
    { "hookType": "PAYMENT_CONFIRMED", "url": "https://seusite.com.br/webhooks/paid" },
    { "hookType": "INVOICE_DELETED", "url": "https://seusite.com.br/webhooks/deleted" }
  ]
}'

cURL

Respostas

200 OK

Cobrança criada com sucesso

Retorna o objeto da cobrança criada, incluindo o array installments com as parcelas geradas e a url de pagamento pronta para ser enviada ao pagador.

{
  "id": "00000000-0000-0000-0000-000000000001",
  "description": "Mensalidade junho/2026",
  "invoiceType": "SINGLE",
  "price": 150,
  "dueDate": "2026-06-30T03:00:00.000Z",
  "installmentCount": 1,
  "customer": {
    "id": "00000000-0000-0000-0000-000000000002",
    "fullName": "Maria da Silva"
  },
  "installments": [
    {
      "id": "00000000-0000-0000-0000-000000000003",
      "price": 150,
      "pricePaid": 0,
      "status": "WAITING_PAYMENT"
    }
  ],
  "paymentTypes": [
    { "invoiceId": "00000000-0000-0000-0000-000000000001", "type": "PIX" },
    { "invoiceId": "00000000-0000-0000-0000-000000000001", "type": "BOLETO" }
  ],
  "url": "https://plataforma.ciabra.com.br/i/00000000-0000-0000-0000-000000000003",
  "externalId": "ORDER-1234",
  "createdAt": "2026-05-28T20:00:35.000Z"
}

JSON

Erro

Formato de resposta de erro

Em caso de erro de validação, a API retorna um envelope com code (status HTTP), message (descrição) e errors mapeando cada campo problemático para um array de mensagens.

{
  "code": <código HTTP>,
  "message": "<descrição do erro>",
  "errors": {
    "<campo>": ["<mensagem>"]
  }
}

Formato

Detalhe do cliente Detalhe da cobrança