# Lista de compras

Retorna listas de compras.

Endpoint: GET /api/v3/purchases
Version: 3.0.0
Security: OAuth2

## Header parameters:

  - `CPlug-Company-Id` (number, required)
    Id da Empresa (Company).

Você pode localizar os IDs das empresas no _endpoint_ de listagem de empresas.
    Example: 12

## Query parameters:

  - `search_term` (integer)
    Filtra pelo ID da compra ou pelo número da nota fiscal.
    Example: 123

  - `purchase_status` (string)
    Filtra pelo status da compra.
Exemplo:
  - pending Aguardando.
  - received Entregue.
    Enum: "pending", "received"

  - `supplier_ids` (string)
    Filtra pelos IDs dos fornecedores. Pode passar mais de um ID numérico separado por virgula.

Você pode localizar os IDs dos fornecedores no _endpoint_ de listagem de fornecedores.
    Example: "1,2,3"

  - `registration_start` (string)
    data inicial do registro de compra.
    Example: "2025-01-14"

  - `registration_end` (string)
    data final do registro de compra.
    Example: "2025-01-14"

  - `page` (number)
    Indica a página da paginação.

  - `per_page` (number)
    Indica a quantidade de itens por página.

  - `updated_from` (string)
    Filtra por dados que foram atualizadas a partir de uma data. (Formato: YYYY-MM-DDThh:mm:ss+hh:mm).

  - `deleted` (string)
    Filtro para indicar se deve retornar dados apagados ou não.
    Enum: "not_include", "include", "only"

## Response 200 fields (application/json):

  - `data` (object)

  - `data.purchases` (array)
    Representa a lista de compras

  - `data.purchases.id` (integer)
    Identificador único da compra.
    Example: 123

  - `data.purchases.registration_date` (string)
    Data da compra.
    Example: "2025-01-14"

  - `data.purchases.supplier` (object)
    Dados do fornecedor.

  - `data.purchases.supplier.id` (integer)
    Id único do fornecedor.
    Example: 123

  - `data.purchases.supplier.name` (string)
    Nome do fornecedor.
    Example: "CPlug Supplier"

  - `data.purchases.invoice` (object)
    Dados do frete.

  - `data.purchases.invoice.serie` (string)
    Número de série da nota fiscal
    Example: "1"

  - `data.purchases.invoice.number` (string)
    Número da nota fiscal
    Example: "789"

  - `data.purchases.code` (integer)
    Código do da compra.
    Example: 456

  - `data.purchases.value_of_items` (object)
    Valor total dos itens da compra.

  - `data.purchases.value_of_items.amount` (number, required)
    Valor expresso como um número decimal das principais unidades monetárias
    Example: 99.95

  - `data.purchases.value_of_items.currency` (string, required)
    Código de moeda de 3 letras conforme definido pela ISO-4217
    Example: "BRL"

  - `data.purchases.discount` (object)
    Valor do desconto.

  - `data.purchases.other_expenses_value` (object)
    Valor total de outras despesas.

  - `data.purchases.total` (object)
    Valor total da compra.

  - `data.purchases.notes` (string)
    Observações.
    Example: "my notes"

  - `data.purchases.shipping` (object)
    Dados do frete.

  - `data.purchases.shipping.pay_shipping` (boolean)
    Frete é pago?
    Example: true

  - `data.purchases.shipping.carrier` (object)
    Dados da transportadora.

  - `data.purchases.shipping.carrier.id` (integer)
    Id único da transportadora
    Example: 123

  - `data.purchases.shipping.carrier.name` (string)
    Nome da transportadora
    Example: "CPlug Logistics"

  - `data.purchases.shipping.shipping_value` (object)
    Valor do frete.

  - `data.purchases.status` (string)
    Status da compra.

Exemplo:
  - pending Aguardando.
  - received Entregue.
    Enum: "pending", "received"

  - `data.purchases.order_number` (string)
    Código do pedido de compra.
    Example: "code123"

  - `data.purchases.has_stock_movement_out` (boolean)
    Indica se a compra tem movimentação de estoque de saída.
    Example: true

  - `data.purchases.were_stock_movements_deleted` (boolean)
    Se as movimentações de estoque foram apagadas.

Nota: Este campo só aparece quando o registro está excluído (deleted=true).
    Example: true

  - `data.purchases.created_at` (string)
    Data da última criação.
    Example: "2020-01-01T09:00:00-03:00"

  - `data.purchases.updated_at` (string)
    Data da última atualização.
    Example: "2020-01-01T09:00:00-03:00"

  - `meta` (object)
    Representa as informações de Metadado da paginação da listagem.

  - `meta.current_page` (integer, required)
    Página atual na paginação.
    Example: 1

  - `meta.last_page` (integer, required)
    Quantidade total de páginas.
    Example: 10

  - `meta.per_page` (integer, required)
    Quantidade de resultados por página.
    Example: 20

  - `meta.total` (integer, required)
    Quantidade total de itens.
    Example: 200

## Response 400 fields (application/json):

  - `code` (string, required)
    Código de erro.
    Example: "missing_headers"

  - `message` (string)
    Descrição do erro.
    Example: "error message"

  - `meta` (array)
    Dados adicionais sobre o erro.

## Response 422 fields (application/json):

  - `code` (string, required)
    Código de erro.
    Example: "uneditable_entity"

  - `message` (string)
    Descrição do erro.
    Example: "description error"

  - `meta` (array)
    Dados adicionais sobre o erro.

  - `meta.field` (string, required)
    Nome do campo no qual existe um erro de validação.
    Example: "name"

  - `meta.validations` (array)

  - `meta.validations.type` (string, required)
    Tipo da validação aplicada.
    Example: "Required"

  - `meta.validations.value` (array)
    Tipo de valor aplicável (esse campo pode ser vazio).


## Response 401 fields

## Response 404 fields