Create a payable
POST/payables
Creates a single payable (or an installment/recurring series). Requires scope finance.payables.write. workspace_id is always taken from the token. A person is required — send person: {id} or person: {name}. {name} (person / category / classification_center) is find-or-create; sending both id and name inside the same nested object returns 400. classification_centers[] (rateio) and tax_charges[] are accepted; the rateio Σ is validated against amount. When payment approval is enabled for the workspace (a per-workspace setting, on by default), the created payable enters an approval queue: it is returned here (with its id) but is hidden from GET /payables until an operator approves it in the app — fetch it by id meanwhile. With the setting off, the payable appears on GET /payables immediately. Pass an X-Idempotency-Key header on retries.
Request
Responses
- 201
- 400
- 401
- 403
- 409
- 422
- 429
- 500
Payable created. The Location header points at the new row. The body is the full detail shape (arrays + reconciliation). X-Idempotent-Replay: true marks a replayed response.
Malformed JSON, or id and name sent together inside the same nested entity reference.
Missing / invalid / expired / revoked token.
Token lacks the finance.payables.write scope.
X-Idempotency-Key reused with a different body.
Schema validation failure, or domain violation: missing person, company / account not in tenant, account does not match company, or rateio Σ ≠ amount.
Rate limit exceeded for this token. Reads and writes have separate budgets, both on a 1-hour sliding window. The response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After — wait out Retry-After rather than retrying immediately.
Unhandled server error.