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

Referência da API

Cadeias de aprovação

Quem aprova pedidos de compra e pagamentos de faturas.

Mais sobre este recurso

Configura quem aprova pedidos de compra e pagamentos de faturas - à parte das configurações de autonomia de Liquidação, que controlam se é preciso uma pessoa, e não qual pessoa. Cada um dos dois processos (purchase_order, invoice_payment) tem um fluxo de aprovação, em Fluxos de trabalho na Pleaxy, ou é vinculado para compartilhar o fluxo do outro processo. Um fluxo é uma lista ordenada de grupos, executados um após o outro. Um grupo sequencial é uma etapa com um aprovador; um grupo paralelo são várias etapas que precisam ser todas aprovadas, em qualquer ordem, por pessoas diferentes. Um grupo com condições só é executado quando todas as condições correspondem ao documento (valor, fornecedor ou solicitante); uma etapa marcada com highValueOnly só é executada quando o valor está acima do approvalThreshold de Liquidação. Toda etapa indica um funcionário específico, e só esse funcionário pode agir sobre ela. Uma nova região começa com uma etapa, 'Region administrator'. Quando um pedido de compra ou fatura é criado, a cadeia dele é um retrato do fluxo naquele momento, então editar o fluxo depois não altera documentos que já estão aguardando.

Endpoints

GET…/approval-chains/{process}
PATCH…/approval-chains/{process}

Obter configurações da cadeia de aprovação

Retorna o fluxo de aprovação de um processo.

GET/v1/workspaces/{regionId}/approval-chains/{process}

Parâmetros

process"purchase_order" | "invoice_payment"Obrigatório
De qual fluxo obter a cadeia de aprovação.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna o fluxo de aprovação de um processo, ou { process, groups: [] } se o processo nunca teve um. Aceita uma chave de API de comprador.

Campos da resposta

linkedTo"purchase_order" | "invoice_payment"
Quando definido, este processo usa o fluxo do outro processo (um vínculo ativo, não uma cópia), e groups é ignorado.
groups[].mode"sequential" | "parallel"
sequential: exatamente uma etapa. parallel: todas as etapas precisam ser aprovadas, em qualquer ordem, cada uma por um funcionário diferente.
groups[].conditionsarray
Quando presente, o grupo só é executado se todas as condições corresponderem. amount usa gt, gte, lt ou lte com um número na moeda da região; supplier usa is ou is_not com o ID do espaço de trabalho de um fornecedor (terminado em .supplier); requester usa is ou is_not com uma chave de funcionário. Um documento em uma moeda diferente da da região atende a toda condição de valor.
groups[].stages[].approverEmployeeKeystring
O único funcionário que pode agir sobre a etapa. '' significa que a etapa ainda não tem aprovador - é preciso atribuir um antes que alguém possa agir sobre ela. Só um fluxo salvo antes de os aprovadores indicados se tornarem obrigatórios pode ter esse valor.
groups[].stages[].highValueOnlyboolean
A etapa só é executada quando o valor está acima do approvalThreshold de Liquidação (o limite de alto valor).
source"default"
Presente quando a Pleaxy gravou este fluxo como o padrão da região. Qualquer outro salvamento o remove.
defaultApproverIsAdminboolean
Só com source "default": se o aprovador da etapa padrão ainda é um administrador da região.
requesterRule.eligibleApproverCountnumber
Quantos membros compradores podem aprovar os documentos deste processo. Um solicitante só pode aprovar o próprio documento quando ninguém mais poderia.

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}/approval-chains/{process}

Requisição

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/approval-chains/{process}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

{
   "process": "purchase_order" | "invoice_payment",
   "linkedTo": "purchase_order" | "invoice_payment",
   "groups": [
      {
         "id": "string",
         "mode": "sequential" | "parallel",
         "label": "string",
         "stages": [
            {
               "id": "string",
               "label": "string",
               "approverEmployeeKey": "string",
               "approverName": "string",
               "approverEmail": "string",
               "highValueOnly": boolean
            }
         ],
         "conditions": [
            { "field": "amount" | "supplier" | "requester", "operator": "gt" | "gte" | "lt" | "lte" | "is" | "is_not", "value": number | "string" }
         ]
      }
   ],
   "source": "default",
   "defaultApproverIsAdmin": boolean,
   "requesterRule": { "eligibleApproverCount": number }
}

Atualizar configurações da cadeia de aprovação

Substitui o fluxo de aprovação de um processo.

PATCH/v1/workspaces/{regionId}/approval-chains/{process}

Parâmetros

process"purchase_order" | "invoice_payment"Obrigatório
De qual fluxo atualizar a cadeia de aprovação.

Corpo

groupsarray
O novo fluxo, em ordem. Cada um { id, mode, label?, stages, conditions? }. stages são { id, label, approverEmployeeKey, highValueOnly? }: um grupo sequencial tem exatamente uma, um grupo paralelo pelo menos uma, com ids únicos e aprovadores diferentes. Até 10 condições por grupo. Pelo menos um grupo.
linkedTo"purchase_order" | "invoice_payment"
Usa o fluxo do outro processo em vez do fluxo próprio deste.
useDefaulttrue
Redefine para o padrão da região: uma etapa, 'Region administrator', indicando o administrador responsável pela região ou, se não houver, o primeiro administrador por ordem de nome. Não pode ser combinado com groups, stages nem linkedTo.
stagesarray
Formato plano legado, uma etapa sequencial por entrada, { id, label, approverEmployeeKey, highValueOnly? }. Salvo como os groups equivalentes.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Substitui o fluxo de um processo por groups, vincula-o ao fluxo do outro processo com linkedTo, ou o redefine para o padrão da região com useDefault: true. Enviar groups remove qualquer linkedTo; enviar linkedTo mantém os groups atuais registrados, mas inativos enquanto o vínculo existir. Cada approverEmployeeKey é verificado contra os funcionários do espaço de trabalho. O fluxo precisa manter pelo menos um grupo sem condições que seja executado para valores comuns, para que todo documento chegue a uma pessoa. stages, uma lista plana de grupos de uma etapa, ainda é aceito para clientes mais antigos; prefira groups.

Alterado em 2026-09-27, uma correção de segurança dentro da v1: só sessão conectada, para todos os processos: uma cadeia de aprovação decide quem aprova gastos, então uma chave de API recebe 403 HUMAN_SESSION_REQUIRED, qualquer que seja a função de compras dela.

Erros

400 Bad Request - Uma etapa não tem aprovador ("'{label}' has no approver - every approval step must name a specific employee.") ou indica alguém que não é funcionário do espaço de trabalho; um grupo paralelo indica o mesmo aprovador duas vezes; um grupo sequencial não tem exatamente uma etapa; uma condição está malformada; o fluxo não tem nenhum grupo sem condições que seja executado para valores comuns ("A chain needs at least one approval step with no conditions that applies to ordinary purchase amounts…"); groups ou stages está vazio; linkedTo indica este processo, ou um processo já vinculado de volta a ele; ou useDefault vem combinado com groups, stages ou linkedTo.
409 Conflict - Código NO_REGION_ADMIN, com useDefault: "This region has no administrator to route approvals to. Make someone an administrator first."
403 Forbidden - Código HUMAN_SESSION_REQUIRED. Quem chama não é uma pessoa conectada (por exemplo, uma chave de API), para qualquer processo ("Approval chains can only be changed by a signed-in person. Change them in Pleaxy."). 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.

PATCH /v1/workspaces/{regionId}/approval-chains/{process}

Requisição

curl -X PATCH "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/approval-chains/{process}" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "groups": [
      {
         "id": "string",
         "mode": "sequential" | "parallel",
         "label": "string",
         "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "highValueOnly": boolean }
         ],
         "conditions": [
            { "field": "amount" | "supplier" | "requester", "operator": "gt" | "gte" | "lt" | "lte" | "is" | "is_not", "value": number | "string" }
         ]
      }
   ]
}

Resposta · 200 OK

{
   "process": "purchase_order" | "invoice_payment",
   "linkedTo": "purchase_order" | "invoice_payment",
   "groups": [
      {
         "id": "string",
         "mode": "sequential" | "parallel",
         "label": "string",
         "stages": [
            {
               "id": "string",
               "label": "string",
               "approverEmployeeKey": "string",
               "approverName": "string",
               "approverEmail": "string",
               "highValueOnly": boolean
            }
         ],
         "conditions": [
            { "field": "amount" | "supplier" | "requester", "operator": "gt" | "gte" | "lt" | "lte" | "is" | "is_not", "value": number | "string" }
         ]
      }
   ],
   "source": "default",
   "defaultApproverIsAdmin": boolean,
   "requesterRule": { "eligibleApproverCount": number }
}