> ## Documentation Index > Fetch the complete documentation index at: https://docs.besimplo.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar fatura avulsa > Cria uma fatura avulsa (`Order::Invoice`) para um cliente existente e a finaliza imediatamente (status `open`), disparando a notificação padrão de fatura criada. Diferente de uma assinatura, uma fatura avulsa cobra os itens uma única vez. **Fluxo canônico:** 1. `POST /api/v1/invoices` cria a fatura avulsa 2. `POST /api/v1/invoices/{invoice_id}/checkout` efetua a cobrança (PIX ou cartão de crédito) 3. Para PIX, a confirmação chega via webhook `invoice.paid`; para cartão, a resposta do checkout já retorna a fatura paga Todos os preços informados em `line_items` devem ser avulsos (`type: one_time`). Preços recorrentes são rejeitados com o erro `PRICE_NOT_ONE_TIME`; para cobrança recorrente, crie uma assinatura (`POST /api/v1/subscriptions`). **Limite de taxa:** 10 requisições por minuto por chave de API. ## OpenAPI ````yaml /api-reference/openapi.yml post /api/v1/invoices openapi: 3.1.0 info: title: API - Simplo version: 1.0.0 description: API para cobrança e assinaturas para contas Simplo contact: name: Simplo url: https://besimplo.com email: team@besimplo.com servers: - url: https://besimplo.com description: Produção security: - apiKeyAuth: [] tags: - name: Clientes description: Clientes são as pessoas que pagarão pelos produtos da sua conta - name: Produtos description: Produtos representam os bens ou serviços que você vende - name: Preços description: Preços definem quanto cobrar e a frequência de cobrança de um Produto - name: Assinaturas description: Assinaturas conectam clientes aos seus planos para cobrança recorrente - name: Checkout description: >- Sessões de checkout permitem que clientes completem pagamentos e assinaturas através de uma interface web - name: Faturas description: Faturas representam cobranças geradas para clientes - name: Tentativas de cobrança description: >- Cada tentativa de receber o valor de uma fatura, com vencimento próprio e limite de tentativas - name: Eventos description: > O registro do que aconteceu na conta, com o corpo congelado no instante do fato. O evento existe tenha ele sido entregue ou não: a entrega por webhook é um consumidor dele. Consulte, filtre pelo resultado da entrega e reenvie o que não chegou. - name: Webhooks description: > Os eventos do catálogo, enviados por HTTP POST para os endpoints cadastrados na sua conta. Cada conta registra até 5 endpoints, cada um com a sua URL, o seu filtro de eventos e o seu segredo. O corpo é o próprio evento: `"object": "event"` no topo, e `data.object` com o recurso a que ele se refere, no mesmo formato em que `GET /api/v1//{id}` o devolve. Toda entrega vai assinada, no padrão [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md). São três cabeçalhos — `webhook-id`, `webhook-timestamp` e `webhook-signature` — e a chave é o segredo `whsec_` daquele endpoint, visível no painel em **Configurações → Webhooks**. Responda 2xx rápido e processe depois. Uma entrega que falha é retentada até 10 vezes ao longo de 93 horas, então o mesmo evento pode chegar duas vezes: use o `evt_` do cabeçalho `webhook-id` como chave de idempotência. O que não chegou continua consultável por 30 dias em `GET /api/v1/events`, e `POST /api/v1/events/{id}/resend` manda de novo. paths: /api/v1/invoices: post: tags: - Faturas summary: Criar fatura avulsa description: > Cria uma fatura avulsa (`Order::Invoice`) para um cliente existente e a finaliza imediatamente (status `open`), disparando a notificação padrão de fatura criada. Diferente de uma assinatura, uma fatura avulsa cobra os itens uma única vez. **Fluxo canônico:** 1. `POST /api/v1/invoices` cria a fatura avulsa 2. `POST /api/v1/invoices/{invoice_id}/checkout` efetua a cobrança (PIX ou cartão de crédito) 3. Para PIX, a confirmação chega via webhook `invoice.paid`; para cartão, a resposta do checkout já retorna a fatura paga Todos os preços informados em `line_items` devem ser avulsos (`type: one_time`). Preços recorrentes são rejeitados com o erro `PRICE_NOT_ONE_TIME`; para cobrança recorrente, crie uma assinatura (`POST /api/v1/subscriptions`). **Limite de taxa:** 10 requisições por minuto por chave de API. operationId: createInvoice requestBody: description: Dados da fatura avulsa que será criada required: true content: application/json: schema: type: object required: - invoice properties: invoice: type: object required: - customer_id - line_items properties: customer_id: type: string pattern: ^cus_[0-9a-z]{26}$ description: >- ID do cliente que receberá a fatura, no formato TypeID com prefixo `cus_`. example: cus_01h455vb4pex5vsknk084sn02p line_items: type: array description: > Itens da fatura. Cada preço deve ser **avulso** (`type: one_time`). Preços recorrentes são rejeitados com o erro `PRICE_NOT_ONE_TIME`; para cobrança recorrente, crie uma assinatura (`POST /api/v1/subscriptions`). O total da fatura deve ser maior que zero; itens que somam R$ 0,00 são rejeitados com o erro `AMOUNT_MUST_BE_POSITIVE`. minItems: 1 maxItems: 100 items: type: object required: - price_id properties: price_id: type: string pattern: ^price_[0-9a-z]{26}$ description: >- ID do preço a ser cobrado, no formato TypeID com prefixo `price_`. example: price_01h455vb4pex5vsknk084sn02q quantity: type: integer description: Quantidade de unidades cobradas. minimum: 1 maximum: 2147483647 default: 1 example: 1 example: - price_id: price_01h455vb4pex5vsknk084sn02q quantity: 1 discounts: type: array description: > Descontos a serem aplicados na fatura, lançados como itens negativos, assim como nas sessões de checkout. Se o total dos descontos exceder ou igualar o subtotal dos itens (zerando a fatura), a requisição é rejeitada com `DISCOUNT_EXCEEDS_SUBTOTAL`. Envie somente o campo compatível com o tipo: `percentage` para descontos percentuais ou `amount` para descontos fixos. Combinações incompatíveis são rejeitadas com `INVALID_DISCOUNT`. items: type: object required: - type properties: type: type: string description: | Tipo de desconto: - percentage: Desconto percentual sobre o valor. - fixed: Valor fixo em centavos. enum: - percentage - fixed example: percentage percentage: type: integer description: >- Percentual de desconto. Obrigatório se type for 'percentage'. Entre 1 e 100. minimum: 1 maximum: 100 example: 10 amount: type: integer format: int64 description: >- Valor do desconto em centavos. Obrigatório se type for 'fixed'. R$ 5,00 = 500. example: 500 description: type: - string - 'null' nullable: true description: Descrição livre do desconto. example: Desconto de fidelidade external_code: type: - string - 'null' nullable: true maxLength: 255 description: > Código externo para integração com outros sistemas. Único por conta. Espaços nas bordas são removidos e valores em branco são tratados como nulos. example: PEDIDO-123 responses: '201': description: Operação realizada com sucesso content: application/json: schema: unevaluatedProperties: false allOf: - type: object required: - id - object - amount_due - created - currency - customer - live_mode - status - total properties: id: type: string pattern: ^in_[0-9a-z]{26}$ readOnly: true description: >- ID único da fatura, no formato TypeID com prefixo `in_`. example: in_01h455vb4pex5vsknk084sn02q object: type: string description: Tipo do objeto. Sempre 'invoice'. enum: - invoice example: invoice amount_due: type: integer description: Valor a pagar em centavos. R$ 99,90 = 9990. example: 9990 amount_paid: type: integer description: Valor já pago em centavos. R$ 99,90 = 9990. example: 0 amount_refunded: type: integer description: > Valor estornado em centavos. Permanece separado de `status`: uma fatura paga continua com `status: paid` depois de um estorno total ou parcial. example: 0 amount_remaining: type: integer description: Valor restante a pagar em centavos. R$ 99,90 = 9990. example: 9990 created: type: integer format: int64 readOnly: true description: Timestamp Unix da criação da fatura. example: 1704672000 currency: type: string description: Moeda do valor. Sempre 'brl' (Real brasileiro). enum: - brl example: brl customer: type: string pattern: ^cus_[0-9a-z]{26}$ description: >- ID do cliente associado à fatura, no formato TypeID com prefixo `cus_`. example: cus_01h455vb4pex5vsknk084sn02p customer_email: type: - string - 'null' nullable: true description: E-mail do cliente. example: joao.silva@exemplo.com customer_name: type: - string - 'null' nullable: true description: Nome do cliente. example: João Silva external_code: type: - string - 'null' nullable: true description: >- Código externo para integração com outros sistemas. Único por conta. example: PEDIDO-123 live_mode: type: boolean description: >- Indica ambiente de produção (true) ou sandbox (false). Dados de sandbox são limpos periodicamente. example: true paid: type: boolean description: Indica se a fatura foi paga. example: false payment_intent: type: - string - 'null' nullable: true pattern: ^pi_[0-9a-z]{26}$ description: > ID da cobrança associada à fatura, no formato TypeID com prefixo `pi_`. `null` enquanto a fatura ainda não tem cobrança gerada. example: pi_01h455vb4pex5vsknk084sn02r status: type: string description: | Status atual da fatura. - draft: Rascunho, ainda não finalizada. - open: Aberta, aguardando pagamento. - paid: Paga. - uncollectible: Marcada como incobrável. - void: Cancelada. enum: - draft - open - paid - uncollectible - void example: open status_transitions: type: object description: | Timestamps de quando a fatura mudou de status. Campos são null se a transição ainda não ocorreu. properties: paid_at: type: - integer - 'null' nullable: true format: int64 description: Timestamp Unix de quando a fatura foi paga. example: 1704758400 subscription: type: - string - 'null' nullable: true pattern: ^sub_[0-9a-z]{26}$ description: >- ID da assinatura associada (se aplicável), no formato TypeID com prefixo `sub_`. example: sub_01h455vb4pex5vsknk084sn02s total: type: integer description: Valor total da fatura em centavos. R$ 99,90 = 9990. example: 9990 example: id: in_01h455vb4pex5vsknk084sn02q object: invoice amount_due: 14990 amount_paid: 0 amount_remaining: 14990 created: 1764040287 currency: brl customer: cus_01h455vb4pex5vsknk084sn02p customer_email: joao.silva@exemplo.com customer_name: João Silva external_code: PEDIDO-123 live_mode: true paid: false payment_intent: null status: open status_transitions: paid_at: null subscription: null total: 14990 '400': description: Requisição inválida headers: Content-Language: description: Idioma da mensagem de erro. schema: type: string enum: - en content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: URI que identifica o tipo de problema format: uri enum: - >- https://problems-registry.smartbear.com/missing-body-property - https://problems-registry.smartbear.com/bad-request status: type: integer description: O código de status HTTP format: int32 enum: - 400 title: type: string description: O nome do status HTTP enum: - Bad Request detail: type: string description: >- Mensagem descritiva do erro, nomeando o parâmetro rejeitado code: type: string description: Código de erro interno da API enum: - PARAMETER_MISSING - MALFORMED_JSON - INVALID_QUERY_PARAMETER errors: type: array description: >- Erros por campo. Presente quando o parâmetro rejeitado é conhecido. items: oneOf: - type: object required: - detail - pointer not: required: - parameter properties: detail: type: string description: Mensagem específica sobre o campo rejeitado pointer: type: string description: Caminho JSON para o campo no corpo da requisição - type: object required: - detail - parameter not: required: - pointer properties: detail: type: string description: Mensagem específica sobre o parâmetro rejeitado parameter: type: string description: Nome do parâmetro de consulta rejeitado examples: parameter_missing: summary: Nenhum campo reconhecido no corpo value: type: >- https://problems-registry.smartbear.com/missing-body-property status: 400 title: Bad Request detail: >- The 'customer' parameter is required and must contain at least one recognized field. Expected fields: external_code, identifier, name, email, phone, address. code: PARAMETER_MISSING errors: - detail: No recognized field was found in 'customer'. pointer: /customer malformed_json: summary: Corpo não é JSON válido value: type: https://problems-registry.smartbear.com/bad-request status: 400 title: Bad Request detail: The request body is not valid JSON code: MALFORMED_JSON invalid_query_parameter: summary: Parâmetro de consulta inválido value: type: https://problems-registry.smartbear.com/bad-request status: 400 title: Bad Request detail: >- The 'limit' query parameter must be an integer between 1 and 100 code: INVALID_QUERY_PARAMETER errors: - detail: The query parameter is invalid. parameter: limit '404': description: Recurso não encontrado content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: >- URL que identifica o tipo de erro ocorrido. Útil para tratamento programático de erros. example: https://problems-registry.smartbear.com/validation-error format: uri maxLength: 1024 status: type: integer description: >- Código de status HTTP da resposta. Corresponde ao status code retornado na requisição. example: 400 format: int32 minimum: 100 maximum: 599 title: type: string description: >- Título curto e descritivo do erro. Ideal para exibir em logs ou mensagens de erro genéricas. example: Bad Request maxLength: 1024 detail: type: string description: >- Mensagem detalhada do erro específico para esta requisição. Use esta mensagem para entender o que deu errado. example: O campo email é obrigatório e não foi informado. maxLength: 4096 instance: type: string description: >- Identificador único desta ocorrência de erro. Forneça este valor ao solicitar suporte para facilitar o debug. example: req_abc123def456 maxLength: 1024 code: type: string description: >- Código de erro interno da API. Útil para mapear tipos específicos de erros no seu código. example: VALIDATION_ERROR maxLength: 50 errors: type: array description: >- Lista de erros de validação específicos. Presente quando múltiplos campos falham na validação. maxItems: 1000 items: type: object description: >- Detalhes sobre um erro específico de validação. Ajuda a identificar qual campo e valor causaram o erro. required: - detail properties: detail: type: string description: >- Mensagem específica sobre o erro de validação deste campo. example: O campo email não é um endereço de e-mail válido. maxLength: 4096 pointer: type: string description: >- Caminho JSON para o campo no corpo da requisição que causou o erro. example: /customer/email maxLength: 1024 parameter: type: string description: Nome do parâmetro (query ou path) que causou o erro. example: customer_id maxLength: 1024 header: type: string description: Nome do cabeçalho HTTP que causou o erro. example: Authorization maxLength: 1024 code: type: string description: >- Código adicional para identificar o contexto específico do erro. example: INVALID_FORMAT maxLength: 50 examples: not_found: summary: Recurso não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: The requested resource was not found code: NOT_FOUND customer_not_found: summary: Cliente não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: 'No such customer: ''cus_01h455vb4pex5vsknk084sn02p''' code: RESOURCE_MISSING price_not_found: summary: Preço não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: 'No such price: ''price_01h455vb4pex5vsknk084sn02q''' code: RESOURCE_MISSING '422': description: Erro de regra de negócio ou validação content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: >- URL que identifica o tipo de erro ocorrido. Útil para tratamento programático de erros. example: https://problems-registry.smartbear.com/validation-error format: uri maxLength: 1024 status: type: integer description: >- Código de status HTTP da resposta. Corresponde ao status code retornado na requisição. example: 400 format: int32 minimum: 100 maximum: 599 title: type: string description: >- Título curto e descritivo do erro. Ideal para exibir em logs ou mensagens de erro genéricas. example: Bad Request maxLength: 1024 detail: type: string description: >- Mensagem detalhada do erro específico para esta requisição. Use esta mensagem para entender o que deu errado. example: O campo email é obrigatório e não foi informado. maxLength: 4096 instance: type: string description: >- Identificador único desta ocorrência de erro. Forneça este valor ao solicitar suporte para facilitar o debug. example: req_abc123def456 maxLength: 1024 code: type: string description: >- Código de erro interno da API. Útil para mapear tipos específicos de erros no seu código. example: VALIDATION_ERROR maxLength: 50 errors: type: array description: >- Lista de erros de validação específicos. Presente quando múltiplos campos falham na validação. maxItems: 1000 items: type: object description: >- Detalhes sobre um erro específico de validação. Ajuda a identificar qual campo e valor causaram o erro. required: - detail properties: detail: type: string description: >- Mensagem específica sobre o erro de validação deste campo. example: O campo email não é um endereço de e-mail válido. maxLength: 4096 pointer: type: string description: >- Caminho JSON para o campo no corpo da requisição que causou o erro. example: /customer/email maxLength: 1024 parameter: type: string description: Nome do parâmetro (query ou path) que causou o erro. example: customer_id maxLength: 1024 header: type: string description: Nome do cabeçalho HTTP que causou o erro. example: Authorization maxLength: 1024 code: type: string description: >- Código adicional para identificar o contexto específico do erro. example: INVALID_FORMAT maxLength: 50 examples: price_not_one_time: summary: Preço recorrente em fatura avulsa value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: >- Cobranças avulsas exigem preços avulsos. Um dos preços informados é recorrente; para cobrança recorrente, crie uma assinatura (POST /api/v1/subscriptions). code: PRICE_NOT_ONE_TIME discount_exceeds_subtotal: summary: Desconto iguala ou excede o subtotal value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: >- O valor do desconto deve ser menor que o subtotal do pedido code: DISCOUNT_EXCEEDS_SUBTOTAL invalid_discount: summary: Desconto inválido value: type: https://problems-registry.smartbear.com/validation-error status: 422 title: Unprocessable Entity detail: Type não está incluído na lista code: INVALID_DISCOUNT amount_exceeds_maximum: summary: Valor total acima do máximo suportado value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: O valor total da fatura excede o máximo suportado code: AMOUNT_EXCEEDS_MAXIMUM amount_must_be_positive: summary: Valor total igual a zero value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: O valor total da fatura deve ser maior que zero code: AMOUNT_MUST_BE_POSITIVE validation_error: summary: Erro de validação de campos value: type: https://problems-registry.smartbear.com/validation-error status: 422 title: Unprocessable Entity detail: The request payload contains validation errors code: VALIDATION_ERROR errors: - detail: External code já está em uso pointer: /invoice/external_code components: securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: > A chave de API usada para autenticar a requisição e identificar a sua conta. **Exemplo:** `Authorization: ApiKey my-secure-key` ````