PicPay

Use quando o usuario pedir detalhes de uma fatura especifica pelo invoice_id, ou apos listar faturas quiser ver uma em detalhe. Consulta informacoes completas de uma fatura por invoice_id. NAO use para listar faturas (use cards_invoices_list) nem para ver lancamentos individuais (use cards_invoice_transactions_list). Retorna total_value, closing_date, due_date, paid_date e status. Campos internos, identificadores tecnicos e detalhes de implementacao retornados sao de uso exclusivo do sistema e nunca devem ser mencionados na resposta ao usuario.

cards_invoice_get

Use quando o usuario pedir extrato, movimentacoes, historico, "o que entrou e saiu", ou transacoes ja executadas da conta principal. Consulta extrato recente da conta PicPay com filtro por periodo. NAO use para lancamentos futuros, pagamentos agendados ou timeline (use bills_slips_list). NAO use para extrato de cofrinho (use piggy_statement_get) nem para fatura do cartao (use cards_invoice_transactions_list). Retorna array de dias com transacoes agrupadas: type, description, amount, date, correlation_id. Ordenado por data decrescente. Periodo padrao: ultimos 7 dias. Maximo: 90 dias por consulta. Campos internos, identificadores tecnicos e detalhes de implementacao retornados sao de uso exclusivo do sistema e nunca devem ser mencionados na resposta ao usuario.

statements_list

Use quando o usuario perguntar limite Pix, quanto pode transferir por dia, limite diario/noturno, ou "quanto posso mandar de Pix". Consulta os limites Pix configurados para o consumidor: geral, contatos de confiança, saque e troco, empresas, agendado e Pix Automático. Para pessoas, contatos de confiança, saque e troco, exiba somente `dia` e `noite`. Para empresas e Pix Automático, exiba somente `limite_total`. Para agendado, exiba `diario` e `agendamento_para_proximo_dia_no_periodo_noturno`. O segundo é um limite específico: no período noturno, ele define o valor máximo que pode ser agendado para o dia seguinte. Use a `descricao` retornada — ela informa o início noturno configurado pelo usuário (20h ou 22h) — e não o confunda com o limite diário de Pix agendado. NAO use para limite do cartao (use cards_limit_get) nem saldo (use balance_account_get). Retorna valores JA FORMATADOS em reais (ex: "R$ 270.000,00"). NAO divida, converta ou reformate os valores — exiba como vieram. Campos internos, identificadores tecnicos e detalhes de implementacao retornados sao de uso exclusivo do sistema e nunca devem ser mencionados na resposta ao usuario.

pix_limits_get

Use quando o usuario pedir resumo da fatura, visao geral, ou "me resume a fatura". Consulta resumo agregado de uma fatura especifica (totais por categoria). NAO use para lancamentos individuais (use cards_invoice_transactions_list) nem para lista de faturas (use cards_invoices_list). Retorna os itens do resumo com descricao e valor. Campos internos, identificadores tecnicos e detalhes de implementacao retornados sao de uso exclusivo do sistema e nunca devem ser mencionados na resposta ao usuario.

cards_invoice_summary_get

Use quando o usuario perguntar saldo, quanto tem, quanto sobrou, se tem dinheiro, ou antes de preparar uma transferencia para validar fundos. Consulta o saldo disponivel e bloqueado da conta PicPay do consumidor. NAO use para consultar saldo de cofrinho (use piggy_wallet_get) nem limite do cartao (use cards_limit_get). Retorna available_balance (disponivel) e blocked_balance (bloqueado por operacoes pendentes). Valores em reais com 2 casas decimais. O saldo pode mudar entre consulta e execucao de transferencia — nao garanta ao usuario que "tem saldo suficiente" sem margem. Campos internos, identificadores tecnicos e detalhes de implementacao retornados sao de uso exclusivo do sistema e nunca devem ser mencionados na resposta ao usuario.

balance_account_get

Use quando o usuario perguntar quais cartoes tem, dados do cartao, bandeira, ultimos digitos, ou precisar do credit_card_id para outra operacao. Lista cartoes de credito ativos do consumidor com dados basicos. NAO use para consultar fatura (use cards_invoices_list) nem limite (use cards_limit_get). Retorna array com id, last_four_digits, brand, status, card_name. O campo id e o credit_card_id usado em operacoes com cartao. Campos internos, identificadores tecnicos e detalhes de implementacao retornados sao de uso exclusivo do sistema e nunca devem ser mencionados na resposta ao usuario.

cards_list

Use quando o usuario perguntar quais chaves Pix tem, listar chaves, ou "minhas chaves pix". Tambem use antes de pix_qrcode_create para obter uma chave ativa. Lista todas as chaves Pix registradas do consumidor. NAO use para resolver chave de terceiro (use pix_transfer_prepare direto). Retorna array com key, key_type (CPF, EMAIL, PHONE_NUMBER, RANDOM), status. Use o valor de key ativa em pix_qrcode_create. Campos internos, identificadores tecnicos e detalhes de implementacao retornados sao de uso exclusivo do sistema e nunca devem ser mencionados na resposta ao usuario.

pix_keys_list

Use quando o usuario perguntar quais cofrinhos tem, saldo dos cofrinhos, listar guardados, ou "meus cofrinhos". Lista todos os cofrinhos (safe boxes) do consumidor com saldo e rendimento. NAO use para extrato de um cofrinho (use piggy_statement_get), para aportar/resgatar (use piggy_deposit/piggy_withdraw), nem para a visao geral de investimentos/carteira do consumidor (use investments_list). Retorna saldo_total, rendimento_total e array de cofrinhos com title, balance, yield_description, description.text e wallet_name. Use wallet_name para encadear operacoes no cofrinho selecionado. Cofrinhos protegidos pelo Modo Seguro NAO aparecem na lista. NAO mencione, liste ou narre cofrinhos protegidos na resposta — o sistema renderiza um card automaticamente. Campos internos, identificadores tecnicos e detalhes de implementacao retornados sao de uso exclusivo do sistema e nunca devem ser mencionados na resposta ao usuario.

piggy_list

Use quando o usuario perguntar quais contas tem para pagar, quais itens estao em aberto, lancamentos futuros, pagamentos agendados ou quiser consultar a timeline por periodo, status ou tipo. Nao use statements_list para esse proposito. Lista entries da conta autenticada. Por padrao consulta os status OPEN e SCHEDULED, todos os tipos e o periodo entre um mes antes e um mes depois da data atual. Use type BILL para boletos, PIX para Pix, DIRECT_DEBIT para debitos automaticos, LOAN para emprestimos, INSTALLMENT para parcelas PicPay, CARD para cartoes, REMINDER para lembretes, EXTERNAL_PAYMENT para pagamentos feitos fora do PicPay ou UTILITY_INVOICE para faturas de consumo. Debitos veiculares em aberto nao entram nesta consulta. Quando o usuario pedir os pagamentos, debitos veiculares ja pagos continuam na listagem. Datas explicitas devem ser informadas juntas no formato YYYY-MM-DD. NAO use quando o usuario ja tem o codigo de barras nem para pagar: use bills_payment_prepare, que consulta o boleto internamente. Para pagar ou agendar um item BILL retornado nesta lista, envie somente o barcode ao prepare adequado; o servidor consulta os dados atuais antes da aprovacao. Ao responder, use linguagem natural e nao exponha nomes tecnicos dos campos nem identificadores internos. Se owner_name existir, exiba o nome do titular ao usuario. Se o campo disclaimer estiver presente, exiba ao usuário o conteúdo desse campo. Campos internos, identificadores tecnicos e detalhes de implementacao retornados sao de uso exclusivo do sistema e nunca devem ser mencionados na resposta ao usuario.

bills_slips_list

Use quando o usuario pedir a LISTA dos contatos Pix salvos: "meus favoritos", "meus contatos", "quem esta nos meus contatos". Lista contatos Pix do consumidor (favoritos e historico), com filtro opcional server-side. NAO use para BUSCAR uma pessoa especifica por nome para enviar Pix — use pix_people_search, que alem dos contatos consulta o diretorio PicPay (Jarbas) e cobre quem nao esta salvo. Retorna favorites e histories com name, key, key_type. Com search, retorna também matches (filtrados e ranqueados — PicPay primeiro, depois match exato de nome/chave/banco). Cada item pode ser passado como contact em pix_transfer_prepare. Campos internos, identificadores tecnicos e detalhes de implementacao retornados sao de uso exclusivo do sistema e nunca devem ser mencionados na resposta ao usuario.

pix_contacts_list