> ## Documentation Index > Fetch the complete documentation index at: https://docs.flarepayments.com/llms.txt > Use this file to discover all available pages before exploring further. # Integração com IA > Referência da API Flare Payments para assistentes de IA e agentes de código Use esta página como contexto inicial ao gerar uma integração com a Flare Payments. Ela reúne os contratos essenciais da API pública, exemplos de cobrança e regras para confirmação de pagamentos. Consulte os guias e as referências de cada endpoint. Acesse o conteúdo da documentação em formato otimizado para modelos de linguagem. ## Contrato essencial Estes valores definem o contrato base de qualquer integração: | Item | Valor | | ------------------------- | ---------------------------------------- | | Base URL | `https://api.flarepayments.com/v1` | | Autenticação | `Authorization: Bearer YOUR_API_KEY` | | Chave secreta | Prefixo `sk_live_` | | Unidade de cobrança | Centavos, por exemplo `1000` = R\$ 10,00 | | Identificador da cobrança | `uuid` | | Confirmação de pagamento | Webhook ou consulta de status | Execute chamadas autenticadas somente no backend. Nunca exponha uma chave sk\_live\_ no navegador, em aplicativos client-side, repositórios públicos ou logs. ## Regras para assistentes de IA Siga estas regras ao gerar código para a API: 1. Use somente endpoints e campos documentados pela Flare 2. Envie valores de cobrança em centavos 3. Use a chave `sk_live_` para autenticação 4. Não use uma chave `pk_live_` para autenticar requisições 5. Salve o `uuid` retornado ao criar uma cobrança 6. Considere o pagamento confirmado somente após `status: "paid"` 7. Prefira webhooks para confirmação automática 8. Use `GET /charges/{uuid}/status` para consultas periódicas 9. Trate erros pelo campo `error.code` 10. Não crie parâmetros, respostas, eventos ou endpoints ausentes da documentação Quando houver divergência, use a página específica do endpoint como fonte principal. ## Autenticar requisições Envie a chave secreta no header `Authorization`: ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` Este exemplo consulta o saldo autenticado: ```bash theme={null} curl https://api.flarepayments.com/v1/balance \\ --header 'Authorization: Bearer YOUR_API_KEY' ``` | Status | Código | Motivo | | ------ | ----------------------- | -------------------------------- | | `401` | `missing_authorization` | Header `Authorization` ausente | | `401` | `invalid_authorization` | Formato de autenticação inválido | | `401` | `invalid_api_key` | Chave de API não encontrada | | `403` | `api_key_disabled` | Chave desativada | | `403` | `api_key_revoked` | Chave revogada | | `429` | `rate_limit_exceeded` | Limite de requisições excedido | ## Endpoints disponíveis Use este catálogo para selecionar o endpoint correto: | Operação | Método e caminho | Resultado | | ------------------ | ---------------------------- | ------------------------------------ | | Criar cobrança | `POST /charges` | Cria uma cobrança Pix ou boleto | | Consultar cobrança | `GET /charges/{uuid}` | Retorna os dados da cobrança | | Consultar status | `GET /charges/{uuid}/status` | Retorna `uuid`, `status` e `paid` | | Consultar saldo | `GET /balance` | Retorna saldos disponível e pendente | | Listar transações | `GET /transactions` | Retorna o histórico paginado | Saques não estão disponíveis pela API pública. Solicite saques pelo Dashboard da Flare. ## Criar uma cobrança Envie `POST https://api.flarepayments.com/v1/charges` com `Content-Type: application/json`. O limite documentado é de 60 requisições por minuto. ### Campos da cobrança Pix O corpo aceita os seguintes campos: | Campo | Tipo | Obrigatório | Regra | | ------------------- | ------- | ----------- | ------------------------------ | | `amount` | integer | Sim | Valor mínimo de `500` centavos | | `payment_method` | string | Sim | Use `pix` | | `description` | string | Não | Descrição da cobrança | | `customer` | object | Não | Dados do pagador | | `customer.name` | string | Não | Nome completo | | `customer.email` | string | Não | E-mail | | `customer.document` | string | Não | CPF ou CNPJ | Crie uma cobrança Pix: ```bash theme={null} curl --request POST \\ --url https://api.flarepayments.com/v1/charges \\ --header 'Authorization: Bearer YOUR_API_KEY' \\ --header 'Content-Type: application/json' \\ --data '{ "amount": 1000, "payment_method": "pix", "description": "Pedido #1234" }' ``` A API responde com `201 Created`: ```json theme={null} { "success": true, "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925", "amount": 1000, "expires_at": "2026-09-13T23:59:59Z", "pix_copy_paste": "00020101021226..." } ``` ### Campos da cobrança por boleto O boleto exige os dados do pagador e o endereço de cobrança: | Campo | Tipo | Obrigatório | Regra | | ------------------------------ | ------- | ----------- | ------------------------------------ | | `amount` | integer | Sim | Valor mínimo de `500` centavos | | `payment_method` | string | Sim | Use `boleto` | | `description` | string | Não | Descrição da cobrança | | `customer.name` | string | Sim | Nome completo | | `customer.email` | string | Sim | E-mail | | `customer.document` | string | Sim | CPF ou CNPJ válido | | `customer.phone` | string | Sim | DDD e telefone, com 10 ou 11 dígitos | | `billing_address.zip` | string | Sim | CEP com 8 dígitos | | `billing_address.state` | string | Sim | UF com 2 letras | | `billing_address.city` | string | Sim | Cidade | | `billing_address.street` | string | Sim | Rua ou avenida | | `billing_address.neighborhood` | string | Sim | Bairro | | `billing_address.number` | string | Sim | Número | | `billing_address.complement` | string | Não | Complemento | Crie uma cobrança por boleto: ```bash theme={null} curl --request POST \\ --url https://api.flarepayments.com/v1/charges \\ --header 'Authorization: Bearer YOUR_API_KEY' \\ --header 'Content-Type: application/json' \\ --data '{ "amount": 1000, "payment_method": "boleto", "description": "Pedido #1234", "customer": { "name": "João Silva", "email": "joao@email.com", "document": "52998224725", "phone": "11999999999" }, "billing_address": { "zip": "01001000", "state": "SP", "city": "São Paulo", "street": "Praça da Sé", "neighborhood": "Sé", "number": "100", "complement": "Apto 10" } }' ``` A API responde com `201 Created`: ```json theme={null} { "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925", "success": true, "boleto_url": "https://example.com/boleto.pdf", "barcode": "001905009...", "amount": 1000, "expires_at": "2026-09-16T23:59:59Z" } ``` ## Consultar uma cobrança Consulte `GET /charges/{uuid}` para obter os dados correspondentes ao método de pagamento: ```bash theme={null} curl --request GET \\ --url https://api.flarepayments.com/v1/charges/54e2b712-aca0-4230-b69a-d6dd8542c925 \\ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json theme={null} { "success": true, "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925", "amount": 1000, "status": "paid", "expires_at": "2026-03-05T19:14:48.549Z", "pix_copy_paste": "00020101021226..." } ``` ```json theme={null} { "success": true, "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925", "amount": 1000, "status": "pending", "expires_at": "2026-03-08T23:59:59.000Z", "boleto_url": "https://example.com/boleto.pdf", "barcode": "00190.00009 01234.567890 12345.678901 1 99990000001000" } ``` Os status documentados são `pending`, `paid`, `expired` e `failed`. ## Consultar o status Use `GET /charges/{uuid}/status` quando precisar consultar o status periodicamente: ```bash theme={null} curl --request GET \\ --url https://api.flarepayments.com/v1/charges/54e2b712-aca0-4230-b69a-d6dd8542c925/status \\ --header 'Authorization: Bearer YOUR_API_KEY' ``` ```json theme={null} { "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925", "status": "pending", "paid": false } ``` ## Confirmar pagamentos com webhooks Webhooks notificam seu backend sobre mudanças no pagamento. Responda com HTTP `200` em até 5 segundos e processe o evento de forma assíncrona. | Evento | Uso | | -------------------- | ------------------------------- | | `charge.paid` | Confirma uma cobrança paga | | `charge.expired` | Informa que a cobrança expirou | | `charge.failed` | Informa falha no processamento | | `transfer.completed` | Informa a conclusão de um saque | | `transfer.failed` | Informa falha em um saque | O mesmo evento pode ser entregue mais de uma vez. Use o `uuid` da cobrança para impedir processamento duplicado. Este exemplo responde antes de iniciar o processamento: ```typescript theme={null} app.post('/webhooks/flare', express.json(), (req, res) => { const { event, data } = req.body; res.status(200).json({ received: true }); processarEvento(event, data).catch(console.error); }); ``` Exemplo de `charge.paid`: ```json theme={null} { "event": "charge.paid", "data": { "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925", "amount": 1000, "status": "paid", "description": "Pedido #1234", "customer": { "name": "João Silva", "email": "joao@email.com" }, "paid_at": "2026-03-05T18:16:22.000Z", "created_at": "2026-03-05T18:14:48.552Z" } } ``` ## Consultar saldo Consulte `GET /balance` para obter os saldos disponível e pendente: ```bash theme={null} curl https://api.flarepayments.com/v1/balance \\ --header 'Authorization: Bearer YOUR_API_KEY' ``` Os campos `available[].amount` e `pending[].amount` usam centavos. Os valores dentro de `summary` usam reais. ## Listar transações Consulte `GET /transactions` para obter o histórico paginado: ```bash theme={null} curl --request GET \\ --url 'https://api.flarepayments.com/v1/transactions?limit=20' \\ --header 'Authorization: Bearer YOUR_API_KEY' ``` | Parâmetro | Tipo | Regra | | ---------------- | -------- | -------------------------------------- | | `limit` | integer | De 1 a 100, padrão 10 | | `starting_after` | string | UUID do último item da página anterior | | `type` | string | `charge` ou `withdrawal` | | `status` | string | Filtra pelo status | | `created[gte]` | ISO 8601 | Data inicial | | `created[lte]` | ISO 8601 | Data final | Se `has_more` for `true`, envie o `uuid` do último item em `starting_after`. ## Tratar erros Trate o código estável em `error.code`: ```json theme={null} { "error": { "code": "invalid_amount", "message": "amount deve ser um inteiro positivo em centavos" } } ``` Não dependa apenas do texto em `error.message`. Alguns erros incluem campos adicionais. ## Implementar uma cobrança Pix Use este fluxo no backend: Envie POST /v1/charges com amount em centavos e payment\_method: "pix". Persista o campo uuid retornado pela Flare. Envie pix\_copy\_paste ao cliente. Responda com HTTP 200 e processe charge.paid uma única vez por uuid. Libere o produto ou serviço somente após receber status: "paid". ## Exemplo em TypeScript Este código cria uma cobrança Pix no backend: ```typescript theme={null} const apiKey = process.env.FLARE_API_KEY; const response = await fetch( 'https://api.flarepayments.com/v1/charges', { method: 'POST', headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: 1000, payment_method: 'pix', description: 'Pedido #1234', }), }, ); const data = await response.json(); if (!response.ok) { throw new Error(data?.error?.code ?? 'flare_request_failed'); } ``` ## Checklist da integração Antes de entregar a implementação, confirme: * [ ] As chamadas autenticadas rodam no backend * [ ] A autenticação usa uma chave `sk_live_` * [ ] O header segue o formato `Authorization: Bearer YOUR_API_KEY` * [ ] A URL começa com `https://api.flarepayments.com/v1` * [ ] O campo `amount` usa centavos * [ ] O `payment_method` corresponde a `pix` ou `boleto` * [ ] Cobranças por boleto incluem `customer` e `billing_address` * [ ] O sistema persiste o `uuid` * [ ] O sistema confirma pagamentos somente com `status: "paid"` * [ ] O webhook responde com HTTP `200` em até 5 segundos * [ ] O consumidor do webhook impede processamento duplicado * [ ] O tratamento de erros usa `error.code` * [ ] Nenhuma credencial aparece no frontend ou em logs * [ ] A integração não chama endpoints públicos de saque ## Fontes oficiais Consulte a referência específica quando precisar de detalhes adicionais: