Emita pedidos de compra, aprove e pague faturas, e configure seu espaço de trabalho.

Referência da API

Solicitações de compra

O que as pessoas pedem para comprar antes de existir um pedido: aprovação, verificação de orçamento e depois um pedido.

Mais sobre este recurso

Qualquer membro de um espaço de trabalho comprador pode pedir algo, seja qual for seu papel de compras: uma solicitação não compromete dinheiro, e sua aprovação é o controle. Uma solicitação enviada passa pelo fluxo de aprovação de solicitações de compra do espaço de trabalho (por padrão, o de pedidos de compra), pelo limite de gastos de quem pede e, quando os orçamentos estão ativos, pelo orçamento do seu centro de custo. Depois de aprovada, alguém que pode emitir pedidos a transforma em um pedido de compra com ConvertPurchaseRequest. O pedido mantém a aprovação da solicitação quando fica dentro do que foi aprovado, no mesmo centro de custo e na mesma conta contábil. As solicitações são só do comprador e nunca aparecem para os fornecedores.

Endpoints

GET…/purchase-requests
POST…/purchase-requests
GET…/purchase-requests/{requestId}
PATCH…/purchase-requests/{requestId}
POST…/purchase-requests/{requestId}/submit
POST…/purchase-requests/{requestId}/approve
POST…/purchase-requests/{requestId}/reject
POST…/purchase-requests/{requestId}/cancel
POST…/purchase-requests/{requestId}/convert

Listar solicitações de compra

Lista as solicitações de compra que você pode ver, das mais recentes para as mais antigas.

GET/v1/workspaces/{regionId}/purchase-requests

Parâmetros

status"draft" | "pending_approval" | "approved" | "ordered" | "rejected" | "canceled"
Só as solicitações com este status.
mineboolean
true: só as solicitações de quem chama.
awaitingMeboolean
true: só as solicitações que aguardam a aprovação de quem chama, como na sua fila de aprovações. status e mine são então ignorados.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Lista as solicitações de quem chama; com acesso 'view' aos pedidos de compra, as de todos, exceto os rascunhos de outras pessoas; e qualquer solicitação cuja cadeia de aprovação indique quem chama. Das mais recentes para as mais antigas.

Campos da resposta

statusstring
draft até ser enviada; pending_approval enquanto a cadeia de aprovação corre; approved, e depois ordered quando virou um pedido de compra (poId); ou rejected (rejectionReason) ou canceled.
amountnumber
O total das linhas (qty × unitPrice), em currency.
approvalobject
A cadeia de aprovação, ausente enquanto é um rascunho. Montada a partir do fluxo de aprovação de solicitações de compra do espaço de trabalho (por padrão, o de pedidos de compra), do limite de gastos de quem pede e da verificação de orçamento.
approvalVersionnumber
Aumenta a cada mudança na aprovação. Envie-o como expectedVersion ao aprovar.
budgetCheckobject
A verificação de orçamento do centro de custo quando os orçamentos estão ativos: a última, do envio ou da aprovação final. Os valores estão na moeda do orçamento.

Erros

401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

GET /v1/workspaces/{regionId}/purchase-requests

Requisição

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-requests" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

[
   {
      "id": "string",
      "title": "string",
      "description": "string",
      "requesterEmployeeKey": "string",
      "requesterName": "string",
      "costCenter": "string",
      "glCode": "string",
      "supplier": { "name": "string", "supplierConnectionId": "string", "supplierRegionId": "string" },
      "lineItems": [
         { "name": "string", "lineType": "goods" | "service", "qty": number, "unit": "string", "unitPrice": number }
      ],
      "amount": number,
      "currency": "string",
      "neededBy": "string",
      "quoteDocument": { "importId": "string", "fileName": "string", "contentType": "string", "addedAt": "string", "quoteNumber": "string", "validUntil": "string" },
      "notes": "string",
      "status": "draft" | "pending_approval" | "approved" | "ordered" | "rejected" | "canceled",
      "approval": {
         "requester": "string",
         "requesterEmployeeKey": "string",
         "groups": [
           {
             "id": "string",
             "mode": "sequential" | "parallel",
             "label": "string",
             "status": "pending" | "approved" | "rejected",
             "stages": [
               { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
             ]
           }
         ],
         "groupIndex": number,
         "status": "pending" | "approved" | "rejected",
         "history": [
           { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
         ],
         "autonomy": boolean,
         "selfApproved": boolean
       },
      "approvalVersion": number,
      "budgetCheck": { "outcome": "within" | "over" | "no_budget" | "no_rate" | "off", "mode": "off" | "warn" | "block", "costCenter": "string", "currency": "string", "budget": number, "remaining": number, "amount": number, "overBy": number, "checkedAt": "string" },
      "poId": "string",
      "rejectionReason": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "submittedAt": "string",
      "decidedAt": "string",
      "canceledAt": "string",
      "canceledBy": "string"
   }
]

Criar solicitação de compra

Pede algo: salva um rascunho ou o envia para aprovação.

POST/v1/workspaces/{regionId}/purchase-requests

Corpo

titlestringObrigatório
O que é preciso, em poucas palavras. Até 200 caracteres.
descriptionstring
Por que é preciso: o motivo de negócio. Até 4.000 caracteres. Obrigatório para enviar.
costCenterstring
O código ou o nome de um centro de custo, guardado como seu código. Obrigatório para enviar quando o espaço de trabalho mantém uma lista de centros de custo.
glCodestring
A conta contábil (categoria de gasto), quando não é a do centro de custo. Até 40 caracteres.
supplierobject
Um fornecedor que quem pede sugere: { name, supplierConnectionId?, supplierRegionId? }. Só um nome não direciona nada; um fornecedor aprovado da lista do espaço de trabalho é usado pelas etapas de aprovação por fornecedor.
lineItemsArray<{ name, lineType?, qty, unit?, unitPrice }>Obrigatório
O que é preciso, de 1 a 50 linhas: name (até 200 caracteres), qty (acima de 0), unit (opcional, por exemplo each, hour, month), unitPrice (uma estimativa, 0 ou mais, na moeda da solicitação) e lineType (opcional: goods ou service, levado para a linha do pedido; se omitido, uma unidade de tempo a torna um serviço e qualquer outra, um bem). Uma linha basta para uma estimativa.
currencystring
ISO 4217. A moeda do espaço de trabalho quando omitida.
neededBystring
Quando é preciso, YYYY-MM-DD.
quoteImportIdstring
Uma cotação enviada pela importação de cotações, para anexar.
notesstring
O que compras deve saber. Até 2.000 caracteres.
submitboolean
true a envia para aprovação na hora; caso contrário, é salva como rascunho.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Cria uma solicitação de compra como rascunho, com quem chama como solicitante. Com submit: true ela é enviada na hora, como faz SubmitPurchaseRequest, e a resposta a mostra em pending_approval, ou em approved quando a autonomia ou uma regra de automação a cobre.

Qualquer membro do espaço de trabalho comprador, seja qual for seu papel de compras.

Campos da resposta

statusstring
draft até ser enviada; pending_approval enquanto a cadeia de aprovação corre; approved, e depois ordered quando virou um pedido de compra (poId); ou rejected (rejectionReason) ou canceled.
amountnumber
O total das linhas (qty × unitPrice), em currency.
approvalobject
A cadeia de aprovação, ausente enquanto é um rascunho. Montada a partir do fluxo de aprovação de solicitações de compra do espaço de trabalho (por padrão, o de pedidos de compra), do limite de gastos de quem pede e da verificação de orçamento.
approvalVersionnumber
Aumenta a cada mudança na aprovação. Envie-o como expectedVersion ao aprovar.
budgetCheckobject
A verificação de orçamento do centro de custo quando os orçamentos estão ativos: a última, do envio ou da aprovação final. Os valores estão na moeda do orçamento.

Erros

400 Bad Request - Um campo está faltando ou é inválido. Com submit: true, também quando a solicitação não tem descrição, nem valor acima de 0, nem centro de custo em um espaço de trabalho que mantém uma lista.
409 Conflict - Código over_budget. Os orçamentos são aplicados (modo de bloqueio) e a solicitação levaria seu centro de custo acima do orçamento, ou não há taxa de câmbio para verificá-la. O budgetCheck do corpo traz os valores. Nada é salvo.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/purchase-requests

Requisição

POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/purchase-requests
{
   "title": "Monitors for the design team",
   "description": "Two new designers start on November 3.",
   "costCenter": "CC-1000",
   "lineItems": [ { "name": "27-inch monitor", "lineType": "goods", "qty": 2, "unit": "each", "unitPrice": 320 } ],
   "neededBy": "2026-11-03",
   "submit": true
}

Resposta · 201 Created

{
   "id": "PR-3F9A1C2E",
   "title": "Monitors for the design team",
   "requesterName": "Priya Shah",
   "costCenter": "CC-1000",
   "amount": 640,
   "currency": "USD",
   "status": "pending_approval",
   "approvalVersion": 1,
   ...
}

Obter solicitação de compra

Obtém uma solicitação de compra.

GET/v1/workspaces/{regionId}/purchase-requests/{requestId}

Parâmetros

requestIdstringObrigatório
A solicitação de compra, por exemplo PR-3F9A1C2E.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna uma solicitação de compra com sua cadeia de aprovação, sua verificação de orçamento e, depois de pedida, o pedido de compra em que se transformou (poId). Visível para as mesmas pessoas que em ListPurchaseRequests.

Campos da resposta

statusstring
draft até ser enviada; pending_approval enquanto a cadeia de aprovação corre; approved, e depois ordered quando virou um pedido de compra (poId); ou rejected (rejectionReason) ou canceled.
amountnumber
O total das linhas (qty × unitPrice), em currency.
approvalobject
A cadeia de aprovação, ausente enquanto é um rascunho. Montada a partir do fluxo de aprovação de solicitações de compra do espaço de trabalho (por padrão, o de pedidos de compra), do limite de gastos de quem pede e da verificação de orçamento.
approvalVersionnumber
Aumenta a cada mudança na aprovação. Envie-o como expectedVersion ao aprovar.
budgetCheckobject
A verificação de orçamento do centro de custo quando os orçamentos estão ativos: a última, do envio ou da aprovação final. Os valores estão na moeda do orçamento.

Erros

404 Not Found - Não há solicitação de compra com este id que quem chama possa ver. Quem não pode ver uma solicitação não fica sabendo se ela existe.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

GET /v1/workspaces/{regionId}/purchase-requests/{requestId}

Requisição

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-requests/{requestId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

{
   "id": "string",
   "title": "string",
   "description": "string",
   "requesterEmployeeKey": "string",
   "requesterName": "string",
   "costCenter": "string",
   "glCode": "string",
   "supplier": { "name": "string", "supplierConnectionId": "string", "supplierRegionId": "string" },
   "lineItems": [
      { "name": "string", "lineType": "goods" | "service", "qty": number, "unit": "string", "unitPrice": number }
   ],
   "amount": number,
   "currency": "string",
   "neededBy": "string",
   "quoteDocument": { "importId": "string", "fileName": "string", "contentType": "string", "addedAt": "string", "quoteNumber": "string", "validUntil": "string" },
   "notes": "string",
   "status": "draft" | "pending_approval" | "approved" | "ordered" | "rejected" | "canceled",
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "approvalVersion": number,
   "budgetCheck": { "outcome": "within" | "over" | "no_budget" | "no_rate" | "off", "mode": "off" | "warn" | "block", "costCenter": "string", "currency": "string", "budget": number, "remaining": number, "amount": number, "overBy": number, "checkedAt": "string" },
   "poId": "string",
   "rejectionReason": "string",
   "createdAt": "string",
   "updatedAt": "string",
   "submittedAt": "string",
   "decidedAt": "string",
   "canceledAt": "string",
   "canceledBy": "string"
}

Atualizar solicitação de compra

Altera um rascunho ou uma solicitação que aguarda aprovação.

PATCH/v1/workspaces/{regionId}/purchase-requests/{requestId}

Parâmetros

requestIdstringObrigatório
A solicitação de compra, por exemplo PR-3F9A1C2E.

Corpo

titlestring
O que é preciso, em poucas palavras. Até 200 caracteres.
descriptionstring
Por que é preciso: o motivo de negócio. Até 4.000 caracteres. Obrigatório para enviar.
costCenterstring
O código ou o nome de um centro de custo, guardado como seu código. Obrigatório para enviar quando o espaço de trabalho mantém uma lista de centros de custo.
glCodestring
A conta contábil (categoria de gasto), quando não é a do centro de custo. Até 40 caracteres.
supplierobject
Um fornecedor que quem pede sugere: { name, supplierConnectionId?, supplierRegionId? }. Só um nome não direciona nada; um fornecedor aprovado da lista do espaço de trabalho é usado pelas etapas de aprovação por fornecedor.
lineItemsArray<{ name, lineType?, qty, unit?, unitPrice }>
O que é preciso, de 1 a 50 linhas: name (até 200 caracteres), qty (acima de 0), unit (opcional, por exemplo each, hour, month), unitPrice (uma estimativa, 0 ou mais, na moeda da solicitação) e lineType (opcional: goods ou service, levado para a linha do pedido; se omitido, uma unidade de tempo a torna um serviço e qualquer outra, um bem). Uma linha basta para uma estimativa.
currencystring
ISO 4217. A moeda do espaço de trabalho quando omitida.
neededBystring
Quando é preciso, YYYY-MM-DD.
quoteImportIdstring
Uma cotação enviada pela importação de cotações, para anexar.
notesstring
O que compras deve saber. Até 2.000 caracteres.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Quem pediu altera os campos enviados; o resto se mantém. Enviar lineItems substitui todas as linhas. Uma solicitação que aguarda aprovação volta a passar pela aprovação desde o início, porque suas aprovações eram para o que ela dizia antes.

Só quem pediu.

Campos da resposta

statusstring
draft até ser enviada; pending_approval enquanto a cadeia de aprovação corre; approved, e depois ordered quando virou um pedido de compra (poId); ou rejected (rejectionReason) ou canceled.
amountnumber
O total das linhas (qty × unitPrice), em currency.
approvalobject
A cadeia de aprovação, ausente enquanto é um rascunho. Montada a partir do fluxo de aprovação de solicitações de compra do espaço de trabalho (por padrão, o de pedidos de compra), do limite de gastos de quem pede e da verificação de orçamento.
approvalVersionnumber
Aumenta a cada mudança na aprovação. Envie-o como expectedVersion ao aprovar.
budgetCheckobject
A verificação de orçamento do centro de custo quando os orçamentos estão ativos: a última, do envio ou da aprovação final. Os valores estão na moeda do orçamento.

Erros

400 Bad Request - Um campo é inválido, ou a solicitação está aprovada, pedida, rejeitada ou cancelada e não pode ser alterada.
403 Forbidden - Quem chama não é quem pediu.
404 Not Found - Não há solicitação de compra com este id que quem chama possa ver. Quem não pode ver uma solicitação não fica sabendo se ela existe.
409 Conflict - Código over_budget. Os orçamentos são aplicados (modo de bloqueio) e a solicitação levaria seu centro de custo acima do orçamento, ou não há taxa de câmbio para verificá-la. O budgetCheck do corpo traz os valores. Nada é salvo.
409 Conflict - A solicitação mudou enquanto esta chamada a gravava. Leia-a de novo e tente outra vez.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

PATCH /v1/workspaces/{regionId}/purchase-requests/{requestId}

Requisição

curl -X PATCH "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-requests/{requestId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

{
   "id": "string",
   "title": "string",
   "description": "string",
   "requesterEmployeeKey": "string",
   "requesterName": "string",
   "costCenter": "string",
   "glCode": "string",
   "supplier": { "name": "string", "supplierConnectionId": "string", "supplierRegionId": "string" },
   "lineItems": [
      { "name": "string", "lineType": "goods" | "service", "qty": number, "unit": "string", "unitPrice": number }
   ],
   "amount": number,
   "currency": "string",
   "neededBy": "string",
   "quoteDocument": { "importId": "string", "fileName": "string", "contentType": "string", "addedAt": "string", "quoteNumber": "string", "validUntil": "string" },
   "notes": "string",
   "status": "draft" | "pending_approval" | "approved" | "ordered" | "rejected" | "canceled",
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "approvalVersion": number,
   "budgetCheck": { "outcome": "within" | "over" | "no_budget" | "no_rate" | "off", "mode": "off" | "warn" | "block", "costCenter": "string", "currency": "string", "budget": number, "remaining": number, "amount": number, "overBy": number, "checkedAt": "string" },
   "poId": "string",
   "rejectionReason": "string",
   "createdAt": "string",
   "updatedAt": "string",
   "submittedAt": "string",
   "decidedAt": "string",
   "canceledAt": "string",
   "canceledBy": "string"
}

Enviar solicitação de compra

Envia um rascunho para aprovação.

POST/v1/workspaces/{regionId}/purchase-requests/{requestId}/submit

Parâmetros

requestIdstringObrigatório
A solicitação de compra, por exemplo PR-3F9A1C2E.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Monta a cadeia de aprovação da solicitação e avisa o primeiro aprovador. As etapas de aprovação são direcionadas por valor, fornecedor, solicitante, centro de custo e conta contábil. O status passa a pending_approval, ou direto a approved quando a autonomia ou uma regra de automação a cobre. Uma solicitação em outra moeda que não a do espaço de trabalho é direcionada pela taxa de câmbio do dia; sem taxa, sempre vai para uma pessoa. Não tem corpo.

Só quem pediu.

Campos da resposta

statusstring
draft até ser enviada; pending_approval enquanto a cadeia de aprovação corre; approved, e depois ordered quando virou um pedido de compra (poId); ou rejected (rejectionReason) ou canceled.
amountnumber
O total das linhas (qty × unitPrice), em currency.
approvalobject
A cadeia de aprovação, ausente enquanto é um rascunho. Montada a partir do fluxo de aprovação de solicitações de compra do espaço de trabalho (por padrão, o de pedidos de compra), do limite de gastos de quem pede e da verificação de orçamento.
approvalVersionnumber
Aumenta a cada mudança na aprovação. Envie-o como expectedVersion ao aprovar.
budgetCheckobject
A verificação de orçamento do centro de custo quando os orçamentos estão ativos: a última, do envio ou da aprovação final. Os valores estão na moeda do orçamento.

Erros

400 Bad Request - A solicitação já foi enviada, ou não tem descrição, nem valor acima de 0, nem centro de custo em um espaço de trabalho que mantém uma lista.
403 Forbidden - Quem chama não é quem pediu.
404 Not Found - Não há solicitação de compra com este id que quem chama possa ver. Quem não pode ver uma solicitação não fica sabendo se ela existe.
409 Conflict - Código over_budget. Os orçamentos são aplicados (modo de bloqueio) e a solicitação levaria seu centro de custo acima do orçamento, ou não há taxa de câmbio para verificá-la. O budgetCheck do corpo traz os valores. Nada é salvo.
409 Conflict - A solicitação mudou enquanto esta chamada a gravava. Leia-a de novo e tente outra vez.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/purchase-requests/{requestId}/submit

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-requests/{requestId}/submit" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

{
   "id": "string",
   "title": "string",
   "description": "string",
   "requesterEmployeeKey": "string",
   "requesterName": "string",
   "costCenter": "string",
   "glCode": "string",
   "supplier": { "name": "string", "supplierConnectionId": "string", "supplierRegionId": "string" },
   "lineItems": [
      { "name": "string", "lineType": "goods" | "service", "qty": number, "unit": "string", "unitPrice": number }
   ],
   "amount": number,
   "currency": "string",
   "neededBy": "string",
   "quoteDocument": { "importId": "string", "fileName": "string", "contentType": "string", "addedAt": "string", "quoteNumber": "string", "validUntil": "string" },
   "notes": "string",
   "status": "draft" | "pending_approval" | "approved" | "ordered" | "rejected" | "canceled",
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "approvalVersion": number,
   "budgetCheck": { "outcome": "within" | "over" | "no_budget" | "no_rate" | "off", "mode": "off" | "warn" | "block", "costCenter": "string", "currency": "string", "budget": number, "remaining": number, "amount": number, "overBy": number, "checkedAt": "string" },
   "poId": "string",
   "rejectionReason": "string",
   "createdAt": "string",
   "updatedAt": "string",
   "submittedAt": "string",
   "decidedAt": "string",
   "canceledAt": "string",
   "canceledBy": "string"
}

Aprovar solicitação de compra

Aprova a etapa de aprovação atual de uma solicitação de compra.

POST/v1/workspaces/{regionId}/purchase-requests/{requestId}/approve

Parâmetros

requestIdstringObrigatório
A solicitação de compra, por exemplo PR-3F9A1C2E.

Corpo

expectedVersionnumber
O approvalVersion que quem chama viu. Se a aprovação da solicitação mudou desde então, a chamada é recusada com 409 APPROVAL_VERSION_CHANGED em vez de aprovar outra coisa.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Aprova a etapa que indica quem chama. Na etapa final, o orçamento é verificado de novo antes de a solicitação ficar aprovada; quem pediu é avisado, assim como as pessoas que podem emitir pedidos. Valem as mesmas regras da aprovação de um pedido de compra, inclusive se quem pede pode aprovar a própria solicitação.

Só com sessão iniciada e acesso 'edit' aos pedidos de compra. Qualquer outro chamador, inclusive uma chave de API, recebe 403 HUMAN_APPROVAL_REQUIRED antes de qualquer leitura.

Campos da resposta

statusstring
draft até ser enviada; pending_approval enquanto a cadeia de aprovação corre; approved, e depois ordered quando virou um pedido de compra (poId); ou rejected (rejectionReason) ou canceled.
amountnumber
O total das linhas (qty × unitPrice), em currency.
approvalobject
A cadeia de aprovação, ausente enquanto é um rascunho. Montada a partir do fluxo de aprovação de solicitações de compra do espaço de trabalho (por padrão, o de pedidos de compra), do limite de gastos de quem pede e da verificação de orçamento.
approvalVersionnumber
Aumenta a cada mudança na aprovação. Envie-o como expectedVersion ao aprovar.
budgetCheckobject
A verificação de orçamento do centro de custo quando os orçamentos estão ativos: a última, do envio ou da aprovação final. Os valores estão na moeda do orçamento.

Erros

400 Bad Request - A solicitação não aguarda aprovação.
403 Forbidden - Código HUMAN_APPROVAL_REQUIRED. Quem chama é uma chave de API. As etapas de aprovação indicam um funcionário específico, e uma chave nunca pode ser um, então uma chave não pode aprovar nem rejeitar uma etapa. Peça ao funcionário indicado na etapa que aja sobre ela na Pleaxy.
403 Forbidden - Código APPROVER_NOT_ASSIGNED. A etapa atual não tem aprovador atribuído, então ninguém pode agir sobre ela. Um administrador precisa atribuir um antes, com ReassignPurchaseOrderApprovalStage / ReassignInvoiceApprovalStage.
403 Forbidden - Quem chama não é o funcionário indicado na etapa atual. Só esse funcionário pode aprová-la ou rejeitá-la - nenhuma função ou permissão substitui ser o indicado.
404 Not Found - Não há solicitação de compra com este id que quem chama possa ver. Quem não pode ver uma solicitação não fica sabendo se ela existe.
409 Conflict - Código APPROVAL_VERSION_CHANGED: expectedVersion não corresponde mais. Leia a solicitação de novo.
409 Conflict - Código over_budget. Os orçamentos são aplicados (modo de bloqueio) e a solicitação levaria seu centro de custo acima do orçamento, ou não há taxa de câmbio para verificá-la. O budgetCheck do corpo traz os valores. Nada é salvo.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/purchase-requests/{requestId}/approve

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-requests/{requestId}/approve" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "expectedVersion": number
}

Resposta · 200 OK

{
   "id": "string",
   "title": "string",
   "description": "string",
   "requesterEmployeeKey": "string",
   "requesterName": "string",
   "costCenter": "string",
   "glCode": "string",
   "supplier": { "name": "string", "supplierConnectionId": "string", "supplierRegionId": "string" },
   "lineItems": [
      { "name": "string", "lineType": "goods" | "service", "qty": number, "unit": "string", "unitPrice": number }
   ],
   "amount": number,
   "currency": "string",
   "neededBy": "string",
   "quoteDocument": { "importId": "string", "fileName": "string", "contentType": "string", "addedAt": "string", "quoteNumber": "string", "validUntil": "string" },
   "notes": "string",
   "status": "draft" | "pending_approval" | "approved" | "ordered" | "rejected" | "canceled",
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "approvalVersion": number,
   "budgetCheck": { "outcome": "within" | "over" | "no_budget" | "no_rate" | "off", "mode": "off" | "warn" | "block", "costCenter": "string", "currency": "string", "budget": number, "remaining": number, "amount": number, "overBy": number, "checkedAt": "string" },
   "poId": "string",
   "rejectionReason": "string",
   "createdAt": "string",
   "updatedAt": "string",
   "submittedAt": "string",
   "decidedAt": "string",
   "canceledAt": "string",
   "canceledBy": "string"
}

Rejeitar solicitação de compra

Rejeita uma solicitação de compra com um motivo.

POST/v1/workspaces/{regionId}/purchase-requests/{requestId}/reject

Parâmetros

requestIdstringObrigatório
A solicitação de compra, por exemplo PR-3F9A1C2E.

Corpo

reasonstringObrigatório
Por que a solicitação é rejeitada; quem pediu vê. Até 1.000 caracteres.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Rejeita a solicitação na etapa que indica quem chama. O status passa a rejected e quem pediu é avisado com o motivo. É definitivo: quem pediu faz uma nova solicitação.

Com acesso 'edit' aos pedidos de compra. Só o funcionário que a etapa atual indica; uma chave de API recebe 403 HUMAN_APPROVAL_REQUIRED.

Campos da resposta

statusstring
draft até ser enviada; pending_approval enquanto a cadeia de aprovação corre; approved, e depois ordered quando virou um pedido de compra (poId); ou rejected (rejectionReason) ou canceled.
amountnumber
O total das linhas (qty × unitPrice), em currency.
approvalobject
A cadeia de aprovação, ausente enquanto é um rascunho. Montada a partir do fluxo de aprovação de solicitações de compra do espaço de trabalho (por padrão, o de pedidos de compra), do limite de gastos de quem pede e da verificação de orçamento.
approvalVersionnumber
Aumenta a cada mudança na aprovação. Envie-o como expectedVersion ao aprovar.
budgetCheckobject
A verificação de orçamento do centro de custo quando os orçamentos estão ativos: a última, do envio ou da aprovação final. Os valores estão na moeda do orçamento.

Erros

400 Bad Request - Falta o motivo, ou a solicitação não aguarda aprovação.
403 Forbidden - Código HUMAN_APPROVAL_REQUIRED. Quem chama é uma chave de API. As etapas de aprovação indicam um funcionário específico, e uma chave nunca pode ser um, então uma chave não pode aprovar nem rejeitar uma etapa. Peça ao funcionário indicado na etapa que aja sobre ela na Pleaxy.
403 Forbidden - Código APPROVER_NOT_ASSIGNED. A etapa atual não tem aprovador atribuído, então ninguém pode agir sobre ela. Um administrador precisa atribuir um antes, com ReassignPurchaseOrderApprovalStage / ReassignInvoiceApprovalStage.
403 Forbidden - Quem chama não é o funcionário indicado na etapa atual. Só esse funcionário pode aprová-la ou rejeitá-la - nenhuma função ou permissão substitui ser o indicado.
404 Not Found - Não há solicitação de compra com este id que quem chama possa ver. Quem não pode ver uma solicitação não fica sabendo se ela existe.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/purchase-requests/{requestId}/reject

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-requests/{requestId}/reject" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "reason": "string"
}

Resposta · 200 OK

{
   "id": "string",
   "title": "string",
   "description": "string",
   "requesterEmployeeKey": "string",
   "requesterName": "string",
   "costCenter": "string",
   "glCode": "string",
   "supplier": { "name": "string", "supplierConnectionId": "string", "supplierRegionId": "string" },
   "lineItems": [
      { "name": "string", "lineType": "goods" | "service", "qty": number, "unit": "string", "unitPrice": number }
   ],
   "amount": number,
   "currency": "string",
   "neededBy": "string",
   "quoteDocument": { "importId": "string", "fileName": "string", "contentType": "string", "addedAt": "string", "quoteNumber": "string", "validUntil": "string" },
   "notes": "string",
   "status": "draft" | "pending_approval" | "approved" | "ordered" | "rejected" | "canceled",
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "approvalVersion": number,
   "budgetCheck": { "outcome": "within" | "over" | "no_budget" | "no_rate" | "off", "mode": "off" | "warn" | "block", "costCenter": "string", "currency": "string", "budget": number, "remaining": number, "amount": number, "overBy": number, "checkedAt": "string" },
   "poId": "string",
   "rejectionReason": "string",
   "createdAt": "string",
   "updatedAt": "string",
   "submittedAt": "string",
   "decidedAt": "string",
   "canceledAt": "string",
   "canceledBy": "string"
}

Cancelar solicitação de compra

Retira uma solicitação de compra até ela ser pedida.

POST/v1/workspaces/{regionId}/purchase-requests/{requestId}/cancel

Parâmetros

requestIdstringObrigatório
A solicitação de compra, por exemplo PR-3F9A1C2E.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retira um rascunho, uma solicitação que aguarda aprovação ou uma aprovada ainda não pedida. O status passa a canceled. Não tem corpo.

Quem pediu, ou um administrador do espaço de trabalho.

Campos da resposta

statusstring
draft até ser enviada; pending_approval enquanto a cadeia de aprovação corre; approved, e depois ordered quando virou um pedido de compra (poId); ou rejected (rejectionReason) ou canceled.
amountnumber
O total das linhas (qty × unitPrice), em currency.
approvalobject
A cadeia de aprovação, ausente enquanto é um rascunho. Montada a partir do fluxo de aprovação de solicitações de compra do espaço de trabalho (por padrão, o de pedidos de compra), do limite de gastos de quem pede e da verificação de orçamento.
approvalVersionnumber
Aumenta a cada mudança na aprovação. Envie-o como expectedVersion ao aprovar.
budgetCheckobject
A verificação de orçamento do centro de custo quando os orçamentos estão ativos: a última, do envio ou da aprovação final. Os valores estão na moeda do orçamento.

Erros

400 Bad Request - A solicitação já está pedida, rejeitada ou cancelada.
403 Forbidden - Quem chama não é quem pediu nem um administrador.
404 Not Found - Não há solicitação de compra com este id que quem chama possa ver. Quem não pode ver uma solicitação não fica sabendo se ela existe.
409 Conflict - A solicitação mudou enquanto esta chamada a gravava. Leia-a de novo e tente outra vez.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/purchase-requests/{requestId}/cancel

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-requests/{requestId}/cancel" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

{
   "id": "string",
   "title": "string",
   "description": "string",
   "requesterEmployeeKey": "string",
   "requesterName": "string",
   "costCenter": "string",
   "glCode": "string",
   "supplier": { "name": "string", "supplierConnectionId": "string", "supplierRegionId": "string" },
   "lineItems": [
      { "name": "string", "lineType": "goods" | "service", "qty": number, "unit": "string", "unitPrice": number }
   ],
   "amount": number,
   "currency": "string",
   "neededBy": "string",
   "quoteDocument": { "importId": "string", "fileName": "string", "contentType": "string", "addedAt": "string", "quoteNumber": "string", "validUntil": "string" },
   "notes": "string",
   "status": "draft" | "pending_approval" | "approved" | "ordered" | "rejected" | "canceled",
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "approvalVersion": number,
   "budgetCheck": { "outcome": "within" | "over" | "no_budget" | "no_rate" | "off", "mode": "off" | "warn" | "block", "costCenter": "string", "currency": "string", "budget": number, "remaining": number, "amount": number, "overBy": number, "checkedAt": "string" },
   "poId": "string",
   "rejectionReason": "string",
   "createdAt": "string",
   "updatedAt": "string",
   "submittedAt": "string",
   "decidedAt": "string",
   "canceledAt": "string",
   "canceledBy": "string"
}

Converter solicitação de compra

Pede uma solicitação aprovada: cria seu pedido de compra.

POST/v1/workspaces/{regionId}/purchase-requests/{requestId}/convert

Parâmetros

requestIdstringObrigatório
A solicitação de compra, por exemplo PR-3F9A1C2E.

Corpo

any CreatePurchaseOrder fieldobject
Todos os campos são opcionais e usam por padrão os da solicitação. supplier é necessário quando a solicitação não indica um. Enviar lineItems substitui as linhas da solicitação.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Cria um pedido de compra a partir de uma solicitação aprovada, como faz CreatePurchaseOrder: as linhas da solicitação (uma linha personalizada por quantidade cada), o fornecedor, o centro de custo, a conta contábil, a cotação e as observações, e o corpo pode substituir cada um. O pedido indica a solicitação (requestId) e a solicitação passa a ordered, em um só passo, então uma solicitação vira no máximo um pedido. Quando o pedido usa o mesmo centro de custo e a mesma conta contábil e seu valor, na moeda do espaço de trabalho, não passa do que foi aprovado, ele mantém a aprovação da solicitação; caso contrário, passa pelo fluxo de aprovação de pedidos de compra. Quem pediu é avisado.

Com acesso 'create' aos pedidos de compra.

Erros

400 Bad Request - A solicitação não está aprovada, ou nem a solicitação nem o corpo indicam um fornecedor. Qualquer recusa de CreatePurchaseOrder também vale.
409 Conflict - A solicitação já foi pedida.
404 Not Found - Não há solicitação de compra com este id que quem chama possa ver. Quem não pode ver uma solicitação não fica sabendo se ela existe.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/purchase-requests/{requestId}/convert

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-requests/{requestId}/convert" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 201 Created

{
   "request": {
      "id": "string",
      "title": "string",
      "description": "string",
      "requesterEmployeeKey": "string",
      "requesterName": "string",
      "costCenter": "string",
      "glCode": "string",
      "supplier": { "name": "string", "supplierConnectionId": "string", "supplierRegionId": "string" },
      "lineItems": [
         { "name": "string", "lineType": "goods" | "service", "qty": number, "unit": "string", "unitPrice": number }
      ],
      "amount": number,
      "currency": "string",
      "neededBy": "string",
      "quoteDocument": { "importId": "string", "fileName": "string", "contentType": "string", "addedAt": "string", "quoteNumber": "string", "validUntil": "string" },
      "notes": "string",
      "status": "draft" | "pending_approval" | "approved" | "ordered" | "rejected" | "canceled",
      "approval": {
         "requester": "string",
         "requesterEmployeeKey": "string",
         "groups": [
           {
             "id": "string",
             "mode": "sequential" | "parallel",
             "label": "string",
             "status": "pending" | "approved" | "rejected",
             "stages": [
               { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
             ]
           }
         ],
         "groupIndex": number,
         "status": "pending" | "approved" | "rejected",
         "history": [
           { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
         ],
         "autonomy": boolean,
         "selfApproved": boolean
       },
      "approvalVersion": number,
      "budgetCheck": { "outcome": "within" | "over" | "no_budget" | "no_rate" | "off", "mode": "off" | "warn" | "block", "costCenter": "string", "currency": "string", "budget": number, "remaining": number, "amount": number, "overBy": number, "checkedAt": "string" },
      "poId": "string",
      "rejectionReason": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "submittedAt": "string",
      "decidedAt": "string",
      "canceledAt": "string",
      "canceledBy": "string"
   },
   "purchaseOrder": {
      "id": "string",
      "buyerOrgId": "string",
      "supplierOrgId": "string",
      "supplier": "string",
      "amount": number,
      "currency": "string",
      "status": "draft" | "pending_approval" | "rejected" | "awaiting_fulfillment" | "invoiced" | "paid" | "canceled" | "closed" | "expired",
      "invoiceId": "string",
      "provider": "aws" | "gcp" | "azure" | "oci",
      "payerAccounts": [
         { "id": "string", "label": "string", "detail": "string" }
      ],
      "billToParty": {
         "source": "company_profile" | "custom",
         "companyName": "string",
         "address": { "line1": "string", "line2": "string", "city": "string", "region": "string", "postalCode": "string", "country": "string" },
         "addressText": "string",
         "taxId": "string"
      },
      "costCenter": "string",
      "costCenterChanges": [ { "from": "string", "to": "string", "reason": "string", "by": "string", "byName": "string", "at": "string" } ],
      "budgetOwner": "string",
      "buyerName": "string",
      "supplierSite": "string",
      "notes": "string",
      "requestId": "string",
      "lineItems": [
         {
         "lineNo": number,
         "scopeType": "sku" | "service" | "account" | "custom",
         "scopeId": "string" | null,
         "name": "string",
         "ruleType": "quantity" | "amount",
         "unit": "string",
         "unitPrice": number,
         "qty": number,
         "nteAmount": number,
         "lineType": "goods" | "service",
         "currency": "string",
         "paymentTerms": "string",
         "validFrom": "string",
         "validUntil": "string",
         "consumed": number,
         "customerLineNo": "string",
         "supplierSku": "string",
         "priceSource": "contract" | "list" | "manual"
       }
      ],
      "approval": {
         "requester": "string",
         "requesterEmployeeKey": "string",
         "groups": [
           {
             "id": "string",
             "mode": "sequential" | "parallel",
             "label": "string",
             "status": "pending" | "approved" | "rejected",
             "stages": [
               { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
             ]
           }
         ],
         "groupIndex": number,
         "status": "pending" | "approved" | "rejected",
         "history": [
           { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
         ],
         "autonomy": boolean,
         "selfApproved": boolean
       },
      "supplierEmail": { "to": "string", "at": "string" },
      "priorInvoiced": { "amount": number, "currency": "string", "basis": "invoiced" | "remaining", "sourceSystem": "sap_ariba" | "coupa" | "oracle", "importId": "string", "fileName": "string", "importedAt": "string", "importedBy": "string" },
      "createdAt": "string"
   }
}