Pleaxy

Emite órdenes de compra, aprueba y paga facturas, y configura tu espacio de trabajo.

Referencia de la API

Webhooks

Haz que Pleaxy envíe cada cambio a tu endpoint HTTPS en cuanto ocurre.

Más sobre este recurso

El feed de sincronización, enviado a ti. Cada evento de los tipos a los que se suscribe un endpoint se le envía por POST como JSON (el evento de ListSyncEvents más workspaceId y documentPath, la llamada que lee su documento), nunca el documento en sí. Cada solicitud lleva Pleaxy-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>"> con el secreto del endpoint; rechaza una que no coincida o tenga más de 5 minutos. Responde con un 2xx en 10 segundos; cualquier otra respuesta se reintenta después de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas y 24 horas, y luego se abandona. Los endpoints son direcciones https:// en un nombre de host; las entregas nunca llegan a una red privada ni siguen una redirección. Hasta 5 por lado del espacio de trabajo.

Endpoints

Listar webhooks

Lista tus endpoints de webhook.

GET/v1/workspaces/{regionId}/webhooks

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Los endpoints de tu lado y los tipos de evento que pueden recibir. Nunca un secreto de firma: secretHint muestra su inicio y su final.

Un administrador con sesión iniciada (token Bearer): edit en approvalSettings del comprador, o un administrador de proveedor.

Campos de la respuesta

  • endpoints[].eventsArray<string>

    Los tipos de evento que se envían. Vacío significa todos los tipos de tu lado, incluidos los que se agreguen después.

  • endpoints[].lastErrorCodestring

    Por qué falló el último intento: http_status (consulta lastStatus), blocked_address, unreachable, timeout, redirect, too_large, endpoint_off o failed.

  • endpoints[].failedDeliveriesnumber

    Entregas abandonadas seguidas; un éxito o reanudar el endpoint lo restablece.

Errores

  • 403 Forbidden - Una clave de API, o un llamador que no es administrador de este lado del espacio de trabajo.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
GET /v1/workspaces/{regionId}/webhooks
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 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" ]
}

Crear webhook

Agrega un endpoint de webhook y devuelve su secreto de firma, una sola vez.

POST/v1/workspaces/{regionId}/webhooks

Cuerpo

  • urlstringObligatorio

    Una dirección https:// en un nombre de host, sin dirección IP, puerto, nombre de usuario ni contraseña.

  • descriptionstring

    Hasta 100 caracteres, para distinguir los endpoints.

  • eventsArray<string>

    Los tipos de evento que se envían, de eventTypes. Omítelo para todos.

Devuelve

201 Created con el objeto que se muestra en la respuesta.

Más detalles

Agrega un endpoint. La respuesta lleva su secreto de firma, que solo se muestra esta vez: guárdalo en tu sistema para verificar la firma de cada solicitud.

Un administrador con sesión iniciada (token Bearer): edit en approvalSettings del comprador, o un administrador de proveedor.

Errores

  • 400 Bad Request - Código WEBHOOK_URL_INVALID, WEBHOOK_EVENTS_INVALID o WEBHOOK_LIMIT (ya hay 5 endpoints).
  • 403 Forbidden - Una clave de API, o un llamador que no es administrador de este lado del espacio de trabajo.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
POST /v1/workspaces/{regionId}/webhooks
Solicitud
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" ]
}
Respuesta · 201 Created
{
   "id": "string",
   "url": "string",
   "events": [ "string" ],
   "enabled": true,
   "secret": "string",
   "secretHint": "string",
   "createdAt": "string"
}

Actualizar webhook

Cambia un endpoint de webhook, o lo pausa y lo reanuda.

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

Parámetros

  • webhookIdstringObligatorio

    El id del endpoint, p. ej. WH-3F9A01C2.

Cuerpo

  • enabledboolean

    false pausa el endpoint; true lo reanuda. url, description y events como en CreateWebhook.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Cambia la url, la description o los events de un endpoint, o lo pausa (enabled: false) y lo reanuda (enabled: true). No se pone nada en cola para un endpoint pausado. Reanudarlo restablece failedDeliveries.

Un administrador con sesión iniciada (token Bearer): edit en approvalSettings del comprador, o un administrador de proveedor.

Errores

  • 400 Bad Request - Código WEBHOOK_URL_INVALID o WEBHOOK_EVENTS_INVALID.
  • 404 Not Found - Código WEBHOOK_NOT_FOUND.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
PATCH /v1/workspaces/{regionId}/webhooks/{webhookId}
Solicitud
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
}
Respuesta · 200 OK
The endpoint, as in ListWebhooks.

Eliminar webhook

Elimina un endpoint de webhook.

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

Parámetros

  • webhookIdstringObligatorio

    El id del endpoint, p. ej. WH-3F9A01C2.

Devuelve

204 No Content con el objeto que se muestra en la respuesta.

Más detalles

Elimina un endpoint. Las entregas que todavía esperaban por él se abandonan.

Un administrador con sesión iniciada (token Bearer): edit en approvalSettings del comprador, o un administrador de proveedor.

Errores

  • 404 Not Found - Código WEBHOOK_NOT_FOUND.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
DELETE /v1/workspaces/{regionId}/webhooks/{webhookId}
Solicitud
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 204 No Content
(no content)

Rotar secreto de webhook

Reemplaza el secreto de firma de un endpoint.

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

Parámetros

  • webhookIdstringObligatorio

    El id del endpoint, p. ej. WH-3F9A01C2.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Un nuevo secreto de firma, devuelto esta única vez en secret. El anterior deja de firmar de inmediato, así que actualiza tu sistema enseguida.

Un administrador con sesión iniciada (token Bearer): edit en approvalSettings del comprador, o un administrador de proveedor.

Errores

  • 404 Not Found - Código WEBHOOK_NOT_FOUND.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
POST /v1/workspaces/{regionId}/webhooks/{webhookId}/secret
Solicitud
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/secret" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
The endpoint, as in ListWebhooks, plus secret.

Probar webhook

Envía a un endpoint un ping de prueba firmado.

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

Parámetros

  • webhookIdstringObligatorio

    El id del endpoint, p. ej. WH-3F9A01C2.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Envía al endpoint un ping firmado ahora, una vez, sin reintentos, e indica qué respondió.

Un administrador con sesión iniciada (token Bearer): edit en approvalSettings del comprador, o un administrador de proveedor.

Errores

  • 404 Not Found - Código WEBHOOK_NOT_FOUND.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
POST /v1/workspaces/{regionId}/webhooks/{webhookId}/test
Solicitud
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/test" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "ok": boolean,
   "status": number,
   "errorCode": "string",
   "durationMs": number
}

Listar entregas de webhook

Lista las entregas recientes de un endpoint.

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

Parámetros

  • webhookIdstringObligatorio

    El id del endpoint, p. ej. WH-3F9A01C2.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Las últimas 50 entregas de un endpoint, de la más reciente a la más antigua, conservadas 30 días: el tipo de cada evento, su estado, los intentos y qué falló.

Un administrador con sesión iniciada (token Bearer): edit en approvalSettings del comprador, o un administrador de proveedor.

Campos de la respuesta

  • deliveries[].statusstring

    pending: esperando su siguiente intento (nextAttemptAt). delivered: respondida con un 2xx. failed: abandonada.

Errores

  • 404 Not Found - Código WEBHOOK_NOT_FOUND.
  • 401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
GET /v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 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"
      }
   ]
}
Habla con nosotros