> ## Documentation Index > Fetch the complete documentation index at: https://docs.piposaude.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Listar faturas > Lista as faturas de todas as empresas às quais o cliente tem acesso. Quando nenhum filtro de data é informado, retorna por padrão as faturas com período de referência a partir dos últimos 3 meses, sem limite superior (inclui períodos futuros). ## OpenAPI ````yaml openapi.yaml GET /v1/invoices openapi: 3.1.0 info: title: Pipo Public API version: 0.2.0 description: > API pública da Pipo Saúde para integração de movimentações de benefícios (inclusões, exclusões e consultas) por parceiros e sistemas de folha de pagamento. contact: name: Pipo Engineering email: felipe.rodopoulos@piposaude.com.br servers: - url: https://api.pipo.health description: Homologação (staging) - url: https://api.piposaude.com.br description: Produção security: - bearerAuth: [] tags: - name: Autenticação description: Obtenção do token de acesso. - name: Empresas description: Consulta de empresas e seus produtos. - name: Benefícios description: Consulta de produtos/benefícios disponíveis. - name: Faturas description: Consulta de faturas, boletos e status de pagamento. - name: Movimentações description: Inclusões, exclusões e histórico de movimentações. - name: Membros description: Consulta de membros e seus benefícios. - name: Solicitações description: Consulta do status de requisições assíncronas. - name: Health Check description: Verificação de disponibilidade. paths: /v1/invoices: get: tags: - Faturas summary: Listar faturas description: > Lista as faturas de todas as empresas às quais o cliente tem acesso. Quando nenhum filtro de data é informado, retorna por padrão as faturas com período de referência a partir dos últimos 3 meses, sem limite superior (inclui períodos futuros). parameters: - $ref: '#/components/parameters/FromDt' - $ref: '#/components/parameters/UntilDt' - $ref: '#/components/parameters/InvoiceStatusFilter' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: '200': description: Lista paginada de faturas. content: application/json: schema: type: object properties: result: type: array items: $ref: '#/components/schemas/Invoice' pagination: $ref: '#/components/schemas/Pagination' example: result: - id: inv-2024-01-000123 company-id: 123e4567-e89b-12d3-a456-426614174000 invoice-config-id: 456e7890-e89b-12d3-a456-426614174007 company-name: Acme Corporation carrier-name: HealthCorp invoice-config-name: Plano Saúde Premium - Mensal invoice-config-status: active amount: 1234560 due-date: '2024-02-10' reference-period-start: '2024-01-01' reference-period-end: '2024-01-31' invoice-status: paid-and-pending unique-member-count: 42 invoice-without-payment-slips: false files: - file-id: 789e0123-e89b-12d3-a456-426614174008 name: boleto-01.pdf type: payment-slip payment-slip-code: 34191.79001 01043.510047 91020.150008 1 96610000123456 payment-slip-due-date: '2024-02-10' status: paid pagination: current-page: 1 total-items: 1 total-pages: 1 next-page: null previous-page: null '400': $ref: '#/components/responses/InvalidDateFilter' components: parameters: FromDt: name: from-dt in: query required: false schema: type: string format: date description: Data inicial do filtro (ISO 8601, `YYYY-MM-DD`). UntilDt: name: until-dt in: query required: false schema: type: string format: date description: >- Data final do filtro (ISO 8601, `YYYY-MM-DD`). Deve ser maior que `from-dt`. InvoiceStatusFilter: name: status in: query required: false schema: $ref: '#/components/schemas/InvoiceStatus' description: Filtra as faturas pelo status agregado de pagamento. Page: name: page in: query required: false schema: type: integer minimum: 1 description: Número da página (padrão `1`). PerPage: name: per-page in: query required: false schema: type: integer minimum: 1 description: Quantidade de itens por página (padrão `20`). schemas: Invoice: type: object required: - id - company-id - invoice-config-id - amount - due-date - reference-period-start - reference-period-end - files properties: id: type: string description: Identificador da fatura. company-id: type: string format: uuid invoice-config-id: type: string format: uuid description: >- Identificador da configuração de faturamento (contrato/apólice) que gerou a fatura. company-name: type: string carrier-name: type: string invoice-config-name: type: string invoice-config-status: $ref: '#/components/schemas/InvoiceConfigStatus' amount: type: integer description: Valor total da fatura em centavos (R$ 1.234 56 = 123456).: null due-date: type: string format: date reference-period-start: type: string format: date description: Início do período de referência da fatura. reference-period-end: type: string format: date description: Fim do período de referência da fatura. invoice-status: $ref: '#/components/schemas/InvoiceStatus' unique-member-count: type: integer minimum: 0 description: Quantidade de membros únicos cobertos pela fatura. details-by-benefit: type: object description: > Detalhamento do valor da fatura por benefício. Estrutura livre, definida pela operadora/configuração de faturamento. invoice-without-payment-slips: type: boolean description: Indica que a fatura não possui boletos vinculados. files: type: array items: $ref: '#/components/schemas/InvoiceFile' Pagination: type: object required: - current-page - total-items - total-pages - next-page - previous-page properties: current-page: type: integer minimum: 1 total-items: type: integer minimum: 0 total-pages: type: integer minimum: 1 next-page: type: - integer - 'null' description: Próxima página, ou `null` se esta for a última. previous-page: type: - integer - 'null' description: Página anterior, ou `null` se esta for a primeira. InvoiceStatus: type: string description: > Status agregado de pagamento da fatura. `information-unavailable` indica que o status do(s) boleto(s) não está disponível para vencimentos anteriores a `2026-05-01` ou sem data de vencimento. enum: - all-paid - paid-and-pending - paid-pending-and-overdue - all-pending - all-overdue - pending-and-overdue - paid-and-overdue - information-unavailable - other InvoiceConfigStatus: type: string description: Status da configuração de faturamento vinculada à fatura. enum: - active - archived InvoiceFile: type: object required: - file-id - name properties: file-id: type: string description: Identificador do arquivo. name: type: string description: Nome do arquivo. type: $ref: '#/components/schemas/InvoiceFileType' payment-slip-code: type: string description: Linha digitável do boleto. payment-slip-due-date: type: string format: date description: Data de vencimento do boleto. confirm-date: type: string format: date description: Data de confirmação do pagamento. status: $ref: '#/components/schemas/InvoiceFileStatus' Error: type: object required: - error properties: error: type: string description: Mensagem descritiva do erro. InvoiceFileType: type: string description: Tipo do arquivo da fatura. enum: - payment-slip - invoice-description - other InvoiceFileStatus: type: string description: > Status de pagamento do arquivo (aplicável a boletos). `information-unavailable` indica que o status não está disponível para vencimentos anteriores a `2026-05-01` ou sem data de vencimento. enum: - paid - pending - overdue - information-unavailable responses: InvalidDateFilter: description: Filtro de datas inválido. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: 'Invalid date filter: ''until-dt'' must be greater than ''from-dt''' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Token Bearer obtido em `POST /v1/authenticate`. ````