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

Referência da API

Webhooks

Faça a Pleaxy enviar cada mudança para o seu endpoint HTTPS assim que ela acontece.

Mais sobre este recurso

O feed de sincronização, enviado a você. Cada evento dos tipos que um endpoint assina é enviado a ele por POST como JSON - o evento de ListSyncEvents mais workspaceId e documentPath, a chamada que lê o documento - nunca o documento em si. Toda requisição traz Pleaxy-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>"> com o segredo do endpoint; recuse uma que não corresponda ou tenha mais de 5 minutos. Responda com um 2xx em até 10 segundos; qualquer outra resposta é tentada de novo depois de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas e 24 horas, e então abandonada. Os endpoints são endereços https:// em um nome de host; as entregas nunca chegam a uma rede privada e nunca seguem um redirecionamento. Até 5 por lado do espaço de trabalho.

Endpoints

GET…/webhooks
POST…/webhooks
PATCH…/webhooks/{webhookId}
DELETE…/webhooks/{webhookId}
POST…/webhooks/{webhookId}/secret
POST…/webhooks/{webhookId}/test
GET…/webhooks/{webhookId}/deliveries

Listar webhooks

Lista os seus endpoints de webhook.

GET/v1/workspaces/{regionId}/webhooks

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Os endpoints do seu lado e os tipos de evento que podem receber. Nunca um segredo de assinatura: secretHint mostra o começo e o fim dele.

Um administrador conectado (token Bearer): approvalSettings edit do comprador, ou um administrador de fornecedor.

Campos da resposta

endpoints[].eventsArray<string>
Os tipos de evento enviados. Vazio significa todos os tipos do seu lado, inclusive os adicionados depois.
endpoints[].lastErrorCodestring
Por que a última tentativa falhou: http_status (veja lastStatus), blocked_address, unreachable, timeout, redirect, too_large, endpoint_off ou failed.
endpoints[].failedDeliveriesnumber
Entregas abandonadas seguidas; um sucesso ou a retomada do endpoint zera a contagem.

Erros

403 Forbidden - Uma chave de API, ou quem chama sem ser administrador deste lado do espaço de trabalho.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.

GET /v1/workspaces/{regionId}/webhooks

Requisição

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

Resposta · 200 OK

{
   "endpoints": [
      {
         "id": "string",
         "url": "string",
         "description": "string",
         "events": [ "string" ],
         "enabled": boolean,
         "secretHint": "string",
         "createdAt": "string",
         "lastAttemptAt": "string",
         "lastStatus": number,
         "lastErrorCode": "string",
         "lastSuccessAt": "string",
         "failedDeliveries": number
      }
   ],
   "eventTypes": [ "string" ]
}

Criar webhook

Adiciona um endpoint de webhook e retorna o segredo de assinatura dele, uma única vez.

POST/v1/workspaces/{regionId}/webhooks

Corpo

urlstringObrigatório
Um endereço https:// em um nome de host, sem endereço IP, porta, nome de usuário ou senha.
descriptionstring
Até 100 caracteres, para distinguir os endpoints.
eventsArray<string>
Os tipos de evento a enviar, de eventTypes. Omita para todos.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Adiciona um endpoint. A resposta traz o segredo de assinatura, exibido só desta vez: guarde-o no seu sistema para verificar a assinatura de cada requisição.

Um administrador conectado (token Bearer): approvalSettings edit do comprador, ou um administrador de fornecedor.

Erros

400 Bad Request - Código WEBHOOK_URL_INVALID, WEBHOOK_EVENTS_INVALID ou WEBHOOK_LIMIT (já há 5 endpoints).
403 Forbidden - Uma chave de API, ou quem chama sem ser administrador deste lado do espaço de trabalho.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.

POST /v1/workspaces/{regionId}/webhooks

Requisição

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

body.json

{
   "url": "https://erp.example.com/pleaxy",
   "description": "string",
   "events": [ "invoice.paid", "invoice.remittance_sent" ]
}

Resposta · 201 Created

{
   "id": "string",
   "url": "string",
   "events": [ "string" ],
   "enabled": true,
   "secret": "string",
   "secretHint": "string",
   "createdAt": "string"
}

Atualizar webhook

Altera um endpoint de webhook, ou o pausa e retoma.

PATCH/v1/workspaces/{regionId}/webhooks/{webhookId}

Parâmetros

webhookIdstringObrigatório
O id do endpoint, por exemplo WH-3F9A01C2.

Corpo

enabledboolean
false pausa o endpoint; true o retoma. url, description e events como em CreateWebhook.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Altera a url, a description ou os events de um endpoint, ou o pausa (enabled: false) e retoma (enabled: true). Nada fica na fila para um endpoint pausado. Retomar zera failedDeliveries.

Um administrador conectado (token Bearer): approvalSettings edit do comprador, ou um administrador de fornecedor.

Erros

400 Bad Request - Código WEBHOOK_URL_INVALID ou WEBHOOK_EVENTS_INVALID.
404 Not Found - Código WEBHOOK_NOT_FOUND.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.

PATCH /v1/workspaces/{regionId}/webhooks/{webhookId}

Requisição

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

body.json

{
   "enabled": false
}

Resposta · 200 OK

The endpoint, as in ListWebhooks.

Excluir webhook

Remove um endpoint de webhook.

DELETE/v1/workspaces/{regionId}/webhooks/{webhookId}

Parâmetros

webhookIdstringObrigatório
O id do endpoint, por exemplo WH-3F9A01C2.

Retorna

204 No Content com o objeto mostrado na resposta.

Mais detalhes

Remove um endpoint. As entregas que ainda aguardavam por ele são abandonadas.

Um administrador conectado (token Bearer): approvalSettings edit do comprador, ou um administrador de fornecedor.

Erros

404 Not Found - Código WEBHOOK_NOT_FOUND.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.

DELETE /v1/workspaces/{regionId}/webhooks/{webhookId}

Requisição

curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 204 No Content

(no content)

Rotacionar segredo do webhook

Substitui o segredo de assinatura de um endpoint.

POST/v1/workspaces/{regionId}/webhooks/{webhookId}/secret

Parâmetros

webhookIdstringObrigatório
O id do endpoint, por exemplo WH-3F9A01C2.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Um novo segredo de assinatura, retornado só desta vez em secret. O antigo deixa de assinar imediatamente, então atualize o seu sistema logo em seguida.

Um administrador conectado (token Bearer): approvalSettings edit do comprador, ou um administrador de fornecedor.

Erros

404 Not Found - Código WEBHOOK_NOT_FOUND.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.

POST /v1/workspaces/{regionId}/webhooks/{webhookId}/secret

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/secret" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

The endpoint, as in ListWebhooks, plus secret.

Testar webhook

Envia a um endpoint um ping de teste assinado.

POST/v1/workspaces/{regionId}/webhooks/{webhookId}/test

Parâmetros

webhookIdstringObrigatório
O id do endpoint, por exemplo WH-3F9A01C2.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Envia ao endpoint um ping assinado agora, uma vez, sem novas tentativas, e informa o que ele respondeu.

Um administrador conectado (token Bearer): approvalSettings edit do comprador, ou um administrador de fornecedor.

Erros

404 Not Found - Código WEBHOOK_NOT_FOUND.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.

POST /v1/workspaces/{regionId}/webhooks/{webhookId}/test

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/test" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

{
   "ok": boolean,
   "status": number,
   "errorCode": "string",
   "durationMs": number
}

Listar entregas do webhook

Lista as entregas recentes de um endpoint.

GET/v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries

Parâmetros

webhookIdstringObrigatório
O id do endpoint, por exemplo WH-3F9A01C2.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

As últimas 50 entregas de um endpoint, da mais recente para a mais antiga, guardadas por 30 dias: o tipo, o status, as tentativas e o que deu errado em cada evento.

Um administrador conectado (token Bearer): approvalSettings edit do comprador, ou um administrador de fornecedor.

Campos da resposta

deliveries[].statusstring
pending: aguardando a próxima tentativa (nextAttemptAt). delivered: respondida com um 2xx. failed: abandonada.

Erros

404 Not Found - Código WEBHOOK_NOT_FOUND.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.

GET /v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries

Requisição

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

{
   "deliveries": [
      {
         "eventId": "string",
         "type": "string",
         "status": "pending" | "delivered" | "failed",
         "attempts": number,
         "createdAt": "string",
         "nextAttemptAt": "string",
         "lastAttemptAt": "string",
         "lastStatus": number,
         "lastErrorCode": "string",
         "deliveredAt": "string"
      }
   ]
}