# API FastGivr > API REST da conta digital FastGivr: acesso e token JWT, abertura de conta, cobranças Pix, boleto e BOLEPIX, e consultas de saldo e extrato. Base URL: https://api.banking.fastgivr.com.br # API FastGivr ## Base URL ``` https://api.banking.fastgivr.com.br ``` A API só aceita chamadas de navegador vindas dos sites oficiais da FastGivr (CORS): **integrações externas devem chamar a API pelo servidor (back-end)**, nunca direto do navegador. Esta documentação cobre o caminho de uma integração: 1. **Acesso:** senha, login e renovação do token. 2. **Receber:** cobranças Pix, boleto e BOLEPIX, clientes e QR Code. 3. **Consultar:** cobranças, saldo, extrato e comprovantes. Operações que tiram dinheiro da conta não fazem parte da API documentada: são feitas só por pessoas autorizadas, no portal ou no aplicativo da FastGivr. | Grupo | Prefixo | Conteúdo | | --- | --- | --- | | Acesso | `/access` | Login, perfil, 2FA, conta, usuários, tokens de API, notificações, abertura de conta (`/access/register`) | | Cobranças | `/billing` | Cobranças (`/billing/charges`) e clientes (`/billing/clients`) | | Pix | `/banking/pix` | Chaves Pix e QR Code para receber | | Financeiro | `/consolidation` | Saldo, extrato, comprovantes, exportação | | Enums | `/enums` | Listas de status, meios de pagamento e bancos (público) | | Backoffice | `/backoffice` | Painel interno (só papel `Backoffice`) | ## Autenticação Todas as rotas, menos as públicas (`/enums`, login, recuperação de senha e o início da abertura de conta), exigem um JWT: ```http Authorization: Bearer {token} Accept: application/json ``` - **Pessoas (portal/app):** `POST /access/auth/login` (com 2FA quando ativo). Ver [Login e sessão](/autenticacao/login-e-sessao). - **Integração (sistema a sistema):** o administrador da conta cria um **usuário de API** em [Tokens de API](/gestao/tokens-api); o sistema troca o e-mail desse usuário + o token da conta por um JWT de **10 minutos**: ```http POST /access/account/get-token Content-Type: application/json { "email": "erp@empresa.com", "token": "{token da conta}" } ``` ```json { "code": 200, "success": true, "data": { "token": "eyJ0eXAiOiJKV1Qi...", "token_type": "Bearer", "expires_at": "2026-11-20T15:10:00-03:00", "permissions": [{ "id": 1, "name": "view_charges", "guard_name": "api" }] }, "message": "..." } ``` Renove o token antes de `expires_at`. Login e `get-token` aceitam 10 tentativas por minuto por IP e 5 por e-mail; passando disso, `429`. ### Conta ativa Um usuário pode ter mais de uma conta. Para escolher em qual operar, envie: ```http account: {account_id} ``` Sem o header, a API usa a conta vinculada ao token. Conta de outro usuário: `403`. Conta inativa, suspensa ou encerrada só aceita consultas (`GET`). ### Permissões Cada rota exige uma permissão (ex.: `view_charges`, `create_charges`, `view_extract`). Sem ela, `403`. O token de integração só **opera** (cobranças, clientes, QR Code e consultas). A administração da conta (usuários, tokens, dados da conta, PIN, 2FA, senha, sessões e chaves Pix) é feita só por pessoas, no portal ou no aplicativo: com token de integração, essas rotas respondem `403`. ## Formato das respostas ```json [Sucesso] { "code": 200, "success": true, "data": { "id": 1 }, "message": "Operação realizada com sucesso" } ``` ```json [Paginado] { "data": [], "meta": { "total": 100, "page": 1, "limit": 15, "total_pages": 7, "has_next_page": true, "has_prev_page": false } } ``` ```json [Erro de validação (422)] { "message": "Dados de entrada inválidos.", "success": false, "data": { "campo": ["Detalhe do erro"] } } ``` ```json [Erro] { "message": "Descrição do erro", "success": false, "data": null } ``` **rotas devolvem o erro de validação no formato padrão do Laravel** (`{ "message", "errors": { campo: [...] } }`). Trate os dois: leia `errors` e, se não houver, `data`. | Status | Significado | | --- | --- | | `401` | Token ausente, inválido ou expirado | | `403` | Sem permissão ou conta de outro usuário | | `404` | Recurso não encontrado (ou de outra conta) | | `409` | Mesma `Idempotency-Key` ainda em andamento | | `422` | Dados inválidos ou regra de negócio | | `429` | Limite de tentativas | | `502` | O banco não respondeu; consulte antes de tentar de novo | ## Idempotência Na criação de cobrança e de QR Code dinâmico, envie o header `Idempotency-Key` (um UUID por operação) para que uma repetição não crie outra cobrança. Veja [Idempotência](/idempotencia). ## Módulos - [Autenticação](/autenticacao/): login, sessões, perfil, 2FA, recuperação de senha. - [Abertura de conta](/abertura-de-conta/): cadastro PF e PJ, documentos, prova de vida. - [Clientes](/clientes/) e [Cobranças](/cobrancas/): emissão e gestão de Pix e boleto. - [Pix](/banking/): chaves Pix e QR Code para receber. - [Financeiro](/financeiro/): saldo, extrato, comprovantes. - [Gestão](/gestao/conta): conta, usuários, tokens de API, notificações. - [Prompts para IA](/llm): textos prontos para integrar com ajuda de um LLM. --- # 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`](https://developer.banking.fastgivr.com.br/llms-full.txt) (todas as páginas em um arquivo) ou [`/llms.txt`](https://developer.banking.fastgivr.com.br/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: . 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": "", "token": "" }. 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": "" 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: . - 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 , 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 , 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 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 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 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](/abertura-de-conta/#prompt-para-llm). --- # Idempotência (`Idempotency-Key`) As rotas que **criam cobrança** aceitam o header `Idempotency-Key` (opcional). Ele é um código gerado por quem chama a API e identifica **uma** operação. Se a mesma requisição chegar de novo com o mesmo código (duplo clique, timeout, retry automático), a API **não executa outra vez**: devolve a resposta da primeira. ``` Idempotency-Key: 6f1c2e0a-3b8d-4c1e-9a77-0d5f2b9e4c11 ``` ## Rotas | Método | Rota | |---|---| | `POST` | [`/billing/charges`](/cobrancas/pix-e-boleto#post-billing-charges) | | `POST` | [`/banking/pix/qrcode/dynamic`](/banking/pix-cobrancas#post-banking-pix-qrcode-dynamic) | Sem o header, a requisição é executada normalmente, sem proteção contra repetição. ## Como usar 1. Gere um código novo (recomendado: UUID v4) **para cada operação** que o usuário inicia. 2. Envie o mesmo código em todas as tentativas **dessa** operação. 3. Para uma operação nova (outra cobrança, outro QR Code), gere outro código. O código vale por **conta** e por **rota**. O mesmo valor usado em rotas diferentes, ou por contas diferentes, não colide. ## Comportamento | Situação | Resposta | |---|---| | Código novo | Executa normalmente. A resposta fica guardada, menos se for 4xx | | Código já concluído, mesmos dados | A resposta guardada (mesmo status e body), com o header `Idempotent-Replayed: true`. Nada é executado de novo | | Código já concluído, dados diferentes | `422`: `Esta Idempotency-Key já foi usada com outros dados...` | | Código com requisição ainda em andamento | `409`: `Já existe uma requisição em andamento com esta Idempotency-Key.` | | Header vazio ou com mais de 255 caracteres | `422` | | A primeira tentativa terminou em `4xx` (ex.: validação) | O código é liberado. A próxima tentativa com o mesmo código executa de novo | | A primeira tentativa terminou em `5xx` ou exceção | A resposta de erro fica guardada e é devolvida nas repetições. Confira a lista de cobranças e, se a cobrança não existir, use um código novo | - **Mesmos dados:** a comparação usa o body inteiro. - **Retenção:** cada código fica guardado por **30 dias**. Depois disso, ele é tratado como novo. - **`409` que não some:** se o processo da API cair no meio da operação, o código fica em andamento e continua respondendo `409`. Confira a lista de cobranças antes de tentar com um código novo. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai usar o header Idempotency-Key ao criar cobranças na API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Endpoints: - POST /billing/charges — cria cobrança Pix ou boleto; header Idempotency-Key opcional - POST /banking/pix/qrcode/dynamic { amount } — cria Pix com valor; header Idempotency-Key opcional Regras: gere um UUID v4 quando o usuário inicia a operação e reenvie o mesmo valor em toda nova tentativa dela (timeout, erro de rede, duplo clique); operação nova = UUID novo. Vale por conta e por rota, guardado 30 dias. Mesmo código com corpo diferente: 422. Requisição ainda em andamento: 409 (confira a lista de cobranças antes de usar outro código). Resposta repetida vem com o header Idempotent-Replayed: true. Respostas 4xx liberam o código; 5xx ficam guardadas. Formato de resposta: { "code", "success", "data", "message" }; erro { "message", "success": false, "data" }; erro de validação 422 { "message", "errors": { campo: [..] } }. Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Autenticação Base URL: `https://api.banking.fastgivr.com.br` A API usa JWT. Envie o token em todas as rotas protegidas: ``` Authorization: Bearer {jwt} Content-Type: application/json Accept: application/json account: {account_id} ``` - `account` é opcional. Escolhe a conta ativa entre as contas do usuário (`GET /access/accounts`). Sem ele, vale a conta do login. Conta que não é do usuário → `403`; conta inexistente → `404`. - Sem token, token inválido ou sessão encerrada → `401` `{ "message": "Acesso negado." }`. - Usuário inativo ou bloqueado depois do login → `403` `{ "message", "user_status" }`. - Conta inativa, suspensa ou encerrada só consulta (GET); excluída não abre nada → `403` `{ "message", "account_status" }`. - Sem a permissão da rota → `403` `{ "message", "required_permissions": [...] }` (ver [Papéis e permissões](/gestao/usuarios#papeis-e-permissoes)). ## Dois jeitos de obter o token | Uso | Rota | Validade | | --- | --- | --- | | Pessoa (portal, app) | [`POST /access/auth/login`](/autenticacao/login-e-sessao#post-access-auth-login) com e-mail e senha (e 2FA, se ativado) | 24 horas, renovável | | Integração (servidor a servidor) | [`POST /access/account/get-token`](/autenticacao/login-e-sessao#post-access-account-get-token) com o e-mail do usuário de API e o token da conta | 10 minutos; peça outro ao vencer | O usuário de API é criado em [Tokens de API](/gestao/tokens-api). ## Limite de tentativas Login, `get-token`, `forgot` e `reset` usam o limite `credentials`: **10 por minuto por IP** e **5 por minuto por e-mail + IP**. Passou disso → `429`. ## Páginas - [Login e Sessão](/autenticacao/login-e-sessao): login, 2ª etapa do 2FA, logout, renovação, sessões ativas, token de integração. - [Perfil](/autenticacao/perfil): dados do usuário logado. - [Troca de e-mail e telefone](/autenticacao/troca-de-contato): troca com código enviado ao novo contato. - [Recuperação de Senha](/autenticacao/recuperacao-de-senha): link de redefinição por e-mail. - [Verificação de E-mail](/autenticacao/verificacao-de-email): código de confirmação do e-mail. - [Login em Duas Etapas (2FA)](/autenticacao/2fa): ativar SMS, e-mail ou Google Authenticator; verificar telefone. - [Notificações push](/autenticacao/notificacoes-push): aparelhos e preferências de push. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a autenticação da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id} escolhe a conta ativa (sem ele vale a conta do login). Endpoints: - POST /access/auth/login — body { email, password, device_name? }; resposta { token, session_duration (horas), expires_at, app_id }; se 2FA ativo, resposta { two_factor_required: true, method, challenge_token, expires_at } e é preciso chamar POST /access/auth/login/two-factor/verify { challenge_token, code } (6 dígitos), que devolve o mesmo formato de token. - POST /access/account/get-token — integração servidor a servidor; body { email (do usuário com papel API), token (token da conta) }; resposta data { token, token_type: "Bearer", expires_at (10 minutos), permissions }. - PUT /access/auth/refresh — renova o JWT do login; resposta { token, session_duration, expires_at, app_id }. - POST /access/auth/logout — encerra a sessão. Regras: 401 { "message": "Acesso negado." } sem token ou sessão encerrada; 401 { "error" } credenciais erradas; 403 { "message", "user_status" } usuário inativo/bloqueado; 403 { "message", "account_status" } conta sem operação; 403 { "message", "required_permissions" } sem permissão; 429 ao passar de 10 tentativas/min por IP ou 5/min por e-mail+IP em login, get-token, forgot e reset. Token de get-token vale 10 min: guarde e peça outro antes de vencer. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Login em Duas Etapas (2FA) Base URL: `https://api.banking.fastgivr.com.br` Segundo fator **opcional**, escolhido pelo próprio usuário. Padrão: nenhum. Depois de ativado e confirmado, o login passa a pedir um código (ver [login com 2FA](/autenticacao/login-e-sessao#post-access-auth-login-two-factor-verify)). **Métodos:** `sms`, `email` ou `google` (Google Authenticator ou outro app TOTP: 6 dígitos, período de 30 s, tolerância de ±30 s). - Códigos de SMS e e-mail têm 6 dígitos e valem **10 minutos**. - **5 erros** apagam o desafio: é preciso recomeçar. - `sms` só pode ser ativado com o telefone **verificado** ([verificação de telefone](#verificacao-de-telefone)). - Um setup iniciado e não confirmado não altera nada: o login continua como antes. Todas as rotas desta página exigem `Authorization: Bearer {jwt}` e valem para o usuário logado. Não exigem permissão. --- ## GET /access/account/two-factor Situação do 2FA. Nunca devolve o segredo TOTP. ```json { "code": 200, "success": true, "data": { "method": "sms", "confirmed": true, "email": "ana@empresa.com", "phone": "11988887777", "phone_verified": true } } ``` `method: null` e `confirmed: false`: 2FA desligado. ## POST /access/account/two-factor/setup Inicia a ativação. Para `sms` e `email`, envia o código na hora. Para `google`, gera um segredo novo. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `method` | string | Sim | `sms`, `email` ou `google` | **Response 200:** ```json { "code": 200, "success": true, "data": { "challenge_token": "Kq3...48-caracteres", "secret": "JBSWY3DPEHPK3PXP", "otpauth_uri": "otpauth://totp/FastGivr%3Aana%40empresa.com?secret=JBSWY3DPEHPK3PXP&issuer=FastGivr&algorithm=SHA1&digits=6&period=30" }, "message": "Código enviado — confirme para ativar." } ``` `secret` e `otpauth_uri` só vêm no `google` (`null` nos outros). Gere o QR Code a partir de `otpauth_uri` no próprio cliente. **Erros (422 `{ "error" }`):** `Verifique seu telefone antes de ativar a verificação por SMS.`; usuário sem telefone; falha no envio do SMS ou e-mail. ## POST /access/account/two-factor/confirm Confere o código e ativa o método. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `challenge_token` | string | Sim | do `setup` | | `code` | string | Sim | 6 dígitos (recebido ou do app) | **Response 200:** ```json { "code": 200, "success": true, "data": { "method": "google", "confirmed": true }, "message": "Verificação em dois fatores ativada com sucesso." } ``` **Erros (422 `{ "error" }`):** `Código inválido.`; `Configuração expirada — comece de novo.`; `Muitas tentativas incorretas. Solicite um novo código.` ## DELETE /access/account/two-factor Desliga o 2FA. Pede a senha atual (não um código), para quem perdeu o acesso ao método. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `current_password` | string | Sim | senha atual | **Response 200:** `{ "code": 200, "success": true, "data": null, "message": "Verificação em dois fatores desativada." }` **Erros:** `401` `{ "error": "A senha atual está incorreta." }`. --- ## Verificação de telefone Pré-requisito do 2FA por SMS (pode ser feita sem ativar o 2FA). O telefone do usuário só muda depois do código certo. ### POST /access/account/phone-verification/start Envia um código de 6 dígitos por SMS para o número informado. **Limite:** 5 por minuto. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `phone` | string | Sim | com DDD; mínimo 10 dígitos (máscara é ignorada) | **Response 200:** `{ "code": 200, "success": true, "data": null, "message": "Código de verificação enviado por SMS." }` **Erros (422 `{ "error" }`):** `Informe um telefone válido, com DDD.`; falha no envio. ### POST /access/account/phone-verification/confirm Confere o código e grava o telefone como verificado. **Limite:** 10 por minuto. **Body:** `{ "code": "123456" }` **Response 200:** `{ "code": 200, "success": true, "data": null, "message": "Telefone verificado com sucesso." }` **Erros (422 `{ "error" }`):** `Código inválido.`; `Nenhuma verificação pendente ou o código expirou. Solicite um novo código.`; `Muitas tentativas incorretas. Solicite um novo código.` (5 erros). ### POST /access/account/phone-verification/resend Reenvia um código novo para o mesmo número. **Limite:** 5 por minuto. Sem body. **Response 200:** `{ "code": 200, "success": true, "data": null, "message": "Código reenviado." }` **Erros (422 `{ "error" }`):** `Nenhuma verificação pendente. Informe o telefone novamente.`; falha no envio. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a configuração de 2FA e a verificação de telefone da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Vale para o usuário logado, sem permissão especial. Endpoints: - GET /access/account/two-factor — data { method (null|sms|email|google), confirmed, email, phone, phone_verified }. - POST /access/account/two-factor/setup — body { method: sms|email|google }; data { challenge_token, secret, otpauth_uri } (secret/otpauth_uri só no google; gere o QR Code localmente a partir de otpauth_uri). - POST /access/account/two-factor/confirm — body { challenge_token, code (6 dígitos) }; data { method, confirmed: true }. - DELETE /access/account/two-factor — body { current_password }; desliga; 401 { error } se a senha estiver errada. - POST /access/account/phone-verification/start — body { phone (com DDD, mín. 10 dígitos) }; envia SMS. Limite 5/min. - POST /access/account/phone-verification/confirm — body { code }; grava o telefone como verificado. Limite 10/min. - POST /access/account/phone-verification/resend — sem body; reenvia. Limite 5/min. Regras: códigos têm 6 dígitos e valem 10 min; 5 erros apagam o desafio (recomeçar); ativar sms exige telefone verificado; erros de negócio → 422 { error } (código inválido, expirado, falha no envio); setup não confirmado não muda nada. Depois de ativo, o login responde two_factor_required e exige POST /access/auth/login/two-factor/verify { challenge_token, code }. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Login e Sessão Base URL: `https://api.banking.fastgivr.com.br` Login de pessoas, 2ª etapa do 2FA, renovação, logout, sessões ativas e o token de integração. --- ## POST /access/auth/login Autentica com e-mail e senha. **Autenticação:** não · **Limite:** `credentials` (10/min por IP, 5/min por e-mail + IP) | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `email` | string | Sim | e-mail do usuário | | `password` | string | Sim | senha | | `device_name` | string | Não | padrão `dashboard`. `dashboard_sass` devolve `user` e `roles` em vez de `app_id` | **Response 200 (sem 2FA):** ```json { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "session_duration": 24, "expires_at": "2026-11-21 14:30:00", "app_id": 12 } ``` - O token vale 24 horas (`session_duration`, em horas). `app_id` é o vínculo usuário↔conta do login. - O login cria uma [sessão](#sessoes-ativas); o JWT leva o id dela. **Response 200 (com 2FA ativo):** nenhum token ainda. Conclua em [`POST /access/auth/login/two-factor/verify`](#post-access-auth-login-two-factor-verify). ```json { "two_factor_required": true, "method": "sms", "challenge_token": "Xb7...48-caracteres", "expires_at": "2026-11-20T14:40:00-03:00", "message": "Confirme o código de verificação para continuar." } ``` **Erros:** | Status | Corpo | | --- | --- | | 401 | `{ "error": "Essas credenciais não correspondem aos nossos registros." }` (e-mail, senha ou usuário excluído) | | 401 | `{ "error": "O token fornecido é inválido." }` (usuário sem conta vinculada) | | 403 | `{ "error": "...", "user_status": 0 }` usuário inativo (`0`) ou bloqueado (`2`) | | 422 | campos ausentes (`{ "message", "errors" }`) | | 429 | limite de tentativas | --- ## POST /access/auth/login/two-factor/verify 2ª etapa do login com 2FA. Devolve o mesmo token do login sem 2FA. **Autenticação:** não · **Limite:** 10 por minuto | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `challenge_token` | string | Sim | recebido no login | | `code` | string | Sim | 6 dígitos (SMS, e-mail ou Google Authenticator) | **Response 200:** igual ao login sem 2FA. **Erros (422 `{ "error" }`):** - `Código inválido.` - `Desafio de verificação inválido ou expirado. Faça login novamente.` (o desafio vale 10 minutos) - `Muitas tentativas incorretas. Solicite um novo código.` (5 erros) ## POST /access/auth/login/two-factor/resend Gera e envia outro código (só SMS e e-mail). Zera as tentativas e renova os 10 minutos. **Autenticação:** não · **Limite:** 5 por minuto **Body:** `{ "challenge_token": "..." }` **Response 200:** `{ "message": "Código reenviado com sucesso." }` **Erros (422 `{ "error" }`):** desafio inválido ou expirado; método Google Authenticator (`Este método não usa código reenviável — abra o Google Authenticator.`); falha no envio. --- ## PUT /access/auth/refresh Troca o token atual por um novo e estende a sessão. **Autenticação:** sim **Response 200:** ```json { "token": "eyJ0eXAiOiJKV1Qi...", "session_duration": 1, "expires_at": "2026-11-20 15:30:00", "app_id": 12 } ``` **Erros:** `401` `{ "error": "Could not refresh token" }`. Use `expires_at` da resposta como nova validade. ## POST /access/auth/logout Encerra a sessão atual. O token passa a receber `401`. **Autenticação:** sim **Response 200:** `{ "message": "Successfully logged out" }` --- ## Sessões ativas Cada login cria uma sessão. A cada requisição a API confere a sessão do token: encerrada ou expirada → `401`. `refresh` estende a sessão; `logout` encerra. Tokens de `get-token` não criam sessão. `location` vem dos cabeçalhos de geolocalização do proxy; sem eles, `null`. ### GET /access/auth/sessions Sessões ativas da pessoa logada (em todas as contas), a atual primeiro. **Autenticação:** sim ```json { "data": [ { "id": "9d3f6c1e-2b7a-4c1d-9a51-0f4e2b8c7d10", "device_type": "desktop", "browser": "Chrome", "platform": "Mac", "ip_address": "200.100.50.10", "location": { "city": "São Paulo", "region": "São Paulo", "country": "BR" }, "last_active_at": "2026-11-20T14:32:10-03:00", "created_at": "2026-11-20T09:01:44-03:00", "is_current": true } ] } ``` `device_type`: `desktop`, `smartphone`, `tablet`, `bot`… ou `null`. ### DELETE /access/auth/sessions/\{id\} Encerra uma sessão. **Autenticação:** sim · **Limite:** 10 por minuto **Body:** `{ "password": "senha-atual" }` **Response 200:** `{ "message": "Sessão encerrada." }` **Erros:** `404` sessão não encontrada, já encerrada ou de outra pessoa; `422` senha ausente ou incorreta (`errors.password`). ### POST /access/auth/sessions/logout-others Encerra todas as outras sessões, mantendo a atual. **Autenticação:** sim · **Limite:** 10 por minuto **Body:** `{ "password": "senha-atual" }` **Response 200:** `{ "message": "Outras sessões encerradas.", "data": { "revoked": 2 } }` **Erros:** `422` senha ausente ou incorreta (`errors.password`). --- ## POST /access/account/get-token Token para integração servidor a servidor. Só funciona para usuário com o papel **`API`** vinculado à conta (crie em [Tokens de API](/gestao/tokens-api)). **Autenticação:** não · **Limite:** `credentials` (10/min por IP, 5/min por e-mail + IP) | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `email` | string | Sim | e-mail do usuário de API | | `token` | string | Sim | token da **conta** (campo `token` de [`GET /access/account`](/gestao/conta#get-access-account), visível para quem tem `manage_api`) | **Response 200:** ```json { "code": 200, "success": true, "data": { "token": "eyJ0eXAiOiJKV1Qi...", "token_type": "Bearer", "expires_at": "2026-11-20T14:40:00-03:00", "permissions": [ { "id": 1, "name": "view_balance", "guard_name": "api" } ] }, "message": "Autenticado com sucesso." } ``` - O token vale **10 minutos** e não é renovável: peça outro ao vencer. - `permissions`: permissões efetivas do usuário de API (as operacionais do papel `API`). **Erros:** | Status | Corpo | | --- | --- | | 401 | `{ "message": "Essas credenciais não correspondem aos nossos registros.", "success": false, "data": null }` (e-mail não existe) | | 401 | `{ "message": "O token fornecido é inválido.", "success": false, "data": null }` (token da conta errado, usuário fora da conta ou sem papel `API`) | | 422 | `{ "message": "Dados de entrada inválidos.", "success": false, "data": { "email": [...] } }` | | 429 | limite de tentativas | --- ## GET /access/clock Hora do servidor em milissegundos (para acertar o relógio do cliente). **Autenticação:** não **Response 200:** `{ "now": 1763659200000 }` ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar login, sessão e token de integração da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Endpoints: - POST /access/auth/login — body { email, password, device_name? }; 200 { token, session_duration (horas, 24), expires_at "Y-m-d H:i:s", app_id }. Se 2FA ativo: 200 { two_factor_required: true, method (sms|email|google), challenge_token, expires_at } sem token. - POST /access/auth/login/two-factor/verify — body { challenge_token, code (6 dígitos) }; 200 igual ao login. Limite 10/min. - POST /access/auth/login/two-factor/resend — body { challenge_token }; só sms/email; 200 { message }. Limite 5/min. - PUT /access/auth/refresh — autenticado; 200 { token, session_duration, expires_at, app_id }; 401 { error } se não renovar. - POST /access/auth/logout — autenticado; 200 { message }. - GET /access/auth/sessions — autenticado; { data: [{ id, device_type, browser, platform, ip_address, location, last_active_at, created_at, is_current }] }. - DELETE /access/auth/sessions/{id} — body { password }; 200 { message }; 404 sessão não encontrada; 422 errors.password. Limite 10/min. - POST /access/auth/sessions/logout-others — body { password }; 200 { message, data: { revoked } }. Limite 10/min. - POST /access/account/get-token — integração; body { email (usuário com papel API), token (token da conta) }; 200 { code, success, data: { token, token_type: "Bearer", expires_at (ISO, 10 min), permissions: [{ id, name, guard_name }] }, message }. - GET /access/clock — 200 { now } (ms). Regras: login com credenciais erradas 401 { error }; usuário inativo/bloqueado 403 { error, user_status }; erros do 2FA 422 { error } (código inválido, desafio expirado em 10 min, 5 tentativas); get-token com dados errados 401 { message, success: false, data: null }; limite credentials em login e get-token: 10/min por IP e 5/min por e-mail+IP → 429. Sessão encerrada → 401 { "message": "Acesso negado." }. Para integração, guarde o token de get-token e peça outro antes de 10 minutos. Formato de resposta: { "code", "success", "data", "message" } (login, refresh, logout e sessões respondem sem esse envelope, como acima); erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Notificações push (aplicativo) Base URL: `https://api.banking.fastgivr.com.br` Toda notificação salva para o usuário (a lista de [Notificações](/gestao/notificacoes)) também vai por push aos aparelhos dele, pelo serviço de push do Expo. Cada usuário escolhe quais tipos recebe por push; a lista continua com todas. Todas as rotas exigem `Authorization: Bearer {jwt}`. ## Tipos de notificação | `type` | Quando | Quem recebe | Abre no app | | --- | --- | --- | --- | | `payment_received` | Entrada de dinheiro: Pix, BolePix, boleto ou transferência (não taxas nem saídas) | Usuários da conta com `view_extract` ou `view_transactions` | `/transacoes/{id}` | | `charge_paid` | Cobrança passa para paga | Usuários da conta com `view_charges` | `/cobrancas/{id}` | | `export_ready` | Exportação de transações concluída (ou sem resultado) | Quem pediu a exportação | `/notificacoes` | | `other` | Qualquer outra notificação | O destinatário | `/notificacoes` | Dinheiro recebido e cobrança paga só são avisados depois que o pagamento é gravado. Falha ao notificar nunca interrompe o pagamento. --- ## POST /access/auth/push-tokens Registra o aparelho. **Limite:** 20 por minuto. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `token` | string | Sim | `ExponentPushToken[...]` ou `ExpoPushToken[...]`, até 255 caracteres | | `platform` | string | Não | `ios`, `android` ou `web` | | `device_name` | string | Não | até 100 caracteres | Um token pertence a um só usuário: registrar o mesmo aparelho com outro login passa o token para o novo usuário. **Response 201:** `{ "message": "Aparelho registrado para notificações.", "data": { "id": 1 } }` ## DELETE /access/auth/push-tokens Remove o aparelho (ao sair do app). **Limite:** 20 por minuto. **Body:** `{ "token": "ExponentPushToken[...]" }` **Response 200:** `{ "message": "Aparelho removido das notificações." }` Tokens que o Expo informa como inexistentes (`DeviceNotRegistered`) são removidos automaticamente. --- ## GET /access/auth/notification-preferences ```json { "data": [ { "type": "payment_received", "label": "Dinheiro recebido", "description": "Pix, BolePix, boleto e transferências que entram na conta.", "push": true }, { "type": "charge_paid", "label": "Cobrança paga", "description": "Quando um cliente paga uma cobrança.", "push": true }, { "type": "export_ready", "label": "Exportação pronta", "description": "Arquivo de transações pronto para baixar.", "push": true }, { "type": "other", "label": "Outros avisos", "description": "Demais avisos da conta.", "push": true } ] } ``` Sem escolha salva, todos os tipos ficam ligados. ## PUT /access/auth/notification-preferences | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `preferences` | objeto | Sim | `{ tipo: boolean }`, ao menos um; envie só os que mudaram | ```json { "preferences": { "charge_paid": false } } ``` **Response 200:** `{ "message": "Preferências salvas.", "data": [ ...lista atualizada... ] }` **Erros:** `422` `{ "message": "Tipo de notificação desconhecido: ..." }`; `422` `{ "message", "errors" }` valor não booleano. --- ## Mensagem enviada ao aparelho ```json { "to": "ExponentPushToken[...]", "title": "Pix recebido", "body": "Você recebeu R$ 150,50 na conta Empresa Exemplo Ltda.", "data": { "type": "payment_received", "notification_id": "uuid", "url": "/transacoes/123", "account_id": 1, "transaction_id": 123, "value": 150.5 }, "badge": 3, "sound": "default", "channelId": "default" } ``` `badge` é o total de notificações não lidas. O app usa `data.url` para abrir a tela e `data.account_id` para trocar para a conta certa. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar as notificações push (Expo) da API FastGivr num app. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}. Endpoints: - POST /access/auth/push-tokens — body { token (ExponentPushToken[...] ou ExpoPushToken[...]), platform? (ios|android|web), device_name? }; 201 { message, data: { id } }. Chame após o login. - DELETE /access/auth/push-tokens — body { token }; 200 { message }. Chame ao sair. - GET /access/auth/notification-preferences — { data: [{ type, label, description, push }] }. - PUT /access/auth/notification-preferences — body { preferences: { payment_received|charge_paid|export_ready|other: boolean } }; 200 { message, data }. Regras: limite de 20/min nas rotas de push-tokens; tipo desconhecido → 422 { message }; sem preferência salva todos os tipos ficam ligados. O push chega com data { type, notification_id, url, account_id, ... } e badge = não lidas: abra data.url e troque para data.account_id (header account nas chamadas seguintes). Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Perfil Base URL: `https://api.banking.fastgivr.com.br` Dados do usuário logado. Não exigem permissão. --- ## GET /access/auth/me Usuário logado, conta ativa, permissões e todas as contas dele. **Autenticação:** sim **Response 200:** ```json { "account": { "id": 3, "name": "Empresa Exemplo Ltda", "document": "12345678000199", "email": "financeiro@empresa.com", "agency": "0001", "account": "123456", "status": "ACTIVE", "bank_id": 1 }, "user": { "id": 10, "name": "Ana Silva", "email": "ana@empresa.com", "document": "52998224725", "phone": "11988887777", "status": 1, "email_verified_at": "2026-11-01T10:00:00.000000Z", "phone_verified_at": null }, "permissions": [ { "id": 1, "name": "view_balance", "slug": null } ], "role": { "id": 4, "name": "pj_administrador", "label": "Administrador", "account_type": "pj" }, "accounts": [ { "account": { "id": 3, "name": "Empresa Exemplo Ltda", "document": "12345678000199" }, "role": { "id": 4, "name": "pj_administrador" } } ] } ``` - `account` é a conta ativa (header `account` ou a do login). - `permissions` são as permissões efetivas (papel + diretas) na conta ativa. - `accounts` lista todas as contas do usuário, com o papel em cada uma. --- ## PUT /access/auth/edit Edita os dados do usuário logado. Exige a senha atual. **Autenticação:** sim | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `current_password` | string | Sim | senha atual | | `name` | string | Não | até 50 caracteres | | `document` | string | Não | CPF | | `dt_birth` | string | Não | `YYYY-MM-DD` | | `email` | string | Não | só o e-mail atual ou vazio. Para trocar, use a [troca verificada](/autenticacao/troca-de-contato) | | `phone` | string | Não | até 15 caracteres; só o telefone atual ou vazio (apaga). Para trocar, use a [troca verificada](/autenticacao/troca-de-contato) | | `new_password` | string | Não | mínimo 8 caracteres; exige `new_password_confirmation` igual | **Response 200:** ```json { "code": 200, "success": true, "user": { "id": 10, "name": "Ana Silva", "email": "ana@empresa.com", "phone": "11988887777" }, "message": "Usuário atualizado com sucesso" } ``` **Erros:** | Status | Corpo | | --- | --- | | 401 | `{ "message": "A senha atual está incorreta." }` | | 422 | `{ "message", "errors": { "email": ["Para alterar o e-mail, confirme o novo endereço com o código enviado a ele."] } }` (o mesmo para `phone`) | | 422 | validação dos campos (`{ "message", "errors" }`) | ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar o perfil do usuário logado da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Endpoints: - GET /access/auth/me — 200 { account (conta ativa), user, permissions: [{ id, name, slug }], role: { id, name, label, account_type }, accounts: [{ account, role }] } (sem envelope). - PUT /access/auth/edit — body { current_password (obrigatório), name? (até 50), document?, dt_birth? (YYYY-MM-DD), email? e phone? (só o valor atual ou vazio), new_password? (mín. 8) + new_password_confirmation }; 200 { code, success, user, message }. Regras: senha atual errada → 401 { message }; e-mail ou telefone diferente do atual → 422 { message, errors: { email|phone: [...] } } (troca só por POST /access/contact-changes com código); validação → 422 { message, errors }. Sem permissão especial. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Recuperação de Senha Base URL: `https://api.banking.fastgivr.com.br` "Esqueci minha senha": a API envia por e-mail um link com um token; a tela do link chama `reset` com o token e a nova senha. **Limite (as duas rotas):** `credentials` (10/min por IP, 5/min por e-mail + IP) → `429`. --- ## POST /access/auth/forgot Envia o link de redefinição. Um pedido novo invalida o anterior. **Autenticação:** não | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `email` | string | Sim | e-mail de um usuário existente | | `url` | string | Sim | endereço da tela de redefinição. O token é **concatenado ao fim** da `url` (ex.: `https://portal.banking.fastgivr.com.br/redefinir-senha?token=`). Domínios aceitos: `portal.banking.fastgivr.com.br`, `app.banking.fastgivr.com.br`, `backoffice.banking.fastgivr.com.br` | **Response 201:** ```json { "code": 201, "success": true, "data": null, "message": "Enviamos seu link de redefinição de senha por e-mail!" } ``` **Erros:** `422` `{ "code": 422, "message", "success": false, "data": { "email": [...], "url": ["Endereço de redefinição de senha não permitido."] } }` (e-mail inexistente, `url` inválida ou de outro domínio). --- ## POST /access/auth/reset Grava a nova senha. O link vale **1 hora**. Também marca o e-mail do usuário como verificado. **Autenticação:** não | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `token` | string | Sim | token recebido no link | | `password` | string | Sim | mínimo 6 caracteres | | `password_confirmation` | string | Sim | igual a `password` | **Response 200:** `{ "message": "Senha foi redefinida com sucesso" }` **Erros:** - `422` `{ "message", "errors" }`: token inexistente ou já usado, senha curta ou confirmação diferente. - `422` `{ "message" }`: link com mais de 1 hora (o token é apagado; peça outro em `forgot`). ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a recuperação de senha da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: nenhuma nestas rotas. Endpoints: - POST /access/auth/forgot — body { email (de usuário existente), url (tela de redefinição; o token é concatenado ao fim da url; domínio precisa ser portal.banking.fastgivr.com.br, app.banking.fastgivr.com.br ou backoffice.banking.fastgivr.com.br) }; 201 { code, success, data: null, message }. - POST /access/auth/reset — body { token (do link), password (mín. 6), password_confirmation }; 200 { message }. Regras: link vale 1 hora (depois: 422 { message }, peça outro); forgot com e-mail inexistente ou url de outro domínio → 422 { code, message, success: false, data: { campo: [..] } }; reset com token inválido → 422 { message, errors }; limite 10/min por IP e 5/min por e-mail+IP → 429. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Troca de e-mail e telefone Base URL: `https://api.banking.fastgivr.com.br` O e-mail e o telefone **da conta** (também são valores de chave Pix) e **do usuário** (o e-mail é o login) só mudam depois de um código enviado ao **novo** contato. Até a confirmação, o contato antigo continua valendo. [`PUT /access/account`](/gestao/conta#put-access-account) e [`PUT /access/auth/edit`](/autenticacao/perfil#put-access-auth-edit) recusam (`422`) e-mail ou telefone diferente do atual; aceitam o mesmo valor (com outra máscara) e vazio (remove). Todas as rotas exigem `Authorization: Bearer {jwt}`. Use o header `account` para trocar o contato de uma conta que não é a do login. --- ## POST /access/contact-changes Envia o código ao novo contato. Um pedido novo para o mesmo campo substitui o anterior. **Limite:** 5 por minuto. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `scope` | string | Sim | `account` (dados da conta) ou `user` (seu usuário) | | `field` | string | Sim | `email` ou `phone` | | `value` | string | Sim | até 150 caracteres; e-mail válido ou celular com DDD (com ou sem `+55` e máscara) | | `pin` | string | Se `scope=account` | PIN da conta (exige a permissão `manage_config`) | | `password` | string | Se `scope=user` | senha atual | **Response 201:** ```json { "message": "Enviamos um código para o novo e-mail.", "data": { "id": "9d40a1c2-6b1e-4f7a-8c2d-3e5f6a7b8c9d", "scope": "account", "field": "email", "destination": "no***@empresa.com", "expires_at": "2026-11-20T15:10:00-03:00" } } ``` **Erros:** - `403` sem `manage_config` (`scope=account`). - `422` `errors.pin` (PIN incorreto ou bloqueado: 5 erros bloqueiam o PIN por 15 minutos) ou `errors.password` (senha incorreta). - `422` `{ "error", "errors": { "value": [...] } }`: valor inválido, igual ao atual, e-mail já usado por outro usuário ou falha no envio. ## POST /access/contact-changes/{id}/confirm Confere o código e grava o novo valor. **Limite:** 10 por minuto. - O código vale **10 minutos**. E-mail: **4 números**. SMS: **6 números**. - Depois de 3 erros seguidos, cada erro aumenta a espera: 30 s, 1 min, 2 min, 4 min, 8 min e, a partir daí, 15 min. A espera nunca bloqueia de vez e zera quando o código é confirmado. **Body:** `{ "code": "4821" }` **Response 200 (conta):** `{ "message": "E-mail atualizado.", "account": { ... } }` (mesmo formato de [`GET /access/account`](/gestao/conta#get-access-account)). **Response 200 (usuário):** ```json { "message": "Telefone atualizado.", "user": { "id": 10, "name": "Ana Silva", "email": "ana@empresa.com", "phone": "11977776666", "email_verified_at": "2026-11-01T10:00:00.000000Z", "phone_verified_at": "2026-11-20T15:02:00.000000Z" } } ``` No usuário, o contato confirmado fica marcado como verificado. **Erros:** `422` `{ "error", "errors": { "code": [...] } }` código inválido, expirado ou em espera (com o tempo restante); `404` pedido de outra pessoa ou de outra conta. ## POST /access/contact-changes/{id}/resend Gera e envia um novo código ao mesmo contato, renovando os 10 minutos. **Limite:** 3 por minuto. Sem body. **Response 200:** `{ "message": "Código reenviado.", "data": { "id", "scope", "field", "destination", "expires_at" } }` **Erros:** `422` `{ "error" }` pedido sem pendência ou falha no envio; `404` pedido de outra pessoa. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a troca verificada de e-mail e telefone da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Endpoints: - POST /access/contact-changes — body { scope: account|user, field: email|phone, value, pin (se scope=account), password (se scope=user) }; 201 { message, data: { id, scope, field, destination (mascarado), expires_at } }. Limite 5/min. - POST /access/contact-changes/{id}/confirm — body { code }; 200 { message, account } (scope=account) ou { message, user: { id, name, email, phone, email_verified_at, phone_verified_at } }. Limite 10/min. - POST /access/contact-changes/{id}/resend — sem body; 200 { message, data }. Limite 3/min. Regras: código vale 10 min; e-mail recebe 4 números, SMS 6. Após 3 erros a espera cresce (30 s, 1, 2, 4, 8, 15 min). scope=account exige permissão manage_config (senão 403) e o PIN da conta (5 PINs errados bloqueiam por 15 min). Erros 422: errors.pin, errors.password, { error, errors.value } (valor inválido, igual ao atual, e-mail em uso, falha no envio), { error, errors.code } (código inválido/expirado/em espera). Pedido de outra pessoa → 404. PUT /access/account e PUT /access/auth/edit recusam e-mail/telefone diferente do atual: use este fluxo. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Verificação de E-mail Base URL: `https://api.banking.fastgivr.com.br` Confirma o e-mail do usuário logado com um código de **4 números** enviado a ele. --- ## POST /access/auth/send-verification-code Envia o código ao e-mail do usuário logado. Um envio novo substitui o código anterior. **Autenticação:** sim | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `email` | string | Sim | e-mail do próprio usuário logado | **Response 200:** ```json { "code": 200, "success": true, "data": null, "message": "Código de verificação enviado com sucesso" } ``` **Erros:** `422` e-mail não cadastrado (`data.email`); `404` e-mail de outro usuário. --- ## POST /access/auth/verify-email Confere o código e marca o e-mail como verificado. **Autenticação:** sim | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `email` | string | Sim | o mesmo do envio | | `verification_code` | string | Sim | 4 números | **Response 200:** `{ "message": "E-mail verificado com sucesso!" }` **Erros:** - `400` `{ "error": "Código de verificação inválido." }`. Depois de 3 erros seguidos, cada erro aumenta a espera: 30 s, 1 min, 2 min, 4 min, 8 min e, a partir daí, 15 min. Com espera, a resposta traz `retry_after` (segundos). - `429` `{ "error", "retry_after" }` e cabeçalho `Retry-After`: tentativa durante a espera. - `422` `{ "message", "errors" }`: campos ausentes. A espera nunca bloqueia de vez e zera quando o código é confirmado. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a verificação de e-mail do usuário logado na API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}. Endpoints: - POST /access/auth/send-verification-code — body { email (do próprio usuário) }; 200 { code, success, data: null, message }. Envia um código de 4 números; novo envio substitui o anterior. - POST /access/auth/verify-email — body { email, verification_code }; 200 { message }. Regras: código errado → 400 { error, retry_after? }; após 3 erros seguidos a espera cresce (30 s, 1, 2, 4, 8 e 15 min); tentar durante a espera → 429 { error, retry_after } com header Retry-After; mostre a contagem regressiva com retry_after. E-mail não cadastrado → 422; e-mail de outro usuário → 404. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Conta Base URL: `https://api.banking.fastgivr.com.br` Dados da conta ativa, PIN, evolução do saldo e lista de contas do usuário. **Headers:** ``` Authorization: Bearer {jwt} Content-Type: application/json account: {account_id} ``` `account` é opcional: sem ele vale a conta do login. Conta inativa, suspensa ou encerrada só aceita consultas (`403` `{ "message", "account_status" }` nas demais). --- ## GET /access/accounts Contas a que o usuário tem acesso. Use o `id` no header `account`. Sem permissão. ```json { "code": 200, "success": true, "accounts": [ { "id": 3, "name": "Empresa Exemplo Ltda", "document": "12345678000199", "...": "mesmo formato de GET /access/account" } ], "message": "Informações de Contas" } ``` ## GET /access/account Conta ativa. Sem permissão. Se a conta ainda não tem chave Pix aleatória (`key_pix`), a API cadastra uma nesta chamada. ```json { "code": 200, "success": true, "account": { "id": 3, "code_account": "000123", "client_id": null, "name": "Empresa Exemplo Ltda", "email": "financeiro@empresa.com", "phone": "+5511988887777", "document": "12345678000199", "agency": "0001", "account": "123456", "token": "tok_xxxxxxxx", "key_pix": "7d9f0c3e-1a2b-4c5d-8e9f-0a1b2c3d4e5f", "status": { "code": "ACTIVE", "title": "Ativo" }, "path_logo": null, "address": { "street": "Rua Exemplo", "number": "100", "city": "São Paulo", "state": "SP", "zip_code": "01001000" }, "has_pin": true, "created_at": "...", "updated_at": "..." }, "message": "Conta obtida com sucesso." } ``` - `token` (usado em [`POST /access/account/get-token`](/autenticacao/login-e-sessao#post-access-account-get-token)) só aparece para quem tem `manage_api` na conta. ## PUT /access/account Edita a conta ativa. **Permissão:** `manage_config`. Exige o **PIN** da conta. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `pin` | string | Sim | 6 dígitos; PIN atual da conta | | `name` | string | Não | até 100 caracteres | | `email` | string | Não | só o e-mail atual ou vazio. Para trocar, use a [troca verificada](/autenticacao/troca-de-contato). É o valor da chave Pix tipo e-mail | | `phone` | string | Não | só o celular atual (com ou sem máscara) ou `null`. Para trocar, use a [troca verificada](/autenticacao/troca-de-contato). Gravado como `+55DDDNÚMERO`; é o valor da chave Pix tipo celular | | `document` | string | Não | não pode mudar: só aceita o valor atual | | `new_pin` | string | Não | 6 dígitos; troca o PIN. Recusa `123456`, `654321`, `111111`…`999999` e `400287` | | `address.street` | string | Não | até 255 | | `address.number` | string | Não | até 20 | | `address.city` | string | Não | até 100 | | `address.state` | string | Não | UF, 2 letras | | `address.zip_code` | string | Não | até 10 | | `logo` | arquivo ou string | Não | imagem (multipart) ou base64 | Taxas, limites, status e agência não mudam por esta rota. **Response 200:** `{ "code": 200, "success": true, "account": { ... }, "message": "Conta atualizada com sucesso." }` **Erros:** | Status | Motivo | | --- | --- | | 403 | PIN ausente, errado ou bloqueado, ou conta sem PIN definido. 5 PINs errados bloqueiam o PIN por 15 minutos | | 403 | sem `manage_config` (`{ "message", "required_permissions" }`) | | 422 | `errors.email` / `errors.phone`: contato diferente do atual | | 422 | `errors.document`: `O CPF/CNPJ da conta não pode ser alterado.` | | 422 | validação dos campos (`{ "message", "errors" }`) | ## POST /access/account/pin Define o PIN da conta pela primeira vez. **Permissão:** `manage_pin`. Para trocar um PIN existente, use `new_pin` em `PUT /access/account`. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `pin` | string | Sim | 6 caracteres | | `confirm_pin` | string | Sim | igual a `pin` | **Response 200:** `{ "code": 200, "success": true, "account": { ... }, "message": "Pin definido com sucesso." }` **Erros:** `400` `{ "message": "Pin já foi definido anteriormente." }`; `422` validação. ## GET /access/account/balance-evolution Evolução do saldo, recalculada a partir das transações confirmadas. **Permissão:** `view_balance` ou `view_extract`. | Parâmetro | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `period` | string | Não | `week` (7 dias, por dia), `month` (30 dias, por dia; padrão) ou `year` (12 meses, por mês) | ```json { "code": 200, "success": true, "data": { "period": "month", "range": { "from": "2026-10-22T00:00:00-03:00", "to": "2026-11-20T23:59:59-03:00" }, "summary": { "starting_balance": 1000, "ending_balance": 1500, "variation": 500, "variation_percent": 50, "total_in": 800, "total_out": 300 }, "history": [ { "reference_at": "2026-10-22T23:59:59-03:00", "label": "22/10", "balance": 1000, "inflow": 0, "outflow": 0, "variation": 0 } ] } } ``` `variation_percent` é `null` quando o saldo inicial é zero e o final não. **Erros:** `422` `Período inválido. Valores aceitos: week, month, year.` ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar os dados da conta da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id} (sem ele vale a conta do login). Endpoints: - GET /access/accounts — { code, success, accounts: [conta], message }; use o id no header account. - GET /access/account — { code, success, account: { id, name, email, phone, document, agency, account, token (só com manage_api), key_pix, status: { code (ACTIVE|INACTIVE|SUSPENDED|CLOSED...), title }, address, has_pin, ... }, message }. - PUT /access/account — permissão manage_config; body { pin (obrigatório, 6 dígitos), name?, email?/phone? (só o valor atual ou vazio), document? (não muda), new_pin?, address: { street, number, city, state, zip_code }?, logo? }; 200 { code, success, account, message }. - POST /access/account/pin — permissão manage_pin; body { pin, confirm_pin }; define o PIN só se ainda não existe (senão 400). - GET /access/account/balance-evolution?period=week|month|year — permissão view_balance ou view_extract; data { period, range: { from, to }, summary: { starting_balance, ending_balance, variation, variation_percent, total_in, total_out }, history: [{ reference_at, label, balance, inflow, outflow, variation }] }. Regras: PIN errado/ausente/bloqueado no PUT → 403 (5 erros bloqueiam o PIN por 15 min); sem permissão → 403 { message, required_permissions }; e-mail/telefone diferente do atual → 422 errors.email/phone (troca só por POST /access/contact-changes); CPF/CNPJ diferente → 422 errors.document; new_pin não pode ser sequência óbvia (123456, 654321, 111111…999999, 400287); conta inativa/suspensa/encerrada → 403 { message, account_status } em escrita. Formato de resposta: { "code", "success", "data", "message" } (aqui a conta vem em "account"/"accounts"); erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Notificações do Usuário Base URL: `https://api.banking.fastgivr.com.br` Lista de avisos do usuário logado (a mesma que vai por [push](/autenticacao/notificacoes-push)). Exigem `Authorization: Bearer {jwt}`; não exigem permissão. **Formato de uma notificação:** ```json { "id": "0b9a7c2e-5d1f-4e3a-9b8c-7d6e5f4a3b2c", "type": "App\\Notifications\\PaymentReceivedNotification", "notifiable_type": "App\\Models\\User", "notifiable_id": 10, "data": { "type": "payment_received", "title": "Pix recebido", "message": "Você recebeu R$ 150,50 na conta Empresa Exemplo Ltda.", "transaction_id": 123, "account_id": 3, "value": 150.5, "url": "/transacoes/123" }, "read_at": null, "created_at": "2026-11-20T17:30:00.000000Z", "updated_at": "2026-11-20T17:30:00.000000Z" } ``` O conteúdo de `data` depende do tipo de aviso; `data.type` segue os [tipos de notificação](/autenticacao/notificacoes-push#tipos-de-notificacao). --- ## GET /access/auth/notifications Lista as notificações, mais novas primeiro. | Parâmetro | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `unread_only` | boolean | Não | só não lidas; padrão `false` | | `per_page` | integer | Não | padrão 15 | | `page` | integer | Não | | ```json { "data": [ { "id": "0b9a7c2e-...", "data": { "...": "..." }, "read_at": null } ], "meta": { "total": 3, "page": 1, "limit": 15, "total_pages": 1, "has_next_page": false, "has_prev_page": false }, "unread_count": 3 } ``` ## GET /access/auth/notifications/unread Só as não lidas. Aceita `per_page` e `page`. Mesmo formato, sem `unread_count`. ## GET /access/auth/notifications/unread-count **Response 200:** `{ "unread_count": 3 }` ## PUT /access/auth/notifications/{id}/read Marca uma notificação como lida. **Response 200:** `{ "message": "Notificação marcada como lida", "notification": { ... } }` **Erros:** `404` notificação de outro usuário ou inexistente. ## PUT /access/auth/notifications/mark-all-read **Response 200:** `{ "message": "Todas as notificações foram marcadas como lidas", "unread_count": 0 }` ## DELETE /access/auth/notifications/\{id\} **Response 200:** `{ "message": "Notificação deletada com sucesso" }` **Erros:** `404` notificação de outro usuário ou inexistente. ## DELETE /access/auth/notifications/read/all Apaga todas as já lidas. **Response 200:** `{ "message": "Notificações lidas deletadas com sucesso", "deleted_count": 12 }` ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a central de notificações do usuário da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}. Sem permissão especial. Endpoints: - GET /access/auth/notifications?unread_only&per_page(15)&page — { data: [notificação], meta: { total, page, limit, total_pages, has_next_page, has_prev_page }, unread_count }. - GET /access/auth/notifications/unread?per_page&page — { data, meta }. - GET /access/auth/notifications/unread-count — { unread_count }. - PUT /access/auth/notifications/{id}/read — { message, notification }. - PUT /access/auth/notifications/mark-all-read — { message, unread_count: 0 }. - DELETE /access/auth/notifications/{id} — { message }. - DELETE /access/auth/notifications/read/all — { message, deleted_count }. Notificação: { id (uuid), type (classe), data: { type (payment_received|charge_paid|export_ready|other), title, message, url, account_id, ... }, read_at (null = não lida), created_at }. Regras: id de outro usuário ou inexistente → 404; use data.url para abrir a tela e data.account_id para trocar a conta ativa (header account). Formato de resposta: { "code", "success", "data", "message" } (estas rotas respondem sem esse envelope, como acima); erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Tokens de API Base URL: `https://api.banking.fastgivr.com.br` Integrações servidor a servidor usam um **usuário com o papel `API`** vinculado à conta. Ele não tem senha: o JWT sai de [`POST /access/account/get-token`](/autenticacao/login-e-sessao#post-access-account-get-token) com o e-mail dele e o token da conta. **Headers:** `Authorization: Bearer {jwt}` e, opcional, `account: {account_id}`. **Permissão:** `manage_api` em todas as rotas desta página. O `{id}` das rotas é o **id do vínculo usuário↔conta** (`data.id`), não o do usuário (`data.user.id`). Vínculo de outra conta ou sem papel `API` → `404`. ## Passo a passo da integração 1. Um administrador (com `manage_api`) cria o usuário de API: `POST /access/manager/api-tokens`. 2. Pega o token da conta no campo `token` de [`GET /access/account`](/gestao/conta#get-access-account) (só aparece para quem tem `manage_api`). 3. O sistema integrado chama `POST /access/account/get-token` com `{ "email": "", "token": "" }` e recebe um JWT de **10 minutos**. 4. Usa o JWT em `Authorization: Bearer {jwt}` e pede outro ao vencer. O usuário de API só **opera**: cobranças, clientes, QR Code e consultas (saldo, extrato, relatórios). Ele **não administra nada**: usuários, tokens de API, dados e contatos da conta, PIN, 2FA, senha, sessões e chaves Pix são só para pessoas, no portal ou no aplicativo. Nessas rotas, o token de integração recebe `403` com `"message": "Usuários de API não podem fazer esta operação. Use o portal ou o aplicativo."`. O JWT traz as permissões em `data.permissions`. --- ## GET /access/manager/api-tokens | Parâmetro | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `search` | string | Não | nome, e-mail ou documento | | `per_page` | integer | Não | padrão 100 | | `page` | integer | Não | padrão 1 | ```json { "data": [ { "id": 2, "user_id": 20, "account_id": 3, "user": { "id": 20, "name": "Integracao ERP", "email": "erp@empresa.com", "phone": null, "document": "52998224725", "status": 1 }, "role": { "id": 8, "name": "API", "label": "Usuário de API", "account_type": null }, "created_at": "2026-11-20T13:52:00.000000Z", "updated_at": "2026-11-20T13:52:00.000000Z" } ], "meta": { "total": 1, "page": 1, "limit": 100, "total_pages": 1, "has_next_page": false, "has_prev_page": false }, "message": "Lista de usuários API recuperada com sucesso!" } ``` ## POST /access/manager/api-tokens | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `name` | string | Sim | até 30 caracteres | | `email` | string | Sim | e-mail único entre os usuários | | `document` | string | Sim | único entre os usuários | | `phone` | string | Não | | **Response 201:** `{ "data": { ...item da lista... }, "message": "Usuário API criado com sucesso!" }` **Erros:** `422` `{ "message", "errors" }` (e-mail ou documento já usado). ## GET /access/manager/api-tokens/\{id\} **Response 200:** `{ "data": { ... }, "message": "Usuário API recuperado com sucesso!" }` ## PUT /access/manager/api-tokens/\{id\} Mesmos campos e regras do `POST` (todos obrigatórios, menos `phone`). Manter o próprio e-mail e documento é aceito. Também aceita `PATCH`. **Response 200:** `{ "data": { ... }, "message": "Usuário API atualizado com sucesso!" }` **Erros:** `422` e-mail ou documento de outro usuário; `404` não encontrado. ## DELETE /access/manager/api-tokens/\{id\} Remove o vínculo. Se o usuário não tiver outra conta, ele também é apagado. **Response 200:** `{ "data": { ... }, "message": "Usuário API removido com sucesso!" }` --- ## Histórico de webhooks Registro dos webhooks enviados pela API ao sistema da conta (ver [Webhooks de cobrança](/cobrancas/webhooks)). ### GET /access/webhook-notifications | Parâmetro | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `status` | string | Não | `pending`, `sent` ou `failed` | | `event` | string | Não | contém o texto (ex.: `charge.paid`) | | `charge_id` | integer | Não | id de cobrança existente | | `search` | string | Não | URL, evento ou código da cobrança | | `created_at_start` | date | Não | `YYYY-MM-DD` | | `created_at_end` | date | Não | `YYYY-MM-DD`, maior ou igual ao início | | `per_page` | integer | Não | 1 a 100, padrão 15 | | `page` | integer | Não | | Resposta paginada no formato padrão do Laravel, mais `success` e `message`: ```json { "current_page": 1, "data": [ { "id": 41, "account_id": 3, "charge_id": 120, "status": "sent", "url": "https://erp.empresa.com/webhooks/fastgivr", "event": "charge.paid", "attempts": 1, "payload": { "...": "..." }, "response": { "...": "..." }, "last_attempt_at": { "raw": "2026-11-20 14:00:00", "formatted": "20/11/2026 14:00:00" }, "created_at": { "raw": "2026-11-20T17:00:00.000000Z", "formatted": "20/11/2026 14:00:00" }, "updated_at": { "raw": "2026-11-20T17:00:00.000000Z", "formatted": "20/11/2026 14:00:00" }, "charge": { "id": 120, "...": "..." } } ], "per_page": 15, "total": 1, "last_page": 1, "success": true, "message": "Listagem de notificações webhook" } ``` **Erros:** `422` filtros inválidos. ### GET /access/webhook-notifications/\{id\} **Response 200:** `{ "code": 200, "success": true, "data": { ...item... }, "message": "Detalhes da notificação webhook" }` **Erros:** `404` registro de outra conta ou inexistente. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar os usuários de API (integração servidor a servidor) e o histórico de webhooks da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Permissão manage_api em todas as rotas abaixo. Fluxo de integração: criar usuário de API → ler o token da conta em GET /access/account (campo account.token) → POST /access/account/get-token { email, token } → JWT de 10 minutos em data.token → renovar chamando get-token de novo. Endpoints ({id} = id do vínculo, data.id): - GET /access/manager/api-tokens?search&per_page(100)&page — { data: [{ id, user_id, account_id, user: { id, name, email, phone, document, status }, role, created_at, updated_at }], meta: { total, page, limit, total_pages, has_next_page, has_prev_page }, message }. - POST /access/manager/api-tokens — body { name (até 30), email (único), document (único), phone? }; 201 { data, message }. - GET /access/manager/api-tokens/{id} — { data, message }. - PUT /access/manager/api-tokens/{id} — body { name, email, document, phone? } (todos obrigatórios menos phone); { data, message }. - DELETE /access/manager/api-tokens/{id} — { data, message }. - GET /access/webhook-notifications?status(pending|sent|failed)&event&charge_id&search&created_at_start&created_at_end&per_page(1-100)&page — paginação padrão do Laravel (current_page, data, per_page, total, last_page) + success, message; item { id, charge_id, status, url, event, attempts, payload, response, last_attempt_at: { raw, formatted }, created_at, charge }. - GET /access/webhook-notifications/{id} — { code, success, data, message }. Regras: e-mail/documento já usados → 422 { message, errors }; vínculo de outra conta ou sem papel API → 404; sem manage_api → 403 { message, required_permissions }; get-token com dados errados → 401; limite de get-token 10/min por IP e 5/min por e-mail+IP → 429. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Usuários da Conta Base URL: `https://api.banking.fastgivr.com.br` Usuários (pessoas) vinculados à conta ativa, seus papéis e permissões. Usuários de API ficam em [Tokens de API](/gestao/tokens-api). **Headers:** `Authorization: Bearer {jwt}` e, opcional, `account: {account_id}`. **Permissão:** `manage_users` em todas as rotas, exceto `GET /access/manager/guard/permissions` (`manage_users` ou `manage_api`). O `{id}` das rotas é o **id do vínculo usuário↔conta** (`data.id`), não o do usuário (`data.user.id`). Vínculo de outra conta → `404`. **Formato de um usuário (`data`):** ```json { "id": 15, "user_id": 10, "account_id": 3, "user": { "id": 10, "name": "Ana Silva", "email": "ana@empresa.com", "phone": "11988887777", "document": "52998224725", "status": 1 }, "role": { "id": 5, "name": "pj_financeiro", "label": "Financeiro", "account_type": "pj" }, "created_at": "2026-11-20T13:52:00.000000Z", "updated_at": "2026-11-20T13:52:00.000000Z" } ``` `user.status`: `1` ativo, `0` inativo, `2` bloqueado. --- ## GET /access/manager/users Lista os usuários da conta, sem o próprio usuário logado e sem usuários de API. | Parâmetro | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `search` | string | Não | nome, e-mail ou documento | | `status` | integer | Não | `1`, `0` ou `2` | | `role` | string | Não | `name` do papel (ex.: `pj_financeiro`) | | `per_page` | integer | Não | padrão 100 | | `page` | integer | Não | padrão 1 | ```json { "data": [ { "id": 15, "user_id": 10, "account_id": 3, "user": { "...": "..." }, "role": { "...": "..." } } ], "meta": { "total": 1, "page": 1, "limit": 100, "total_pages": 1, "has_next_page": false, "has_prev_page": false }, "message": "Lista de usuários recuperada com sucesso!" } ``` ## POST /access/manager/users Cria um usuário e o vincula à conta. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `name` | string | Sim | até 30 caracteres | | `email` | string | Sim | e-mail único entre os usuários | | `document` | string | Sim | único entre os usuários | | `password` | string | Sim | mínimo 5 caracteres | | `role` | integer | Sim | **id** de um papel do tipo da conta ([`GET /access/manager/guard/roles`](#get-access-manager-guard-roles)) | | `phone` | string | Não | | **Response 201:** `{ "data": { ...usuário... }, "message": "Usuário criado com sucesso!" }` **Erros:** `422` `{ "message", "errors" }` (e-mail ou documento em uso; `errors.role`: `Este papel não pode ser usado neste tipo de conta.`). ## GET /access/manager/users/\{id\} **Response 200:** `{ "data": { ...usuário... }, "message": "Usuário recuperado com sucesso!" }` **Erros:** `404` `{ "code": 404, "message", "success": false, "data": null }`. ## PUT /access/manager/users/\{id\} Edita o usuário. Todos os campos são opcionais; os ausentes ficam como estão. Também aceita `PATCH`. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `name` | string | Não | até 30 caracteres | | `email` | string | Não | único; manter o atual é aceito | | `document` | string | Não | único; manter o atual é aceito | | `phone` | string | Não | | | `password` | string | Não | mínimo 6 caracteres | | `role` | integer | Não | **id** de um papel do tipo da conta | | `status` | integer | Não | `1` (ativo) ou `0` (inativo) | **Response 200:** `{ "data": { ...usuário... }, "message": "Usuário atualizado com sucesso!" }` **Erros:** - `422` `{ "message", "errors" }`: validação ou papel de outro tipo de conta. - `422` `{ "message": "Dados de entrada inválidos.", "success": false, "data": { "status": ["Este usuário foi bloqueado pelo suporte e não pode ser reativado por aqui."] } }`. - `404` vínculo não encontrado. ## DELETE /access/manager/users/\{id\} Remove o vínculo e o usuário. **Response 200:** `{ "data": { ...usuário removido... }, "message": "Usuário removido com sucesso!" }` **Erros:** `422` `{ "message": "Usuário não pode apagar a si mesmo." }`; `404` vínculo não encontrado. --- ## Papéis e permissões Cada função da API exige uma permissão. Quem não tem recebe `403`: ```json { "message": "Seu usuário não tem permissão para esta ação. Peça ao administrador da conta.", "required_permissions": ["manage_users"] } ``` As permissões valem na **conta ativa** (header `account`): ser administrador numa conta não dá acesso em outra. | Grupo | Permissões | | --- | --- | | Saldo e extrato | `view_balance`, `view_extract`, `generate_extract`, `view_transactions`, `view_reports` | | Pix | `receive_pix` (QR Code), `view_pix_history`, `view_pix_keys`, `manage_pix_keys` | | Cobranças | `view_charges`, `create_charges`, `edit_charges`, `delete_charges` | | Clientes | `view_clients`, `manage_clients` | | Conta | `view_profile`, `manage_config` (dados e contatos da conta), `manage_pin`, `manage_users`, `manage_api` (usuários de API e webhooks) | Sem permissão: `GET /access/auth/me`, `GET /access/account`, `GET /access/accounts`, o próprio perfil, 2FA, sessões e notificações do usuário. ### Papéis por tipo de conta | Conta | Papel (`name` → `label`) | Permissões | | --- | --- | --- | | PJ | `pj_administrador` → Administrador | todas | | PJ | `pj_financeiro` → Financeiro | todas menos `manage_users` e `manage_api` | | PJ | `pj_operador_cobrancas` → Operador de cobranças | cobranças, clientes, `receive_pix`, `view_profile` | | PJ | `pj_consulta` → Consulta | só consulta: saldo, extrato, transações, relatórios, cobranças, clientes e Pix | | PJ | `pj_integracao` → Integração | `manage_api`, `view_profile` | | PF | `pf_titular` → Titular | todas menos `manage_users` e `manage_api` | | PF | `pf_consulta` → Consulta | `view_balance`, `view_extract`, `view_transactions`, `view_charges`, `view_profile` | | — | `API` → Usuário de API | operacionais, sem `manage_users`, `manage_api`, `manage_config` e `manage_pin` | - O dono da conta recebe `pj_administrador` (CNPJ) ou `pf_titular` (CPF). - Em `POST`/`PUT /access/manager/users` só entram papéis do tipo da conta ativa. O papel `API` não pode ser atribuído aqui: use [Tokens de API](/gestao/tokens-api). ## GET /access/manager/guard/roles Papéis que podem ser atribuídos na conta ativa (PJ ou PF), com as permissões. **Permissão:** `manage_users`. Resposta paginada no formato padrão do Laravel (15 por página): ```json { "current_page": 1, "data": [ { "id": 4, "name": "pj_administrador", "guard_name": "api", "label": "Administrador", "account_type": "pj", "permissions": [ { "id": 1, "name": "view_balance" } ] } ], "per_page": 15, "total": 5, "last_page": 1 } ``` ## GET /access/manager/guard/permissions Catálogo de permissões, com rótulo e grupo. **Permissão:** `manage_users` ou `manage_api`. ```json { "code": 200, "success": true, "data": [ { "id": 1, "name": "view_charges", "label": "Ver cobranças", "group": "Cobranças" } ], "message": "Permissões do portal" } ``` ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a gestão de usuários da conta da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Permissão manage_users. Endpoints ({id} = id do vínculo usuário↔conta, data.id, não data.user.id): - GET /access/manager/users?search&status(1|0|2)&role(name)&per_page(100)&page — { data: [usuário], meta: { total, page, limit, total_pages, has_next_page, has_prev_page }, message }. Não lista o próprio usuário nem usuários de API. - POST /access/manager/users — body { name (até 30), email (único), document (único), password (mín. 5), role (id do papel), phone? }; 201 { data, message }. - GET /access/manager/users/{id} — { data, message }. - PUT /access/manager/users/{id} — body opcional { name, email, document, phone, password (mín. 6), role (id), status (1|0) }; { data, message }. - DELETE /access/manager/users/{id} — remove vínculo e usuário; { data, message }. - GET /access/manager/guard/roles — papéis atribuíveis na conta (paginação padrão do Laravel: current_page, data: [{ id, name, label, account_type, permissions }], per_page, total). - GET /access/manager/guard/permissions — permissão manage_users ou manage_api; { code, success, data: [{ id, name, label, group }], message }. Usuário: { id, user_id, account_id, user: { id, name, email, phone, document, status (1 ativo, 0 inativo, 2 bloqueado) }, role: { id, name, label, account_type }, created_at, updated_at }. Regras: só papéis do tipo da conta (PJ: pj_administrador, pj_financeiro, pj_operador_cobrancas, pj_consulta, pj_integracao; PF: pf_titular, pf_consulta); outro papel → 422 errors.role; usuário bloqueado pelo suporte não pode ser reativado → 422 data.status; apagar a si mesmo → 422; vínculo de outra conta → 404; sem permissão → 403 { message, required_permissions }. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Abertura de Conta Cadastro de um novo cliente Pessoa Física (PF) ou Pessoa Jurídica (PJ) até a solicitação ficar pronta para análise, e a revisão no backoffice até a conta ser aberta no banco. É o fluxo usado por `register.banking.fastgivr.com.br`. Base URL: `https://api.banking.fastgivr.com.br` ## Páginas - [Pessoa Física](/abertura-de-conta/pessoa-fisica) — passo a passo PF. - [Pessoa Jurídica](/abertura-de-conta/pessoa-juridica) — passo a passo PJ, com sócios. - [Referência de Endpoints](/abertura-de-conta/endpoints) — contrato de cada rota `/access/register/*`. - [Validação de Identidade](/abertura-de-conta/validacao-de-identidade) — prova de vida e fotos do documento pelo link. - [Status da Solicitação](/abertura-de-conta/status-da-solicitacao) — `account_status` e `current_step`. - [Revisão e Aprovação](/abertura-de-conta/revisao-e-aprovacao) — rotas `/backoffice/registers/*`. ## Como funciona 1. `POST /access/register/user` cria o usuário (nome, e-mail, documento, telefone, senha). 2. `POST /access/register` com `document` + `password` cria a solicitação e devolve o `session_token`. O tipo de conta sai do tamanho do documento: 11 dígitos = PF (`account_type: 1`), 14 = PJ (`account_type: 2`). 3. As demais etapas usam o header `Authorization: Bearer {session_token}`. 4. As etapas de preenchimento não têm ordem obrigatória e podem ser repetidas. Não existe "finalizar": quando tudo está completo, `account_status` vira `0` (`PENDING`, pronto para análise) sozinho. 5. O backoffice revisa, envia ao banco e a conta é aberta (`account_status: 3`). ## Sessão do cadastro | Item | Valor | |---|---| | Como obter | `POST /access/register` ou `POST /access/register/resume` (campo `data.session_token`) | | Como enviar | `Authorization: Bearer {session_token}` | | Validade | 30 dias | | Sem token, token inválido ou expirado | `401` `{ "code": 401, "success": false, "message": "Sessão do cadastro inválida ou expirada. Entre novamente com o documento e a senha." }` | Nas rotas com sessão, `register_id` e `document` vêm do token. Não é preciso enviá-los; se enviar, são ignorados. Para retomar um cadastro (outro aparelho, token perdido), chame `POST /access/register/resume` com `document` + `password`: devolve tudo o que já foi preenchido, `current_step` e um novo `session_token`. ## Formato das respostas ```json { "code": 200, "success": true, "data": { }, "message": "..." } ``` | Caso | Formato | |---|---| | Sucesso | `{ "code", "success": true, "data", "message" }` | | Erro de regra do cadastro (`400`, `404`, `409`, `410`, `422`, `429`, `503`) | `{ "code", "success": true, "data": null, "message" }` — o `success` vem `true`; use o status HTTP | | Registro não encontrado / erro interno | `{ "code", "success": false, "data": null, "message" }` | | Validação de campos (`422`) | `{ "message", "errors": { "campo": ["..."] } }` | | Limite de requisições (`429`) | `{ "message": "Too Many Attempts." }` + header `Retry-After` | ## Limites de requisição | Rota | Limite | |---|---| | `POST /access/register/user` | 10/min por IP e 5/min por e-mail + IP | | `POST /access/register` | 10/min | | `GET /access/register/status` | 20/min | | `POST /access/register/resume` | 10/min | | `GET /access/register/cbo` | 120/min | | `POST /access/register/phone-verification/start` | 5/min | | `POST /access/register/phone-verification/confirm` | 10/min | Acima do limite: `429`. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a abertura de conta (Pessoa Física e Pessoa Jurídica) da API FastGivr, do cadastro até a solicitação ficar pronta para análise. Base URL: https://api.banking.fastgivr.com.br Autenticação: as rotas 1, 2, status, resume e cbo são públicas. As demais exigem Authorization: Bearer {session_token}, recebido em POST /access/register ou POST /access/register/resume (válido 30 dias; 401 = sessão inválida, refaça resume). Com sessão, não envie register_id/document. Documento: CPF (11 dígitos) = PF, account_type 1; CNPJ (14 dígitos) = PJ, account_type 2. Máscara é aceita. Passos (em ordem recomendada; etapas 4 a 9 aceitam qualquer ordem e podem ser repetidas): 1. POST /access/register/user {name, email, document, phone, password (mín. 5)} — 201 cria; 200 "Cadastro retomado." se o documento existe e a senha confere; 422 "Documento já cadastrado." se a senha não confere; 422 {message, errors} se e-mail já usado ou CPF/CNPJ inválido. 2. POST /access/register {document, password} — cria a solicitação e envia um código de 4 dígitos ao e-mail; resposta data.id, data.account_type, data.account_status ("6"), data.session_token. Se já existe, devolve a existente (com novo token). 422 se documento/senha inválidos. 3. POST /access/register/email/verify {validation_code (4 dígitos)} — confirma o e-mail. 400 código incorreto ou expirado (10 min); após 3 erros há espera crescente (30 s até 15 min): 429 com data.retry_after e header Retry-After. Reenvio: POST /access/register/email (400 se pedido antes de 2 min do último envio). 4a. PF: PATCH /access/register/personal-data {mother_name, birth_date (data), invoicing (texto), social_name?, cbo? (código de 6 dígitos de GET /access/register/cbo?q=termo, resposta {data:[{code,name}]})}. 422 se a solicitação for PJ. 4b. PJ: PATCH /access/register/company-data {legal_nature, cnae, founding_date (data), invoicing, profitable ("Y"|"N"), trade_name?}. 422 se for PF. 5. PJ: POST /access/register/partners, uma vez por sócio: {partner_name, partner_document (CPF), partner_email, partner_phone, partner_mother_name, partner_birth_date (antes de hoje), partner_invoicing, partner_cbo (6 dígitos, existente), partner_street, partner_address_number, partner_neighborhood, partner_city, partner_state (2 letras), partner_zip_code, partner_complement?, partner_social_name?, ownership_percentage? (0-100), legal_representative? (bool)}. Mesmo partner_document atualiza. Marque um sócio como legal_representative=true. DELETE /access/register/partners/{partnerId} remove. Documento do sócio: POST /access/register/partners/{partnerId}/documents multipart {type, file}; obrigatório type=proof_of_address. 6. PATCH /access/register/address {street, address_number, neighborhood, city, state (2 letras), zip_code, complement?}. 7. Telefone: POST /access/register/phone-verification/start {phone_number (celular com DDD)} — 202 {sent_to, expires_in: 600}; depois POST /access/register/phone-verification/confirm {code (6 dígitos)} — grava o telefone validado. Erros: 422 celular/código inválido, 410 código expirado, 429 aguarde 60 s ou 5 tentativas, 409 cadastro fora de preenchimento, 503 SMS indisponível. Alternativa sem SMS: PATCH /access/register/phone {phone_number}. 8. POST /access/register/documents multipart {type, file (jpeg/png/jpg/pdf, até 10 MB)}, um por tipo; reenviar substitui. PF: proof_of_address. PJ: cnpj_card, social_contract, proof_of_address, invoicing_proof. 9. Validação de identidade: POST /access/register/identity-validation {partner_document? (CPF do sócio; obrigatório na PJ, ausente na PF)} — devolve data.token e data.link (válido 24 h). Na PJ, uma por sócio. A pessoa abre o link no celular; a página (pública, sem sessão) chama GET /access/register/identity-validation/{token} → {status, expires_at, subject_name, account_type}, POST .../{token}/liveness-session → {session_id} (usar no FaceLivenessDetector da AWS Amplify UI), e POST .../{token}/verify multipart {id_document_front, id_document_back (imagens até 5 MB), liveness_session_id} → {status: completed|failed, result}. failed pode tentar de novo no mesmo link. As fotos viram identity_front, identity_back e selfie do titular (PF) ou do sócio legal_representative (PJ). Status: GET /access/register/identity-validation[?partner_document=]. Acompanhamento: GET /access/register/me (sessão) devolve tudo, com current_step, completed_steps, pending_steps, documents (com rejection_reason), partners (data_complete, documents_complete, identity_validation_status) e identity_validation (PF). GET /access/register/status?document= devolve {id, document, email, name, account_type, account_status} sem sessão. account_status: "6" e-mail não verificado; "7" faltam dados/sócios/endereço/telefone; "8" faltam documentos ou validação de identidade; "0" pronto para análise; "9" em análise no banco; "3" conta ativa; "2" reprovada (ver rejection_reason); "5" cancelada. Documento reprovado pelo backoffice volta o status para "8" até reenviar o mesmo type. Regras: limites 429 — user 5/min por e-mail+IP e 10/min por IP; register e resume 10/min; status 20/min; cbo 120/min; phone start 5/min, confirm 10/min. Formato de resposta: { "code", "success", "data", "message" }; erros de regra trazem o status HTTP e "message" (success pode vir true, confie no status); erro 422 de validação traz os campos em "errors" ({ "message", "errors": { campo: [..] } }). Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Abertura de Conta — Referência de Endpoints Base URL: `https://api.banking.fastgivr.com.br` Contrato de cada rota `/access/register/*`. A ordem das etapas está em [Pessoa Física](/abertura-de-conta/pessoa-fisica) e [Pessoa Jurídica](/abertura-de-conta/pessoa-juridica); sessão, formato de resposta e limites em [Abertura de Conta](/abertura-de-conta/). **Sessão:** as rotas marcadas com "Sessão: sim" exigem `Authorization: Bearer {session_token}` (de `POST /access/register` ou `POST /access/register/resume`). Sem token válido: `401`. Nelas, `register_id` e `document` vêm do token. **Documento:** `document`, `partner_document` e `cbo` aceitam máscara; a API guarda só os dígitos. --- ## POST /access/register/user Cria o usuário que vai abrir a conta. Sessão: não. Limite: 10/min por IP e 5/min por e-mail + IP. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `name` | string | Sim | até 255 (PJ: razão social) | | `email` | string | Sim | e-mail válido, único entre usuários | | `document` | string | Sim | CPF (11) ou CNPJ (14) válido | | `phone` | string | Sim | até 30 | | `password` | string | Sim | mín. 5 | ```json { "name": "Maria Teste", "email": "maria@empresa.com", "document": "123.456.789-09", "phone": "11999998888", "password": "senha123" } ``` | Status | Quando | |---|---| | `201` | "Usuário cadastrado com sucesso." — `data` é o usuário (sem senha) | | `200` | "Cadastro retomado." — documento já existe e a senha confere (os outros campos são ignorados) | | `422` | "Documento já cadastrado." — documento existe e a senha não confere | | `422` | Validação (`errors`), ex.: e-mail já usado, CPF/CNPJ inválido | ## POST /access/register Cria a solicitação de abertura de conta do usuário e envia um código de 4 dígitos ao e-mail. Sessão: não. Limite: 10/min. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `document` | string | Sim | 11 a 14, precisa existir em usuários | | `password` | string | Sim | senha do usuário | Resposta `200` ("Abertura de Conta Realizada" ou "Retomando abertura de conta já iniciada."): ```json { "code": 200, "success": true, "data": { "id": 42, "user_id": 7, "document": "12345678909", "email": "maria@empresa.com", "name": "Maria Teste", "account_type": 1, "account_status": "6", "current_step": "verify_email", "email_verification_status": "code_sent", "session_token": "Zx8...64 caracteres" }, "message": "Abertura de Conta Realizada" } ``` - `account_type`: `1` PF (11 dígitos), `2` PJ (14 dígitos). - Se a solicitação já existe, devolve a existente com um novo `session_token` e não reenvia o e-mail. - `422` "Documento ou senha inválidos." ou validação (documento sem usuário). ## GET /access/register/status Consulta resumida por documento. Sessão: não. Limite: 20/min. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `document` (query) | string | Sim | 11 a 14 | `200` com `data`: `document`, `id`, `email`, `name`, `account_type`, `account_status`. `404` se não houver solicitação. ## POST /access/register/resume Retoma o cadastro com documento e senha. Sessão: não. Limite: 10/min. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `document` | string | Sim | 11 a 14 | | `password` | string | Sim | | `200` "Cadastro em andamento encontrado." com o mesmo `data` de [GET /access/register/me](#get-access-register-me) mais `session_token` (novo). `422` "Documento ou senha inválidos."; `404` "Nenhuma abertura de conta em andamento para este usuário." ## GET /access/register/cbo Busca ocupações (CBO) por código ou nome, até 50 resultados. Sessão: não. Limite: 120/min. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `q` (query) | string | Não | até 100; vazio devolve lista vazia | ```json { "data": [ { "code": "212405", "name": "Analista de desenvolvimento de sistemas" } ] } ``` ## GET /access/register/me Tudo o que já foi preenchido. Sessão: sim. ```json { "code": 200, "success": true, "data": { "id": 42, "document": "12345678909", "email": "maria@empresa.com", "name": "Maria Teste", "social_name": null, "birth_date": "1990-05-10", "mother_name": "Ana Teste", "cbo": "212405", "trade_name": null, "cnae": null, "legal_nature": null, "founding_date": null, "invoicing": "5000", "profitable": null, "phone_number": "11999998888", "phone_validated": true, "phone_validated_via": "phone", "account_type": 1, "account_status": "8", "email_verification_status": "verified", "current_step": "documents", "completed_steps": ["verify_email", "personal_data", "address", "phone"], "pending_steps": ["documents", "identity_validation", "ready_for_analysis"], "rejection_reason": null, "address": { "street": "Rua Teste", "number": "100", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "zip": "01000000", "observation": null }, "documents": [ { "id": 10, "type": "proof_of_address", "rejection_reason": null } ], "partners": [], "identity_validation": "link_generated" } } ``` - `partners` (PJ): cada sócio traz `id`, `name`, `social_name`, `document`, `email`, `phone`, `mother_name`, `birth_date`, `invoicing`, `cbo`, `ownership_percentage`, `legal_representative`, `address`, `documents`, `data_complete`, `documents_complete`, `identity_validation_status`. - `identity_validation`: status da validação do titular (PF); `null` na PJ. - `current_step`, `completed_steps`, `pending_steps`: ver [Status da Solicitação](/abertura-de-conta/status-da-solicitacao). - No endereço, `number` é o `address_number` enviado, `zip` é o `zip_code` e `observation` é o `complement`. ## POST /access/register/email Reenvia o código de confirmação do e-mail (novo código, 4 dígitos). Sessão: sim. Sem corpo. `200` "Email Enviado". `400` "Você só pode enviar um novo e-mail de validação após 2 minutos." ## POST /access/register/email/verify Confirma o e-mail. Sessão: sim. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `validation_code` | string | Sim | 4 caracteres | | Status | Quando | |---|---| | `200` | "E-mail validado com sucesso!" — `account_status` sai de `6` | | `400` | "O código de validação expirou. Solicite um novo código." (10 min) | | `400` | "Código de validação incorreto." — a partir do 4º erro seguido, `data.retry_after` (segundos) | | `429` | Ainda em espera: `data.retry_after` + header `Retry-After` | Espera após erros: 3 tentativas livres, depois 30 s, 1 min, 2 min, 4 min, 8 min e 15 min. Zera ao acertar. ## PATCH /access/register/personal-data Dados pessoais (só PF). Sessão: sim. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `mother_name` | string | Sim | até 255 | | `birth_date` | date | Sim | `YYYY-MM-DD` | | `invoicing` | string | Sim | renda, até 255 | | `social_name` | string | Não | nome social | | `cbo` | string | Não | código existente em [GET /access/register/cbo](#get-access-register-cbo) | | `profitable` | string | Não | `Y` ou `N` | `200` "Dados pessoais atualizados." com a solicitação. `422` "Esta abertura de conta é Pessoa Jurídica — use PATCH register/company-data." ## PATCH /access/register/company-data Dados da empresa (só PJ). Sessão: sim. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `legal_nature` | string | Sim | natureza jurídica, até 255 | | `cnae` | string | Sim | até 255 | | `founding_date` | date | Sim | `YYYY-MM-DD` | | `invoicing` | string | Sim | faturamento, até 255 | | `profitable` | string | Sim | `Y` ou `N` | | `trade_name` | string | Não | nome fantasia | `200` "Dados da empresa atualizados." `422` "Esta abertura de conta é Pessoa Física — use PATCH register/personal-data." ## POST /access/register/partners Adiciona ou atualiza um sócio (só PJ). O mesmo `partner_document` atualiza em vez de duplicar. Sessão: sim. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `partner_name` | string | Sim | até 255 | | `partner_document` | string | Sim | CPF válido | | `partner_email` | string | Sim | e-mail | | `partner_phone` | string | Sim | até 30 | | `partner_mother_name` | string | Sim | até 255 | | `partner_birth_date` | date | Sim | antes de hoje | | `partner_invoicing` | string | Sim | renda, até 255 | | `partner_cbo` | string | Sim | 6 dígitos, existente | | `partner_street` | string | Sim | até 255 | | `partner_address_number` | string | Sim | até 20 | | `partner_neighborhood` | string | Sim | até 255 | | `partner_city` | string | Sim | até 255 | | `partner_state` | string | Sim | 2 letras | | `partner_zip_code` | string | Sim | até 10 | | `partner_complement` | string | Não | até 255 | | `partner_social_name` | string | Não | até 255 | | `ownership_percentage` | number | Não | 0 a 100 | | `legal_representative` | boolean | Não | `true` para quem responde pela empresa | `200` "Sócio adicionado." com o sócio (`id`, dados, `address`, `documents`). `422` "Sócios só se aplicam a uma abertura de conta Pessoa Jurídica." ## DELETE /access/register/partners/{partnerId} {#delete-access-register-partners-partnerid} Remove um sócio (com endereço e documentos). Sessão: sim. `200` "Sócio removido."; `404` se o sócio não for desta solicitação. ## POST /access/register/partners/{partnerId}/documents Envia um documento do sócio. `multipart/form-data`. Sessão: sim. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `type` | string | Sim | `identity`, `identity_front`, `identity_back`, `proof_of_address`, `complementary_document`, `selfie` | | `file` | arquivo | Sim | jpeg, png, jpg ou pdf, até 10 MB | Obrigatório para cada sócio: `proof_of_address`. Identidade e selfie do sócio vêm da [validação de identidade](/abertura-de-conta/validacao-de-identidade). Reenviar o mesmo `type` substitui o arquivo e limpa a reprovação. `200` "Documento do sócio enviado."; `404` sócio de outra solicitação. ## PATCH /access/register/address Endereço do titular (PF) ou da empresa (PJ). Chamar de novo substitui. Sessão: sim. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `street` | string | Sim | até 255 | | `address_number` | string | Sim | até 20 | | `neighborhood` | string | Sim | até 255 | | `city` | string | Sim | até 255 | | `state` | string | Sim | 2 letras | | `zip_code` | string | Sim | até 10 | | `complement` | string | Não | até 255 | `200` "Endereço atualizado." com o endereço. ## PATCH /access/register/phone Grava o telefone sem validar por SMS. Marca `phone_validated: false`. Sessão: sim. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `phone_number` | string | Sim | até 30 | `200` "Telefone atualizado." ## POST /access/register/phone-verification/start Envia um código de 6 dígitos por SMS. O telefone só é gravado após a confirmação. Sessão: sim. Limite: 5/min. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `phone_number` | string | Sim | 10 a 20; celular brasileiro com DDD (aceita `+55` e máscara) | | Status | Quando | |---|---| | `202` | "Código enviado por SMS." — `data`: `{ "sent_to": "(11) 9****-8888", "expires_in": 600 }` | | `422` | "Informe um celular válido com DDD — o código é enviado por SMS." | | `429` | "Aguarde N segundos para pedir um novo código." (60 s entre envios) | | `409` | "Este cadastro não está mais em preenchimento." | | `503` | Falha no envio do SMS | ## POST /access/register/phone-verification/confirm Confere o código e grava `phone_number`, `phone_validated: true`, `phone_validated_via: "phone"`. Sessão: sim. Limite: 10/min. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `code` | string | Sim | 6 dígitos | | Status | Quando | |---|---| | `200` | "Telefone validado." — `data`: `phone_number`, `phone_validated`, `phone_validated_via`, `account_status` | | `422` | "Código inválido. Restam N tentativa(s)." | | `410` | Sem código pendente ou expirado (10 min) | | `429` | 5 tentativas erradas — peça novo código | | `409` | Cadastro fora de preenchimento | ## POST /access/register/documents Envia um documento da solicitação, um por chamada. `multipart/form-data`. Sessão: sim. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `type` | string | Sim | `identity`, `identity_front`, `identity_back`, `cpf`, `proof_of_address`, `complementary_document`, `selfie`, `cnpj_card`, `social_contract`, `invoicing_proof` | | `file` | arquivo | Sim | jpeg, png, jpg ou pdf, até 10 MB | Obrigatórios: | Tipo de conta | Enviar aqui | Vêm da validação de identidade | |---|---|---| | PF | `proof_of_address` | `identity_front`, `identity_back`, `selfie` (titular) | | PJ | `cnpj_card`, `social_contract`, `proof_of_address`, `invoicing_proof` | `identity_front`, `identity_back`, `selfie` (sócio `legal_representative`) | Reenviar o mesmo `type` substitui o arquivo e limpa a reprovação. `200` "Documento enviado." com `id`, `register_id`, `type`, `path`, `rejection_reason`. ## POST /access/register/identity-validation Gera o link de validação de identidade do titular (PF) ou de um sócio (PJ). Se já existe uma validação ativa da mesma pessoa, devolve a mesma. Sessão: sim. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `partner_document` | string | Na PJ | CPF de um sócio já cadastrado; omitir na PF | ```json { "code": 200, "success": true, "data": { "id": 5, "register_id": 42, "register_partner_id": null, "status": "link_generated", "token": "9b1d...uuid", "expires_at": "2026-11-21T12:00:00.000000Z", "link": "https://register.banking.fastgivr.com.br/validacao-identidade/9b1d...uuid" }, "message": "Sessão de validação de identidade gerada." } ``` `404` se o `partner_document` não for sócio desta solicitação. Fluxo do link: [Validação de Identidade](/abertura-de-conta/validacao-de-identidade). ## GET /access/register/identity-validation Status das validações. Sessão: sim. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `partner_document` (query) | string | Não | CPF do sócio | Sem `partner_document`: lista com todas as validações da solicitação. Com: só a última daquele sócio (ou `null`). ## GET /access/register/identity-validation/{token} {#get-access-register-identity-validation-token} Usada pela página do link. Sessão: não (o `token` identifica a pessoa). `200` com `data`: `status`, `expires_at`, `subject_name` (titular ou sócio), `account_type`. `404` token inexistente. ## POST /access/register/identity-validation/{token}/liveness-session Abre a sessão de prova de vida (Amazon Rekognition Face Liveness). Sessão: não. Sem corpo. `200` `{ "data": { "session_id": "..." } }`. `422` se a AWS não abrir a sessão (motivo em `message`). ## POST /access/register/identity-validation/{token}/verify Envia as fotos do documento e conclui a validação. `multipart/form-data`. Sessão: não. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `id_document_front` | imagem | Sim | até 5 MB | | `id_document_back` | imagem | Sim | até 5 MB | | `liveness_session_id` | string | Sim | `session_id` da etapa anterior, já concluída no navegador | `200` "Verificação processada.": ```json { "code": 200, "success": true, "data": { "status": "completed", "result": { "liveness_status": "SUCCEEDED", "confidence": 98.7 } }, "message": "Verificação processada." } ``` `status` é `completed` ou `failed` (em falha, `result` pode trazer `error`). `failed` pode ser repetido no mesmo token; `completed` não é reprocessado. ## POST /access/register/identity-validation/callback Resultado enviado por um provedor de validação externo, não pelo front-end. Sessão: não. Exige o header `X-Callback-Secret` com o segredo configurado na API; sem ele, `403`. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `token` | string | Sim | token da validação | | `status` | string | Sim | `completed` ou `failed` | | `result` | object | Não | guardado como veio | `200` "Callback processado." com a validação. Idempotente: validação já `completed`/`failed` não muda. `404` token inexistente. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar os endpoints de abertura de conta (/access/register/*) da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: user, register, status, resume, cbo e identity-validation/{token}/* são públicas. As demais exigem Authorization: Bearer {session_token} (de POST /access/register ou /resume; 30 dias; 401 = refazer resume). Com sessão, não envie register_id/document. Endpoints: - POST /access/register/user {name, email (único), document (CPF/CNPJ válido), phone, password (mín. 5)} — 201 criado; 200 "Cadastro retomado." (doc existente + senha certa); 422 "Documento já cadastrado.". - POST /access/register {document, password} — cria/retoma a solicitação e envia código de 4 dígitos ao e-mail; data.id, data.account_type (1 PF, 2 PJ), data.account_status, data.session_token. 422 documento/senha inválidos. - GET /access/register/status?document= — {id, document, email, name, account_type, account_status}; 404 sem solicitação. - POST /access/register/resume {document, password} — dados completos + novo session_token; 422 credenciais; 404 sem solicitação. - GET /access/register/cbo?q= — {data:[{code,name}]} até 50. - GET /access/register/me — dados completos: current_step, completed_steps, pending_steps, address, documents[{id,type,rejection_reason}], partners[...data_complete, documents_complete, identity_validation_status], identity_validation. - POST /access/register/email — reenvia código; 400 antes de 2 min. - POST /access/register/email/verify {validation_code (4)} — 400 incorreto/expirado (10 min); 429 em espera com data.retry_after. - PATCH /access/register/personal-data (PF) {mother_name, birth_date, invoicing, social_name?, cbo?, profitable? Y|N}; 422 se PJ. - PATCH /access/register/company-data (PJ) {legal_nature, cnae, founding_date, invoicing, profitable Y|N, trade_name?}; 422 se PF. - POST /access/register/partners (PJ) {partner_name, partner_document (CPF), partner_email, partner_phone, partner_mother_name, partner_birth_date, partner_invoicing, partner_cbo (6 dígitos), partner_street, partner_address_number, partner_neighborhood, partner_city, partner_state (2), partner_zip_code, partner_complement?, partner_social_name?, ownership_percentage? 0-100, legal_representative? bool} — mesmo CPF atualiza. - DELETE /access/register/partners/{partnerId}. - POST /access/register/partners/{partnerId}/documents multipart {type: identity|identity_front|identity_back|proof_of_address|complementary_document|selfie, file jpeg/png/jpg/pdf ≤10 MB}; obrigatório proof_of_address. - PATCH /access/register/address {street, address_number, neighborhood, city, state (2), zip_code, complement?}. - PATCH /access/register/phone {phone_number} — grava sem validar. - POST /access/register/phone-verification/start {phone_number celular com DDD} — 202 {sent_to, expires_in}; 422 celular inválido; 429 60 s entre envios; 409 fora de preenchimento; 503 SMS falhou. - POST /access/register/phone-verification/confirm {code 6 dígitos} — 200 telefone validado; 422 código errado; 410 expirado; 429 5 tentativas. - POST /access/register/documents multipart {type, file ≤10 MB}. PF envia proof_of_address; PJ envia cnpj_card, social_contract, proof_of_address, invoicing_proof. identity_front/identity_back/selfie vêm da validação de identidade. - POST /access/register/identity-validation {partner_document? (obrigatório na PJ)} — data.token, data.link (24 h), data.status. - GET /access/register/identity-validation[?partner_document=] — status. - GET /access/register/identity-validation/{token} — {status, expires_at, subject_name, account_type}. - POST /access/register/identity-validation/{token}/liveness-session — {session_id} para o FaceLivenessDetector (AWS Amplify UI); 422 erro da AWS. - POST /access/register/identity-validation/{token}/verify multipart {id_document_front, id_document_back (imagens ≤5 MB), liveness_session_id} — {status: completed|failed, result}; failed pode repetir. - POST /access/register/identity-validation/callback {token, status completed|failed, result?} com header X-Callback-Secret (só para provedor externo; 403 sem segredo). Regras: limites 429 — user 10/min IP e 5/min e-mail+IP; register e resume 10/min; status 20/min; cbo 120/min; phone start 5/min, confirm 10/min. Documento reprovado: reenviar o mesmo type. Formato de resposta: { "code", "success", "data", "message" }; erros de regra vêm com o status HTTP e "message" (success pode vir true, confie no status); erro 422 de validação traz os campos em "errors"; 404/500 trazem success false. Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Abertura de Conta — Pessoa Física (PF) Base URL: `https://api.banking.fastgivr.com.br` Passo a passo para abrir uma conta com CPF. Campos e erros de cada rota: [Referência de Endpoints](/abertura-de-conta/endpoints). Sessão e formato de resposta: [Abertura de Conta](/abertura-de-conta/). ## Sequência | # | Etapa | Rota | Sessão | |---|---|---|---| | 1 | Criar usuário | `POST /access/register/user` | Não | | 2 | Iniciar solicitação | `POST /access/register` | Não (devolve o `session_token`) | | 3 | Confirmar e-mail | `POST /access/register/email/verify` | Sim | | 4 | Dados pessoais | `PATCH /access/register/personal-data` | Sim | | 5 | Endereço | `PATCH /access/register/address` | Sim | | 6 | Telefone | `POST /access/register/phone-verification/start` + `confirm` | Sim | | 7 | Documentos | `POST /access/register/documents` | Sim | | 8 | Validação de identidade | `POST /access/register/identity-validation` + link | Sim (o link é público) | As etapas 4 a 8 aceitam qualquer ordem e podem ser repetidas. Ao completar tudo, `account_status` vira `0` sozinho. ## 1. Criar usuário `POST /access/register/user` ```json { "name": "Maria Teste", "email": "maria@empresa.com", "document": "123.456.789-09", "phone": "11999998888", "password": "senha123" } ``` `document` com 11 dígitos define o fluxo PF. ## 2. Iniciar a solicitação `POST /access/register` ```json { "document": "12345678909", "password": "senha123" } ``` Guarde `data.session_token` e envie `Authorization: Bearer {session_token}` daqui em diante. A API manda um código de 4 dígitos ao e-mail. ## 3. Confirmar o e-mail `POST /access/register/email/verify` ```json { "validation_code": "4821" } ``` Código válido por 10 minutos. Para reenviar: `POST /access/register/email` (a cada 2 minutos). ## 4. Dados pessoais `PATCH /access/register/personal-data` ```json { "mother_name": "Ana Teste", "birth_date": "1990-05-10", "invoicing": "5000", "social_name": null, "cbo": "212405" } ``` Obrigatórios: `mother_name`, `birth_date`, `invoicing`. O `cbo` vem de `GET /access/register/cbo?q=analista`. ## 5. Endereço `PATCH /access/register/address` ```json { "street": "Rua Teste", "address_number": "100", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "zip_code": "01000-000", "complement": "Apto 1" } ``` ## 6. Telefone 1. `POST /access/register/phone-verification/start` com `{ "phone_number": "(11) 99999-8888" }` — envia SMS com código de 6 dígitos (`202`). 2. `POST /access/register/phone-verification/confirm` com `{ "code": "123456" }` — grava o telefone validado. Sem SMS, `PATCH /access/register/phone` com `{ "phone_number": "..." }` grava o número sem validar. Para o status, basta o número preenchido. ## 7. Documentos `POST /access/register/documents` (`multipart/form-data`, campos `type` e `file`). | `type` | Documento | |---|---| | `proof_of_address` | Comprovante de endereço | `identity_front`, `identity_back` e `selfie` também são obrigatórios, mas chegam pela etapa 8. ## 8. Validação de identidade `POST /access/register/identity-validation` sem corpo (sem `partner_document`). Devolve `data.link`, válido por 24 horas. O titular abre o link no celular, faz a prova de vida e fotografa frente e verso do documento. Detalhes: [Validação de Identidade](/abertura-de-conta/validacao-de-identidade). ## Depois Use `GET /access/register/me` para ver `current_step` e o que falta. Com tudo completo, `account_status` = `0` e o backoffice assume ([Revisão e Aprovação](/abertura-de-conta/revisao-e-aprovacao)). ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a abertura de conta Pessoa Física (CPF) da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: passos 1 e 2 são públicos. Do passo 3 em diante, Authorization: Bearer {session_token} (data.session_token do passo 2 ou de POST /access/register/resume {document, password}; 30 dias; 401 = sessão inválida). Endpoints / passos do fluxo (em ordem; 4 a 8 aceitam qualquer ordem e podem ser repetidos): 1. POST /access/register/user {name, email, document (CPF), phone, password (mín. 5)} — 201 criado; 200 "Cadastro retomado."; 422 "Documento já cadastrado." (senha não confere). 2. POST /access/register {document, password} — data.id, data.account_type = 1, data.account_status = "6", data.session_token; envia código de 4 dígitos ao e-mail. 3. POST /access/register/email/verify {validation_code} — 400 incorreto/expirado (10 min); 429 em espera (data.retry_after). Reenvio: POST /access/register/email (400 antes de 2 min). 4. PATCH /access/register/personal-data {mother_name, birth_date (YYYY-MM-DD), invoicing, social_name?, cbo? (code de GET /access/register/cbo?q=, resposta {data:[{code,name}]})}. 5. PATCH /access/register/address {street, address_number, neighborhood, city, state (2 letras), zip_code, complement?}. 6. POST /access/register/phone-verification/start {phone_number celular com DDD} — 202 {sent_to, expires_in: 600}; POST /access/register/phone-verification/confirm {code (6 dígitos)}. Erros: 422 inválido, 410 expirado, 429 (60 s entre envios ou 5 tentativas), 503 SMS indisponível. Alternativa: PATCH /access/register/phone {phone_number}. 7. POST /access/register/documents multipart {type: "proof_of_address", file (jpeg/png/jpg/pdf ≤10 MB)}. 8. POST /access/register/identity-validation (sem corpo) — data.link e data.token (24 h). No celular: GET /access/register/identity-validation/{token}; POST .../{token}/liveness-session → {session_id} para o FaceLivenessDetector (AWS Amplify UI); POST .../{token}/verify multipart {id_document_front, id_document_back (imagens ≤5 MB), liveness_session_id} → {status: completed|failed}. failed pode repetir. As fotos viram identity_front, identity_back e selfie. Acompanhar: GET /access/register/me → current_step, pending_steps, account_status, documents[].rejection_reason, identity_validation. Regras: account_status "6" e-mail pendente, "7" faltam dados/endereço/telefone, "8" faltam documentos ou validação, "0" pronto para análise, "9" em análise no banco, "3" ativa, "2" reprovada. Limites 429: user 5/min por e-mail+IP, register/resume 10/min, phone start 5/min, confirm 10/min. Formato de resposta: { "code", "success", "data", "message" }; erros de regra vêm com o status HTTP e "message" (confie no status); erro 422 de validação traz os campos em "errors". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Abertura de Conta — Pessoa Jurídica (PJ) Base URL: `https://api.banking.fastgivr.com.br` Passo a passo para abrir uma conta com CNPJ. Campos e erros de cada rota: [Referência de Endpoints](/abertura-de-conta/endpoints). Sessão e formato de resposta: [Abertura de Conta](/abertura-de-conta/). ## Sequência | # | Etapa | Rota | Sessão | |---|---|---|---| | 1 | Criar usuário | `POST /access/register/user` | Não | | 2 | Iniciar solicitação | `POST /access/register` | Não (devolve o `session_token`) | | 3 | Confirmar e-mail | `POST /access/register/email/verify` | Sim | | 4 | Dados da empresa | `PATCH /access/register/company-data` | Sim | | 5 | Sócios e documentos dos sócios | `POST /access/register/partners` + `/partners/{partnerId}/documents` | Sim | | 6 | Endereço da empresa | `PATCH /access/register/address` | Sim | | 7 | Telefone | `POST /access/register/phone-verification/start` + `confirm` | Sim | | 8 | Documentos da empresa | `POST /access/register/documents` | Sim | | 9 | Validação de identidade (uma por sócio) | `POST /access/register/identity-validation` + link | Sim (o link é público) | As etapas 4 a 9 aceitam qualquer ordem e podem ser repetidas. Ao completar tudo, `account_status` vira `0` sozinho. ## 1. Criar usuário `POST /access/register/user` ```json { "name": "Empresa Teste Ltda", "email": "financeiro@empresa.com", "document": "11.222.333/0001-81", "phone": "11999998888", "password": "senha123" } ``` `name` é a razão social. `document` com 14 dígitos define o fluxo PJ. ## 2. Iniciar a solicitação `POST /access/register` com `{ "document": "11222333000181", "password": "senha123" }`. Guarde `data.session_token` e envie `Authorization: Bearer {session_token}` daqui em diante. Um código de 4 dígitos vai ao e-mail. ## 3. Confirmar o e-mail `POST /access/register/email/verify` com `{ "validation_code": "4821" }`. Reenvio: `POST /access/register/email` (a cada 2 minutos). ## 4. Dados da empresa `PATCH /access/register/company-data` ```json { "legal_nature": "LTDA", "cnae": "6201501", "founding_date": "2015-03-01", "invoicing": "100000", "profitable": "Y", "trade_name": "Teste" } ``` Obrigatórios: `legal_nature`, `cnae`, `founding_date`, `invoicing`, `profitable` (`Y`/`N`). ## 5. Sócios `POST /access/register/partners`, uma chamada por sócio. Pelo menos um sócio, com todos os dados obrigatórios. ```json { "partner_name": "João Sócio", "partner_document": "529.982.247-25", "partner_email": "joao@empresa.com", "partner_phone": "11988887777", "partner_mother_name": "Maria Sócio", "partner_birth_date": "1985-01-20", "partner_invoicing": "8000", "partner_cbo": "123105", "partner_street": "Rua Teste", "partner_address_number": "50", "partner_neighborhood": "Centro", "partner_city": "São Paulo", "partner_state": "SP", "partner_zip_code": "01000-000", "ownership_percentage": 100, "legal_representative": true } ``` - O mesmo `partner_document` atualiza o sócio. `DELETE /access/register/partners/{partnerId}` remove. - Marque com `legal_representative: true` quem responde pela empresa: as fotos da validação de identidade dele viram os documentos `identity_front`, `identity_back` e `selfie` da empresa. - Cada sócio envia `proof_of_address` em `POST /access/register/partners/{partnerId}/documents` (`multipart/form-data`, `type` + `file`). O `partnerId` é o `data.id` da resposta ou `partners[].id` de `GET /access/register/me`. ## 6. Endereço da empresa `PATCH /access/register/address` com `street`, `address_number`, `neighborhood`, `city`, `state`, `zip_code` e `complement` (opcional). ## 7. Telefone `POST /access/register/phone-verification/start` com `{ "phone_number": "(11) 99999-8888" }` e depois `POST /access/register/phone-verification/confirm` com `{ "code": "123456" }`. Sem SMS: `PATCH /access/register/phone`. ## 8. Documentos da empresa `POST /access/register/documents` (`multipart/form-data`, `type` + `file`), um por tipo: | `type` | Documento | |---|---| | `cnpj_card` | Cartão CNPJ | | `social_contract` | Contrato social / estatuto | | `proof_of_address` | Comprovante de endereço da empresa | | `invoicing_proof` | Comprovante de faturamento | ## 9. Validação de identidade `POST /access/register/identity-validation` com `{ "partner_document": "52998224725" }`, uma vez por sócio. Cada sócio recebe o próprio `link` (24 horas) e faz a prova de vida no celular. A solicitação só fica pronta quando **todos** os sócios concluírem. Detalhes: [Validação de Identidade](/abertura-de-conta/validacao-de-identidade). ## Depois `GET /access/register/me` mostra `current_step` e, por sócio, `data_complete`, `documents_complete` e `identity_validation_status`. Com tudo completo, `account_status` = `0` e o backoffice assume ([Revisão e Aprovação](/abertura-de-conta/revisao-e-aprovacao)). ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a abertura de conta Pessoa Jurídica (CNPJ) da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: passos 1 e 2 são públicos. Do passo 3 em diante, Authorization: Bearer {session_token} (data.session_token do passo 2 ou de POST /access/register/resume {document, password}; 30 dias; 401 = sessão inválida). Endpoints / passos do fluxo (em ordem; 4 a 9 aceitam qualquer ordem e podem ser repetidos): 1. POST /access/register/user {name (razão social), email, document (CNPJ), phone, password (mín. 5)} — 201 criado; 200 "Cadastro retomado."; 422 "Documento já cadastrado.". 2. POST /access/register {document, password} — data.id, data.account_type = 2, data.account_status = "6", data.session_token; envia código de 4 dígitos ao e-mail. 3. POST /access/register/email/verify {validation_code} — 400 incorreto/expirado (10 min); 429 em espera (data.retry_after). Reenvio: POST /access/register/email (400 antes de 2 min). 4. PATCH /access/register/company-data {legal_nature, cnae, founding_date (YYYY-MM-DD), invoicing, profitable "Y"|"N", trade_name?}. 5. POST /access/register/partners por sócio (pelo menos um): {partner_name, partner_document (CPF), partner_email, partner_phone, partner_mother_name, partner_birth_date (antes de hoje), partner_invoicing, partner_cbo (6 dígitos de GET /access/register/cbo?q=), partner_street, partner_address_number, partner_neighborhood, partner_city, partner_state (2), partner_zip_code, partner_complement?, partner_social_name?, ownership_percentage? 0-100, legal_representative? bool}. Mesmo CPF atualiza; DELETE /access/register/partners/{partnerId} remove. Marque um sócio legal_representative=true. Para cada sócio: POST /access/register/partners/{partnerId}/documents multipart {type: "proof_of_address", file ≤10 MB}. 6. PATCH /access/register/address {street, address_number, neighborhood, city, state (2), zip_code, complement?} (endereço da empresa). 7. POST /access/register/phone-verification/start {phone_number celular com DDD} — 202 {sent_to, expires_in}; POST /access/register/phone-verification/confirm {code 6 dígitos}. Erros: 422 inválido, 410 expirado, 429 (60 s entre envios ou 5 tentativas), 503 SMS indisponível. Alternativa: PATCH /access/register/phone {phone_number}. 8. POST /access/register/documents multipart {type, file jpeg/png/jpg/pdf ≤10 MB} para cnpj_card, social_contract, proof_of_address, invoicing_proof. 9. POST /access/register/identity-validation {partner_document} por sócio — data.link e data.token (24 h). No celular do sócio: GET /access/register/identity-validation/{token}; POST .../{token}/liveness-session → {session_id} para o FaceLivenessDetector (AWS Amplify UI); POST .../{token}/verify multipart {id_document_front, id_document_back (imagens ≤5 MB), liveness_session_id} → {status: completed|failed}. failed pode repetir. As fotos do sócio legal_representative viram identity_front, identity_back e selfie da empresa. Status: GET /access/register/identity-validation?partner_document=. Acompanhar: GET /access/register/me → current_step, pending_steps, account_status, documents[].rejection_reason, partners[].data_complete/documents_complete/identity_validation_status. Regras: account_status "6" e-mail pendente, "7" faltam dados/sócios/endereço/telefone, "8" faltam documentos ou validações, "0" pronto para análise, "9" em análise no banco, "3" ativa, "2" reprovada. 422 em company-data se a solicitação for PF. Limites 429: user 5/min por e-mail+IP, register/resume 10/min, phone start 5/min, confirm 10/min. Formato de resposta: { "code", "success", "data", "message" }; erros de regra vêm com o status HTTP e "message" (confie no status); erro 422 de validação traz os campos em "errors". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Abertura de Conta — Revisão e Aprovação Base URL: `https://api.banking.fastgivr.com.br` Rotas do backoffice para revisar as solicitações, enviá-las ao banco e confirmar a conta aberta. **Autenticação:** `Authorization: Bearer {jwt}` de um usuário com o papel `Backoffice` (login em `/access/auth/login`, ver [Autenticação](/autenticacao/)). Sem o papel: `403` "Acesso restrito aos operadores do backoffice." Mais sobre o painel em [Backoffice](/backoffice/). ## Fluxo 1. A solicitação chega a `account_status` `0` (ver [Status da Solicitação](/abertura-de-conta/status-da-solicitacao)). 2. O operador revisa (`GET /backoffice/registers/{id}`) e, se preciso, reprova documentos ou a solicitação. 3. `POST /backoffice/registers/{id}/approve` confere se está completa. 4. O operador envia a abertura ao banco pelo painel do backoffice (status `9`). 5. O banco devolve o resultado: conta aberta → status `3` e conta criada; recusa → status `2`. Se o resultado não chegar, o operador usa `POST /backoffice/registers/{id}/confirm-account`. ## GET /backoffice/registers Lista paginada. | Campo (query) | Tipo | Obrigatório | Regras | |---|---|---|---| | `search` | string | Não | nome, documento ou e-mail (contém) | | `status` | string | Não | valor de `account_status` | | `account_type` | integer | Não | `1` PF, `2` PJ | | `created_from` / `created_to` | date | Não | `YYYY-MM-DD` | | `order_by` | string | Não | coluna, padrão `id` | | `order_dir` | string | Não | `asc` ou `desc` (padrão) | | `per_page` | integer | Não | padrão 15 | | `page` | integer | Não | padrão 1 | Resposta no formato de paginação padrão do Laravel (sem `code`/`success`): ```json { "data": [ { "id": 42, "name": "Maria Teste", "document": "12345678909", "email": "maria@empresa.com", "phone_number": "11999998888", "account_type": 1, "status": { "id": "0", "title": "Pendente", "description": "Cadastro completo — aguardando análise do backoffice." }, "rejection_reason": null, "created_at": "2026-11-20T12:00:00.000000Z", "updated_at": "2026-11-20T12:30:00.000000Z" } ], "links": { "first": "...", "last": "...", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "...", "per_page": 15, "to": 1, "total": 1 } } ``` ## GET /backoffice/registers/{id} {#get-backoffice-registers-id} Detalhe completo em `{ "data": { ... } }`: dados pessoais/da empresa, telefone (`phone_validated`, `phone_validated_via`), `status` (`id`, `title`, `description`), `rejection_reason`, `approved_bank`, `approved_at`, campos de acompanhamento do envio ao banco, `user`, `address`, `documents` (`id`, `type`, `type_title`, `path`, `rejection_reason`, datas) e `partners` (dados, `address`, `documents`). `404` se não existir. ## PUT /backoffice/registers/{id}/reject Reprova a solicitação inteira (status `2`). Aceita `PUT` ou `PATCH`. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `reason` | string | Sim | até 500 | `200` "Solicitação de abertura de conta reprovada." com o detalhe. A solicitação não sai de `2` sozinha. ## PUT /backoffice/registers/{id}/documents/{documentId}/reject Reprova um documento da solicitação. Aceita `PUT` ou `PATCH`. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `reason` | string | Sim | até 500 | `200` "Documento reprovado." com o documento. Se a solicitação estava `0`, volta para `8` até o cliente reenviar o mesmo `type`. `404` se o documento não for desta solicitação. Vale para documentos da solicitação (`documents`), não dos sócios. ## POST /backoffice/registers/{id}/phone-verification/resend Reenvia o SMS de validação do celular ao cliente (usa o número em verificação, o do cadastro ou o do usuário, o primeiro celular válido). Sem corpo. | Status | Quando | |---|---| | `202` | "Código reenviado por SMS." — `data`: `{ "sent_to": "(11) 9****-8888", "expires_in": 600 }` | | `409` | Telefone já validado ou cadastro fora de preenchimento | | `422` | Nenhum celular válido no cadastro | | `429` | Menos de 60 s desde o último envio | | `503` | Falha no envio do SMS | ## POST /backoffice/registers/{id}/approve Confere se a solicitação está completa. Não altera nada. Sem corpo. `200` "Solicitação pronta para aprovação — selecione o banco." com o detalhe. `422` "Só é possível aprovar solicitações com o cadastro completo (status Pendente)." ## GET /backoffice/registers/{id}/account/status Resultado gravado do envio ao banco: `account_status`, `approved_bank`, `approved_at` e os dados de acompanhamento do envio (referência, resposta do banco, etapas concluídas e último erro). ```json { "code": 200, "success": true, "data": { "account_status": "9", "approved_bank": null, "approved_at": null } } ``` ## POST /backoffice/registers/{id}/confirm-account Confirma manualmente a conta aberta no banco, quando o resultado não chega sozinho. Só para status `9`. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `agency` | string | Sim | só números, até 10 | | `account` | string | Sim | números com dígito opcional (`123456-7`), até 20 | Cria a conta (titular com acesso de dono), marca a solicitação como `3` e envia o e-mail de boas-vindas. `201` "Conta criada e solicitação concluída.": ```json { "code": 201, "success": true, "data": { "register": { "id": 42, "status": { "id": "3", "title": "Ativa" } }, "account": { "id": 10, "agency": "0001", "account": "123456-7", "status": "ACTIVE" } }, "message": "Conta criada e solicitação concluída." } ``` `422` (mensagem do primeiro erro em `message`, todos em `data.errors`): status diferente de `9`, agência/conta já usadas ou formato inválido. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a revisão e aprovação de aberturas de conta no backoffice da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt} de POST /access/auth/login com um usuário do papel Backoffice; sem o papel, 403. Endpoints: - GET /backoffice/registers?search=&status=&account_type=&created_from=&created_to=&order_by=id&order_dir=desc&per_page=15&page=1 — paginação padrão Laravel {data:[{id, name, document, email, phone_number, account_type, status{id,title,description}, rejection_reason, created_at}], links, meta{current_page, last_page, per_page, total}}. - GET /backoffice/registers/{id} — {data:{...dados, status, user, address, documents[{id,type,type_title,path,rejection_reason}], partners[...]}}. - PUT|PATCH /backoffice/registers/{id}/reject {reason (até 500)} — status "2". - PUT|PATCH /backoffice/registers/{id}/documents/{documentId}/reject {reason} — documento reprovado; solicitação volta para "8" até o cliente reenviar. - POST /backoffice/registers/{id}/phone-verification/resend — 202 {sent_to, expires_in}; 409 já validado/fora de preenchimento; 422 sem celular válido; 429 60 s; 503 SMS. - POST /backoffice/registers/{id}/approve — só confere; 422 se status ≠ "0". - GET /backoffice/registers/{id}/account/status — {account_status, approved_bank, approved_at, dados de acompanhamento do envio}. - POST /backoffice/registers/{id}/confirm-account {agency (números), account (números com dígito opcional, ex. 123456-7)} — 201 {register, account{id, agency, account, status}}; só com status "9"; 422 com data.errors. Regras: status "0" pronto para análise, "9" em análise no banco, "3" ativa, "2" reprovada, "5" cancelada. Normalmente o próprio banco devolve o resultado e abre a conta (status "3") ou recusa ("2"); confirm-account é o caminho manual. Faça polling de account/status enquanto status = "9". Formato de resposta: { "code", "success", "data", "message" }; erros trazem o status HTTP e "message"; erro 422 de validação traz os campos em "errors" ou "data.errors". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Abertura de Conta — Status da Solicitação O campo `account_status` (string) mostra em que ponto a solicitação está. Ele é recalculado a cada etapa preenchida; não existe rota de "enviar para análise". Também pode voltar, por exemplo ao remover um sócio ou quando o backoffice reprova um documento. Onde ler: `GET /access/register/status?document=`, `GET /access/register/me` ou `POST /access/register/resume`. ## Valores | Valor | Título | Significado | |---|---|---| | `6` | E-mail Não Verificado | Inicial, até confirmar o e-mail | | `7` | Dados Pendentes | Faltam dados pessoais/da empresa, sócios (PJ), endereço ou telefone | | `8` | Documentos Pendentes | Faltam documentos obrigatórios ou validação de identidade | | `0` | Pendente | Completo, aguardando análise do backoffice | | `9` | Em análise no banco | Enviado ao banco pelo backoffice | | `3` | Ativa | Conta aberta | | `2` | Rejeitada | Reprovada pelo backoffice ou pelo banco; motivo em `rejection_reason` | | `5` | Cancelada | Conta encerrada pelo banco | | `1` | Aprovada | Reservado; o fluxo atual não usa | | `4` | Bloqueada | Reservado; o fluxo atual não usa | | `-1` | Removida | Reservado; o fluxo atual não usa | ## Como o status muda no preenchimento Só vale enquanto o status está em `7`, `8` ou `0`: - `0`: dados completos, endereço, telefone preenchido, documentos obrigatórios sem reprovação e validação de identidade concluída. - `8`: dados, endereço e telefone completos, mas falta documento ou validação. - `7`: qualquer outro caso. "Dados completos": - PF: `mother_name`, `birth_date` e `invoicing`. - PJ: `legal_nature`, `cnae`, `founding_date`, `invoicing`, `profitable` e pelo menos um sócio, cada um com e-mail, telefone, nome da mãe, nascimento, renda, CBO e endereço. Documentos obrigatórios: - PF: `proof_of_address`, `identity_front`, `identity_back`, `selfie`. - PJ: `cnpj_card`, `social_contract`, `proof_of_address`, `invoicing_proof`, `identity_front`, `identity_back`, `selfie`, e `proof_of_address` de cada sócio. Validação de identidade: `completed` do titular (PF) ou de todos os sócios (PJ). Telefone validado por SMS não é exigido; basta o número preenchido. Documento reprovado pelo backoffice deixa de contar: a solicitação volta para `8` até o cliente reenviar o mesmo `type`. Uma solicitação reprovada inteira (`2`) não sai desse status sozinha. ## current_step `GET /access/register/me` e `POST /access/register/resume` trazem `current_step` (primeira etapa em aberto), `completed_steps` e `pending_steps`, na ordem: | Ordem | Valor | PF | PJ | |---|---|---|---| | 1 | `verify_email` | Sim | Sim | | 2 | `personal_data` | Sim | — | | 2 | `company_data` | — | Sim | | 3 | `partners` | — | Sim | | 4 | `address` | Sim | Sim | | 5 | `phone` | Sim | Sim | | 6 | `documents` | Sim | Sim | | 7 | `identity_validation` | Sim | Sim | | 8 | `ready_for_analysis` | Sim | Sim | É informativo: serve para a tela saber onde retomar e não bloqueia chamadas fora de ordem. A etapa `documents` considera só os documentos enviados pela rota de documentos (identidade e selfie chegam em `identity_validation`). Fora do preenchimento (status `9`, `3`, `2`, `5`), `current_step` para de mudar. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar o acompanhamento de status da abertura de conta da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: GET /access/register/status é público; GET /access/register/me usa Authorization: Bearer {session_token}; POST /access/register/resume {document, password} devolve os dados e um novo session_token. Endpoints: - GET /access/register/status?document= — {id, document, email, name, account_type, account_status}; 404 sem solicitação; limite 20/min. - GET /access/register/me — dados completos com account_status, current_step, completed_steps, pending_steps, rejection_reason, documents[{id,type,rejection_reason}], partners[{data_complete, documents_complete, identity_validation_status}], identity_validation. - POST /access/register/resume {document, password} — mesmo conteúdo + session_token; 422 credenciais; 404 sem solicitação; limite 10/min. Regras: account_status é string: "6" e-mail não verificado; "7" faltam dados/sócios/endereço/telefone; "8" faltam documentos ou validação de identidade; "0" completo, aguardando análise; "9" em análise no banco; "3" conta ativa; "2" reprovada (rejection_reason); "5" cancelada. current_step: verify_email → personal_data (PF) ou company_data → partners (PJ) → address → phone → documents → identity_validation → ready_for_analysis. Documento com rejection_reason precisa ser reenviado (mesmo type) e o status volta a "8" até lá. Mostre ao usuário a próxima etapa pelo current_step. Formato de resposta: { "code", "success", "data", "message" }; erros trazem o status HTTP e "message"; erro 422 de validação traz os campos em "errors". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Abertura de Conta — Validação de Identidade Base URL: `https://api.banking.fastgivr.com.br` Prova de vida (Amazon Rekognition Face Liveness) e fotos do documento, feitas pelo celular por meio de um link. É obrigatória para a solicitação chegar a `account_status` `0`. | Tipo de conta | Quem valida | |---|---| | PF | O titular (uma validação) | | PJ | Cada sócio (uma validação por sócio, com `partner_document`) | As fotos da validação viram os documentos `identity_front`, `identity_back` e `selfie` da solicitação quando quem validou é o titular (PF) ou o sócio com `legal_representative: true` (PJ). Na PJ, as fotos de cada sócio também ficam como documentos do próprio sócio. ## Fluxo 1. O cadastro (com sessão) chama [POST /access/register/identity-validation](/abertura-de-conta/endpoints#post-access-register-identity-validation) e recebe `token` e `link` (válido por 24 horas). 2. A pessoa abre o `link` no celular. A página chama `GET /access/register/identity-validation/{token}` para mostrar o nome (`subject_name`) e o `status`. 3. A página chama `POST /access/register/identity-validation/{token}/liveness-session` e recebe `session_id`. 4. O componente `FaceLivenessDetector` (AWS Amplify UI) usa o `session_id` e envia o vídeo direto à AWS. 5. A pessoa fotografa frente e verso do documento e a página envia `POST /access/register/identity-validation/{token}/verify` com as duas imagens e o `liveness_session_id`. 6. A resposta já traz `completed` ou `failed`. O cadastro acompanha por `GET /access/register/identity-validation` ou `GET /access/register/me`. As rotas com `{token}` são públicas: o token identifica a pessoa. Contrato completo de cada uma na [Referência de Endpoints](/abertura-de-conta/endpoints). Para o relógio do celular, `GET /access/clock` devolve `{ "now": }` (hora do servidor), útil para o `systemClockOffset` do Face Liveness. ## Status | Status | Significado | |---|---| | `pending` | Criada, ainda sem link (passa a `link_generated` na mesma chamada) | | `link_generated` | Link gerado, aguardando a pessoa | | `in_progress` | Em andamento no provedor | | `completed` | Prova de vida confirmada. Definitivo | | `failed` | Reprovada (sessão inválida ou confiança baixa). Pode tentar de novo no mesmo link | | `expired` | Link expirou sem conclusão | ## Regras - Chamar `POST /access/register/identity-validation` de novo para a mesma pessoa devolve a validação em aberto. Se a última estiver `failed` ou `expired`, cria uma nova (novo `token` e `link`). - Após `failed`, basta abrir nova `liveness-session` e chamar `verify` de novo no mesmo token. - `verify` numa validação `completed` não reprocessa; devolve o resultado atual. - Na PJ, envie sempre `partner_document`. A validação sem ele não conta para a PJ. ## Callback do provedor `POST /access/register/identity-validation/callback` recebe `{ "token", "status": "completed" | "failed", "result" }` de um provedor externo, com o header `X-Callback-Secret`. Sem o segredo correto: `403`. Já `completed`/`failed`: responde `200` sem alterar. O fluxo com Face Liveness resolve tudo no `verify` e não usa o callback. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a validação de identidade (prova de vida + fotos do documento) da abertura de conta da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: passo 1 e o status usam Authorization: Bearer {session_token} do cadastro. As rotas com {token} são públicas (o token do link identifica a pessoa). Endpoints / passos do fluxo (em ordem): 1. POST /access/register/identity-validation {partner_document? — CPF do sócio, obrigatório na PJ, omitir na PF} — data.token, data.link (válido 24 h), data.status "link_generated". Repetir devolve a validação em aberto; se a última for failed/expired, cria outra. 2. GET /access/register/identity-validation/{token} — {status, expires_at, subject_name, account_type}; 404 token inválido. 3. POST /access/register/identity-validation/{token}/liveness-session — {session_id}; 422 se a AWS falhar (message). 4. No navegador do celular, rode o FaceLivenessDetector (AWS Amplify UI) com esse session_id. GET /access/clock → {now: ms} ajuda a calcular o systemClockOffset. 5. POST /access/register/identity-validation/{token}/verify multipart {id_document_front, id_document_back (imagens até 5 MB), liveness_session_id} — {status: "completed"|"failed", result: {liveness_status, confidence} ou {error}}. 6. GET /access/register/identity-validation[?partner_document=] (com sessão) — sem filtro, lista todas; com filtro, a do sócio. Regras: status pending, link_generated, in_progress, completed (definitivo), failed (pode repetir 3 e 5 no mesmo token), expired. PJ precisa de completed para todos os sócios; PF, do titular. As fotos do titular (PF) ou do sócio legal_representative (PJ) viram os documentos identity_front, identity_back e selfie. Formato de resposta: { "code", "success", "data", "message" }; erros trazem o status HTTP e "message"; erro 422 de validação traz os campos em "errors". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Clientes Clientes (pagadores) da conta ativa, usados nas [cobranças](/cobrancas/). Uma cobrança também cria ou atualiza o cliente pelo documento quando recebe `name`, `email` e `document`. Base URL: `https://api.banking.fastgivr.com.br` ``` Authorization: Bearer {jwt} Content-Type: application/json account: {account_id} (opcional; sem ele vale a conta do login) ``` | Método e rota | Permissão (qualquer uma) | | --- | --- | | `GET /billing/clients`, `GET /billing/clients/{id}` | `view_clients`, `manage_clients`, `create_charges` | | `POST`, `PUT`/`PATCH`, `DELETE` | `manage_clients` | Sem permissão: `403` com `required_permissions`. ## GET /billing/clients Lista paginada, mais recentes primeiro. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `search` | string | Não | Nome ou documento (com ou sem máscara) | | `type` | string | Não | `individual` ou `company` | | `gender` | string | Não | `male` ou `female` | | `status` | string | Não | `2` ativo, `-1` excluído | | `status_id` | integer | Não | Classificação ([`GET /enums/status-clients`](/enums#get-enums-status-clients)) | | `created_at_start`, `created_at_end` | date | Não | `Y-m-d` | | `updated_at_start`, `updated_at_end` | date | Não | `Y-m-d` | | `birthdate_start`, `birthdate_end` | date | Não | `Y-m-d` | | `per_page` | integer | Não | Padrão 15 | | `page` | integer | Não | Padrão 1 | **Response 200:** ```json { "data": [ { "id": 5, "client_id": 5, "name": "Maria Teste", "email": "maria@empresa.com", "phone": { "formatted": "(11) 99999-8888", "raw": "11999998888" }, "document": { "formatted": "529.982.247-25", "raw": "52998224725" }, "type": "individual", "gender": "female", "birthdate": { "formatted": "20 de março de 1985", "raw": "1985-03-20" }, "metadata": [{ "label": "Contrato", "value": "CT-001" }], "code": "CLT-abc123", "status": "2", "client_status": { "id": 1, "title": "Clientes Ativos" }, "created_at": { "formatted": "2 dias atrás", "raw": "2026-11-18T10:00:00.000000Z" }, "updated_at": { "formatted": "2 dias atrás", "raw": "2026-11-18T10:00:00.000000Z" } } ], "meta": { "total": 42, "page": 1, "limit": 15, "total_pages": 3, "has_next_page": true, "has_prev_page": false } } ``` `client_id` repete o `id` (compatibilidade). `address` só vem no detalhe. ## POST /billing/clients Cria um cliente na conta, ativo (`status: "2"`, classificação "Clientes Ativos"). ```json { "name": "João Teste", "email": "joao@empresa.com", "phone": "11988887777", "document": "52998224725", "type": "individual", "gender": "male", "birthdate": "1990-05-10", "address": { "street": "Rua das Flores", "number": "100", "zip": "01310-100", "city": "São Paulo", "state": "SP", "country": "Brasil", "observation": "Apto 42" } } ``` | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `name` | string | Sim | Até 255 | | `email` | string | Sim | E-mail válido, até 255 | | `document` | string | Sim | CPF ou CNPJ válido | | `type` | string | Sim | `individual` ou `company` | | `phone` | string | Não | Até 20 | | `gender` | string | Não | `male` ou `female` | | `birthdate` | date | Não | | | `address` | object | Não | | | `address.street`, `address.city`, `address.state` | string | Com `address` | Até 255 / 100 / 100 | | `address.number`, `address.zip` | string | Não | Até 20 | | `address.country` | string | Não | Até 100 | | `address.observation` | string | Não | Até 500 | O documento não precisa ser único na conta. `metadata` é validado aqui mas só é gravado no `PUT`. **Response 201:** `{ "data": { ...cliente } }`, no formato da listagem. | Status | Quando | | --- | --- | | `422` | Validação (`{ "message", "errors" }`) | ## GET /billing/clients/{id} {#get-billing-clients-id} Detalhe, com `address`. ```json { "data": { "id": 5, "name": "Maria Teste", "address": { "street": "Av. Paulista", "number": "1000", "zip": "01310-100", "city": "São Paulo", "state": "SP", "country": "Brasil", "observation": null } }, "message": "Informações sobre o cliente" } ``` | Status | Quando | | --- | --- | | `404` | `{ "code": 404, "success": true, "data": null, "message": "Cliente não encontrado." }` | ## PUT /billing/clients/{id} {#put-billing-clients-id} Atualiza o cliente. Também aceita `PATCH`. Envie só o que muda. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `name` | string | Não | Se enviado, não pode ser vazio | | `email` | string | Não | E-mail válido | | `phone`, `type`, `gender` | string | Não | | | `document` | string | Não | | | `birthdate` | date | Não | | | `status_id` | integer | Não | Classificação existente | | `address` | object | Não | Mesmas regras do `POST`; cria ou atualiza o endereço | | `metadata` | array | Não | Itens `{ "label": "até 255", "value": "até 1000" }`; substitui o anterior | **Response 201:** ```json { "data": { "id": 5, "name": "Maria Teste Silva" }, "message": "Cliente atualizado com sucesso!" } ``` | Status | Quando | | --- | --- | | `404` | `Cliente não encontrado` | | `422` | Validação | ## DELETE /billing/clients/{id} {#delete-billing-clients-id} Exclui o cliente (exclusão lógica, `status: "-1"`). As cobranças dele continuam. **Response 204**, sem corpo. Inexistente: `404` `Cliente não encontrado`. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar o cadastro de clientes (pagadores) da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Endpoints: - GET /billing/clients — lista, mais recentes primeiro; filtros search (nome ou documento), type, gender, status ("2" ativo), status_id, created_at_start/end, updated_at_start/end, birthdate_start/end (Y-m-d), per_page (padrão 15), page. Resposta { "data": [cliente], "meta": { total, page, limit, total_pages, has_next_page, has_prev_page } }. - POST /billing/clients — obrigatórios name (até 255), email, document (CPF ou CNPJ válido), type (individual|company); opcionais phone (até 20), gender (male|female), birthdate, address { street, city, state obrigatórios com address; number, zip, country, observation }. Resposta 201 { "data": cliente }. - GET /billing/clients/{id} — { "data": cliente com address, "message" }. - PUT /billing/clients/{id} — campos opcionais name, email, phone, document, type, gender, birthdate, status_id, address, metadata [{ label, value }]. Resposta 201 { data, message }. - DELETE /billing/clients/{id} — 204 sem corpo. Cliente: { id, name, email, phone { formatted, raw }, document { formatted, raw }, type, gender, birthdate { formatted, raw }, metadata, code, status, client_status { id, title }, created_at { formatted, raw } }. Regras: leitura exige view_clients, manage_clients ou create_charges; escrita exige manage_clients; sem permissão 403 com required_permissions. 404 com message "Cliente não encontrado" (no GET o corpo vem com success true, confie no status HTTP). O documento não é único na conta. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Cobranças Cobranças por **Pix**, **boleto** ou **boleto + Pix (BOLEPIX)**, emitidas no banco pela conta ativa. Tudo fica em `/billing/charges`. O contrato completo de cada endpoint está em [Cobranças Pix e boleto](/cobrancas/pix-e-boleto). O aviso de pagamento enviado ao seu sistema está em [Webhooks de cobrança](/cobrancas/webhooks). ## Autenticação ``` Authorization: Bearer {jwt} Content-Type: application/json account: {account_id} (opcional; sem ele vale a conta do login) ``` O header `X-Account-Id` é aceito no lugar de `account`. Conta de outro usuário: `403`. Conta inativa, suspensa ou encerrada só aceita consultas (`GET`); as demais chamadas recebem `403` com `account_status`. ## Métodos de pagamento | `payment_method` | O que é emitido | | --- | --- | | `PIX` | Pix dinâmico (copia e cola em `pix.qrcode`). Cliente e vencimento opcionais | | `BOLETO` | Boleto com vencimento | | `BOLEPIX` | Boleto e Pix dinâmico com o mesmo valor; o que for pago primeiro quita a cobrança | ## Status da cobrança Lista atual em [`GET /enums/charge-status`](/enums#get-enums-charge-status). | `status.title` | Significado | | --- | --- | | `pending` | Aguardando pagamento | | `paid` | Paga (`amount_paid`, `payment_date` preenchidos) | | `failed` | A emissão no banco falhou; a cobrança fica registrada para consulta | | `canceled` | Cancelada por `POST /billing/charges/{id}/cancel`; continua visível | | `DELETED` | Excluída por `DELETE /billing/charges/{id}`; some das listagens e do detalhe | ## Endpoints e permissões A permissão é a do usuário na conta ativa. Sem ela: `403` com `required_permissions`. | Método e rota | Permissão (qualquer uma) | Função | | --- | --- | --- | | [`GET /billing/charges`](/cobrancas/pix-e-boleto#get-billing-charges) | `view_charges` | Lista paginada | | [`POST /billing/charges`](/cobrancas/pix-e-boleto#post-billing-charges) | `create_charges` | Emite a cobrança (aceita `Idempotency-Key`) | | [`GET /billing/charges/{id}`](/cobrancas/pix-e-boleto#get-billing-charges-id) | `view_charges` | Detalhe | | [`PUT /billing/charges/{id}`](/cobrancas/pix-e-boleto#put-billing-charges-id) | `edit_charges` | Altera cobrança pendente | | [`DELETE /billing/charges/{id}`](/cobrancas/pix-e-boleto#delete-billing-charges-id) | `delete_charges` | Exclui (baixa o boleto no banco) | | [`POST /billing/charges/{id}/cancel`](/cobrancas/pix-e-boleto#post-billing-charges-id-cancel) | `delete_charges` | Cancela e mantém visível | | [`GET /billing/charges/{id}/download-pdf`](/cobrancas/pix-e-boleto#get-billing-charges-id-download-pdf) | `view_charges` | PDF da cobrança | | [`GET /billing/charges/reports`](/cobrancas/pix-e-boleto#get-billing-charges-reports) | `view_reports`, `view_charges` | Totais por dia ou mês | | [`POST /billing/charges/{id}/webhook`](/cobrancas/webhooks#post-billing-charges-id-webhook) | `edit_charges` | Reenvia o aviso de pagamento | Clientes (pagadores) ficam em [Clientes](/clientes/). ## Fluxo típico 1. `POST /billing/charges` com `payment_method`, valor, pagador e `webhook` (URL do seu sistema). 2. Mostre `pix.qrcode` (copia e cola) ou `boleto.digitable_line` ao pagador, ou envie o PDF. 3. Quando o banco confirma o pagamento, a cobrança vira `paid` e a API faz `POST` no seu `webhook`. 4. Confira com `GET /billing/charges/{id}` se precisar. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar o módulo de cobranças (Pix, boleto e BOLEPIX) da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Endpoints: - GET /billing/charges — lista paginada; filtros search, status_id, client_id, payment_method (PIX,BOLETO,BOLEPIX, aceita lista por vírgula), 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 (até 500), page. - POST /billing/charges — emite; obrigatórios amount (ou value) e payment_method; BOLETO/BOLEPIX também exigem due_date (>= hoje) e client_id ou name+email+document; opcionais description (até 500), webhook (URL), discount+days_discount+type_discount, rate+type_rate (juros no banco), amount_rate (juros gravados), late_fee+late_fee_type, informative (array). Resposta 201 { "data": cobrança } com pix.qrcode, boleto.digitable_line, boleto.barcode. - GET /billing/charges/{id} — detalhe. - PUT /billing/charges/{id} — só pendente; value/amount, due_date, description, webhook, payment_method etc. Resposta traz a cobrança na chave "charge". - DELETE /billing/charges/{id} — exclui (status DELETED) e pede baixa do boleto no banco. - POST /billing/charges/{id}/cancel — só pendente; baixa o boleto no banco e deixa status canceled; banco recusou = 422 sem mudança. - GET /billing/charges/{id}/download-pdf — PDF (application/pdf). - GET /billing/charges/reports?group_by=days|months&date_start=&date_end= — array de totais por data, status e método. - POST /billing/charges/{id}/webhook — reenvia o aviso de uma cobrança paga ao webhook. Regras: permissões view_charges, create_charges, edit_charges, delete_charges, view_reports (403 com required_permissions). POST /billing/charges aceita Idempotency-Key opcional (mesma chave e mesmo corpo devolvem a resposta salva com header Idempotent-Replayed: true; corpo diferente 422; em andamento 409). Limites de valor por conta (min_pix_in, min_boleto_in, max_boleto_in) viram 422. 404 para cobrança de outra conta ou excluída. Erro do banco na emissão: 4xx/5xx com message e a cobrança fica com status failed. Status: pending, paid, failed, canceled, DELETED. Lista: { "data": [...], "meta": { total, page, limit, total_pages, has_next_page, has_prev_page } }. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Cobranças Pix e boleto Contrato de `/billing/charges`. Visão geral, status e permissões em [Cobranças](/cobrancas/). Base URL: `https://api.banking.fastgivr.com.br` ``` Authorization: Bearer {jwt} Content-Type: application/json account: {account_id} (opcional) ``` ## POST /billing/charges Emite a cobrança no banco. Permissão `create_charges`. Aceita o header opcional `Idempotency-Key`: repetir a mesma chave com o mesmo corpo devolve a resposta já salva (header `Idempotent-Replayed: true`), sem emitir de novo. Ver [Idempotência](/idempotencia). ### Pix (sem cliente) ```json { "amount": 25.00, "payment_method": "PIX", "webhook": "https://empresa.com/webhooks/fastgivr" } ``` Com `name`, `email` e `document` juntos (ou `client_id`), o cliente é criado ou atualizado pelo documento e vinculado à cobrança. Sem eles, nenhum cliente é criado e `client` vem `null`. ### Boleto e BOLEPIX ```json { "amount": 150.75, "payment_method": "BOLEPIX", "due_date": "2026-12-10", "name": "Maria Teste", "email": "maria@empresa.com", "document": "52998224725", "description": "Mensalidade dezembro", "late_fee": 2, "late_fee_type": "PERCENTAGE", "rate": 1, "type_rate": "PERCENTAGE", "amount_rate": 1, "discount": 5, "days_discount": 2, "type_discount": "ABSOLUTE", "informative": ["Não receber após o vencimento"], "webhook": "https://empresa.com/webhooks/fastgivr" } ``` | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `amount` ou `value` | numeric | Sim (um dos dois) | ≥ 0,01 e dentro dos limites da conta: PIX ≥ `min_pix_in`; BOLETO ≥ `min_boleto_in`; BOLEPIX ≥ o menor dos dois mínimos; BOLETO/BOLEPIX ≤ `max_boleto_in` | | `payment_method` | string | Sim | `PIX`, `BOLETO` ou `BOLEPIX` | | `due_date` | date | Sim, exceto PIX | ≥ hoje. Vencimento do boleto | | `client_id` | integer | Não | Cliente existente. Com ele, `name`/`email`/`document` não são exigidos e, se enviados, atualizam o cliente | | `name` | string | Sim sem `client_id`, exceto PIX | Até 200 | | `email` | string | Sim sem `client_id`, exceto PIX | E-mail válido | | `document` | string | Sim sem `client_id`, exceto PIX | CPF ou CNPJ. Chave para criar/atualizar o cliente | | `phone` | string | Não | Telefone do cliente | | `address` | object | Não | Endereço do cliente (`street`, `number`, `zip`, `city`, `state`, `country`) | | `description` | string | Não | Até 500 | | `details`, `instructions` | string | Não | Texto livre gravado na cobrança | | `webhook` | string | Não | URL que recebe o aviso de pagamento. Ver [Webhooks de cobrança](/cobrancas/webhooks) | | `rate` + `type_rate` | numeric + string | Não | Juros enviados ao banco. `type_rate`: `ABSOLUTE` ou `PERCENTAGE`. Só vão juntos | | `amount_rate` | numeric | Não | Juros gravados na cobrança (`rate` da resposta). Para o banco cobrar e a cobrança mostrar, envie `rate` e `amount_rate` | | `discount` + `days_discount` | numeric | Não | Desconto até `days_discount` dias antes do vencimento. A data resultante não pode ser anterior a hoje | | `type_discount` | string | Não | `ABSOLUTE` (padrão) ou `PERCENTAGE` | | `late_fee` | numeric | Não | Multa, ≥ 0 | | `late_fee_type` | string | Não | `PERCENTAGE` (padrão) ou `ABSOLUTE` | | `informative` | array | Não | Mensagens impressas no boleto | - **BOLEPIX** emite um boleto e um Pix dinâmico com o mesmo valor. O que for pago primeiro quita a cobrança. - Multa, juros, desconto e `informative` só valem para boleto. **Response 201** (`data` sem `code`/`success`): ```json { "data": { "id": 2, "amount": 150.75, "value": 150.75, "code": null, "rate": 1, "type_rate": "PERCENTAGE", "description": "Mensalidade dezembro", "details": null, "instructions": null, "discount": 5, "amount_paid": 0, "payment_method": "BOLEPIX", "path_pdf": null, "due_date": "2026-12-10T03:00:00.000000Z", "payment_date": null, "created_at": "2026-11-20T13:00:00.000000Z", "pix_id": 2, "boleto_id": 1, "client": { "id": 1, "name": "Maria Teste", "email": "maria@empresa.com", "document": { "formatted": "529.982.247-25", "raw": "52998224725" } }, "status": { "id": 1, "title": "pending", "description": "Pendente" }, "timestamps": { "due_date": { "raw": "...", "formatted": "10/12/2026 00:00:00", "iso": "...", "human": "..." } }, "pix": { "id": 2, "txid": "5f8cc3b5-4fe0-4814-b9c0-cd2c0becc97c", "qrcode": "00020126440014br.gov.bcb.pix...", "amount": 150.75, "status": 0, "paid_amount": 0, "payment_date": null }, "boleto": { "boleto_id": 1, "txid": "NS97220531", "barcode": "3150412345...", "digitable_line": "31504 12345.67890 ...", "status": 0, "amount": 150.75, "late_fee": 2, "our_number": "...", "your_number": "...", "webhook": "https://empresa.com/webhooks/fastgivr" } } } ``` `pix.qrcode` é o copia e cola (monte a imagem do QR Code a partir dele). Em PIX, `boleto` vem `null`; em BOLETO, `pix` vem `null`. Status de Pix e boleto: [Enums](/enums). | Status | Quando | | --- | --- | | `422` | Validação (`{ "message", "errors" }`), incluindo limites de valor da conta | | `422` | `Idempotency-Key` reutilizada com outro corpo | | `409` | Requisição com a mesma `Idempotency-Key` ainda em andamento | | `400`/`4xx` | O banco recusou a emissão: `{ "code", "success", "data": null, "message" }` com o motivo | | `500` | Erro inesperado: `Ocorreu um erro. Processo não concluído.` | Em erro na emissão, a cobrança fica registrada com status `failed`. ## GET /billing/charges Lista as cobranças da conta, mais recentes conforme `order_by`. Permissão `view_charges`. Cobranças `DELETED` não aparecem. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `search` | string | Não | Até 100. Nome, e-mail ou documento do cliente | | `status_id` | string | Não | Um ou vários ids separados por vírgula | | `client_id` | integer | Não | Cliente existente | | `payment_method` | string | Não | `PIX`, `BOLETO`, `BOLEPIX`; vários por vírgula | | `created_at_start`, `created_at_end` | date | Não | `Y-m-d` | | `due_date_start`, `due_date_end` | date | Não | `Y-m-d` | | `payment_date_start`, `payment_date_end` | date | Não | `Y-m-d` | | `order_by` | string | Não | `created_at`, `due_date`, `payment_date` ou `id` | | `order_dir` | string | Não | `asc` ou `desc` | | `per_page` | integer | Não | 1 a 500 (padrão 15) | | `page` | integer | Não | ≥ 1 | ``` GET /billing/charges?payment_method=BOLETO,BOLEPIX&status_id=1&per_page=20 ``` **Response 200:** ```json { "data": [ { "id": 2, "amount": 150.75, "payment_method": "BOLEPIX", "status": { "id": 1, "title": "pending" }, "pix": { }, "boleto": { }, "client": { }, "account": { "id": 1, "name": "Empresa Teste", "document": { "formatted": "...", "raw": "..." } } } ], "meta": { "total": 48, "page": 1, "limit": 20, "total_pages": 3, "has_next_page": true, "has_prev_page": false } } ``` Cada item tem o formato do `POST`. ## GET /billing/charges/{id} {#get-billing-charges-id} Detalhe de uma cobrança da conta, com `client`, `pix`, `boleto` e `created_by`. Permissão `view_charges`. ```json { "code": 200, "success": true, "data": { "id": 2, "status": { "title": "pending" } }, "message": "Detalhes da Cobrança" } ``` | Status | Quando | | --- | --- | | `404` | Outra conta, inexistente ou `DELETED`: `{ "message": "Cobrança não encontrada", "success": false, "data": null }` | ## PUT /billing/charges/{id} {#put-billing-charges-id} Altera uma cobrança **pendente**. Permissão `edit_charges`. Também aceita `PATCH`. Campos não enviados ficam como estão. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `value` ou `amount` | numeric | Não | ≥ 0,01 | | `due_date` | date | Não | ≥ hoje | | `payment_method` | string | Não | `PIX`, `BOLETO` ou `BOLEPIX` | | `description` | string | Não | Até 500 | | `details`, `instructions` | string | Não | | | `amount_rate` | numeric | Não | | | `type_rate` | string | Não | `ABSOLUTE` ou `PERCENTAGE` | | `discount` | numeric | Não | ≥ 0 | | `webhook` | string | Não | URL | - Mudança de valor em PIX/BOLEPIX atualiza o valor do Pix (ou emite um Pix novo, se não houver). - O boleto já emitido **não** é reemitido no banco. Para mudar valor ou vencimento de um boleto, cancele e emita outra cobrança. - Trocar para `BOLETO` desvincula o Pix. **Response 200** (a cobrança vem na chave `charge`, com os campos da tabela): ```json { "code": 200, "success": true, "charge": { "id": 2, "value": "200.00", "status_id": 1 }, "message": "Cobrança atualizada com sucesso!" } ``` | Status | Quando | | --- | --- | | `404` | `Cobrança não encontrada` | | `422` | Não pendente: `A cobrança não está em status aguardando pagamento e não pode ser atualizada.` | | `422` | Validação | ## DELETE /billing/charges/{id} {#delete-billing-charges-id} Exclui a cobrança (status `DELETED`). Permissão `delete_charges`. Ela some das listagens e do detalhe. 1. Boleto pendente: a API pede a baixa ao banco. Aceita, o boleto fica cancelado (`-5`); recusada, fica excluído (`-1`) e a exclusão continua. 2. Pix pendente fica excluído (`-2`). 3. Pix ou boleto já pagos não mudam. ```json { "code": 200, "success": true, "data": { "id": 2, "status_id": 4 }, "message": "Cobrança apagado com sucesso!" } ``` | Status | Quando | | --- | --- | | `404` | `Nenhum resultado encontrado para o modelo especificado.` | ## POST /billing/charges/{id}/cancel Cancela uma cobrança **pendente** e a mantém visível com status `canceled`. Permissão `delete_charges`. 1. Boleto pendente: a API pede a baixa ao banco. Se o banco recusar, responde `422` e nada muda. 2. Com a baixa aceita, o boleto fica cancelado (`-5`) e o Pix pendente, excluído (`-2`). 3. A cobrança passa para `canceled`. **Response 200:** a cobrança, como no detalhe. ```json { "code": 200, "success": true, "data": { "id": 2, "status": { "title": "canceled", "description": "Cancelada" } }, "message": "Cobrança cancelada com sucesso!" } ``` | Status | Quando | | --- | --- | | `404` | `Cobrança não encontrada` (outra conta, inexistente ou `DELETED`) | | `422` | `Só cobranças pendentes podem ser canceladas.` | | `422` | `O banco recusou a baixa do boleto: ...` | ## GET /billing/charges/{id}/download-pdf PDF da cobrança, gerado na hora, com boleto e QR Code Pix quando houver. Permissão `view_charges`. - `200`: `application/pdf`, anexo `fatura_{id}.pdf`. - Cobrança de outra conta ou inexistente: `404`. ## GET /billing/charges/reports Totais agrupados por data, status e método. A data de referência é a de pagamento para cobranças pagas e a de vencimento para as demais. Permissão `view_reports` ou `view_charges`. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `group_by` | string | Sim | `days` ou `months` | | `date_start` | date | Sim | | | `date_end` | date | Sim | ≥ `date_start` | **Response 200** (array, sem envelope): ```json [ { "reference_date": "2026-11-01", "status_id": 2, "payment_method": "PIX", "total_qtd": 12, "total_amount_paid": "1800.00", "total_value": "1800.00", "total_method_paid": "1800.00", "total_method_unpaid": "0.00", "status": { "id": 2, "title": "paid", "description": "Pago" } } ] ``` Com `group_by=months`, `reference_date` vem como `YYYY-MM`. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a emissão e a gestão de cobranças Pix, boleto e BOLEPIX da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Endpoints: - POST /billing/charges — emite. Obrigatórios: amount (ou value, >= 0,01) e payment_method (PIX|BOLETO|BOLEPIX). Para BOLETO e BOLEPIX também due_date (Y-m-d, >= hoje) e client_id ou name+email+document (CPF/CNPJ). Opcionais: phone, address{street,number,zip,city,state,country}, description (até 500), details, instructions, webhook (URL que recebe o aviso de pagamento), rate+type_rate (juros enviados ao banco, ABSOLUTE|PERCENTAGE), amount_rate (juros gravados), discount+days_discount+type_discount, late_fee+late_fee_type (padrão PERCENTAGE), informative (array de mensagens). Resposta 201 { "data": cobrança }: id, amount, payment_method, due_date, status{id,title,description}, client, pix{txid,qrcode (copia e cola),amount,status}, boleto{txid,barcode,digitable_line,our_number,amount,status}. - GET /billing/charges — lista; filtros search, status_id (vírgula), client_id, payment_method (vírgula), 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 (asc|desc), per_page (1-500, padrão 15), page. Resposta { "data": [...], "meta": { total, page, limit, total_pages, has_next_page, has_prev_page } }. - GET /billing/charges/{id} — { code, success, data, message }. - PUT /billing/charges/{id} — só cobrança pending; value/amount, due_date, payment_method, description, details, instructions, amount_rate, type_rate, discount, webhook. Resposta com a cobrança na chave "charge". Não reemite o boleto no banco. - DELETE /billing/charges/{id} — status DELETED; pede baixa do boleto pendente no banco (falha no banco não impede). - POST /billing/charges/{id}/cancel — só pending; baixa o boleto no banco antes; status vira canceled e a cobrança continua visível. - GET /billing/charges/{id}/download-pdf — application/pdf. - GET /billing/charges/reports?group_by=days|months&date_start=Y-m-d&date_end=Y-m-d — array [{ reference_date, status_id, payment_method, total_qtd, total_amount_paid, total_value, total_method_paid, total_method_unpaid, status }]. Regras: permissões create_charges (POST), view_charges (GET), edit_charges (PUT), delete_charges (DELETE e cancel), view_reports ou view_charges (reports); sem permissão 403 com required_permissions. Envie Idempotency-Key (UUID por operação) no POST /billing/charges: repetição com o mesmo corpo devolve a resposta salva com header Idempotent-Replayed: true; corpo diferente 422; requisição ainda em andamento 409. Valor fora dos limites da conta = 422. 404 para cobrança de outra conta, inexistente ou excluída. 422 "Só cobranças pendentes podem ser canceladas." e "O banco recusou a baixa do boleto: ...". Erro do banco na emissão = 4xx/5xx com message, e a cobrança fica com status failed. Status possíveis: pending, paid, failed, canceled, DELETED. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Webhooks de cobrança Quando uma cobrança é paga, a API faz um `POST` na URL informada em `webhook` ao criar a cobrança ([`POST /billing/charges`](/cobrancas/pix-e-boleto#post-billing-charges)). Não há URL de webhook por conta: cada cobrança leva a sua. Sem `webhook`, nada é enviado. ## Quando é enviado - O banco confirma o pagamento do Pix ou do boleto. - A API dá baixa na cobrança (`paid`, `amount_paid`, `payment_date`) e, depois de gravar, envia o aviso com o evento `charge.paid`. - Envio síncrono, **uma tentativa**. Não há nova tentativa automática. Se o seu sistema falhar, use [`POST /billing/charges/{id}/webhook`](#post-billing-charges-id-webhook). - Pode chegar mais de um aviso para a mesma cobrança (reenvio manual). Trate de forma idempotente. ## Requisição enviada ao seu sistema ``` POST {webhook} Content-Type: application/json ``` Não há assinatura nem header de autenticação. Para validar a origem, use uma URL com segredo seu (por exemplo, um token na query string) e confira a cobrança com [`GET /billing/charges/{id}`](/cobrancas/pix-e-boleto#get-billing-charges-id) antes de liberar o pedido. ```json { "type": { "name": "PIX IN" }, "txid": "5f8cc3b5-4fe0-4814-b9c0-cd2c0becc97c", "value": "150.75", "account": "token-da-conta", "date_time": "2026-11-20 14:32:10", "details": { "id": 2, "value": "150.75", "amount_paid": "150.75", "payment_date": "2026-11-20 14:32:10", "payment_method": "PIX", "status_id": 2, "client_id": 1, "description": "Mensalidade dezembro" }, "payer": { "id": 1, "name": "Maria Teste", "email": "maria@empresa.com", "document": "52998224725" }, "event": "charge.paid", "attempts": 0, "last_attempt_at": null } ``` | Campo | Descrição | | --- | --- | | `type.name` | `PIX IN` (Pix de cobrança PIX), `BOLEPIX` (Pix de uma BOLEPIX) ou `BOLETO` (boleto pago) | | `txid` | `txid` do Pix ou do boleto pago (o mesmo de `data.pix.txid` / `data.boleto.txid`) | | `value` | Valor pago, string com 2 casas. Acima de 999,99 vem com separador de milhar: `"1,500.00"` | | `account` | Token da conta FastGivr | | `date_time` | Data e hora do pagamento (`Y-m-d H:i:s`) | | `details` | A cobrança (campos da tabela `charges`). Use `details.id` para identificar a cobrança | | `payer` | Cliente da cobrança, ou `[]` se não houver | | `event` | `charge.paid` no envio automático; `null` no reenvio manual | Responda `2xx` para confirmar. Qualquer outro status, erro de conexão ou demora acima de 30 segundos conta como falha. A API registra cada envio (URL, payload, status e resposta) em `webhook_notifications`, que a conta consulta em `GET /access/webhook-notifications` (permissão `manage_api`). ## POST /billing/charges/{id}/webhook Reenvia o aviso de uma cobrança **paga** da conta ativa. Permissão `edit_charges`. Usa o `webhook` e o `txid` do boleto ou, sem boleto, do Pix. No reenvio, `type.name` é sempre `BOLEPIX`, `event` vem `null` e `details` traz a cobrança junto com os dados do boleto ou do Pix. **Response 200** (ou `500` se o seu sistema não respondeu `2xx`): ```json { "message": "Notificação enviada com sucesso", "charge_id": "12", "status": "success", "http_status": 200, "error": null, "webhook_url": "https://empresa.com/webhooks/fastgivr", "webhook_notification_id": 34, "response": { "ok": true } } ``` Na falha: `"message": "Erro ao enviar notificação"`, `"status": "error"` e o status devolvido pelo seu sistema em `http_status`. | Status | Quando | | --- | --- | | `404` | `Cobrança não encontrada.` (inexistente, de outra conta ou não paga) | | `400` | `Não há PIX ou Boleto associado a esta cobrança.` | ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar o recebimento dos webhooks de cobrança paga da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação (para as chamadas à API): Authorization: Bearer {jwt}; header opcional account: {account_id}. Como funciona: ao criar a cobrança (POST /billing/charges) envio "webhook": "". Quando a cobrança é paga, a FastGivr faz POST nessa URL com Content-Type: application/json, sem assinatura e sem header de autenticação. Uma tentativa só, timeout de 30 s, sem retry automático. Corpo recebido: { "type": { "name": "PIX IN" | "BOLEPIX" | "BOLETO" }, "txid": string, "value": string com 2 casas (pode ter vírgula de milhar, ex. "1,500.00"), "account": token da conta, "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" ou null (reenvio), "attempts": 0, "last_attempt_at": null }. Construa o endpoint receptor: - Proteja a URL com um segredo meu (token na query string) e rejeite chamadas sem ele. - Responda 2xx rápido (antes de 30 s); faça o processamento pesado em fila. - Processe de forma idempotente pela chave details.id (+ txid): 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. - Converta "value" removendo a vírgula de milhar. Endpoints: - GET /billing/charges/{id} — confirma a cobrança; { code, success, data: { id, status: { title }, amount_paid, payment_date, pix, boleto }, message }. - POST /billing/charges/{id}/webhook — pede o reenvio do aviso de uma cobrança paga; 200 { message, status: "success", http_status, webhook_notification_id, response } ou 500 com status "error"; 404 se não paga ou de outra conta; 400 sem Pix nem boleto. Regras: permissões view_charges (GET) e edit_charges (reenvio); sem permissão 403. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Banking — receber Pix O prefixo `/banking` reúne o lado de **recebimento** da conta no banco: chaves Pix e QR Codes para receber. Cobranças com cliente e vencimento ficam em [Cobranças Pix e boleto](/cobrancas/pix-e-boleto). Base URL: `https://api.banking.fastgivr.com.br` ## Autenticação e conta ativa ``` Authorization: Bearer {jwt} Content-Type: application/json account: {account_id} ``` - O JWT vem de `POST /access/auth/login` ([Login e sessão](/autenticacao/login-e-sessao)). - `account` (ou `X-Account-Id`) escolhe a conta. Sem o header, vale a conta do login. Conta sem vínculo com o usuário: `403`; conta inexistente: `404`. - Conta inativa, suspensa ou encerrada só consulta (`GET`). Nas demais rotas, `403` com `{ "message", "account_status" }`. ## Permissões Cada rota exige ao menos uma das permissões listadas, na conta ativa. Sem ela: ```json { "message": "Seu usuário não tem permissão para esta ação. Peça ao administrador da conta.", "required_permissions": ["receive_pix"] } ``` ## Rotas | Método | Rota | Permissão | Página | |---|---|---|---| | `GET` | `/banking/pix/keys` | `view_pix_keys`, `manage_pix_keys` | [Chaves Pix](/banking/chaves-pix#get-banking-pix-keys) | | `POST` | `/banking/pix/keys/verification` | `manage_pix_keys` | [Chaves Pix](/banking/chaves-pix#post-banking-pix-keys-verification) | | `POST` | `/banking/pix/keys` | `manage_pix_keys` | [Chaves Pix](/banking/chaves-pix#post-banking-pix-keys) | | `GET` | `/banking/pix/keys/{key}` | `view_pix_keys`, `manage_pix_keys` | [Chaves Pix](/banking/chaves-pix#get-banking-pix-keys-key) | | `DELETE` | `/banking/pix/keys/{key}` | `manage_pix_keys` | [Chaves Pix](/banking/chaves-pix#delete-banking-pix-keys-key) | | `GET` | `/banking/pix/keys/verify` | `view_pix_keys`, `manage_pix_keys` | [Chaves Pix](/banking/chaves-pix#get-banking-pix-keys-verify) | | `GET` | `/banking/pix/static-qrcode` | `receive_pix` | [QR Code para receber](/banking/pix-cobrancas#get-banking-pix-static-qrcode) | | `POST` | `/banking/pix/qrcode/dynamic` | `receive_pix` | [QR Code para receber](/banking/pix-cobrancas#post-banking-pix-qrcode-dynamic) | ## Formato das respostas As rotas respondem `{ "code", "success", "data", "message" }`. Erros: - Validação do corpo: `422` `{ "message", "errors": { "campo": ["..."] } }`. - Regras de negócio e recusas do banco: `{ "code", "success": false, "message", "data" }` (em alguns `422`, os campos vêm em `data`). ## Ambientes Contas de homologação (sandbox) não movimentam dinheiro real; contas de produção, sim. A URL da API é a mesma; o ambiente depende da conta. ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar o recebimento de Pix (chaves Pix e QR Codes) da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt} (obtido em POST /access/auth/login); header opcional account: {account_id} para escolher a conta. Endpoints: - GET /banking/pix/keys — lista as chaves da conta - POST /banking/pix/keys/verification { key_type: 2|3 } — envia código de posse ao e-mail/celular da conta; data.id - POST /banking/pix/keys { key_type: 1|2|3|4, verification_id?, code? } — inclui chave (código obrigatório para 2 e 3) - GET /banking/pix/keys/{key}, DELETE /banking/pix/keys/{key} — consulta e exclui - GET /banking/pix/keys/verify?key= — dono de uma chave no DICT - GET /banking/pix/static-qrcode — copia e cola estático, sem valor; data { payload, pix_id } - POST /banking/pix/qrcode/dynamic { amount } — copia e cola com valor; 201 data { id, txid, value, qrcode, status } Regras: permissões view_pix_keys/manage_pix_keys (chaves) e receive_pix (QR Codes); sem permissão 403 com required_permissions. Incluir, verificar e excluir chaves é só pelo portal/app: com token de integração, 403. Idempotency-Key opcional no POST /banking/pix/qrcode/dynamic (UUID v4 por QR Code, repetido nas tentativas). Limite de 5 chaves (CPF) ou 20 (CNPJ). Formato de resposta: { "code", "success", "data", "message" }; erro de validação 422 { "message", "errors": { campo: [..] } } (alguns 422 trazem os campos em "data"). Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Chaves Pix Chaves Pix da própria conta, para receber. A chave é registrada no DICT pela banco. Autenticação, headers e permissões: [Banking — visão geral](/banking/). - Não existe "editar chave": o DICT só permite incluir uma nova ou excluir. - Listar e consultar leem a cópia local das chaves incluídas por esta API. Incluir e excluir sempre chamam o banco. - **Limite do Banco Central:** 5 chaves para CPF e 20 para CNPJ. Acima disso, `422`. - **Valor da chave:** CPF/CNPJ, e-mail e celular são sempre os dados cadastrados na conta. Não é possível informar outro valor. A chave aleatória é gerada pelo banco. - **Senha transacional do banco:** incluir e excluir exigem a senha transacional configurada na conta (`PUT /access/account`, ver [Conta](/gestao/conta)). Ela nunca vai no corpo destas rotas. Sem ela, `422`. | `key_type` | Chave | Origem do valor | |:---:|---|---| | `1` | CPF/CNPJ (só dígitos) | `document` da conta | | `2` | E-mail | `email` da conta (exige código de posse) | | `3` | Celular `+55DDDNÚMERO` | `phone` da conta (exige código de posse) | | `4` | Aleatória (EVP) | Gerada pelo banco | --- ## GET /banking/pix/keys Lista as chaves da conta. Permissão: `view_pix_keys` ou `manage_pix_keys`. **Response 200:** ```json { "code": 200, "success": true, "data": [ { "id": 2, "key_type": 2, "key_value": "financeiro@empresa.com", "created_at": "2026-11-10T12:05:00.000000Z" }, { "id": 1, "key_type": 1, "key_value": "12345678000199", "created_at": "2026-11-10T12:00:00.000000Z" } ], "meta": { "account_values": { "1": "12345678000199", "2": "financeiro@empresa.com", "3": null }, "key_limit": 20, "keys_count": 2, "verified_types": [2, 3], "requires_transactional_password": true, "has_transactional_password": true }, "message": "Chaves Pix listadas com sucesso." } ``` - `account_values`: valor que cada tipo usaria (`null` = dado não cadastrado na conta). - `verified_types`: tipos que exigem código de posse. --- ## POST /banking/pix/keys/verification Envia um código de 6 dígitos ao e-mail (`key_type: 2`) ou, por SMS, ao celular (`key_type: 3`) cadastrado na conta. Permissão: `manage_pix_keys`. Só pessoas (portal/app). Limite: 5 chamadas por minuto (`429`). | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `key_type` | integer | Sim | `2` ou `3` | **Response 201:** ```json { "message": "Enviamos um código para o e-mail da conta.", "data": { "id": "9d41c3a0-...", "key_type": 2, "destination": "fi***@empresa.com", "expires_at": "2026-11-10T15:10:00-03:00" } } ``` O código vale 10 minutos. Cinco tentativas erradas o invalidam. Um novo envio substitui o anterior. | Status | Quando | |---|---| | `422` | `key_type` inválido; dado não cadastrado na conta; dado já é chave da conta; limite de chaves atingido; falha no envio do código | | `429` | Mais de 5 chamadas por minuto | --- ## POST /banking/pix/keys Inclui uma chave. Permissão: `manage_pix_keys`. Só pessoas (portal/app): com token de integração, `403`. | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `key_type` | integer | Sim | `1`, `2`, `3` ou `4` | | `verification_id` | string | Para `2` e `3` | `data.id` de `POST /banking/pix/keys/verification` | | `code` | string | Para `2` e `3` | Código recebido | ```json { "key_type": 2, "verification_id": "9d41c3a0-...", "code": "123456" } ``` **Response 201:** ```json { "data": { "id": 3, "key_type": 2, "key_value": "financeiro@empresa.com", "created_at": "2026-11-10T12:10:00.000000Z" }, "message": "Chave Pix incluída com sucesso." } ``` O código de posse só é consumido depois que o banco registra a chave. Se o e-mail ou celular da conta mudar depois do envio, peça outro código. | Status | Quando | |---|---| | `422` | `key_type` inválido; dado não cadastrado ou já usado como chave; limite de chaves; código ausente, errado ou expirado (`code`); senha transacional não configurada | | `4xx` | Recusa do banco (ex.: chave já registrada em outra instituição), com o mesmo status e a mensagem do banco em `message` | Erros de regra vêm como `{ "code": 422, "success": false, "message", "data": { "campo": ["..."] } }`. --- ## GET /banking/pix/keys/{key} {#get-banking-pix-keys-key} Consulta uma chave da conta pelo valor exato (use URL-encode, ex.: `financeiro%40empresa.com`). Permissão: `view_pix_keys` ou `manage_pix_keys`. **Response 200:** ```json { "code": 200, "success": true, "data": { "id": 2, "key_type": 2, "key_value": "financeiro@empresa.com", "created_at": "2026-11-10T12:05:00.000000Z" }, "message": "Chave Pix consultada com sucesso." } ``` **404:** `{ "code": 404, "success": true, "data": null, "message": "Chave Pix não encontrada." }`. Chaves registradas fora desta API não aparecem aqui. --- ## DELETE /banking/pix/keys/{key} {#delete-banking-pix-keys-key} Exclui a chave no banco e, se existir, a cópia local. Sem corpo. Permissão: `manage_pix_keys`. Só pessoas (portal/app): com token de integração, `403`. **Response 200:** `{ "code": 200, "success": true, "data": { ...retorno do banco }, "message": "Chave Pix removida com sucesso." }` | Status | Quando | |---|---| | `422` | Senha transacional não configurada | | `4xx` | Recusa do banco (ex.: chave não pertence à conta), com a mensagem do banco | --- ## GET /banking/pix/keys/verify Consulta no DICT a quem pertence uma chave (própria ou de terceiro), sem mover dinheiro. Permissão: `view_pix_keys` ou `manage_pix_keys`. | Query | Tipo | Obrigatório | Regras | |---|---|---|---| | `key` | string | Sim | Máx. 150 | **Response 200:** ```json { "code": 200, "success": true, "data": { "key": "financeiro@empresa.com", "found": true, "owner": { "name": null, "document": null, "bank_name": null, "agency": null, "account": null }, "raw": { "status": "sucesso", "retorno": { "chave": "financeiro@empresa.com", "tpChave": 2, "nome": "EMPRESA LTDA", "cpfCnpj": "12345678000199", "banco": { "nome_reduzido": "BANCO EXEMPLO", "ispb": "12345678" } } } }, "message": "Chave Pix verificada com sucesso." } ``` Os dados do dono vêm em `raw.retorno` (`nome`, `cpfCnpj`, `banco`); os campos de `owner` podem vir `null`. CPF de pessoa física costuma vir mascarado. | Status | Quando | |---|---| | `422` | `key` ausente (campos em `data`) | | `404` | Chave não encontrada no DICT | ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a gestão de chaves Pix da conta na API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Endpoints: - GET /banking/pix/keys — lista; data[] { id, key_type, key_value, created_at }; meta { account_values, key_limit, keys_count, verified_types, has_transactional_password } - POST /banking/pix/keys/verification { key_type: 2|3 } — envia código ao e-mail/celular da conta; retorna data.id (verification_id); vale 10 min; máx. 5 chamadas/min (429) - POST /banking/pix/keys { key_type: 1|2|3|4, verification_id?, code? } — inclui; verification_id e code obrigatórios para 2 (e-mail) e 3 (celular); 201 com data { id, key_type, key_value } - GET /banking/pix/keys/{key} — consulta pelo valor (URL-encode); 404 se não existir - DELETE /banking/pix/keys/{key} — exclui no banco - GET /banking/pix/keys/verify?key= — dono de qualquer chave no DICT; use data.raw.retorno { nome, cpfCnpj, banco } (data.owner pode vir com null) Regras: key_type 1 CPF/CNPJ, 2 e-mail, 3 celular, 4 aleatória; o valor é sempre o dado cadastrado na conta (não se envia o valor). Limite 5 chaves (CPF) ou 20 (CNPJ). Incluir/excluir exigem a senha transacional do banco já configurada na conta (meta.has_transactional_password); sem ela 422. Permissões: view_pix_keys/manage_pix_keys (leitura), manage_pix_keys (incluir/excluir). Recusas do banco voltam com o status do banco e a mensagem em message. Formato de resposta: { "code", "success", "data", "message" }; erro { "message", "success": false, "data" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # QR Code para receber Códigos Pix para a conta **receber**, sem criar cobrança: o estático (sem valor, reutilizável) e o dinâmico (com valor, uso único). Cobranças com cliente e vencimento ficam em [Cobranças Pix e boleto](/cobrancas/pix-e-boleto). Autenticação, headers e permissões: [Banking — visão geral](/banking/). Os dois usam a chave Pix da conta (`key_pix`). Ela é uma chave aleatória criada automaticamente quando a conta é carregada (`GET /access/account`) e ainda não tem chave, desde que a senha transacional do banco esteja configurada na conta. --- ## GET /banking/pix/static-qrcode Gera o copia e cola **estático** da conta: sem valor (quem paga escolhe), reutilizável. Permissão: `receive_pix`. **Response 200:** ```json { "code": 200, "success": true, "data": { "payload": "00020126...6304ABCD", "pix_id": 123 } } ``` - O código é gerado pelo banco. Cada chamada gera um código novo e um novo registro de Pix (`pix_id`), sem valor. - Conta sem chave Pix: `422` `A conta não tem chave Pix cadastrada para gerar o código estático.` --- ## POST /banking/pix/qrcode/dynamic Gera um Pix **dinâmico** (com valor, uso único) e o grava como pendente. Quando for pago, entra no extrato. Permissão: `receive_pix`. Aceita o header `Idempotency-Key` (opcional, ver [Idempotência](/idempotencia)). | Campo | Tipo | Obrigatório | Regras | |---|---|---|---| | `amount` | number | Sim | Mín. `0.01` e mín. `min_pix_in` da conta | ```json { "amount": 42.50 } ``` **Response 201:** ```json { "code": 201, "success": true, "data": { "id": 15, "txid": "9F2C4A7B1E0D3C5A8B6F2E1D0C9B8A7F", "value": 42.5, "qrcode": "00020101021226...6304ABCD", "status": 0, "created_at": "2026-11-10T20:10:00.000000Z" }, "message": "Pix gerado com sucesso." } ``` `status` `0` = pendente. | Status | Quando | |---|---| | `422` | `amount` ausente ou abaixo do mínimo (`errors.amount`); conta sem chave Pix | | `500` | Falha no banco ao gerar o código | ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar a geração de QR Code Pix para receber da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Endpoints: - GET /banking/pix/static-qrcode — copia e cola estático, sem valor e reutilizável; data { payload, pix_id } - POST /banking/pix/qrcode/dynamic { amount } — copia e cola dinâmico com valor, uso único; 201 com data { id, txid, value, qrcode, status (0 = pendente), created_at } Regras: permissão receive_pix. amount mínimo 0.01 e o mínimo de Pix de entrada da conta. Idempotency-Key opcional no dinâmico (UUID v4 por QR Code, repetido nas tentativas). A conta precisa ter chave Pix (senão 422). Gere a imagem do QR Code a partir do texto payload/qrcode. Formato de resposta: { "code", "success", "data", "message" }; erro de validação 422 { "message", "errors": { campo: [..] } }; outros erros { "message", "success": false, "data" }. Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Financeiro Saldo, extrato, comprovantes, exportação e indicadores da conta ativa, em `/consolidation`. Base URL: `https://api.banking.fastgivr.com.br` ``` Authorization: Bearer {jwt} Content-Type: application/json account: {account_id} (opcional; sem ele vale a conta do login) ``` | Método e rota | Permissão (qualquer uma) | | --- | --- | | `GET /consolidation/balance` | `view_balance` | | `GET /consolidation/financial-movements`, `/{id}`, `/{id}/download-pdf` | `view_extract`, `view_transactions` | | `POST /consolidation/transactions/export-document` | `generate_extract` | | `POST /consolidation/statistic/cards` | `view_reports`, `view_balance` | | `GET /consolidation/transaction-types` | só autenticação | | `GET /consolidation/exports/download/{id}` | link assinado (sem token) | Sem permissão: `403` com `required_permissions`. Conta inativa, suspensa ou encerrada continua consultando (inclusive os dois `POST` desta página). ## GET /consolidation/balance ```json { "balance": 4523.75, "available": 4323.75 } ``` | Campo | Descrição | | --- | --- | | `balance` | Saldo do extrato | | `available` | Saldo disponível: `balance` menos operações ainda em processamento | ## GET /consolidation/financial-movements Extrato da conta, paginado, com resumo do período. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `search` | string | Não | Até 100. Busca em `txid`, `endtoendid` e descrição | | `type_id` | integer | Não | Tipo de transação ([`GET /consolidation/transaction-types`](#get-consolidation-transaction-types)) | | `type_ids[]` | array | Não | Vários tipos | | `status` | integer | Não | Status da transação | | `status_ids[]` | array | Não | Vários status. Padrão: `1`, `2` e `4` | | `date_start` | date | Não | Padrão: 30 dias atrás | | `date_end` | date | Não | ≥ `date_start`. Padrão: hoje | | `order_by` | string | Não | `created_at` (padrão), `datetime`, `id` ou `value` | | `order_dir` | string | Não | `asc` ou `desc` (padrão) | | `per_page` | integer | Não | 1 a 200 (padrão 15) | | `page` | integer | Não | ≥ 1 | | `include[]` | array | Não | `summary` e/ou `daily_evolution`. Sem `include`, vem `summary` | Status de transação: `0` pendente, `1` confirmada, `2` cancelada, `4` concluída, `-1` erro. Para `4`, `status_description` vem `Desconhecido`. **Response 200** (paginação padrão do Laravel): ```json { "data": [ { "id": 981, "txid": "5f8cc3b5-4fe0-4814-b9c0-cd2c0becc97c", "endtoendid": "E1234567820261120143210abcdef", "description": null, "value": 150.75, "balance": 4523.75, "status": 1, "status_description": "Confirmada", "currency": "BRL", "origin": null, "type": { "id": 1, "slug": "pix-in", "name": "Pix In", "description": null }, "payer": { "name": "Maria Teste", "document": "52998224725", "bank": null, "agency": null, "account": null }, "receiver": { "name": null, "document": null, "bank": null, "agency": null, "account": null }, "datetime": "2026-11-20 14:32:10", "created_at": "2026-11-20T17:32:10.000000Z", "updated_at": "2026-11-20T17:32:10.000000Z" } ], "links": { "first": "...", "last": "...", "prev": null, "next": "..." }, "meta": { "current_page": 1, "from": 1, "last_page": 4, "per_page": 15, "to": 15, "total": 52, "path": "...", "links": [] }, "summary": { "total_count": 52, "total_value": 1200.5, "income_value": 3000, "expenses_value": -1799.5, "income_count": 30, "expenses_count": 22, "initial_balance": 3323.25, "final_balance": 4523.75, "current_balance": 4523.75, "by_type": [{ "type_id": 1, "type_name": "Pix In", "count": 30, "total_value": 3000 }], "period": { "start_date": "2026-10-21", "end_date": "2026-11-20" } }, "daily_evolution": [ { "date": "2026-11-20", "balance": 4523.75, "variation": 150.75, "inflow": 150.75, "outflow": 0 } ] } ``` `daily_evolution` só vem com `include[]=daily_evolution`. ## GET /consolidation/financial-movements/{id} {#get-consolidation-financial-movements-id} Uma transação da conta, no formato da listagem. ```json { "code": 200, "success": true, "data": { "id": 981, "value": 150.75 }, "message": "Movimentação encontrada." } ``` Outra conta ou inexistente: `404` com `"message": "Movimentação não encontrada."`. ## GET /consolidation/financial-movements/{id}/download-pdf Comprovante em PDF (`application/pdf`, `transacao-{id}-{data}.pdf`). Por padrão é anexo; `?download=false` abre no navegador. Outra conta ou inexistente: `404`. ## GET /consolidation/transaction-types Tipos de transação, para os filtros. Corpo JSON (array), sem envelope. ```json [ { "id": 1, "name": "Pix In", "slug": "pix-in" }, { "id": 2, "name": "Pix Out", "slug": "pix-out" }, { "id": 3, "name": "Boleto", "slug": "boleto" } ] ``` ## POST /consolidation/transactions/export-document Exporta o extrato em XLSX, CSV ou PDF. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `format` | string | Não | `xlsx` (padrão), `csv` ou `pdf` | | `download` | boolean | Não | `true`: devolve o arquivo na resposta. `false` (padrão): gera em segundo plano | | `created_at_start`, `created_at_end` | date | Não | `Y-m-d` | | `type` | string ou array | Não | Ids de tipo, separados por vírgula ou em array | | `search` | string | Não | Até 100. Só no modo em segundo plano | - `download=true`: resposta é o arquivo (`transacoes_{data}.xlsx|csv|pdf`), com transações de status `1`, `2` e `4`. - Em segundo plano: só transações confirmadas (`1`). Resposta `200` com `"message": "A exportação foi iniciada. Você receberá uma notificação quando o arquivo estiver pronto."`. O usuário recebe um e-mail com o arquivo anexado e uma notificação com o link de download (válido por 24 horas). | Status | Quando | | --- | --- | | `404` | `Nenhuma transação encontrada para exportação.` (segundo plano) | | `422` | Formato inválido ou validação | ## GET /consolidation/exports/download/{id} {#get-consolidation-exports-download-id} Link de download de uma exportação feita em segundo plano. Público: quem autoriza é a assinatura do link (vem pronto na notificação, válido por 24 horas). O arquivo é gerado de novo a cada download. | Status | Quando | | --- | --- | | `403` | `Link de download inválido ou expirado.` | | `404` | Notificação ou exportação não encontrada, ou o usuário perdeu o acesso à conta | ## POST /consolidation/statistic/cards Números dos cards do painel. Devolve só os cards pedidos. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `cards` | array | Sim | Itens abaixo | | `period` | string | Não | `last_15_days`, `current_month`, `last_month`, `current_year` ou `custom`. Sem ele, todo o histórico | | `data_inicial`, `data_final` | date | Com `custom` | `data_final` ≥ `data_inicial` | | Card | Valor | | --- | --- | | `PIXS_COUNT` | Quantidade de Pix emitidos | | `BOLETOS_COUNT` | Quantidade de boletos emitidos | | `CLIENTS_COUNT` | Clientes cadastrados | | `CHARGE_COUNT_PAID` | Cobranças pagas | | `CHARGE_SUM_PAID` | Soma de `amount_paid` das cobranças pagas | | `TOTAL_CHARGE_EXPECTED_TO_RECEIVE` | Soma das cobranças pendentes | | `PIX_IN_SUM` | Soma dos Pix recebidos | | `PIX_OUT_SUM` | Soma das saídas Pix (valor negativo) | O período filtra pela data de criação. ```json { "cards": ["CHARGE_COUNT_PAID", "CHARGE_SUM_PAID"], "period": "current_month" } ``` **Response 200** (sem envelope): ```json { "CHARGE_COUNT_PAID": 12, "CHARGE_SUM_PAID": "1800.00" } ``` ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar saldo, extrato, comprovantes, exportação e indicadores (módulo financeiro) da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt}; header opcional account: {account_id}. Endpoints: - GET /consolidation/balance — { "balance", "available" } (available = saldo menos operações em processamento). Permissão view_balance. - GET /consolidation/financial-movements — extrato paginado; filtros search, type_id ou type_ids[], status ou status_ids[] (padrão 1,2,4), date_start/date_end (padrão últimos 30 dias), order_by (created_at|datetime|id|value), order_dir, per_page (1-200), page, include[]=summary|daily_evolution (sem include vem summary). Resposta { data: [{ id, txid, endtoendid, description, value, balance, status, status_description, type { id, slug, name }, payer {...}, receiver {...}, datetime }], links, meta { current_page, last_page, per_page, total }, summary { total_count, income_value, expenses_value, initial_balance, final_balance, current_balance, by_type[], period }, daily_evolution [{ date, balance, variation, inflow, outflow }] }. Permissão view_extract ou view_transactions. - GET /consolidation/financial-movements/{id} — { code, success, data, message }; 404 "Movimentação não encontrada.". - GET /consolidation/financial-movements/{id}/download-pdf — comprovante PDF; ?download=false abre inline. - GET /consolidation/transaction-types — array [{ id, name, slug }]. - POST /consolidation/transactions/export-document — { format: xlsx|csv|pdf, download: bool, created_at_start, created_at_end, type }. download=true devolve o arquivo; senão 200 com message e o usuário recebe e-mail e notificação com link assinado (24 h) para GET /consolidation/exports/download/{id}; 404 se não houver transações. Permissão generate_extract. - POST /consolidation/statistic/cards — { cards: [PIXS_COUNT|BOLETOS_COUNT|CLIENTS_COUNT|CHARGE_COUNT_PAID|CHARGE_SUM_PAID|TOTAL_CHARGE_EXPECTED_TO_RECEIVE|PIX_IN_SUM|PIX_OUT_SUM], period: last_15_days|current_month|last_month|current_year|custom, data_inicial, data_final (com custom) } → objeto { CARD: valor }. Permissão view_reports ou view_balance. Regras: sem permissão 403 com required_permissions. Status de transação: 0 pendente, 1 confirmada, 2 cancelada, 4 concluída, -1 erro. Valores negativos são débitos. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Enums Listas de valores para montar filtros e telas. Rotas públicas: não exigem token nem header `account`. Base URL: `https://api.banking.fastgivr.com.br` ## GET /enums/charge-status Status de cobrança (`status_id` de `/billing/charges`). Array, sem envelope. ```json [ { "id": 1, "title": "pending", "description": "Pendente" }, { "id": 2, "title": "paid", "description": "Pago" }, { "id": 3, "title": "failed", "description": "Falhou" }, { "id": 4, "title": "DELETED", "description": "Excluída" }, { "id": 5, "title": "canceled", "description": "Cancelada" } ] ``` Os itens também trazem `created_at` e `updated_at`. Use o `title` para regras no seu código; o `id` pode variar entre ambientes. ## GET /enums/payment-method Métodos de pagamento de cobrança. Objeto `valor → nome`. ```json { "PIX": "Pix", "BOLETO": "Boleto Bancário", "BOLEPIX": "Boleto com Pix", "UNKNOWN": "Desconhecido" } ``` `UNKNOWN` só aparece em cobranças com falha na emissão. ## GET /enums/pix-status Status do Pix de uma cobrança (`data.pix.status`). Objeto `valor → nome`. ```json { "1": "PAID", "0": "PENDING", "-2": "DELETED", "3": "EXPIRED", "2": "PAIDWITHBOLETO" } ``` `PAIDWITHBOLETO`: a BOLEPIX foi paga pelo boleto. ## GET /enums/boleto-status Status do boleto de uma cobrança (`data.boleto.status`). Objeto `valor → nome`. ```json { "0": "PENDING", "1": "PAID", "-5": "CANCELLED", "3": "EXPIRED", "4": "FAILED", "-1": "DELETED", "-2": "Deleted", "5": "PAIDWITHPIX" } ``` `PAIDWITHPIX`: a BOLEPIX foi paga pelo Pix. `-5`: baixado no banco. ## GET /enums/status-clients Classificações de cliente (`status_id` de `/billing/clients`). Array com `id`, `title`, `created_at` e `updated_at`. ```json [ { "id": 1, "title": "Clientes Ativos" }, { "id": 2, "title": "Clientes com Pagamentos em Aberto" }, { "id": 3, "title": "Clientes em Alerta" }, { "id": 4, "title": "Clientes Inadimplentes" } ] ``` ## GET /enums/webhook-type Tipos dos webhooks recebidos dos bancos. Array `[{ "value", "title" }]`. | `value` | `title` | | --- | --- | | 1 | Pix | | 2 | Boleto | | 3 | Desconhecido | | 4 | TED (Entrada) | | 5 | Pix (Entrada) | | 6 | Pix (Saída) | | 7 | Pagamento de Boleto | | 8 | Recebimento de Boleto | | 9 | Listagem de Boletos | | 10 | TED (Saída) | | 20 | Abertura de Conta | | 21 | Recusa de Abertura de Conta | | 22 | Encerramento de Conta | ## GET /enums/webhook-status Status de processamento dos webhooks recebidos dos bancos. Array `[{ "value", "title" }]`. | `value` | `title` | | --- | --- | | 0 | Pendente | | 1 | Erro de validação | | 2 | Sucesso | | 3 | Falha | | 4 | Duplicado | | 5 | Em processamento | | 6 | Expirado | | 7 | Aguardando | | 8 | Desconhecido | | 9 | Erro | | 10 | Boleto pendente | | 11 | Boleto em processamento | | 12 | Listagem de boleto registrada | ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai integrar as listas de valores (enums) da API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: nenhuma (rotas públicas). Endpoints: - GET /enums/charge-status — array [{ id, title (pending|paid|failed|DELETED|canceled), description }]. Use title nas regras; id varia entre ambientes. - GET /enums/payment-method — objeto { "PIX": "Pix", "BOLETO": "Boleto Bancário", "BOLEPIX": "Boleto com Pix", "UNKNOWN": "Desconhecido" }. - GET /enums/pix-status — objeto valor→nome: 0 PENDING, 1 PAID, 2 PAIDWITHBOLETO, 3 EXPIRED, -2 DELETED. - GET /enums/boleto-status — objeto valor→nome: 0 PENDING, 1 PAID, 3 EXPIRED, 4 FAILED, 5 PAIDWITHPIX, -1 DELETED, -2 Deleted, -5 CANCELLED. - GET /enums/status-clients — array [{ id, title }] das classificações de cliente. - GET /enums/webhook-type e GET /enums/webhook-status — array [{ value, title }] (webhooks recebidos dos bancos). Regras: as respostas de charge-status, payment-method, pix-status, boleto-status, status-clients, webhook-type e webhook-status vêm sem envelope; guarde em cache (mudam raramente). Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Backoffice Rotas do painel interno da FastGivr (`fastgivr-backoffice`), em `/backoffice`. Dão visão entre contas: indicadores, contas, usuários, clientes, cobranças, transações, logs e webhooks recebidos dos bancos. Não são para clientes. Base URL: `https://api.banking.fastgivr.com.br` ## Acesso Todas as rotas exigem `Authorization: Bearer {jwt}` de um usuário com o papel **`Backoffice`**. O header `account` não é usado. | Situação | Resposta | | --- | --- | | Sem token ou token inválido | `401` | | Usuário sem o papel (inclusive papéis de conta e tokens de API) | `403` `{ "message": "Acesso restrito aos operadores do backoffice." }` | | Usuário com o papel, logado no painel (`POST /access/auth/login` com `device_name: dashboard`) | liberado | O papel é do usuário, não da conta. Conceder ou remover: ```bash php artisan backoffice:operator operador@fastgivr.com.br php artisan backoffice:operator operador@fastgivr.com.br --remove ``` ## Paginação As listas usam a paginação padrão do Laravel: `{ "data": [...], "links": { first, last, prev, next }, "meta": { current_page, from, last_page, per_page, to, total, path } }`. `per_page` padrão 15 (logs e webhooks: 25, máximo 100). Registro inexistente: `404`. ## GET /backoffice/dashboard Indicadores do período (cache de 5 minutos). | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `date_from` | date | Não | Padrão: início do mês | | `date_to` | date | Não | Padrão: hoje | Resposta (sem envelope): `period { from, to }`, `stats[]` (`title`, `value`, `icon`, `color`, `trend` em % contra o período anterior de mesma duração, para cobranças, usuários, contas e transações), `recent_charges[]` (últimas 5) e `financial` (`total_balance`, `active_accounts_count`, `monthly_inflows`, `monthly_outflows` e versões formatadas). ## Contas ### GET /backoffice/accounts Filtros: `search`, `status`, `bank_id`, `date_from`, `date_to`, `order_by` (`id`, `name`, `document`, `agency`, `account`, `status`, `created_at`), `order_dir`, `per_page`. Além da paginação, traz `summary { total, active, deleted }` e `banks [{ id, title, total_balance }]`. ### GET /backoffice/accounts/{id} {#get-backoffice-accounts-id} Detalhe com banco, endereço, usuários e papéis, histórico de status e `stats { transactions, charges }` (totais e quebra por tipo/status), filtráveis por `date_from`/`date_to`. ### GET /backoffice/accounts/{id}/balance `{ account_id, name, balance, balances, total_balance, formatted_balance }`. ### GET /backoffice/accounts/{id}/balance-evolution `period`: `week`, `month` ou `year`. Resposta `{ code, success, data }`. ### GET /backoffice/accounts/{id}/charges-report Relatório de cobranças da conta. Resposta `{ code, success, data }`. ### PUT /backoffice/accounts/{id} {#put-backoffice-accounts-id} Também aceita `PATCH`. Envie só o que muda. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `name` | string | Não | Até 255 | | `email` | string | Não | Único entre contas | | `document` | string | Não | CPF/CNPJ. Não pode mudar se a conta já tem documento (`422` `O CPF/CNPJ da conta não pode ser alterado.`) | | `phone` | string | Não | Celular com DDD, com ou sem +55 | | `status` | string | Não | `ACTIVE`, `INACTIVE`, `SUSPENDED`, `SOFT_DELETED`, `DELETED` | | `bank_id`, `agency`, `account` | | Não | Bloqueados (`422`) se a conta já tem transações | | `tax_pix_in`, `tax_boleto_in`, `tax_bolepix` | numeric | Não | Taxas de recebimento, ≥ 0 | | `min_pix_in`, `min_boleto_in`, `max_boleto_in` | numeric | Não | Limites de cobrança, ≥ 0 | | `address` | object | Não | `street`, `city`, `state` obrigatórios; `number`, `zip`, `country` | Resposta: `{ code, success, account: {...}, message: "Account updated successfully" }`. ### PATCH /backoffice/accounts/{id}/status Troca o status com registro de autor e motivo. | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `status` | string | Sim | `ACTIVE`, `INACTIVE`, `SUSPENDED`, `CLOSED`, `SOFT_DELETED`, `DELETED` | | `reason` | string | Sim | 3 a 500 | Resposta: `{ code, success, data: conta, message: "Status da conta atualizado." }`. ### GET /backoffice/reports/accounts Todas as contas (sem paginação), com banco, saldos e usuários. Filtros `search`, `status`. ## Usuários ### GET /backoffice/users Usuários (exceto usuários de API). Filtros `search` (nome, e-mail, documento), `status`, `order_by`, `order_dir`, `per_page`. ### GET /backoffice/users/{id} {#get-backoffice-users-id} Detalhe com contas, papéis, endereço, histórico de status e logs. `meta` traz `boletos_count`, `pixs_count`, `charges_count`, filtráveis por `date_from`/`date_to`. ### PATCH /backoffice/users/{id}/status | Campo | Tipo | Obrigatório | Regras | | --- | --- | --- | --- | | `status` | integer | Sim | `1` ativo, `0` inativo, `2` bloqueado, `-1` excluído | | `reason` | string | Sim | 3 a 500 | O operador não pode mudar o próprio status (`422`). Resposta: `{ code, success, data: usuário, message: "Status do usuário atualizado." }`. ### GET /backoffice/reports/users Todos os usuários, sem paginação. Filtro `search`. ## Clientes - `GET /backoffice/clients`: filtros `search`, `status`, `status_id`, `account_id`, `created_from`, `created_to`, `order_by`, `order_dir`, `per_page`. - `GET /backoffice/clients/{id}`: com conta, endereço e classificação. - `GET /backoffice/reports/clients`: todos, sem paginação (filtros `search`, `status`, `status_id`, `account_id`). ## Cobranças - `GET /backoffice/charges`: filtros `search`, `status_id`, `account_id`, `client_id`, `created_from`/`created_to`, `due_from`/`due_to`, `payment_from`/`payment_to`, `updated_from`/`updated_to`, `order_by`, `order_dir`, `per_page`. Traz `summary [{ status, count, total_value, total_paid }]`. - `GET /backoffice/charges/{id}`: cobrança com cliente, conta, status, Pix, boleto, transação e notificação de webhook (JSON do modelo, sem envelope). - `GET /backoffice/reports/charges`: todas, sem paginação. Filtros `search`, `status_id`, `date_from`, `date_to`. ## Transações Só consulta. ### GET /backoffice/transactions Mesmos filtros e formato de [`GET /consolidation/financial-movements`](/financeiro/#get-consolidation-financial-movements), mais `account_id` (sem ele, todas as contas). Sem filtro de status por padrão. Sempre traz `summary`; `include[]=daily_evolution` adiciona a evolução diária. Cada item traz `account` e `created_by`. ### GET /backoffice/transactions/{id} {#get-backoffice-transactions-id} Transação com conta, tipo e autor. ## Logs - `GET /backoffice/logs`: mais recentes primeiro. Filtros `type` (`audit`, `system` ou `api`), `level`, `event`, `method`, `user_id`, `account_id`, `search` (descrição, evento, tag, URL, IP), `date_from`, `date_to`, `per_page` (até 100). A lista não traz `context` nem valores antigos/novos. - `GET /backoffice/logs/{id}`: com `context`, `old_values` e `new_values`, campos sensíveis mascarados. ## Webhooks recebidos Webhooks que o banco envia à API (não os avisos enviados aos clientes, que estão em [Webhooks de cobrança](/cobrancas/webhooks)). - `GET /backoffice/webhooks`: filtros `status`, `type_id` (valores em [Enums](/enums#get-enums-webhook-status)), `bank_id`, `txid`, `search`, `date_from`, `date_to`, `per_page` (até 100). Traz `options { statuses, types, banks }` para os filtros. A lista não traz o `payload`. - `GET /backoffice/webhooks/{id}`: com `payload` mascarado e o que ele baixou (Pix, boleto, cobrança, transações). - `POST /backoffice/webhooks/{id}/reprocess`: devolve o webhook à fila, que confere tudo de novo no banco antes de dar baixa. `202` com o webhook. Já aplicado (sucesso ou duplicado) ou que não pode ser reprocessado: `409`. - `POST /backoffice/webhooks/reprocess`: `{ "ids": [1, 2] }` (1 a 100, distintos). `202` `{ "message", "queued": [...], "skipped": [...] }`. ## Aberturas de conta `/backoffice/registers/*` está em [Revisão e aprovação](/abertura-de-conta/revisao-e-aprovacao). ## Prompt para LLM Copie o texto abaixo e cole no seu assistente de IA para ele integrar este módulo. ```txt Você vai construir o painel interno (backoffice) da FastGivr sobre a API FastGivr. Base URL: https://api.banking.fastgivr.com.br Autenticação: Authorization: Bearer {jwt} de usuário com o papel Backoffice (login em POST /access/auth/login com device_name: dashboard). Sem token 401; sem o papel 403 { "message": "Acesso restrito aos operadores do backoffice." }. Não use o header account. Endpoints: - GET /backoffice/dashboard?date_from=&date_to= — { period, stats[{ title, value, icon, color, trend }], recent_charges[], financial{ total_balance, active_accounts_count, monthly_inflows, monthly_outflows } }. - GET /backoffice/accounts (search, status, bank_id, date_from, date_to, order_by, order_dir, per_page) + summary e banks; GET /backoffice/accounts/{id} (+ stats; date_from/date_to); GET /backoffice/accounts/{id}/balance; GET /backoffice/accounts/{id}/balance-evolution?period=week|month|year; GET /backoffice/accounts/{id}/charges-report; PUT /backoffice/accounts/{id} (name, email, document, phone, status, taxas de recebimento tax_pix_in, tax_boleto_in, tax_bolepix, limites de cobrança min_pix_in, min_boleto_in, max_boleto_in, address; bank_id/agency/account bloqueados se há transações → 422; resposta na chave "account"); PATCH /backoffice/accounts/{id}/status { status: ACTIVE|INACTIVE|SUSPENDED|CLOSED|SOFT_DELETED|DELETED, reason (3-500) }; GET /backoffice/reports/accounts. - GET /backoffice/users (search, status); GET /backoffice/users/{id} (+ meta com contagens); PATCH /backoffice/users/{id}/status { status: 1|0|2|-1, reason } (não o próprio: 422); GET /backoffice/reports/users. - GET /backoffice/clients (search, status, status_id, account_id, created_from, created_to); GET /backoffice/clients/{id}; GET /backoffice/reports/clients. - GET /backoffice/charges (search, status_id, account_id, client_id, created_from/to, due_from/to, payment_from/to, updated_from/to) + summary; GET /backoffice/charges/{id}; GET /backoffice/reports/charges. - GET /backoffice/transactions (filtros do extrato: search, type_ids[], status_ids[], date_start, date_end, order_by, order_dir, per_page até 200, account_id, include[]=daily_evolution) + summary; GET /backoffice/transactions/{id}. - GET /backoffice/logs (type, level, event, method, user_id, account_id, search, date_from, date_to, per_page até 100); GET /backoffice/logs/{id}. - GET /backoffice/webhooks (status, type_id, bank_id, txid, search, date_from, date_to) + options; GET /backoffice/webhooks/{id}; POST /backoffice/webhooks/{id}/reprocess (202; 409 se já aplicado); POST /backoffice/webhooks/reprocess { ids: [..] até 100 } → 202 { message, queued, skipped }. Regras: listas usam paginação Laravel { data, links, meta { current_page, last_page, per_page, total } }; per_page padrão 15 (logs/webhooks 25). Relatórios reports/* devolvem tudo sem paginação. 404 para id inexistente. Status de conta em texto, de usuário em número. Formato de resposta: { "code", "success", "data", "message" }; erro 422 traz os campos em "errors" ou "data". Chame a API pelo servidor (CORS só libera os sites da FastGivr). Gere o código com tratamento desses erros. ``` --- # Novidades Mudanças da API que afetam quem integra, da mais recente para a mais antiga. O histórico técnico completo está no `CHANGELOG.md` do repositório. ## 19 de novembro de 2026 - **`POST /access/account/get-token` só para usuários de API.** O e-mail precisa ser de um usuário com o papel `API` na conta; outro usuário recebe `401`. - **Token da conta só para quem gerencia integrações.** `GET /access/account` e `GET /access/accounts` só trazem `token` para quem tem a permissão `manage_api`. - **Limite de tentativas.** Login, `get-token`, `forgot`, `reset` e `POST /access/register/user`: 10 por minuto por IP e 5 por minuto por e-mail/documento + IP. Passando disso, `429`. ## 18 de novembro de 2026 - **`Idempotency-Key`:** um erro `5xx` não libera mais a chave; a repetição devolve a mesma resposta. Ver [Idempotência](/idempotencia). - **CORS fechado:** o navegador só chama a API a partir dos sites da FastGivr. Integrações chamam pelo servidor. - **Saldo disponível:** `GET /consolidation/balance` devolve `available` (saldo menos o que está em processamento), além de `balance`. - **Códigos de e-mail com 4 números** e espera progressiva depois de 3 erros (`429` com `Retry-After`). - **`POST /access/auth/forgot`** não exige mais `document`. - **Erros sem detalhes internos:** em erro genérico (`500`), recurso não encontrado e falha do banco, `data` vem `null`. ## 17 de novembro de 2026 - **Rotas duplicadas removidas:** `PUT /access/accounts` (use `PUT /access/account`), `POST /consolidation/statistic/balance` (use `POST /consolidation/statistic/cards`) e `GET /enums/type-transactions` (use `GET /consolidation/transaction-types`).