Referência

📘 Criando uma fatura avulsa

No Bempaggo, o recurso Invoice (Fatura) facilita o processo de cobrança ao consolidar produtos, serviços ou assinaturas em um único documento, gerando automaticamente um checkout simples e seguro. Isso torna o desenvolvimento mais rápido, pois elimina a necessidade de criar uma interface personalizada para cobranças, permitindo que você envie a fatura diretamente ao cliente ou gerencie o pagamento de forma prática.


Passo 1 - Criar um Cliente

Endpoint

POST /api/v2/customers

Request Body

{
    "name": "Tony Stark",
    "document": "51190844001",
    "birthdate": "2000-01-01",
    "phone": {
        "countryCode": 55,
        "areaCode": 48,
        "number": 998870001
    },
    "email": "[email protected]",
    "address": {
        "street": "Rua Jair Hamms",
        "streetNumber": "38",
        "lineTwo": "Sala 101",
        "neighborhood": "Pedra Branca",
        "state": "SC",
        "zipCode": "88137084",
        "city": "Palhoça"
    }
}

Resposta de Sucesso

Status: 201 Created

Headers:

  • Content-ID: ID do cliente recém-criado.
  • Location: URL para acessar o cliente criado.

Passo 2 - Criar um Produto

Endpoint

POST /api/v2/products

Request Body

{
    "productType": "ONETIME",
    "affiliateId": 1,
    "name": "Produto Exemplo",
    "value": 500,
    "softDescriptor": "Product Plus",
    "maxInstallments": 12,
    "active": true,
    "methods": [
        "CREDIT_CARD",
        "PIX"
    ],
    "description": "Este é um produto exemplo.",
    "themeId": 1,
    "feePassThrough": false
}

Resposta de Sucesso

Status: 201 Created

Headers:

  • Location: URL para acessar o produto criado.

📘

Informação

Na API de fatura, o produto é usado apenas como referência. Ao gerar uma fatura, o ID do produto serve para identificar os itens que serão cobrados na fatura. As informações enviadas na API de criação de produto são utilizadas exclusivamente no link de pagamento e não no Checkout da Fatura.


Passo 3 - Criar a Fatura

Endpoint

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

Request Body

{
   "customerId":1,
   "invoiceNumber":"TEST_1731446753",
   "dueDate":"1732310753051",
   "notificationUrl": "https://meusite.com.br/events",
   "successUrl":"https://google.com",
   "items":[
      {
         "productId":1,
         "quantity":1,
         "unitPriceInCents":70000
      }
   ],
   "acceptedPaymentMethods":[
      {
         "method":"CREDIT_CARD",
         "cardSettings":{
            "maxInstallments":10,
            "feePassThrough":false
         }
      }
   ]
}

Resposta de Sucesso

Status: 201 Created

Headers:

  • Location: URL para acessar a fatura criada.
  • Link: URL para pagamento da fatura.

Exemplo de checkout de uma Fatura



Recebendo Eventos de Pagamento (Opcional)

Quando uma fatura é paga, um evento será enviado para a URL especificada em notificationUrl.

👍

Confirmando autenticidade do evento

Para um fluxo seguro, não enviamos informações no corpo do evento. Ao receber o evento, utilize nossa API autenticada para confirmar o pagamento da fatura, evitando, assim, o recebimento de eventos de fontes fraudulentas.

📘

Boas práticas - Habilitação de Redirecionamento Automático

Para obter o recurso criado automaticamente em uma única requisição, é necessário habilitar o redirecionamento automático no seu cliente HTTP. Essa configuração permite que seu cliente siga os cabeçalhos Location retornados pela API, simplificando o processo de recuperação do recurso recém-criado.

Exemplo C# - Redirecionamento Automático

var handler = new HttpClientHandler
{
    AllowAutoRedirect = true,  // Permite redirecionamentos automáticos
    MaxAutomaticRedirections = 10  // Número máximo de redirecionamentos a seguir
};

var httpClient = new HttpClient(handler)
{
    BaseAddress = new Uri("https://apisandbox.bempaggo.io")
};

httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "SUA_API_KEY");