Compras
Pedidos de compra e os itens de cada pedido. Exigem o recurso Pedidos de Compra no plano.
Pedidos de compra
Recurso do plano: Pedidos de Compra.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/purchase-orders | Lista com paginação |
GET | /external/v1/purchase-orders/:id | Busca um registro pelo ID |
POST | /external/v1/purchase-orders | Cria um registro |
PUT | /external/v1/purchase-orders/:id | Atualiza um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
curl -G "https://erp-api.ideros.api.br/external/v1/purchase-orders" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25"
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/purchase-orders/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
supplierId | string | Sim | ID de pessoa. |
buyerId | string | Sim | ID de usuário da empresa. |
workspaceId | string | Não | ID de workspace. |
businessUnitId | string | Não | ID de unidade de negócio. |
projectId | string | Não | ID de projeto. |
dealId | string | Não | ID de negócio. Vincula a ordem de compra a uma venda/serviço (Deal), de forma independente do projectId. |
requisitionId | string | Não | ID de requisição de compra. |
orderCode | string | Não | Código único da ordem de compra. Gerado automaticamente pelo sistema se omitido. |
title | string | Sim | Título da ordem de compra. |
description | string | Não | Descrição detalhada da ordem de compra. |
expectedDeliveryDate | string (data ISO 8601) | Não | Data esperada para entrega dos itens. |
notes | string | Não | Observações adicionais sobre a ordem de compra. |
totalAmount | number | Sim | Valor total da ordem de compra. |
paymentTerms | string | Não | Condições de pagamento da ordem de compra. |
deliveryTerms | string | Não | Condições de entrega da ordem de compra. |
warrantyTerms | string | Não | Termos de garantia dos itens. |
requiresApproval | boolean | Não | Pedir aprovação mesmo assim: força o fluxo de aprovação mesmo abaixo da trava de valor da empresa. Só tem efeito se houver fluxo de aprovação configurado para Pedidos de Compra. |
defaultPurchaseNature | enum | Não | Natureza (destinação) PADRÃO herdada pelos itens deste pedido de compra. Cada item pode ter natureza própria — esta é apenas a sugestão inicial. Valores: RESALE, INDUSTRIALIZATION, PACKAGING, SERVICE_MATERIAL_ICMS, SERVICE_MATERIAL_ISS, CONSUMPTION, FIXED_ASSET, FREE_SAMPLE, CONSIGNMENT_IN, TOLLING_IN, TOLLING_RETURN, TRANSFER_IN, RETURN_IN, SERVICE, OTHER. |
costCenterId | string | Não | ID de centro de custo. |
Atualizar
Envie no corpo só os campos que mudam, com os mesmos nomes da tabela de criação. Responde 200 com o registro atualizado. Registro de outra empresa responde 403; registro inexistente, 404.
Itens do pedido de compra
Itens podem ser listados, consultados e criados. Não há rota de atualização.
Recurso do plano: Pedidos de Compra.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/purchase-order-items | Lista com paginação |
GET | /external/v1/purchase-order-items/:id | Busca um registro pelo ID |
POST | /external/v1/purchase-order-items | Cria um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
Exemplo com filtro (o valor de relations vai codificado para URL; aqui ele aparece legível: {"where":{"purchaseOrderId":"ID_DO_PEDIDO"}}):
curl -G "https://erp-api.ideros.api.br/external/v1/purchase-order-items" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"purchaseOrderId":"ID_DO_PEDIDO"}}'
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/purchase-order-items/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
purchaseOrderId | string | Sim | ID de pedido de compra. |
productId | string | Não | ID de produto. |
productPriceTableId | string | Não | ID da tabela de preço (ProductPriceTable) de origem do unitPrice. Opcional — registra de qual tabela o preço foi tirado para rastreabilidade. |
description | string | Sim | Descrição do item. |
itemType | enum | Não | Tipo do item (Produto, Serviço, Mão de obra, Outros). Valores: LABOR, SERVICE, PARTS, OTHERS. |
valueType | enum | Não | Formato do preço. AMOUNT (padrão): unitPrice é valor em reais. PERCENTAGE: unitPrice é percentual sobre originalUnitPrice. Valores: PERCENTAGE, AMOUNT. |
quantity | number | Sim | Quantidade do item a ser comprada. |
originalUnitPrice | number | Não | Preço unitário cheio/base. Obrigatório quando valueType=PERCENTAGE. Se omitido, assume o unitPrice. |
unitPrice | number | Sim | Preço unitário do item. |
totalPrice | number | Sim | Preço total calculado (quantidade * preço unitário). |
discount | number | Não | Valor de desconto aplicado ao item. |
discountPercentage | number | Não | Percentual de desconto aplicado ao item. |
purchaseNature | enum | Não | Natureza (destinação) da compra deste item: revenda, industrialização, uso e consumo, ativo imobilizado, material aplicado em serviço, entre outras. Determina o CFOP de entrada, o direito a crédito e a natureza com que o item entra no estoque. Quando omitida, herda a natureza padrão do pedido de compra. Valores: RESALE, INDUSTRIALIZATION, PACKAGING, SERVICE_MATERIAL_ICMS, SERVICE_MATERIAL_ISS, CONSUMPTION, FIXED_ASSET, FREE_SAMPLE, CONSIGNMENT_IN, TOLLING_IN, TOLLING_RETURN, TRANSFER_IN, RETURN_IN, SERVICE, OTHER. |
unit | string | Não | Unidade de COMPRA do item, que pode ser diferente da unidade de estoque do produto. |
conversionFactor | number | Não | Fator de conversão da unidade de compra para a unidade de estoque do produto. Comprar uma caixa com 12 unidades corresponde ao fator 12. |
ncm | string | Não | Código NCM do item. Quando omitido, é herdado do cadastro do produto. |
cfop | string | Não | CFOP de entrada do item. Quando omitido, é derivado da natureza da compra. Informe manualmente para operações que o sistema não cobre automaticamente. |
stockLocationId | string | Não | ID de local de estoque. Depósito de destino previsto para o item. Só utilizado quando a empresa habilita o controle de depósitos. |
costCenterId | string | Não | ID de centro de custo. |
A nossa equipe ajuda você a configurar e usar esse recurso.