Skip to content

Prompts para IA ​

Textos prontos para colar num assistente de IA (Claude, ChatGPT, Copilot, Cursor…) e gerar a integração com a API FastGivr no seu sistema. Copie o bloco, troque o que está entre <...> e cole.

Cada página de módulo também termina com um prompt específico.

Documentação inteira em um link

Para dar ao assistente o contexto completo, envie /llms-full.txt (todas as páginas em um arquivo) ou /llms.txt (índice).

1. Prompt geral (contexto da API) ​

Use primeiro: ele explica a API inteira. Depois peça a tarefa (ex.: "agora gere a emissão de boleto").

txt
Você vai me ajudar a integrar meu sistema com a API FastGivr (conta digital).
Linguagem/stack do meu projeto: <ex.: Node.js 20 + TypeScript | PHP 8 + Laravel | Python 3 + FastAPI>.

API
- Base URL: https://api.banking.fastgivr.com.br
- REST + JSON. Envie sempre Accept: application/json.
- Chame a API pelo servidor (back-end). O CORS só libera os sites da FastGivr; chamadas do navegador falham.

AUTENTICAÇÃO (integração sistema a sistema)
- O administrador da conta cria um "usuário de API" no portal (Tokens de API) e copia o token da conta.
- Para obter o JWT: POST /access/account/get-token com { "email": "<e-mail do usuário de API>", "token": "<token da conta>" }.
  Resposta: { "code": 200, "success": true, "data": { "token", "token_type": "Bearer", "expires_at" (ISO 8601), "permissions": [{ "name" }] }, "message" }.
- O JWT vale 10 minutos. Guarde-o em cache e peça outro antes de expires_at (ou ao receber 401).
- Envie Authorization: Bearer {token} em todas as chamadas.
- Header opcional account: {account_id} para escolher a conta; sem ele vale a conta do token.
- Limite: 10 tentativas/min por IP e 5/min por e-mail no get-token; acima disso 429.
- O token de integração só opera (cobranças, clientes, QR Code, consultas). Não gere código para administrar a conta (usuários, tokens, dados da conta, PIN, 2FA, senha, sessões, chaves Pix): isso é só pelo portal/app e responde 403 para o token de integração.

FORMATO DAS RESPOSTAS
- Sucesso: { "code", "success": true, "data", "message" }. Algumas rotas devolvem o objeto direto ou outra chave; trate pelo status HTTP.
- Lista paginada: { "data": [...], "meta": { "total", "page", "limit", "total_pages", "has_next_page", "has_prev_page" } } (algumas usam meta.current_page/last_page do Laravel).
- Erro: { "message", "success": false, "data" }. Validação 422 traz os campos em "errors" ou em "data".
- Status: 401 token inválido/expirado; 403 sem permissão (vem required_permissions) ou conta de outro usuário; 404 não encontrado ou de outra conta; 409 Idempotency-Key em andamento; 422 validação/regra de negócio; 429 limite de tentativas; 5xx erro interno ou do banco.
- Confie no status HTTP, não só em "success".

O QUE A INTEGRAÇÃO FAZ
1. Clientes: GET/POST /billing/clients, GET/PUT/DELETE /billing/clients/{id}.
2. Cobranças: POST /billing/charges com payment_method PIX, BOLETO ou BOLEPIX; GET /billing/charges (filtros) e GET /billing/charges/{id}; PUT (só pendente); POST /billing/charges/{id}/cancel; DELETE; GET /billing/charges/{id}/download-pdf.
3. Pix para receber: GET /banking/pix/keys (chaves da conta), GET /banking/pix/static-qrcode, POST /banking/pix/qrcode/dynamic.
4. Aviso de pagamento: a cobrança criada com "webhook": "<URL>" recebe um POST quando é paga (event "charge.paid").
5. Consultas: GET /consolidation/balance, GET /consolidation/financial-movements (extrato), GET /consolidation/financial-movements/{id}/download-pdf (comprovante), GET /billing/charges/reports.

IDEMPOTÊNCIA
- Em POST /billing/charges e POST /banking/pix/qrcode/dynamic envie Idempotency-Key: <UUID v4 novo por cobrança>.
- Repita o MESMO UUID ao tentar de novo a mesma cobrança (timeout, erro de rede). A API devolve a resposta original com Idempotent-Replayed: true.
- Mesmo UUID com corpo diferente: 422. Ainda em andamento: 409 (espere e consulte).

REGRAS DE CÓDIGO
- Centralize as chamadas num cliente HTTP com: renovação automática do token, timeout de 30 s, retry só com a mesma Idempotency-Key, log sem dados sensíveis.
- Nunca grave o token da conta no código-fonte nem no front-end: use variável de ambiente/cofre.
- Valores em reais com 2 casas decimais. Datas Y-m-d.

Quando eu pedir uma tarefa, gere o código completo em <minha stack>, com tipos, tratamento de cada status de erro acima e um exemplo de uso.

2. Autenticação e renovação do token ​

txt
Gere, em <minha stack>, um cliente HTTP para a API FastGivr (https://api.banking.fastgivr.com.br) que:
- Obtém o JWT com POST /access/account/get-token, body { "email": FASTGIVR_API_EMAIL, "token": FASTGIVR_ACCOUNT_TOKEN } (variáveis de ambiente).
  Resposta: data.token, data.token_type ("Bearer"), data.expires_at (ISO 8601, 10 minutos), data.permissions[].name.
- Guarda o token em memória/cache e renova 1 minuto antes de expires_at; se receber 401, renova uma vez e repete a requisição.
- Envia Authorization: Bearer {token}, Accept: application/json e, se configurado, account: FASTGIVR_ACCOUNT_ID.
- Trata 401 (credenciais inválidas: e-mail não é de usuário de API ou token da conta errado; não fique tentando), 429 (limite de 5/min por e-mail: espere e tente depois) e 5xx.
- Só roda no servidor (CORS bloqueia o navegador).
Inclua testes simulando expiração do token.

3. Emitir cobrança Pix, boleto ou BOLEPIX ​

txt
Usando o cliente da API FastGivr que já existe no meu projeto, gere em <minha stack> a função de emitir cobrança.
Endpoint: POST /billing/charges, header Idempotency-Key (UUID v4 novo por cobrança, reutilizado nas tentativas da mesma cobrança).
Body:
- amount (número, >= 0.01) e payment_method: "PIX" | "BOLETO" | "BOLEPIX" (obrigatórios).
- BOLETO e BOLEPIX: due_date (Y-m-d, hoje ou depois) e o pagador: client_id OU name + email + document (CPF/CNPJ só números).
- Opcionais: phone, address { street, number, zip, city, state, country }, description (até 500), webhook (URL que recebe o aviso de pagamento),
  discount + days_discount + type_discount, late_fee + late_fee_type (PERCENTAGE padrão | ABSOLUTE), rate + type_rate (juros), informative (array de mensagens no boleto).
- PIX pode ir sem cliente e sem vencimento.
Resposta 201: { "data": { id, amount, payment_method, due_date, status { id, title }, client,
  pix { txid, qrcode (copia e cola), amount, status }, boleto { txid, barcode, digitable_line, our_number, amount, status } } }.
Erros: 422 validação (campos em errors ou data) ou valor fora do limite da conta; 403 sem permissão create_charges; 409 mesma Idempotency-Key em andamento; 4xx/5xx do banco (a cobrança fica com status failed; não reenvie com outra chave sem consultar GET /billing/charges?search=...).
Mostre também: como exibir o QR Code a partir de pix.qrcode, como baixar o PDF (GET /billing/charges/{id}/download-pdf) e como guardar o id da cobrança no meu pedido.

4. Receber o aviso de pagamento (webhook) ​

txt
Gere em <minha stack> o endpoint que recebe o aviso de cobrança paga da FastGivr.
- A URL é a que envio em "webhook" ao criar a cobrança. Inclua nela um segredo meu (?secret=...) e rejeite chamadas sem ele (não há assinatura).
- Chega POST com JSON: { "type": { "name": "PIX IN" | "BOLEPIX" | "BOLETO" }, "txid", "value" (string, pode vir "1,500.00"),
  "account", "date_time" ("Y-m-d H:i:s"), "details": { "id" (id da cobrança), "amount_paid", "payment_date", "payment_method", "status_id" },
  "payer": { "name", "email", "document" } ou [], "event": "charge.paid" (null em reenvio manual) }.
- Responda 2xx em menos de 30 s e processe em fila. Não há retry automático.
- Seja idempotente por details.id: o mesmo aviso pode chegar mais de uma vez.
- Antes de liberar o pedido, confirme com GET /billing/charges/{details.id} que status.title é "paid" e que amount_paid confere.
- Para pedir um reenvio: POST /billing/charges/{id}/webhook (só cobrança paga).
- Para auditar entregas: GET /access/webhook-notifications?charge_id={id}.

5. Consultas (cobranças, saldo e extrato) ​

txt
Gere em <minha stack> as consultas da API FastGivr usando o cliente que já existe:
- GET /billing/charges — filtros search, status_id, client_id, payment_method, created_at_start/end, due_date_start/end, payment_date_start/end (Y-m-d),
  order_by (created_at|due_date|payment_date|id), order_dir, per_page (1-500), page. Paginação em meta { total, page, limit, total_pages, has_next_page }.
- GET /billing/charges/{id} — detalhe com status, pix e boleto.
- GET /billing/charges/reports?group_by=days|months&date_start=Y-m-d&date_end=Y-m-d — totais por período.
- GET /consolidation/balance — { balance, available }.
- GET /consolidation/financial-movements — extrato; filtros date_start, date_end, type_id, status_ids[], search, per_page (1-200), page, include[]=summary|daily_evolution.
  Paginação Laravel: meta { current_page, last_page, per_page, total }. Valores negativos são débitos.
- GET /consolidation/financial-movements/{id}/download-pdf — comprovante em PDF.
Crie uma função que percorre todas as páginas, e um job diário que concilia as cobranças pagas do dia com meu sistema.

6. Abertura de conta ​

O fluxo completo (PF e PJ, documentos, prova de vida e status) tem prompt próprio em Abertura de conta.