# Cria uma nova compra

Cria uma nova compra.

Endpoint: POST /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

  - `Idempotency-Key` (string, required)
    UUID aleatório gerado por você. Nós utilizamos esse header para evitar duplicidade de registros, ou seja, caso você não tenha recebido a resposta de alguma requisição e mandar o mesmo UUID, nós não duplicaremos o registro.

## Request fields (application/json):

  - `supplier_id` (integer, required)
    ID único do fornecedor.

Você pode localizar os IDs dos fornecedores no _endpoint_ de [listagem de fornecedores](#tag/Suppliers/operation/get-suppliers).
    Example: 456

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

  - `items` (array, required)
    Lista de produtos desta compra.

  - `items.item_id` (integer)
    Id único do item
    Example: 123

  - `items.amount` (number)
    quantidade
    Example: 5

  - `items.unitary_cost_value` (object)
    Valor do custo unitário do item.

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

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

  - `items.total_value` (object)
    Valor total do item.

É a multiplicação da quantidade pelo valor unitário deste item.

Fórmula: total_value = amount * unitary_value

  - `items.unitary_sale_value` (object)
    Valor de venda do item. 

Só deve ser enviado caso queira alterar o preço de venda e se na configuração do ERP está habilitado esta opção.

  - `items.expiration_date` (string)
    Data de validado do item.
    Example: "2025-01-14"

  - `items.stock_id` (integer)
    ID único do estoque.

Você pode localizar o ID do estoque no _endpoint_ de [listagem de estoques](#tag/Stocks/operation/get-stocks).
    Example: 1234

  - `items.status_detail_id` (integer)
    ID único do detalhe do status.

Você pode localizar o ID do detalhe do status no _endpoint_ de 
[listagem de detalhes do status](#tag/Status/operation/get-status-details) com o filtro system_area_type=stock.
    Example: 37

  - `items.status_id` (integer)
    ID único do do status.

Você pode localizar o ID do status no _endpoint_ de [listagem de status](#tag/Status/operation/get-status).
    Example: 1

  - `items.arrival_forecast_date` (string)
    Previsão de entrega do item.
    Example: "2025-03-14"

  - `items.attributes` (array)
    Lista de atributos deste item nesta compra.

  - `items.attributes.attribute_id` (integer, required)
    ID único do atributo do item.
    Example: 2

  - `items.attributes.options` (array, required)
    Lista de opções de um atributo.

  - `items.attributes.options.option_id` (integer, required)
    Id único da opção
    Example: 123

  - `invoice` (object)
    Dados da nota fiscal.

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

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

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

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

  - `discount` (object)
    Valor do desconto.

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

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

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

  - `shipping` (object)
    Dados do frete.

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

  - `shipping.carrier_id` (integer)
    ID único da transportadora.
    Example: 1234

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

  - `payments` (array, required)
    Lista de pagamentos desta compra.

  - `payments.payment_method_id` (integer, required)
    ID único do método de pagamento.

Você pode localizar os IDs das formas de pagamento no _endpoint_ de [listagem de formas de pagamento](#tag/Payments/operation/get-payments).
    Example: 1

  - `payments.total_value` (object, required)
    Valor total do pagamento

  - `payments.installments` (array, required)
    Lista de parcelamento.

  - `payments.installments.due_date` (string, required)
    Data do vencimento da parcela.
    Example: "2025-01-30"

  - `payments.installments.value` (object, required)
    Valor da parcela

  - `payments.installments.is_paid` (boolean)
    Está paga esta parcela?

  - `payments.installments.notes` (string)
    Observação da parcela
    Example: "pagamento à vista"

  - `payments.installments.account_plan_descriptions` (array)
    Lista de planos de contas associados à movimentação financeira.

  - `payments.installments.account_plan_descriptions.account_plan_id` (integer)
    ID do plano de contas.
    Example: 1

  - `payments.installments.account_plan_descriptions.center_cost_id` (integer)
    Id único do centro de custo.

Você pode localizar os IDs dos centro de custos no _endpoint_ de [listagem de centro deo custo](#tag/CostCenters/operation/get-cost-centers).
    Example: 1

  - `payments.installments.account_plan_descriptions.value` (object)
    Valor associado ao centro de custo.

  - `payments.bank_account_id` (number)
    ID único da conta bancária

Você pode localizar os IDs das contas bancárias no _endpoint_ de [listagem de contas bancárias](#tag/BankAccounts/operation/get-bank-accounts).
    Example: 5

  - `payments.card_brand_id` (integer)
    ID único da bandeira do cartão de crédito.

Você pode localizar os IDs das bandeiras do cartão de crédito no _endpoint_ de [listagem de bandeiras de cartão](#tag/CardBrands/operation/get-cards-brands).

Obs: Obrigatório quando o método de pagamento for cartão.
    Example: 1

## Response 201 fields (application/json):

  - `data` (object)
    Representa uma compra com detalhes.

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

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

  - `data.items` (array)
    Lista de produtos desta compra.

  - `data.items.id` (integer)
    Id único da relação entre o item e a compra

Obs: Se estiver atualizando este item, este campo deve ser enviado.
    Example: 123

  - `data.items.item_id` (integer)
    Id único do item
    Example: 456

  - `data.items.amount` (number)
    quantidade
    Example: 5

  - `data.items.unitary_cost_value` (object)
    Valor do custo unitário do item.

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

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

  - `data.items.total_value` (object)
    Valor total do item.

É a multiplicação da quantidade pelo valor unitário deste item.

Fórmula: total_value = amount * unitary_value

  - `data.items.unitary_sale_value` (object)
    Valor de venda do item. 

Só deve ser enviado caso queira alterar o preço de venda e se na configuração do ERP está habilitado esta opção.

  - `data.items.expiration_date` (string)
    Data de validado do item.
    Example: "2025-01-14"

  - `data.items.stock` (object)
    Representa um estoque.

  - `data.items.stock.id` (integer)
    ID único do estoque
    Example: 1

  - `data.items.stock.name` (string)
    Nome do estoque
    Example: "Estoque padrão"

  - `data.items.status` (object)
    Representa um status.

  - `data.items.status.id` (integer)
    ID único do status
    Example: 1

  - `data.items.status.name` (string)
    Nome do status
    Example: "Aberto"

  - `data.items.status_detail` (object)
    Representa o detalhe do status.

  - `data.items.status_detail.id` (integer)
    ID único do detalhe do status
    Example: 37

  - `data.items.status_detail.name` (string)
    Nome do detalhe do status
    Example: "Aguardando fornecedor"

  - `data.items.arrival_forecast_date` (string)
    Previsão de entrega do item.
    Example: "2025-03-14"

  - `data.items.attributes` (array)
    Lista de atributos deste item nesta compra.

  - `data.items.attributes.attribute_id` (integer)
    ID único do atributo do item.
    Example: 2

  - `data.items.attributes.name` (string)
    Nome do atributo do item.
    Example: "Cor"

  - `data.items.attributes.options` (array)
    Lista de opções de um atributo.

  - `data.items.attributes.options.id` (integer)
    Id único da relação entre a opção e a compra.

Obs: Se estiver atualizando esta opção, este campo deve ser enviado.
    Example: 789

  - `data.items.attributes.options.option_id` (integer)
    Id único da opção
    Example: 147

  - `data.items.attributes.options.name` (string)
    Nome da opção.
    Example: "Branca"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `data.payments` (array)
    Lista de pagamentos.

  - `data.payments.id` (integer)
    ID único da relação do método de pagamento com a compra.

Obs: Se estiver atualizando este pagamento, este campo dever ser enviado.
    Example: 1

  - `data.payments.payment_method` (object)
    Representa um Método de pagamento.

  - `data.payments.payment_method.id` (integer, required)
    Identificador único da um método de pagamento.
    Example: 123

  - `data.payments.payment_method.name` (string, required)
    Nome do método de pagamento.
    Example: "Dinheiro"

  - `data.payments.payment_method.fiscal_code` (string, required)
    Código fiscal a ser informado na nota fiscal.

Exemplo:

- 01: Dinheiro
- 02: Cheque
- 03: Cartão de Crédito
- 04: Cartão de Débito
- 05: Crédito de Loja
- 10: Vale Alimentação
- 11: Vale Refeição
- 12: Vale Presente
- 13: Vale Combustível
- 14: Duplicata Mercantil
- 15: Boleto Bancário
- 16: Depósito Bancário
- 17: Pagamento Instantâneo (PIX)
- 18: Transferência bancária, Carteira Digital
- 19: Programa de fidelidade, Cashback, Crédito Virtual
- 90: Sem Pagamento
- 99: Outros
    Enum: "01", "02", "03", "04", "05", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "90", "99"

  - `data.payments.payment_method.is_editable` (boolean)
    Indica se o método de pagamento pode ser editável ou não.
    Example: true

  - `data.payments.payment_method.allow_installment` (boolean)
    Indica se o método de pagamento permite ou não o parcelamento.
    Example: true

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

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

  - `data.payments.total_value` (object, required)
    Valor total do pagamento

  - `data.payments.installments` (array, required)
    Lista de parcelamento.

  - `data.payments.installments.id` (integer)
    ID único do relacionamento da parcela com o pagamento.

Obs: Se estiver atualizando esta parcela, este campo deve ser enviado.
    Example: 258

  - `data.payments.installments.due_date` (string, required)
    Data do vencimento da parcela.
    Example: "2025-01-30"

  - `data.payments.installments.value` (object, required)
    Valor da parcela

  - `data.payments.installments.is_paid` (boolean)
    Está paga esta parcela?

  - `data.payments.installments.notes` (string)
    Observação da parcela
    Example: "pagamento à vista"

  - `data.payments.installments.account_plan_descriptions` (array)
    Lista de planos de contas associados à movimentação financeira.

  - `data.payments.installments.account_plan_descriptions.account_plan` (object)
    Dados do plano de conta.

  - `data.payments.installments.account_plan_descriptions.account_plan.id` (integer)
    Identificador único do plano de conta.
    Example: 123

  - `data.payments.installments.account_plan_descriptions.account_plan.name` (string)
    Nome do plano de conta.
    Example: "Plano de conta 1"

  - `data.payments.installments.account_plan_descriptions.account_plan.financial_group` (object)
    Representa um grupo financeiro.

  - `data.payments.installments.account_plan_descriptions.account_plan.financial_group.id` (integer)
    Identificador único do grupo financeiro.
    Example: 123

  - `data.payments.installments.account_plan_descriptions.account_plan.financial_group.name` (string)
    Nome do grupo financeiro.
    Example: "Receitas Operacionais"

  - `data.payments.installments.account_plan_descriptions.account_plan.financial_group.type` (string)
    Tipo da movimentação financeira.

Exemplo:

  - income: Receita
  - expense: Despesa
    Enum: "income", "expense"

  - `data.payments.installments.account_plan_descriptions.account_plan.financial_group.order` (integer)
    Ordem que este grupo será ordenado.
    Example: 1

  - `data.payments.installments.account_plan_descriptions.cost_center` (object)
    Dados do centro de custo associado a uma movimentação financeira.

  - `data.payments.installments.account_plan_descriptions.cost_center.id` (integer)
    Identificador único do centro de custo.
    Example: 123

  - `data.payments.installments.account_plan_descriptions.cost_center.name` (string)
    Nome do centro de custo.
    Example: "Centro de custo 1"

  - `data.payments.installments.account_plan_descriptions.value` (object, required)
    Valor referente ao plano de conta na movimentação financeira.

Exemplo: 
- Se uma movimentação financeira for de R$ 100,00, o valor do plano de conta seria 100.00.
- Se uma movimentação financeira for de R$ 100,00, houver 2 planos de contas divididos em 50% entre eles, então o valor do plano de contas seria 50.00 para cada.

  - `data.payments.bank_account` (object)
    Dados da conta bancária.

  - `data.payments.bank_account.id` (integer)
    Id único da conta bancária
    Example: 123

  - `data.payments.bank_account.name` (string)
    Nome da conta bancária
    Example: "CPlug Bank"

  - `data.payments.card_brand` (object)
    Dados da bandeira do cartão.

  - `data.payments.card_brand.id` (integer)
    Id único da bandeira do cartão
    Example: 123

  - `data.payments.card_brand.name` (string)
    Nome da bandeira do cartão
    Example: "CPlug Card"

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

  - `data.files` (array)
    Lista de arquivos.

  - `data.files.id` (integer)
    Identificador do arquivo de compra.
    Example: 1

  - `data.files.name` (string)
    Nome do arquivo.
    Example: "arquivo.csv"

  - `data.files.url` (string)
    URL do arquivo.
    Example: "https://example.com/purchase-2025-01-15.pdf"

  - `data.files.mime_type` (string)
    Tipo MIME do arquivo.
    Example: "text/csv"

  - `data.files.created_at` (string)
    Data de criação do arquivo.
    Example: "2025-01-15T15:30:00Z"

  - `data.files.updated_at` (string)
    Data de última atualização do arquivo.
    Example: "2025-01-15T15:35:00Z"

## 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