Referência
  1. Pagamentos
  2. Faturas

📖 Visão Geral


API v2 - Documentação dos Endpoints de Faturas (Invoices)

Esta documentação descreve todos os endpoints disponíveis na API v2 para gerenciamento de faturas (invoices) do sistema Bempaggo.

Sumário

Visão Geral

A API v2 de faturas está organizada em diferentes grupos de endpoints que gerenciam diferentes aspectos das faturas:

  • Operações Básicas: CRUD de faturas, listagem e filtros
  • Criação por Seller: Criação de faturas por vendedor
  • Itens de Faturas: Gerenciamento de itens de faturas
  • Faturas Recorrentes: Faturas recorrentes e carnês
  • Temas: Personalização visual das faturas

Autenticação

Todos os endpoints requerem autenticação Bearer Token:

Authorization: Bearer <token>

1. Operações Básicas de Faturas (/api/v2/invoices)

1.1 Listar Faturas

GET /api/v2/invoices

Obtém uma lista paginada de faturas com filtros opcionais.

Parâmetros de Query:

  • invoiceNumber (string): Número único da fatura
  • dueDateFrom (number): Data inicial do vencimento (Unix timestamp)
  • dueDateTo (number): Data final do vencimento (Unix timestamp)
  • closeDateFrom (number): Data inicial de fechamento (Unix timestamp)
  • closeDateTo (number): Data final de fechamento (Unix timestamp)
  • paymentDateFrom (number): Data inicial de pagamento (Unix timestamp)
  • paymentDateTo (number): Data final de pagamento (Unix timestamp)
  • status (array): Status da fatura (OPEN, CLOSED, PAID, CANCELLED, UNCOLLECTIBLE)
  • document (string): CPF/CNPJ do cliente
  • page (number): Número da página (padrão: 0)
  • size (number): Registros por página (padrão: 10)
  • pastDue (boolean): Faturas em atraso

Exemplo de Resposta:

{
  "content": [...],
  "pageable": {...},
  "totalElements": 100,
  "totalPages": 10
}

1.2 Obter Fatura por ID

GET /api/v2/invoices/{id}

Obtém uma fatura específica com todos os detalhes.

Parâmetros:

  • id (path): ID da fatura

Resposta: Detalhes completos da fatura incluindo itens e transações

1.3 Finalizar Fatura

POST /api/v2/invoices/{id}/finalize

Finaliza uma fatura que está em status OPEN.

Parâmetros:

  • id (path): ID da fatura

Resposta: 201 Created (com link para a cobrança gerada)

1.4 Enviar Fatura por E-mail

POST /api/v2/invoices/{id}/send-email

Envia uma fatura por e-mail para o cliente.

Parâmetros:

  • id (path): ID da fatura

Resposta: 200 OK

1.5 Cancelar Fatura

POST /api/v2/invoices/{id}/void

Cancela uma fatura.

Parâmetros:

  • id (path): ID da fatura

Resposta: 200 OK

1.6 Marcar como Inadimplente

POST /api/v2/invoices/{id}/uncollectible

Marca uma fatura como inadimplente.

Parâmetros:

  • id (path): ID da fatura

Resposta: 200 OK

1.7 Obter Última Cobrança por Número da Fatura

GET /api/v2/invoices/charges/latest

Obtém a última cobrança de uma fatura pelo número da fatura.

Parâmetros de Query:

  • invoiceNumber (string): Número da fatura

Resposta: Detalhes da cobrança com histórico de transações

1.8 Obter Última Cobrança por ID da Fatura

GET /api/v2/invoices/{id}/charges/latest

Obtém a última cobrança de uma fatura pelo ID.

Parâmetros:

  • id (path): ID da fatura

Resposta: Detalhes da cobrança com histórico de transações

1.9 Gerar Relatório CSV

GET /api/v2/invoices/csv

Gera um relatório CSV das faturas com os filtros aplicados.

Parâmetros: Mesmos filtros da listagem de faturas

Resposta: Arquivo CSV para download

2. Pagamentos de Faturas

2.1 Pagamento com Cartão de Crédito

POST /api/v2/invoices/{id}/credit-card/pay

Processa pagamento de uma fatura com cartão de crédito.

Parâmetros:

  • id (path): ID da fatura

Body: Dados do pagamento com cartão

{
  "cardId": 123,
  "installments": 1,
  "keepYourCardForAutomaticCharges": true
}

Resposta: 201 Created (com link para a cobrança)

2.2 Pagamento com Cartão de Crédito (3D Secure)

POST /api/v2/invoices/{id}/credit-card/three-d-secure/authorize

Processa pagamento com autenticação 3D Secure.

Parâmetros:

  • id (path): ID da fatura

Body: Dados do pagamento com cartão e 3D Secure

{
  "cardId": 123,
  "installments": 1,
  "keepYourCardForAutomaticCharges": true,
  "mode": "AUTHENTICATION",
  "threeDSecure": {
    "authenticationValue": "string",
    "eci": "string",
    "version": "string"
  }
}

Resposta: 201 Created (pode incluir link para challenge 3D Secure)

2.3 Gerar Boleto

POST /api/v2/invoices/{id}/boleto

Gera um boleto bancário para pagamento da fatura.

Parâmetros:

  • id (path): ID da fatura

Resposta: 201 Created (com link para o PDF do boleto)

3. Criação de Faturas por Seller (/api/v2/sellers/{sellerId})

3.1 Criar Fatura

POST /api/v2/sellers/{sellerId}/invoices

Cria uma nova fatura para um cliente específico.

Parâmetros:

  • sellerId (path): ID do seller

Body: Dados da fatura

{
  "customerId": 123,
  "dueDate": 1846438350000,
  "invoiceNumber": "INV-00001",
  "notificationUrl": "https://example.com/notification",
  "successUrl": "https://example.com/success",
  "paymentLimitDate": 1846438350000,
  "acceptedPaymentMethods": [...],
  "items": [...],
  "splits": [...],
  "fine": {...},
  "interest": {...}
}

Resposta: 201 Created (com links para fatura e pagamento)

3.2 Criar Fatura Recorrente

POST /api/v2/sellers/{sellerId}/recurring-invoices

Cria uma nova fatura recorrente.

Parâmetros:

  • sellerId (path): ID do seller

Body: Dados da fatura recorrente

{
  "customerId": 123,
  "billingCycleStartDate": 1846438350000,
  "isBillingCycleStartDateOverridden": false,
  "daysUntilDue": 7,
  "billingFrequency": "MONTHLY",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "orderReference": "ORDER-123",
  "nextCycleDueDate": 1846438350000,
  "notificationUrl": "https://example.com/notification",
  "acceptedPaymentMethods": [...],
  "recurringItems": [...],
  "extraItems": [...],
  "splits": [...],
  "fine": {...},
  "interest": {...}
}

Resposta: 201 Created (com links para fatura recorrente, assinatura e faturas)

3.3 Criar Carnê

POST /api/v2/sellers/{sellerId}/booklet

Cria um carnê (fatura recorrente com múltiplas parcelas).

Parâmetros:

  • sellerId (path): ID do seller

Body: Dados do carnê

{
  "customerId": 123,
  "daysUntilDue": 7,
  "billingFrequency": "MONTHLY",
  "collectionMethod": "CHARGE_AUTOMATICALLY",
  "chargesByBooklet": 12,
  "acceptedPaymentMethods": [...],
  "recurringItem": {...},
  "splits": [...],
  "fine": {...},
  "interest": {...}
}

Resposta: 201 Created (com links para fatura recorrente e assinatura)

4. Itens de Faturas (/api/v2/invoices/{invoiceId}/items)

4.1 Listar Itens da Fatura

GET /api/v2/invoices/{invoiceId}/items

Obtém todos os itens de uma fatura específica.

Parâmetros:

  • invoiceId (path): ID da fatura

Resposta: Lista de itens da fatura com detalhes

5. Faturas Recorrentes (/api/v2/recurring-invoices)

5.1 Obter Fatura Recorrente por ID

GET /api/v2/recurring-invoices/{id}

Obtém detalhes de uma fatura recorrente.

Parâmetros:

  • id (path): ID da fatura recorrente

Resposta: Detalhes da fatura recorrente

5.2 Listar Faturas de uma Fatura Recorrente

GET /api/v2/recurring-invoices/{id}/invoices

Lista todas as faturas geradas por uma fatura recorrente.

Parâmetros:

  • id (path): ID da fatura recorrente

Resposta: Lista de faturas geradas

5.3 Listar Faturas por Referência do Pedido

GET /api/v2/recurring-invoices/reference/{orderReference}/invoices

Lista faturas recorrentes por referência do pedido.

Parâmetros:

  • orderReference (path): Referência do pedido

Resposta: Lista de faturas geradas

5.4 Obter Carnê (HTML)

GET /api/v2/recurring-invoices/{id}/booklet

Gera o HTML do carnê com todos os boletos.

Parâmetros:

  • id (path): ID da fatura recorrente

Resposta: HTML do carnê

5.5 Gerar Múltiplos Boletos

POST /api/v2/recurring-invoices/{id}/boleto/generate-bulk

Gera boletos para todas as faturas fechadas de uma fatura recorrente.

Parâmetros:

  • id (path): ID da fatura recorrente

Resposta: Lista de boletos gerados

6. Temas de Faturas (/api/v2/invoices)

6.1 Obter Tema da Fatura

GET /api/v2/invoices/themes

Obtém o tema configurado para as faturas da empresa.

Resposta: Configuração do tema da fatura

6.2 Atualizar Tema da Fatura

PUT /api/v2/invoices/themes

Atualiza o tema das faturas da empresa.

Body: Configuração do tema

{
  "primaryColor": "#FF0000",
  "secondaryColor": "#00FF00",
  "logoUrl": "https://example.com/logo.png",
  "colors": {
    "headerBackground": "#FFFFFF",
    "headerText": "#000000",
    "bodyBackground": "#F5F5F5",
    "bodyText": "#333333"
  }
}

Resposta: Configuração do tema da fatura

7. Códigos de Status HTTP

  • 200 OK: Operação realizada com sucesso
  • 201 Created: Recurso criado com sucesso
  • 400 Bad Request: Dados inválidos
  • 401 Unauthorized: Token de autenticação inválido
  • 404 Not Found: Recurso não encontrado
  • 422 Unprocessable Entity: Erro de validação ou regra de negócio
  • 500 Internal Server Error: Erro interno do servidor

8. Exemplos de Uso

Criar uma Fatura Simples

curl -X POST "https://api.bempaggo.com/api/v2/sellers/123/invoices" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": 456,
    "dueDate": 1846438350000,
    "invoiceNumber": "INV-001",
    "acceptedPaymentMethods": [
      {
        "method": "CREDIT_CARD",
        "cardSettings": {
          "maxInstallments": 12,
          "feePassThrough": false
        }
      }
    ],
    "items": [
      {
        "productId": 789,
        "unitPriceInCents": 10000,
        "quantity": 1
      }
    ]
  }'

Listar Faturas com Filtros

curl -X GET "https://api.bempaggo.com/api/v2/invoices?status=OPEN&page=0&size=20" \
  -H "Authorization: Bearer <token>"

Pagar Fatura com Cartão

curl -X POST "https://api.bempaggo.com/api/v2/invoices/123/credit-card/pay" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": 456,
    "installments": 1,
    "keepYourCardForAutomaticCharges": true
  }'

9. Notas Importantes

  1. Timestamps: Todas as datas são enviadas como Unix timestamps em milissegundos
  2. Paginação: Use os parâmetros page e size para controlar a paginação
  3. Filtros: Combine múltiplos filtros para refinar as consultas
  4. Links: Muitas respostas incluem links úteis no header Link
  5. Validação: Todos os endpoints validam os dados de entrada
  6. Rate Limiting: Respeite os limites de taxa da API
  7. Webhooks: Configure URLs de notificação para receber atualizações de status

Esta documentação cobre todos os endpoints disponíveis na API v2 de faturas do Bempaggo. Para mais detalhes sobre os schemas de request/response, consulte a documentação OpenAPI/Swagger da API ou entre em contato com o suporte técnico.

Updated 10 months ago

Did this page help you?

Updated 10 months ago

Did this page help you?