> For the complete documentation index, see [llms.txt](https://changelog.maino.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://changelog.maino.com.br/api-reference-maino/19.-ordens-de-compra.md).

# 19. 🛒 Ordens De Compra

**Ordens de Compra** Consulta das ordens de compra da empresa. A listagem devolve **todas** as ordens cadastradas, inclusive as criadas fora do fluxo de compras da tela — ou seja, sem cotação nem solicitação de compra vinculada. **Funcionalidades:**

* Listagem paginada com filtros por fornecedor, período de criação, número, descrição, referência, finalidade do produto, termo de busca e situação de arquivamento
* Consulta individual por identificador, com os itens e os vínculos da ordem

## Lista ordens de compra

> \*\*Lista as ordens de compra da empresa\*\*\
> \
> Retorna \*\*todas\*\* as ordens de compra da empresa autenticada, da mais recente para a mais\
> antiga, com paginação fixa de 100 registros por página. Diferente da tela de Fluxo de\
> Compras, a listagem \*\*não\*\* se restringe às ordens originadas de cotação ou solicitação de\
> compra — ordens criadas por qualquer caminho aparecem aqui.\
> \
> Os itens da ordem \*\*não\*\* vêm na listagem; use \`GET /ordem\_de\_compras/{id}\` para obtê-los.\
> \
> \*\*Filtros disponíveis (todos opcionais e combináveis):\*\*\
> \- \`fornecedor\_id\`: identificador do fornecedor, o mesmo usado em \`/stakeholders/{id}\`.\
> &#x20; Fornecedor inexistente devolve lista vazia, nunca a lista completa\
> \- \`termo\_de\_busca\`: busca parcial em número e descrição da ordem, razão social e nome\
> &#x20; fantasia do fornecedor, e nos códigos das referências vinculadas\
> \- \`data\_inicio\` / \`data\_fim\`: período de criação da ordem (formato \`AAAA-MM-DD\`)\
> \- \`numero\`, \`descricao\`, \`referencia\`: busca parcial (case-insensitive)\
> \- \`finalidade\_produto\_id\`: identificador da finalidade do produto\
> \- \`arquivada\`: \`true\` devolve só as arquivadas, \`false\` só as ativas. \*\*Omitido devolve as\
> &#x20; duas\*\* — a listagem não esconde ordens arquivadas por padrão\
> \- \`page\`: número da página (padrão: 1; 100 registros por página, fixo)

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"19. 🛒 Ordens de Compra","description":"**Ordens de Compra**\nConsulta das ordens de compra da empresa. A listagem devolve **todas** as ordens\ncadastradas, inclusive as criadas fora do fluxo de compras da tela — ou seja, sem\ncotação nem solicitação de compra vinculada.\n**Funcionalidades:**\n- Listagem paginada com filtros por fornecedor, período de criação, número, descrição,\n  referência, finalidade do produto, termo de busca e situação de arquivamento\n- Consulta individual por identificador, com os itens e os vínculos da ordem"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/ordem_de_compras":{"get":{"summary":"Lista ordens de compra","tags":["19. 🛒 Ordens de Compra"],"description":"**Lista as ordens de compra da empresa**\n\nRetorna **todas** as ordens de compra da empresa autenticada, da mais recente para a mais\nantiga, com paginação fixa de 100 registros por página. Diferente da tela de Fluxo de\nCompras, a listagem **não** se restringe às ordens originadas de cotação ou solicitação de\ncompra — ordens criadas por qualquer caminho aparecem aqui.\n\nOs itens da ordem **não** vêm na listagem; use `GET /ordem_de_compras/{id}` para obtê-los.\n\n**Filtros disponíveis (todos opcionais e combináveis):**\n- `fornecedor_id`: identificador do fornecedor, o mesmo usado em `/stakeholders/{id}`.\n  Fornecedor inexistente devolve lista vazia, nunca a lista completa\n- `termo_de_busca`: busca parcial em número e descrição da ordem, razão social e nome\n  fantasia do fornecedor, e nos códigos das referências vinculadas\n- `data_inicio` / `data_fim`: período de criação da ordem (formato `AAAA-MM-DD`)\n- `numero`, `descricao`, `referencia`: busca parcial (case-insensitive)\n- `finalidade_produto_id`: identificador da finalidade do produto\n- `arquivada`: `true` devolve só as arquivadas, `false` só as ativas. **Omitido devolve as\n  duas** — a listagem não esconde ordens arquivadas por padrão\n- `page`: número da página (padrão: 1; 100 registros por página, fixo)","parameters":[{"name":"fornecedor_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Identificador do fornecedor (mesmo id de /stakeholders)","required":false},{"name":"termo_de_busca","in":"query","schema":{"type":"string"},"description":"Busca parcial em número, descrição, fornecedor e referências","required":false},{"name":"data_inicio","in":"query","schema":{"type":"string","format":"date"},"description":"Data inicial de criação (>=), no formato AAAA-MM-DD","required":false},{"name":"data_fim","in":"query","schema":{"type":"string","format":"date"},"description":"Data final de criação (<=), no formato AAAA-MM-DD","required":false},{"name":"numero","in":"query","schema":{"type":"string"},"description":"Busca parcial no número da ordem","required":false},{"name":"descricao","in":"query","schema":{"type":"string"},"description":"Busca parcial na descrição da ordem","required":false},{"name":"referencia","in":"query","schema":{"type":"string"},"description":"Busca parcial no número do pedido, da exportação ou no código da produção","required":false},{"name":"finalidade_produto_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Identificador da finalidade do produto","required":false},{"name":"arquivada","in":"query","schema":{"type":"boolean"},"description":"Omitido devolve arquivadas e ativas; true ou false restringe","required":false},{"name":"page","in":"query","schema":{"type":"integer"},"description":"Número da página (padrão: 1; 100 registros por página)","required":false}],"responses":{"200":{"description":"Lista de ordens de compra","content":{"application/json":{"schema":{"type":"object","properties":{"ordem_de_compras":{"type":"array","description":"Ordens de compra da página","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador público da ordem de compra"},"numero":{"type":"string","nullable":true,"description":"Número da ordem de compra"},"descricao":{"type":"string","nullable":true,"description":"Descrição da ordem"},"observacoes":{"type":"string","nullable":true,"description":"Observações internas"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento acordada"},"sugestao_de_entrega":{"type":"string","format":"date","nullable":true,"description":"Data sugerida de entrega"},"cambio":{"type":"number","format":"float","nullable":true,"description":"Taxa de câmbio da ordem"},"arquivada":{"type":"boolean","description":"Indica se a ordem está arquivada"},"valor_total":{"type":"number","format":"float","description":"Soma de pu × quantidade dos itens"},"criada_em":{"type":"string","format":"datetime","description":"Data e hora de criação"},"atualizada_em":{"type":"string","format":"datetime","description":"Data e hora da última alteração"},"fornecedor":{"type":"object","nullable":true,"description":"Fornecedor da ordem de compra. O id é o mesmo aceito por GET /stakeholders/{id}","properties":{"id":{"type":"string","format":"uuid","description":"Identificador público do fornecedor"},"razao_social":{"type":"string","nullable":true,"description":"Razão social"},"nome_fantasia":{"type":"string","nullable":true,"description":"Nome fantasia"}}},"moeda":{"type":"object","nullable":true,"description":"Moeda da ordem de compra. Identificada pelo código ISO, que é a chave natural estável","properties":{"codigo_iso":{"type":"string","nullable":true,"description":"Código ISO da moeda"},"descricao":{"type":"string","nullable":true,"description":"Nome da moeda"}}},"finalidade_produto":{"type":"object","nullable":true,"description":"Finalidade do produto associada à ordem de compra","properties":{"id":{"type":"string","format":"uuid","description":"Identificador da finalidade"},"codigo":{"type":"string","nullable":true,"description":"Código da finalidade"},"descricao":{"type":"string","nullable":true,"description":"Descrição da finalidade"}}}}}},"pagination":{"type":"object","description":"Metadados de paginação. As chaves de página só aparecem quando existem","properties":{"total":{"type":"integer","description":"Total de ordens que casam com os filtros"},"previous_page":{"type":"string","description":"URL da página anterior"},"next_page":{"type":"string","description":"URL da próxima página"}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"422":{"description":"Filtro com valor malformado","content":{"application/json":{"schema":{"type":"object","description":"Erros de validação no formato JSON Pointer","properties":{"errors":{"type":"object","description":"Cada chave é um JSON Pointer para o filtro recusado"}}}}}}}}}}}
```

## Cria ordem de compra

> \*\*Cria uma ordem de compra com seus itens\*\*\
> \
> Cria a ordem para a empresa autenticada e devolve o cadastro completo, com a \*\*mesma\
> estrutura\*\* do \`GET /ordem\_de\_compras/{id}\`. Obrigatórios: \`descricao\`, \`fornecedor\_id\` e\
> ao menos um item em \`itens\`.\
> \
> \*\*Identificadores aceitos — os mesmos que os GETs publicam:\*\*\
> \- \`fornecedor\_id\`: o identificador de \`/stakeholders/{id}\`\
> \- \`produto\_id\` do item: o identificador inteiro de \`/produtos/{id}\`. Alternativamente,\
> &#x20; \`codigo\` do produto — nesse caso a busca considera apenas produtos \*\*ativos\*\*\
> \- \`moeda\`: o código ISO (ex: \`USD\`). Omitido, a ordem assume o real (\`BRL\`)\
> \- \`finalidade\_produto\_id\`: o identificador devolvido no bloco \`finalidade\_produto\`\
> \
> \*\*Número (\`numero\`):\*\* opcional. Omitido, o servidor gera o próximo número sequencial da\
> empresa. Informado e já usado por outra ordem da empresa, devolve \*\*422\*\* em \`/numero\`.\
> \
> \*\*Descrição:\*\* é única por empresa. Descrição repetida devolve \*\*422\*\* em \`/descricao\`.\
> \
> \*\*Criação é atômica:\*\* um item inválido no meio de itens válidos recusa a requisição\
> inteira — nenhuma ordem, item ou solicitação de compra é gravada.\
> \
> \*\*Solicitação de compra automática:\*\* junto com a ordem, o sistema grava a solicitação de\
> compra correspondente (numerada \`ODC-\<numero>\`, já finalizada), o mesmo que a importação\
> por planilha faz. É ela que torna a ordem visível na tela de Fluxo de Compras e faz o\
> vínculo com NF-e de terceiros \*\*casar\*\* os itens em vez de duplicá-los.\
> \
> \*\*Erros (422):\*\* saem no formato JSON Pointer. Erro de item é identificado pelo \*\*índice\*\*\
> no array — \`/itens/0/produto\_id\`, \`/itens/1/quantidade\`.\
> \
> Produto, fornecedor ou finalidade de \*\*outra empresa\*\* são tratados como inexistentes:\
> devolvem \*\*422\*\* no ponteiro do campo, nunca 404 nem 403.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"19. 🛒 Ordens de Compra","description":"**Ordens de Compra**\nConsulta das ordens de compra da empresa. A listagem devolve **todas** as ordens\ncadastradas, inclusive as criadas fora do fluxo de compras da tela — ou seja, sem\ncotação nem solicitação de compra vinculada.\n**Funcionalidades:**\n- Listagem paginada com filtros por fornecedor, período de criação, número, descrição,\n  referência, finalidade do produto, termo de busca e situação de arquivamento\n- Consulta individual por identificador, com os itens e os vínculos da ordem"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/ordem_de_compras":{"post":{"summary":"Cria ordem de compra","tags":["19. 🛒 Ordens de Compra"],"description":"**Cria uma ordem de compra com seus itens**\n\nCria a ordem para a empresa autenticada e devolve o cadastro completo, com a **mesma\nestrutura** do `GET /ordem_de_compras/{id}`. Obrigatórios: `descricao`, `fornecedor_id` e\nao menos um item em `itens`.\n\n**Identificadores aceitos — os mesmos que os GETs publicam:**\n- `fornecedor_id`: o identificador de `/stakeholders/{id}`\n- `produto_id` do item: o identificador inteiro de `/produtos/{id}`. Alternativamente,\n  `codigo` do produto — nesse caso a busca considera apenas produtos **ativos**\n- `moeda`: o código ISO (ex: `USD`). Omitido, a ordem assume o real (`BRL`)\n- `finalidade_produto_id`: o identificador devolvido no bloco `finalidade_produto`\n\n**Número (`numero`):** opcional. Omitido, o servidor gera o próximo número sequencial da\nempresa. Informado e já usado por outra ordem da empresa, devolve **422** em `/numero`.\n\n**Descrição:** é única por empresa. Descrição repetida devolve **422** em `/descricao`.\n\n**Criação é atômica:** um item inválido no meio de itens válidos recusa a requisição\ninteira — nenhuma ordem, item ou solicitação de compra é gravada.\n\n**Solicitação de compra automática:** junto com a ordem, o sistema grava a solicitação de\ncompra correspondente (numerada `ODC-<numero>`, já finalizada), o mesmo que a importação\npor planilha faz. É ela que torna a ordem visível na tela de Fluxo de Compras e faz o\nvínculo com NF-e de terceiros **casar** os itens em vez de duplicá-los.\n\n**Erros (422):** saem no formato JSON Pointer. Erro de item é identificado pelo **índice**\nno array — `/itens/0/produto_id`, `/itens/1/quantidade`.\n\nProduto, fornecedor ou finalidade de **outra empresa** são tratados como inexistentes:\ndevolvem **422** no ponteiro do campo, nunca 404 nem 403.","parameters":[],"responses":{"201":{"description":"Ordem de compra criada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador público da ordem de compra"},"numero":{"type":"string","nullable":true,"description":"Número da ordem de compra"},"descricao":{"type":"string","nullable":true,"description":"Descrição da ordem"},"observacoes":{"type":"string","nullable":true,"description":"Observações internas"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento acordada"},"sugestao_de_entrega":{"type":"string","format":"date","nullable":true,"description":"Data sugerida de entrega"},"cambio":{"type":"number","format":"float","nullable":true,"description":"Taxa de câmbio da ordem"},"arquivada":{"type":"boolean","description":"Indica se a ordem está arquivada"},"valor_total":{"type":"number","format":"float","description":"Soma de pu × quantidade dos itens"},"criada_em":{"type":"string","format":"datetime","description":"Data e hora de criação"},"atualizada_em":{"type":"string","format":"datetime","description":"Data e hora da última alteração"},"fornecedor":{"type":"object","nullable":true,"description":"Fornecedor da ordem de compra. O id é o mesmo aceito por GET /stakeholders/{id}","properties":{"id":{"type":"string","format":"uuid","description":"Identificador público do fornecedor"},"razao_social":{"type":"string","nullable":true,"description":"Razão social"},"nome_fantasia":{"type":"string","nullable":true,"description":"Nome fantasia"}}},"moeda":{"type":"object","nullable":true,"description":"Moeda da ordem de compra. Identificada pelo código ISO, que é a chave natural estável","properties":{"codigo_iso":{"type":"string","nullable":true,"description":"Código ISO da moeda"},"descricao":{"type":"string","nullable":true,"description":"Nome da moeda"}}},"finalidade_produto":{"type":"object","nullable":true,"description":"Finalidade do produto associada à ordem de compra","properties":{"id":{"type":"string","format":"uuid","description":"Identificador da finalidade"},"codigo":{"type":"string","nullable":true,"description":"Código da finalidade"},"descricao":{"type":"string","nullable":true,"description":"Descrição da finalidade"}}},"itens":{"type":"array","description":"Itens da ordem de compra","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identificador do item da ordem de compra"},"quantidade":{"type":"number","format":"float","description":"Quantidade comprada"},"pu":{"type":"number","format":"float","description":"Preço unitário"},"valor_total":{"type":"number","format":"float","description":"pu × quantidade"},"produto":{"type":"object","nullable":true,"description":"Produto de estoque do item. O id é o mesmo aceito por GET /produtos/{id}","properties":{"id":{"type":"integer","description":"Identificador do produto de estoque"},"codigo":{"type":"string","nullable":true,"description":"Código do produto"},"descricao":{"type":"string","nullable":true,"description":"Descrição do produto"},"unidade_de_medida":{"type":"string","nullable":true,"description":"Código da unidade"}}}}}},"vinculos":{"type":"object","description":"Vínculos da ordem com outros documentos. Indicam se a ordem pode ser excluída com segurança","properties":{"possui_processo":{"type":"boolean","description":"True quando há processo vinculado, seja no nível da ordem ou no nível de algum item"},"possui_nfe_de_terceiro":{"type":"boolean","description":"True quando há NF-e de terceiro vinculada"},"possui_nota_fiscal":{"type":"boolean","description":"True quando há nota fiscal vinculada"},"possui_conta_a_pagar":{"type":"boolean","description":"True quando há conta a pagar vinculada"},"possui_fatura":{"type":"boolean","description":"True quando há fatura vinculada"}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"422":{"description":"Payload recusado","content":{"application/json":{"schema":{"type":"object","description":"Erros de validação no formato JSON Pointer","properties":{"errors":{"type":"object","description":"Cada chave é um JSON Pointer para o campo recusado. Itens são identificados pelo índice"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ordem_de_compra":{"type":"object","properties":{"descricao":{"type":"string","description":"Descrição da ordem, única na empresa"},"numero":{"type":"string","nullable":true,"description":"Número da ordem. Omitido, o servidor gera o próximo número da empresa"},"observacoes":{"type":"string","nullable":true,"description":"Observações internas"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento acordada"},"sugestao_de_entrega":{"type":"string","format":"date","nullable":true,"description":"Data sugerida de entrega, no formato AAAA-MM-DD"},"cambio":{"type":"number","format":"float","nullable":true,"description":"Taxa de câmbio. Omitida, assume a taxa cadastrada na moeda"},"fornecedor_id":{"type":"string","format":"uuid","description":"Identificador do fornecedor, o mesmo usado em /stakeholders/{id}"},"moeda":{"type":"string","nullable":true,"description":"Código ISO da moeda. Omitido, assume o real (BRL)"},"finalidade_produto_id":{"type":"string","format":"uuid","nullable":true,"description":"Identificador da finalidade do produto"},"itens":{"type":"array","description":"Itens da ordem. Ao menos um item é obrigatório","items":{"type":"object","description":"Item da ordem. Informe `produto_id` **ou** `codigo` — um dos dois é obrigatório","properties":{"produto_id":{"type":"integer","nullable":true,"description":"Identificador do produto de estoque, o mesmo devolvido por GET /produtos"},"codigo":{"type":"string","nullable":true,"description":"Código do produto de estoque. Alternativa a produto_id; considera só produtos ativos"},"quantidade":{"type":"number","format":"float","description":"Quantidade comprada, maior que zero"},"pu":{"type":"number","format":"float","description":"Preço unitário, maior que zero"}},"required":["quantidade","pu"]}}},"required":["descricao","fornecedor_id","itens"]}},"required":["ordem_de_compra"]}}},"required":true}}}}}
```

## Exibe ordem de compra

> \*\*Consulta uma ordem de compra específica\*\*\
> \
> Retorna o cabeçalho da ordem, os itens com o produto de estoque de cada um, e os vínculos\
> da ordem com outros documentos.\
> \
> \*\*Sobre \`vinculos\`:\*\* os cinco campos são booleanos e indicam se a ordem está amarrada a\
> algum outro documento. \`possui\_processo\` considera \*\*tanto\*\* o vínculo no nível da ordem\
> quanto o vínculo no nível de item — uma ordem com apenas um item alocado a um processo já\
> devolve \`true\`. \`possui\_fatura\` também é uma trava da exclusão — exposto aqui para que o\
> integrador saiba de antemão por que um \`DELETE /ordem\_de\_compras/{id}\` pode ser recusado.\
> \
> Ordem de outra empresa devolve \`404\`, e não \`403\`, para não revelar que o registro existe.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"19. 🛒 Ordens de Compra","description":"**Ordens de Compra**\nConsulta das ordens de compra da empresa. A listagem devolve **todas** as ordens\ncadastradas, inclusive as criadas fora do fluxo de compras da tela — ou seja, sem\ncotação nem solicitação de compra vinculada.\n**Funcionalidades:**\n- Listagem paginada com filtros por fornecedor, período de criação, número, descrição,\n  referência, finalidade do produto, termo de busca e situação de arquivamento\n- Consulta individual por identificador, com os itens e os vínculos da ordem"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/ordem_de_compras/{id}":{"get":{"summary":"Exibe ordem de compra","tags":["19. 🛒 Ordens de Compra"],"description":"**Consulta uma ordem de compra específica**\n\nRetorna o cabeçalho da ordem, os itens com o produto de estoque de cada um, e os vínculos\nda ordem com outros documentos.\n\n**Sobre `vinculos`:** os cinco campos são booleanos e indicam se a ordem está amarrada a\nalgum outro documento. `possui_processo` considera **tanto** o vínculo no nível da ordem\nquanto o vínculo no nível de item — uma ordem com apenas um item alocado a um processo já\ndevolve `true`. `possui_fatura` também é uma trava da exclusão — exposto aqui para que o\nintegrador saiba de antemão por que um `DELETE /ordem_de_compras/{id}` pode ser recusado.\n\nOrdem de outra empresa devolve `404`, e não `403`, para não revelar que o registro existe.","responses":{"200":{"description":"Ordem de compra encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador público da ordem de compra"},"numero":{"type":"string","nullable":true,"description":"Número da ordem de compra"},"descricao":{"type":"string","nullable":true,"description":"Descrição da ordem"},"observacoes":{"type":"string","nullable":true,"description":"Observações internas"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento acordada"},"sugestao_de_entrega":{"type":"string","format":"date","nullable":true,"description":"Data sugerida de entrega"},"cambio":{"type":"number","format":"float","nullable":true,"description":"Taxa de câmbio da ordem"},"arquivada":{"type":"boolean","description":"Indica se a ordem está arquivada"},"valor_total":{"type":"number","format":"float","description":"Soma de pu × quantidade dos itens"},"criada_em":{"type":"string","format":"datetime","description":"Data e hora de criação"},"atualizada_em":{"type":"string","format":"datetime","description":"Data e hora da última alteração"},"fornecedor":{"type":"object","nullable":true,"description":"Fornecedor da ordem de compra. O id é o mesmo aceito por GET /stakeholders/{id}","properties":{"id":{"type":"string","format":"uuid","description":"Identificador público do fornecedor"},"razao_social":{"type":"string","nullable":true,"description":"Razão social"},"nome_fantasia":{"type":"string","nullable":true,"description":"Nome fantasia"}}},"moeda":{"type":"object","nullable":true,"description":"Moeda da ordem de compra. Identificada pelo código ISO, que é a chave natural estável","properties":{"codigo_iso":{"type":"string","nullable":true,"description":"Código ISO da moeda"},"descricao":{"type":"string","nullable":true,"description":"Nome da moeda"}}},"finalidade_produto":{"type":"object","nullable":true,"description":"Finalidade do produto associada à ordem de compra","properties":{"id":{"type":"string","format":"uuid","description":"Identificador da finalidade"},"codigo":{"type":"string","nullable":true,"description":"Código da finalidade"},"descricao":{"type":"string","nullable":true,"description":"Descrição da finalidade"}}},"itens":{"type":"array","description":"Itens da ordem de compra","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identificador do item da ordem de compra"},"quantidade":{"type":"number","format":"float","description":"Quantidade comprada"},"pu":{"type":"number","format":"float","description":"Preço unitário"},"valor_total":{"type":"number","format":"float","description":"pu × quantidade"},"produto":{"type":"object","nullable":true,"description":"Produto de estoque do item. O id é o mesmo aceito por GET /produtos/{id}","properties":{"id":{"type":"integer","description":"Identificador do produto de estoque"},"codigo":{"type":"string","nullable":true,"description":"Código do produto"},"descricao":{"type":"string","nullable":true,"description":"Descrição do produto"},"unidade_de_medida":{"type":"string","nullable":true,"description":"Código da unidade"}}}}}},"vinculos":{"type":"object","description":"Vínculos da ordem com outros documentos. Indicam se a ordem pode ser excluída com segurança","properties":{"possui_processo":{"type":"boolean","description":"True quando há processo vinculado, seja no nível da ordem ou no nível de algum item"},"possui_nfe_de_terceiro":{"type":"boolean","description":"True quando há NF-e de terceiro vinculada"},"possui_nota_fiscal":{"type":"boolean","description":"True quando há nota fiscal vinculada"},"possui_conta_a_pagar":{"type":"boolean","description":"True quando há conta a pagar vinculada"},"possui_fatura":{"type":"boolean","description":"True quando há fatura vinculada"}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Ordem de compra não encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Exclui ordem de compra

> \*\*Exclui uma ordem de compra, com todos os seus itens\*\*\
> \
> A exclusão é recusada quando a ordem tem qualquer vínculo com outro documento: NF-e de\
> terceiro, nota fiscal, processo de importação (no nível da ordem \*\*ou\*\* no nível de\
> algum item), conta a pagar ou fatura. Cada vínculo bloqueante encontrado é reportado, um\
> ponteiro por vez, na mesma requisição — o integrador não precisa de um round-trip por\
> impedimento.\
> \
> \*\*Não há exclusão parcial:\*\* havendo qualquer vínculo, nada é excluído.\
> \
> Ordem de outra empresa devolve \`404\`, e não \`403\`, para não revelar que o registro existe.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"19. 🛒 Ordens de Compra","description":"**Ordens de Compra**\nConsulta das ordens de compra da empresa. A listagem devolve **todas** as ordens\ncadastradas, inclusive as criadas fora do fluxo de compras da tela — ou seja, sem\ncotação nem solicitação de compra vinculada.\n**Funcionalidades:**\n- Listagem paginada com filtros por fornecedor, período de criação, número, descrição,\n  referência, finalidade do produto, termo de busca e situação de arquivamento\n- Consulta individual por identificador, com os itens e os vínculos da ordem"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/ordem_de_compras/{id}":{"delete":{"summary":"Exclui ordem de compra","tags":["19. 🛒 Ordens de Compra"],"description":"**Exclui uma ordem de compra, com todos os seus itens**\n\nA exclusão é recusada quando a ordem tem qualquer vínculo com outro documento: NF-e de\nterceiro, nota fiscal, processo de importação (no nível da ordem **ou** no nível de\nalgum item), conta a pagar ou fatura. Cada vínculo bloqueante encontrado é reportado, um\nponteiro por vez, na mesma requisição — o integrador não precisa de um round-trip por\nimpedimento.\n\n**Não há exclusão parcial:** havendo qualquer vínculo, nada é excluído.\n\nOrdem de outra empresa devolve `404`, e não `403`, para não revelar que o registro existe.","responses":{"200":{"description":"Ordem de compra excluída","content":{"application/json":{"schema":{"type":"object","properties":{"mensagem":{"type":"string"}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Ordem de compra não encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"422":{"description":"Ordem possui vínculo bloqueante","content":{"application/json":{"schema":{"type":"object","description":"Erros de validação no formato JSON Pointer","properties":{"errors":{"type":"object","description":"Cada chave é um JSON Pointer para o campo recusado. Itens são identificados pelo índice"}}}}}}}}}}}
```

## Edita ordem de compra

> \*\*Edita parcialmente uma ordem de compra e seus itens\*\*\
> \
> Só os campos presentes no corpo são alterados — campo omitido fica como está. A resposta\
> tem a \*\*mesma estrutura\*\* do \`GET /ordem\_de\_compras/{id}\`.\
> \
> \*\*Campos editáveis:\*\* \`descricao\`, \`observacoes\`, \`condicao\_pagamento\`,\
> \`sugestao\_de\_entrega\`, \`cambio\` e \`finalidade\_produto\_id\`.\
> \
> \*\*Campos que definem a origem da ordem são imutáveis\*\* e ignorados em silêncio se vierem\
> no corpo: \`numero\`, \`fornecedor\_id\`, \`moeda\` e os vínculos com solicitação de compra,\
> cotação e processo. Alterá-los quebraria o casamento de itens com NF-e de terceiros.\
> \
> \*\*Itens (\`itens\`) — a chave é opcional:\*\*\
> \- \*\*Omitida:\*\* os itens da ordem ficam intactos\
> \- \*\*Item com \`id\`:\*\* atualiza \`quantidade\` e/ou \`pu\` daquele item\
> \- \*\*Item com \`id\` e \`\_destroy: true\`:\*\* remove o item\
> \- \*\*Item sem \`id\`:\*\* cria um item novo, com as mesmas regras do POST (\`produto\_id\` \*\*ou\*\*\
> &#x20; \`codigo\`, ambos com \`quantidade\` e \`pu\` maiores que zero)\
> \- \*\*Lista vazia:\*\* nada acontece; a lista descreve operações, não o estado final\
> \
> \*\*Produto de item existente é imutável.\*\* Reenviar \`produto\_id\` ou \`codigo\` \*\*iguais\*\* aos\
> do item é aceito em silêncio — é o round-trip normal de quem lê com o GET e devolve o item\
> inteiro no PATCH. Informar um produto \*\*diferente\*\* devolve \*\*422\*\* no ponteiro do campo:\
> para trocar o produto, remova o item e adicione outro.\
> \
> \*\*Itens alocados a processo de importação são protegidos:\*\* remover um item com quantidade\
> alocada, ou reduzir sua quantidade abaixo do que já está alocado, devolve \*\*422\*\*. Nada é\
> desalocado em silêncio.\
> \
> \*\*Edição é atômica:\*\* um item recusado no meio de itens válidos recusa a requisição\
> inteira — nem o cabeçalho nem os demais itens são gravados.\
> \
> \*\*Erros (422):\*\* saem no formato JSON Pointer, com o item identificado pelo \*\*índice\*\* no\
> array — \`/itens/0/quantidade\`, \`/itens/1/id\`.\
> \
> Ordem de outra empresa devolve \`404\`, e não \`403\`, para não revelar que o registro existe.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"19. 🛒 Ordens de Compra","description":"**Ordens de Compra**\nConsulta das ordens de compra da empresa. A listagem devolve **todas** as ordens\ncadastradas, inclusive as criadas fora do fluxo de compras da tela — ou seja, sem\ncotação nem solicitação de compra vinculada.\n**Funcionalidades:**\n- Listagem paginada com filtros por fornecedor, período de criação, número, descrição,\n  referência, finalidade do produto, termo de busca e situação de arquivamento\n- Consulta individual por identificador, com os itens e os vínculos da ordem"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/ordem_de_compras/{id}":{"patch":{"summary":"Edita ordem de compra","tags":["19. 🛒 Ordens de Compra"],"description":"**Edita parcialmente uma ordem de compra e seus itens**\n\nSó os campos presentes no corpo são alterados — campo omitido fica como está. A resposta\ntem a **mesma estrutura** do `GET /ordem_de_compras/{id}`.\n\n**Campos editáveis:** `descricao`, `observacoes`, `condicao_pagamento`,\n`sugestao_de_entrega`, `cambio` e `finalidade_produto_id`.\n\n**Campos que definem a origem da ordem são imutáveis** e ignorados em silêncio se vierem\nno corpo: `numero`, `fornecedor_id`, `moeda` e os vínculos com solicitação de compra,\ncotação e processo. Alterá-los quebraria o casamento de itens com NF-e de terceiros.\n\n**Itens (`itens`) — a chave é opcional:**\n- **Omitida:** os itens da ordem ficam intactos\n- **Item com `id`:** atualiza `quantidade` e/ou `pu` daquele item\n- **Item com `id` e `_destroy: true`:** remove o item\n- **Item sem `id`:** cria um item novo, com as mesmas regras do POST (`produto_id` **ou**\n  `codigo`, ambos com `quantidade` e `pu` maiores que zero)\n- **Lista vazia:** nada acontece; a lista descreve operações, não o estado final\n\n**Produto de item existente é imutável.** Reenviar `produto_id` ou `codigo` **iguais** aos\ndo item é aceito em silêncio — é o round-trip normal de quem lê com o GET e devolve o item\ninteiro no PATCH. Informar um produto **diferente** devolve **422** no ponteiro do campo:\npara trocar o produto, remova o item e adicione outro.\n\n**Itens alocados a processo de importação são protegidos:** remover um item com quantidade\nalocada, ou reduzir sua quantidade abaixo do que já está alocado, devolve **422**. Nada é\ndesalocado em silêncio.\n\n**Edição é atômica:** um item recusado no meio de itens válidos recusa a requisição\ninteira — nem o cabeçalho nem os demais itens são gravados.\n\n**Erros (422):** saem no formato JSON Pointer, com o item identificado pelo **índice** no\narray — `/itens/0/quantidade`, `/itens/1/id`.\n\nOrdem de outra empresa devolve `404`, e não `403`, para não revelar que o registro existe.","parameters":[],"responses":{"200":{"description":"Ordem de compra editada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identificador público da ordem de compra"},"numero":{"type":"string","nullable":true,"description":"Número da ordem de compra"},"descricao":{"type":"string","nullable":true,"description":"Descrição da ordem"},"observacoes":{"type":"string","nullable":true,"description":"Observações internas"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento acordada"},"sugestao_de_entrega":{"type":"string","format":"date","nullable":true,"description":"Data sugerida de entrega"},"cambio":{"type":"number","format":"float","nullable":true,"description":"Taxa de câmbio da ordem"},"arquivada":{"type":"boolean","description":"Indica se a ordem está arquivada"},"valor_total":{"type":"number","format":"float","description":"Soma de pu × quantidade dos itens"},"criada_em":{"type":"string","format":"datetime","description":"Data e hora de criação"},"atualizada_em":{"type":"string","format":"datetime","description":"Data e hora da última alteração"},"fornecedor":{"type":"object","nullable":true,"description":"Fornecedor da ordem de compra. O id é o mesmo aceito por GET /stakeholders/{id}","properties":{"id":{"type":"string","format":"uuid","description":"Identificador público do fornecedor"},"razao_social":{"type":"string","nullable":true,"description":"Razão social"},"nome_fantasia":{"type":"string","nullable":true,"description":"Nome fantasia"}}},"moeda":{"type":"object","nullable":true,"description":"Moeda da ordem de compra. Identificada pelo código ISO, que é a chave natural estável","properties":{"codigo_iso":{"type":"string","nullable":true,"description":"Código ISO da moeda"},"descricao":{"type":"string","nullable":true,"description":"Nome da moeda"}}},"finalidade_produto":{"type":"object","nullable":true,"description":"Finalidade do produto associada à ordem de compra","properties":{"id":{"type":"string","format":"uuid","description":"Identificador da finalidade"},"codigo":{"type":"string","nullable":true,"description":"Código da finalidade"},"descricao":{"type":"string","nullable":true,"description":"Descrição da finalidade"}}},"itens":{"type":"array","description":"Itens da ordem de compra","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identificador do item da ordem de compra"},"quantidade":{"type":"number","format":"float","description":"Quantidade comprada"},"pu":{"type":"number","format":"float","description":"Preço unitário"},"valor_total":{"type":"number","format":"float","description":"pu × quantidade"},"produto":{"type":"object","nullable":true,"description":"Produto de estoque do item. O id é o mesmo aceito por GET /produtos/{id}","properties":{"id":{"type":"integer","description":"Identificador do produto de estoque"},"codigo":{"type":"string","nullable":true,"description":"Código do produto"},"descricao":{"type":"string","nullable":true,"description":"Descrição do produto"},"unidade_de_medida":{"type":"string","nullable":true,"description":"Código da unidade"}}}}}},"vinculos":{"type":"object","description":"Vínculos da ordem com outros documentos. Indicam se a ordem pode ser excluída com segurança","properties":{"possui_processo":{"type":"boolean","description":"True quando há processo vinculado, seja no nível da ordem ou no nível de algum item"},"possui_nfe_de_terceiro":{"type":"boolean","description":"True quando há NF-e de terceiro vinculada"},"possui_nota_fiscal":{"type":"boolean","description":"True quando há nota fiscal vinculada"},"possui_conta_a_pagar":{"type":"boolean","description":"True quando há conta a pagar vinculada"},"possui_fatura":{"type":"boolean","description":"True quando há fatura vinculada"}}}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Ordem de compra não encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"422":{"description":"Payload recusado","content":{"application/json":{"schema":{"type":"object","description":"Erros de validação no formato JSON Pointer","properties":{"errors":{"type":"object","description":"Cada chave é um JSON Pointer para o campo recusado. Itens são identificados pelo índice"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ordem_de_compra":{"type":"object","description":"Só os campos presentes são alterados. Campos de origem da ordem (numero, fornecedor_id, moeda) são ignorados","properties":{"descricao":{"type":"string","nullable":true,"description":"Descrição da ordem, única na empresa"},"observacoes":{"type":"string","nullable":true,"description":"Observações internas"},"condicao_pagamento":{"type":"string","nullable":true,"description":"Condição de pagamento acordada"},"sugestao_de_entrega":{"type":"string","format":"date","nullable":true,"description":"Data sugerida de entrega, no formato AAAA-MM-DD"},"cambio":{"type":"number","format":"float","nullable":true,"description":"Taxa de câmbio da ordem"},"finalidade_produto_id":{"type":"string","format":"uuid","nullable":true,"description":"Identificador da finalidade do produto"},"itens":{"type":"array","description":"Operações sobre os itens. Omitida, os itens ficam intactos","items":{"type":"object","description":"Operação sobre um item. Com `id` atualiza ou remove o item; sem `id` cria um item novo","properties":{"id":{"type":"integer","nullable":true,"description":"Identificador do item já existente na ordem. Omitido, o item é criado"},"produto_id":{"type":"integer","nullable":true,"description":"Produto do item. Em item novo, define o produto. Em item existente, só é aceito se for igual ao produto atual — trocar o produto devolve 422"},"codigo":{"type":"string","nullable":true,"description":"Código do produto. Mesma regra de produto_id: em item existente só é aceito se for o código do produto atual"},"quantidade":{"type":"number","format":"float","nullable":true,"description":"Quantidade comprada. Em item novo precisa ser maior que zero; em item existente aceita zero, mas nunca abaixo do que já está alocado em processo"},"pu":{"type":"number","format":"float","nullable":true,"description":"Preço unitário, maior que zero"},"_destroy":{"type":"boolean","nullable":true,"description":"Com `true` e `id` informado, remove o item. Item com quantidade alocada em processo não é removido: devolve 422"}}}}}}},"required":["ordem_de_compra"]}}},"required":true}}}}}
```
