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

# Referência

> Requisição, Ordem e Pedido de Compra

O módulo de Compras segue um fluxo em três etapas: uma área solicita a compra (**Requisição**), a compra é aprovada e organizada internamente (**Ordem**) e, por fim, é formalizada junto ao fornecedor (**Pedido**).

<img
  src="https://mintlify.s3.us-west-1.amazonaws.com/abacatepay/images/payment-checkout-placeholder.png"
  alt="Fluxo de Compras: Requisição → Ordem → Pedido"
  style={{
maxWidth: "100%",
height: "auto",
margin: "24px 0",
borderRadius: "8px"
}}
/>

## Requisição de Compra

Use `/compras/requisicao/create` para abrir uma requisição. O número é gerado automaticamente.

<Card title="Campos obrigatórios" horizontal>
  `codigoDaFilial`, `codigoDoTipoDeCompra`, `codigoDoColaborador` e `itens` (com ao menos 1 item).
</Card>

**Exemplo:**

```json theme={null}
POST /v2/compras/requisicao
{
  "codigoDaFilial": 1,           // obrigatório
  "codigoDoTipoDeCompra": 2,     // obrigatório
  "codigoDoColaborador": 15,     // obrigatório - solicitante
  "codigoDoMotivo": 3,           // opcional
  "itens": [                     // obrigatório - ao menos 1 item
    {
      "idProduto": 0,                              // 0 = item avulso
      "descricaoDoProduto": "Parafuso sextavado M8", // obrigatório quando idProduto = 0
      "quantidade": 100                              // obrigatório, maior que zero
    }
  ]
}
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "data": {
    "numeroDaRequisicao": 5321,
    "codigoDaFilial": 1,
    "codigoDoColaborador": 15,
    "itens": [
      {
        "seq": 1,
        "descricaoDoProduto": "Parafuso sextavado M8",
        "quantidade": 100,
        "quantidadeAprovada": 0
      }
    ]
  }
}
```

<Tip>
  Campos obrigatórios ausentes ou inválidos retornam `400` com o detalhe em `notifications`/`errors`.
</Tip>

## Ordem de Compra

Depois de aprovada, a requisição dá origem a uma Ordem de Compra (`POST /v2/compras/ordem`), com a mesma estrutura de cabeçalho e itens da Requisição. É nesta etapa que a compra é organizada internamente antes de ser enviada a um fornecedor.

## Pedido de Compra

O `POST /v2/compras/pedido` formaliza a compra junto a um fornecedor específico.

<Warning>
  Diferente dos demais endpoints de escrita da API, este **sempre responde `200`**, mesmo quando a operação falha por regra de negócio. Verifique `data.notifications`: vazio indica sucesso (com o pedido em `data.payload`); não vazio indica falha.
</Warning>

<Note>
  O `data.payload` de retorno usa um formato **diferente** do retornado nas rotas de consulta (GET) — não assuma a mesma estrutura.
</Note>

**Exemplo:**

```json theme={null}
POST /v2/compras/pedido
{
  "codigoDaFilial": 1,
  "codigoDoFornecedor": 88,
  "itens": [
    { "idProduto": 1234, "quantidade": 100, "valorUnitario": 3.50 }
  ]
}
```

**Resposta (sucesso):**

```json theme={null}
{
  "success": true,
  "data": {
    "notifications": [],
    "payload": {
      "numeroPedido": 9012,
      "codigoDoFornecedor": 88
    }
  }
}
```

**Resposta (falha de regra de negócio, ainda com HTTP 200):**

```json theme={null}
{
  "success": true,
  "data": {
    "notifications": [
      { "key": "codigoDoFornecedor", "value": "Fornecedor inativo." }
    ],
    "payload": null
  }
}
```

## Planejamento orçamentário e cadastros de apoio

O **Planejamento Orçamentário** (`/v2/compras/planejamento`) permite definir limites de gasto por filial, centro de custo, item de lançamento e projeto em um dado período (ano/mês), servindo de referência para aprovação de requisições e ordens. Os **Tipos** e **Motivos de Compra** (`/v2/compras/gerenciamento/*`) são cadastros de apoio consultados ao abrir uma Requisição ou Ordem.