> ## Documentation Index > Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar fatura avulsa > Cria uma fatura separada do ciclo, com vencimento e formas de pagamento próprios. `POST /invoices` Faz parte do recurso [Faturas](/pt-BR/subscriptions/invoices) — o conceito, os oito estados e os links hospedados estão lá. Cria uma cobrança fora do ciclo, atrelada a uma assinatura: uma taxa de implantação, um acordo de dívida, um serviço pontual. O cliente recebe uma cobrança própria, com vencimento e formas de pagamento independentes da mensalidade. Para valores pequenos que podem esperar a virada do ciclo, prefira [lançar uma cobrança extra](/pt-BR/subscriptions/extra-items) — ela entra na fatura da mensalidade, sem gerar uma segunda cobrança. **O vencimento decide quando a cobrança dispara.** `dueAt` precisa ser futuro; a cobrança é disparada em `dueAt - chargeLeadTimeDays` da assinatura. Com folga, a fatura nasce `scheduled` e vira `open` na hora certa; vencimento próximo nasce `open` e cobra já. Se a data cair em fim de semana ou feriado e a conta só cobra em dia útil, o vencimento desliza para o próximo dia útil. A fatura participa do split da assinatura como qualquer outra e sai nos mesmos webhooks de fatura. Funciona também em contrato encerrado — é o caminho para cobrar um valor renegociado ou uma dívida remanescente. ## OpenAPI ````yaml openapi/billing.json POST /invoices openapi: 3.0.3 info: title: Z2Pay Billing API version: 1.0.0 description: Cobrança recorrente da Z2Pay — planos, assinaturas e faturas servers: - url: https://api.sandbox.z2pay.com/v1 description: Sandbox - url: https://api.z2pay.com/v1 description: Produção security: [] tags: - name: Invoices description: Faturas emitidas pelas assinaturas - name: Plans description: Planos de cobrança e versões de preço - name: Subscriptions description: Assinaturas recorrentes paths: /invoices: post: tags: - Invoices summary: Criar fatura avulsa description: >- Cria uma fatura separada, fora do ciclo — o cliente recebe uma cobrança própria, com vencimento e formas de pagamento independentes da mensalidade. Para valores pequenos que podem esperar a virada do ciclo, prefira `POST /subscriptions/{id}/extra-items`: entra na fatura da mensalidade, sem gerar uma segunda cobrança. O vencimento precisa ser futuro. A cobrança dispara em `dueAt - chargeLeadTimeDays` da assinatura: com folga, a fatura nasce `scheduled` e vira `open` na hora certa; vencimento próximo nasce `open` e cobra já. A fatura participa do split da assinatura como qualquer outra e aparece nos mesmos webhooks de fatura. Funciona também em contratos encerrados — é o caminho para cobrar um valor renegociado ou dívida remanescente de um contrato que já fechou. **Os `items` da fatura podem não estar disponíveis imediatamente.** O `total` desta resposta já é o definitivo; a composição aparece em `GET /invoices/{id}`, que pode devolver `items` vazio nos instantes seguintes. O webhook `invoice.issued` marca o momento em que ela está completa. operationId: InvoiceController_create parameters: - name: Idempotency-Key in: header required: false description: Chave única para garantir idempotência da requisição schema: type: string requestBody: required: true content: application/json: schema: type: object properties: subscriptionId: type: string minLength: 1 description: >- Assinatura dona da fatura. Aceita contratos encerrados — é o caminho para cobrar um valor renegociado ou dívida remanescente. description: type: string minLength: 1 maxLength: 200 description: >- O que está sendo cobrado (aparece na linha da fatura e na página de pagamento). amount: type: integer minimum: 0 exclusiveMinimum: true description: >- Valor unitário, em centavos (menor unidade da moeda). A moeda é a da assinatura. quantity: type: integer minimum: 0 exclusiveMinimum: true default: 1 description: >- Quantidade. Default `1` — o total da fatura é `amount * quantity`. dueAt: type: string format: date-time description: >- Vencimento (ISO 8601 com timezone), estritamente no futuro. A cobrança dispara em `dueAt - chargeLeadTimeDays` da assinatura; se a data cair em fim de semana ou feriado e a política da conta só cobrar em dia útil, o vencimento desliza para o próximo dia útil. reason: type: string enum: - extra_service - adjustment - penalty - ad_hoc - other description: Classificação da cobrança, para auditoria e relatório. reasonDetails: type: string minLength: 1 maxLength: 500 description: >- Justificativa em texto livre (1 a 500 caracteres). Fica na trilha de auditoria — o pagador não vê; o que ele vê é `description`. allowedPaymentMethods: type: array items: type: string enum: - card - pix - boleto minItems: 1 maxItems: 3 description: >- Formas de pagamento oferecidas na página de pagamento desta fatura. Ausente = o método padrão da assinatura. installmentsConfig: type: object properties: maxInstallments: type: integer minimum: 1 maximum: 12 freeInstallments: type: integer minimum: 1 maximum: 12 interestRate: type: number minimum: 0 maximum: 100 required: - maxInstallments nullable: true description: >- Parcelamento oferecido ao pagador no cartão — só faz sentido com `card` em `allowedPaymentMethods`. Ausente/null = à vista. required: - subscriptionId - description - amount - dueAt - reason - reasonDetails responses: '201': description: Fatura criada '400': description: Vencimento no passado ou corpo inválido content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: >- Identificador estável do erro. É por ele que você deve ramificar, não pela mensagem. message: type: string description: >- Descrição legível. Pode mudar sem aviso e não deve ser usada em condicional. issues: type: array description: >- Um item por campo rejeitado. Nunca vem vazio: se há 400 de validação, há pelo menos um. items: type: object properties: path: type: string description: >- Campo que falhou. Vem vazio quando o erro é do corpo como um todo. message: type: string description: O que há de errado com esse campo. example: error: code: VALIDATION_ERROR message: Validation failed issues: - path: status message: >- Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded - path: startDate message: >- Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z) '401': description: Chave de API ausente, malformada ou inválida content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: >- Identificador estável do erro. É por ele que você deve ramificar, não pela mensagem. message: type: string description: >- Descrição legível. Pode mudar sem aviso e não deve ser usada em condicional. example: error: code: UNAUTHORIZED message: Invalid API key '404': description: Assinatura não encontrada content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: >- Identificador estável do erro. É por ele que você deve ramificar, não pela mensagem. message: type: string description: >- Descrição legível. Pode mudar sem aviso e não deve ser usada em condicional. example: error: code: NOT_FOUND message: Invoice not found '409': description: >- Já existe uma requisição em andamento com esta Idempotency-Key. A API aguarda a primeira concluir por até 5 segundos antes de responder assim content: application/json: schema: type: object properties: error: type: string description: >- Mensagem do conflito de idempotência. Aqui `error` é texto, não objeto — ramifique pelo status HTTP. example: error: A request with this idempotency key is already being processed '422': description: >- Idempotency-Key já usada com um corpo diferente. Use uma chave nova para uma operação diferente content: application/json: schema: type: object properties: error: type: string description: >- Mensagem do conflito de idempotência. Aqui `error` é texto, não objeto — ramifique pelo status HTTP. example: error: Idempotency key already used with a different request body security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: API Key da Credential (gerada no Backoffice) ````