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

Referência da API

Atendimento de pedidos

Os fornecedores confirmam pedidos e avisam sobre envios; os compradores veem os dois no pedido.

Mais sobre este recurso

O que um fornecedor informa sobre um pedido depois que ele é emitido: se o aceita, quando ele vai chegar e o que já foi enviado. O ERP de um fornecedor envia o mesmo em cXML: faça um post de um ConfirmationRequest ou ShipNoticeRequest (DTD Fulfill do cXML 1.2.071) para /v1/cxml/fulfillment com a chave de API em X-Api-Key ou como SharedSecret do Sender, e uma credencial To com domain PleaxyWorkspaceID indicando o comprador; a resposta é um Status do cXML, e um payloadID reenviado não muda nada. Fornecedores sem nenhum dos dois podem responder por e-mail: todo pedido enviado por e-mail a um fornecedor tem um endereço próprio (ListPurchaseOrderEmails), onde uma resposta ou um documento cXML fica guardado no pedido. Nada aqui altera o pedido: cabe ao comprador cancelar um pedido recusado, e um envio nunca é um recebimento. O solicitante e o recebedor do comprador são notificados, e o feed de sincronização e os webhooks do comprador recebem purchase_order.confirmed e purchase_order.shipped.

Endpoints

GET…/purchase-orders/{poId}/fulfillment
POST…/purchase-orders/{poId}/confirmations/{confirmationId}/apply
POST…/purchase-orders/{poId}/confirmations/{confirmationId}/decline
GET…/purchase-orders/{poId}/emails
POST…/purchase-orders/{poId}/emails/{emailId}/record
POST…/purchase-orders/{poId}/emails/{emailId}/dismiss

Obter o atendimento do pedido de compra

Retorna as confirmações e os envios do fornecedor para um pedido.

GET/v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment

Parâmetros

poIdstringObrigatório
O identificador do pedido de compra.
buyerstring
Quem chama como Fornecedor: o ID do espaço de trabalho do comprador, quando dois compradores emitiram o mesmo id.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

O que o fornecedor informou sobre um pedido: a confirmação mais recente (resultado accepted, backordered, changed, partial ou rejected, linha por linha, com a decisão do comprador sobre as alterações), as anteriores e os envios (planned, shipped ou canceled, com transportadora e rastreamento). Cada envio lista os recebimentos de mercadorias aprovados lançados contra ele. shippedByLine soma as quantidades enviadas; expectedDeliveryDate é a data de entrega mais recente que o fornecedor informou. Um fornecedor cujos compradores compartilham um id de pedido adiciona ?buyer=<ID do espaço de trabalho do comprador>.

Campos da resposta

confirmationOrderConfirmation
A confirmação mais recente, ausente até o fornecedor responder. O resultado dela é o do pedido.
shippedByLineArray
Por linha, a quantidade nos envios com status shipped. Os planned e canceled não entram na conta.

Erros

404 Not Found - Nenhum pedido de compra com este id é seu.
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-orders/{poId}/fulfillment

Requisição

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

Resposta · 200 OK

{
   "confirmation": OrderConfirmation,
   "confirmations": [
      {
         "id": "string",
         "poId": "string",
         "outcome": "accepted" | "backordered" | "changed" | "partial" | "rejected",
         "confirmId": "string",
         "deliveryDate": "YYYY-MM-DD",
         "note": "string",
         "lines": [ { "lineNo": number, "status": "accept" | "backordered" | "change" | "reject", "qty": number, "unitPrice": number, "substitute": { "supplierPartId": "string", "name": "string", "catalogItemId": "string" }, "shipmentDate": "YYYY-MM-DD", "deliveryDate": "YYYY-MM-DD", "reason": "string" } ],
         "decision": { "decision": "applied" | "declined", "at": "string", "version": number, "reason": "string" },
         "source": "portal" | "api" | "cxml",
         "createdAt": "string"
      }
   ],
   "shipNotices": [
      {
         "shipmentId": "string",
         "status": "planned" | "shipped" | "canceled",
         "shipmentDate": "YYYY-MM-DD",
         "deliveryDate": "YYYY-MM-DD",
         "carrier": "string",
         "trackingNumber": "string",
         "trackingUrl": "string",
         "lines": [ { "lineNo": number, "qty": number } ],
         "source": "portal" | "api" | "cxml",
         "createdAt": "string",
         "updatedAt": "string",
         "receipts": [ { "id": "string", "receivedAt": "YYYY-MM-DD" } ]
      }
   ],
   "shippedByLine": [ { "lineNo": number, "qty": number } ],
   "expectedDeliveryDate": "YYYY-MM-DD"
}

Aplicar alterações da confirmação

Leva para o pedido as quantidades e os preços alterados pelo fornecedor.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply

Parâmetros

poIdstringObrigatório
O identificador do pedido de compra.
confirmationIdstringObrigatório
O id da confirmação, obtido em GetPurchaseOrderFulfillment.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Aplica às linhas do pedido as alterações da confirmação mais recente do fornecedor (resultado changed). É uma edição de linhas comum, como a que UpdatePurchaseOrder faz: o pedido ganha uma nova versão, volta para aprovação quando as regras dele exigem, e o fornecedor recebe po_changed. Responde { purchaseOrder, confirmation } com a decisão aplicada e a versão do pedido resultante.

Erros

404 Not Found - Pedido inexistente, ou código CONFIRMATION_NOT_FOUND.
409 Conflict - Código CONFIRMATION_SUPERSEDED (o fornecedor confirmou de novo depois disso), CONFIRMATION_DECIDED (já aplicada ou recusada), NO_CHANGES ou ORDER_NOT_OPEN.
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-orders/{poId}/confirmations/{confirmationId}/apply

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

{
   "purchaseOrder": PurchaseOrder,
   "confirmation": OrderConfirmation
}

Recusar alterações da confirmação

Mantém o pedido como está, em vez das alterações do fornecedor.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline

Parâmetros

poIdstringObrigatório
O identificador do pedido de compra.
confirmationIdstringObrigatório
O id da confirmação, obtido em GetPurchaseOrderFulfillment.

Corpo

reasonstring
Por quê, até 500 caracteres. O fornecedor vê o texto.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Recusa as alterações da confirmação mais recente do fornecedor. O pedido não muda; o fornecedor é avisado, com o seu motivo quando você informa um. Responde com a confirmação e a decisão dela.

Erros

404 Not Found - Pedido inexistente, ou código CONFIRMATION_NOT_FOUND.
409 Conflict - Código CONFIRMATION_SUPERSEDED, CONFIRMATION_DECIDED ou NO_CHANGES.
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-orders/{poId}/confirmations/{confirmationId}/decline

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "reason": "string"
}

Resposta · 200 OK

OrderConfirmation

Listar e-mails do pedido de compra

Retorna o endereço de e-mail próprio de um pedido e os e-mails que chegaram a ele.

GET/v1/workspaces/{regionId}/purchase-orders/{poId}/emails

Parâmetros

poIdstringObrigatório
O identificador do pedido de compra.
buyerstring
Fornecedores: o ID do espaço de trabalho do comprador, quando dois compradores emitiram o mesmo id.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Todo pedido enviado por e-mail ao fornecedor recebe um endereço próprio, como um segundo Reply-To no e-mail do pedido e impresso no PDF. A resposta de um fornecedor, ou um ConfirmationRequest ou ShipNoticeRequest do cXML que o sistema dele envia para lá, fica guardada no pedido, do mais recente para o mais antigo. Um documento cXML de um remetente verificado (o contato do fornecedor ou o domínio da empresa dele, verificado com SPF, DKIM e DMARC) é registrado na hora (outcome applied). Um e-mail simples é lido pelo Pleaxy Assistant e vira um rascunho de confirmação ou de aviso de envio, e um documento de um remetente que a Pleaxy não consegue verificar fica retido: os dois aguardam alguém registrá-los com RecordPurchaseOrderEmail. address fica ausente até o pedido ser emitido.

Erros

404 Not Found - Pedido de compra inexistente.
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-orders/{poId}/emails

Requisição

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

Resposta · 200 OK

{
   "address": "string",
   "emails": [
      {
         "id": "string",
         "from": "string",
         "subject": "string",
         "receivedAt": "string",
         "trust": "verified" | "unverified",
         "kind": "cxml" | "text",
         "outcome": "applied" | "draft" | "held" | "noAction" | "test" | "failed" | "ignored",
         "reasonCode": "string",
         "summary": "string",
         "text": "string",
         "attachments": [ { "name": "string", "contentType": "string", "size": number } ],
         "draft": { "kind": "confirmation" | "shipNotice", "summary": "string", "confirmation": object, "shipNotice": object },
         "result": { "confirmationId": "string", "shipmentId": "string" },
         "decision": { "action": "recorded" | "dismissed", "by": "string", "at": "string" }
      }
   ]
}

Registrar e-mail do pedido de compra

Registra o rascunho de um e-mail como a confirmação ou o aviso de envio do fornecedor.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record

Parâmetros

poIdstringObrigatório
O identificador do pedido de compra.
emailIdstringObrigatório
O id do e-mail, obtido em ListPurchaseOrderEmails.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Registra o rascunho de um e-mail com outcome draft ou held como a confirmação de pedido ou o aviso de envio do fornecedor, com origem e-mail, com as mesmas verificações de ConfirmPurchaseOrder e SendShipNotice. Responde ao e-mail com a decisão. O comprador precisa poder editar pedidos de compra.

Erros

400 Bad Request - O rascunho indica uma linha desconhecida, ou uma linha que não pode ser enviada.
404 Not Found - Pedido ou e-mail inexistente.
409 Conflict - Código EMAIL_DECIDED (já registrado ou descartado), NOTHING_TO_RECORD ou ORDER_NOT_OPEN.
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-orders/{poId}/emails/{emailId}/record

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

InboundEmail

Descartar e-mail do pedido de compra

Mantém o pedido como está em vez de registrar o que um e-mail pede.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss

Parâmetros

poIdstringObrigatório
O identificador do pedido de compra.
emailIdstringObrigatório
O id do e-mail, obtido em ListPurchaseOrderEmails.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Marca um e-mail como descartado: nada é registrado. Responde ao e-mail com a decisão.

Erros

404 Not Found - Pedido ou e-mail inexistente.
409 Conflict - Código EMAIL_DECIDED: já registrado ou descartado.
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-orders/{poId}/emails/{emailId}/dismiss

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

InboundEmail