Documentação da API de Links de Pagamento - Admin (Gerenciamento)

Esta documentação descreve os endpoints utilizados para a gestão interna dos Links de Pagamento. Estes recursos exigem autenticação e permissões administrativas.

Base URL: /billing/payment-links
Headers Obrigatórios:

• Authorization: Bearer <token>
• X-Account-Id: <id-da-conta>

---

Endpoints Administrativos

1. Listar Links de Pagamento

Retorna uma lista paginada de todos os links de pagamento vinculados à conta, com resumos financeiros por status.

• Método: GET
• Rota: /

Parâmetros de Filtro (Query String):

Campo	Tipo	Descrição
id	Integer	Filtra por ID interno específico.
status	String	Filtra por status (draft, paid, expired, etc).
search	String	Busca por descrição ou código de referência.
created_start	Date	Data inicial de criação (Y-m-d).
created_end	Date	Data final de criação (Y-m-d).
due_date_start	Date	Data inicial de vencimento (Y-m-d).
due_date_end	Date	Data final de vencimento (Y-m-d).
per_page	Integer	Itens por página (default: 15).
page	Integer	Número da página.
order	String	Ordenação (asc ou desc, default: desc).

Exemplo de Resposta (200 OK):

{
  "data": [
    {
      "id": 1,
      "external_id": "pl_65d8a0f1b2c3d",
      "title": "Venda de Equipamento",
      "amount": 1500.0,
      "installments": 10,
      "status": {
        "value": "draft",
        "label": "Rascunho"
      },
      "public_url": "https://checkout-gateway.fastgivr.com.br/pl_65d8a0f1b2c3d"
    }
  ],
  "summary": {
    "all": { "value": "all", "label": "Todos", "count": 5, "amount": 2500.0 },
    "draft": {
      "value": "draft",
      "label": "Rascunho",
      "count": 2,
      "amount": 1000.0
    }
  },
  "message": "Links de pagamento listados com sucesso."
}

---

2. Criar Link de Pagamento

Cria um novo link de pagamento. Os campos external_id, status e slug são gerados automaticamente pelo sistema.

• Método: POST
• Rota: /

Parâmetros do Payload:

Campo	Tipo	Obrigatório	Descrição
title	String	Sim	Título exibido no checkout.
amount	Numeric	Sim*	Valor fixo (Obrigatório se is_variable_amount for false).
payment_methods	Array	Sim	Ex: ["PIX", "CARD", "BOLETO"].
is_variable_amount	Boolean	Não	Permite ao cliente digitar o valor (default: false).
min_amount	Numeric	Não*	Valor mínimo (Obrigatório se is_variable_amount for true).
max_amount	Numeric	Não	Valor máximo permitido.
installments	Integer	Não	Limite de parcelas no cartão (1 a 12).
expires_at	DateTime	Não	Data/hora de expiração do link.
description	String	Não	Texto descritivo exibido no checkout.

---

3. Visualizar Detalhes do Link

Retorna os dados completos, incluindo auditoria e cliente vinculado.

• Método: GET
• Rota: /\{external_id\}

---

4. Atualizar Link

Permite modificar configurações do link. Restrição: Não é possível remover métodos de pagamento que já possuam transações realizadas com sucesso.

• Método: PUT / PATCH
• Rota: /\{external_id\}

---

5. Listar Pagamentos do Link

Retorna o histórico de todas as transações vinculadas a este link.

• Método: GET
• Rota: /\{external_id\}/payments

---

6. Listar Pagamentos Confirmados (Pagos)

Retorna apenas as transações que foram efetivamente pagas pelo cliente.

• Método: GET
• Rota: /\{external_id\}/paid-payments

Parâmetros de Filtro:

• per_page: Itens por página.
• page: Número da página.

---

7. Remover Link

Realiza o Soft Delete do recurso.

• Método: DELETE
• Rota: /\{external_id\}