> ## Documentation Index
> Fetch the complete documentation index at: https://docs-corp.usight.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar Faturas

> Retorna faturas paginadas (parâmetros `page` e `limit`) com suporte a filtros por empresa, título e período de vencimento. A resposta inclui `count` (total geral), `page`, `limit` e `total_pages`. Itere `page` de 1 até `total_pages` para percorrer toda a base.



## OpenAPI

````yaml GET /invoices
openapi: 3.0.0
info:
  title: API Corp ERP
  version: 1.1.0
  description: >-
    API para gerenciamento de clientes e faturas no ERP Corp.


    **Autenticação:** envie a API key no header `x-api-key` (ou `Authorization:
    Bearer <apikey>`). Cada chave possui escopos (`clients:read`,
    `clients:write`, `invoices:read`, `invoices:write`) e pode ter data de
    expiração.


    **Paginação:** os endpoints GET são paginados via `page` (1-based) e `limit`
    (default 50, máximo 100). A resposta traz `count`, `page`, `limit` e
    `total_pages`.


    **Limites:** até 1000 registros por requisição POST (em lote); corpo de até
    8 MB; até 120 requisições por minuto por chave (resposta 429 com
    `Retry-After`). Uma importação em lote conta como 1 requisição.
servers:
  - url: https://api-corp.usight.com.br
    description: Produção
  - url: https://api-corp-sandbox.usight.com.br
    description: Sandbox (homologação)
security:
  - ApiKeyAuth: []
paths:
  /invoices:
    get:
      tags:
        - Faturas
      summary: Consultar Faturas
      description: >-
        Retorna faturas paginadas (parâmetros `page` e `limit`) com suporte a
        filtros por empresa, título e período de vencimento. A resposta inclui
        `count` (total geral), `page`, `limit` e `total_pages`. Itere `page` de
        1 até `total_pages` para percorrer toda a base.
      operationId: getFaturas
      parameters:
        - name: codigo
          in: query
          description: Filtra por código da empresa (cont_cd_acesso)
          schema:
            type: string
          example: '001'
        - name: titulo
          in: query
          description: Busca parcial no título da fatura (case-insensitive)
          schema:
            type: string
          example: NF-2025
        - name: from
          in: query
          description: Data mínima de vencimento (YYYY-MM-DD)
          schema:
            type: string
            format: date
          example: '2025-01-01'
        - name: to
          in: query
          description: Data máxima de vencimento (YYYY-MM-DD)
          schema:
            type: string
            format: date
          example: '2025-12-31'
        - name: page
          in: query
          description: Página a retornar (1-based). Use junto com `limit` para paginar.
          schema:
            type: integer
            default: 1
            minimum: 1
          example: 1
        - name: limit
          in: query
          description: Registros por página (default 50, máximo 100)
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
          example: 50
      responses:
        '200':
          description: Lista de faturas
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FaturaOutput'
                  count:
                    type: integer
                    description: >-
                      Total de registros que satisfazem o filtro (todas as
                      páginas)
                    example: 1240
                  page:
                    type: integer
                    description: Página atual
                    example: 1
                  limit:
                    type: integer
                    description: Registros por página
                    example: 50
                  total_pages:
                    type: integer
                    description: Total de páginas disponíveis
                    example: 25
        '401':
          description: Não autorizado — API key ausente, inválida, revogada ou expirada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Sem permissão — a API key não possui o escopo necessário para esta
            operação
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: >-
            Muitas requisições — limite por minuto excedido. Veja o header
            `Retry-After`.
          headers:
            Retry-After:
              description: Segundos a aguardar antes de repetir a requisição
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    FaturaOutput:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        cont_cd_acesso:
          type: string
          example: '001'
        titulo:
          type: string
          example: NF-2025-001
        vencimento:
          type: string
          example: '2025-07-01'
        valor_bruto:
          type: number
          example: 1500
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Cliente não cadastrado para o código '001'.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        `Apikey` fornecida pelo Corp ERP. Também aceita `Authorization: Bearer
        <apikey>`.

````