# Authentication Source: https://docs.piriod.com/api-reference/authentication How to authenticate requests against the Piriod API. The Piriod API uses **API tokens** combined with a **workspace header**. ## API tokens Tokens are obtained from the Piriod dashboard (Settings → API tokens). Pass the token on every request: ```http theme={null} Authorization: Token sk_live_xxxxxxxxxxxxxxxxxxxxxxxx ``` Do not include the token in client-side code. Treat it as a secret. Each user has at most one active API token. Generating a new token from the dashboard invalidates the previous one. ## Workspace header Piriod is multi-workspace: a single user can belong to several accounts. Every request must declare which workspace it operates on: ```http theme={null} x-simple-workspace: acc_01H8XYZ123ABC ``` Requests without this header (or with a workspace the user does not belong to) return `400` or `403`. ## Test mode Set `x-piriod-test-mode: true` to operate against test data — separate from your production data. Resources created in test mode are returned only when this header is `true`. ```http theme={null} x-piriod-test-mode: true ``` ## Publishable keys (payment links) Hosted payment-link endpoints under `/publishable/payment_links/...` are designed to be called from the browser using the link's `publishable_key`. These endpoints do not require `Authorization: Token`. They are read-only or limited to payment-intent operations. ## Putting it all together ```bash theme={null} curl https://api.piriod.com/invoices/ \ -H "Authorization: Token sk_live_xxxxx" \ -H "x-simple-workspace: acc_01H8XYZ123ABC" \ -H "x-piriod-test-mode: false" ``` # Archive addon Source: https://docs.piriod.com/api-reference/billing/addons/archive-addon DELETE /addons/{id}/ # Create addon Source: https://docs.piriod.com/api-reference/billing/addons/create-addon POST /addons/ # List addons Source: https://docs.piriod.com/api-reference/billing/addons/list-addons GET /addons/ # Partial update addon Source: https://docs.piriod.com/api-reference/billing/addons/partial-update-addon PATCH /addons/{id}/ # Retrieve addon Source: https://docs.piriod.com/api-reference/billing/addons/retrieve-addon GET /addons/{id}/ # Create contact Source: https://docs.piriod.com/api-reference/billing/contacts/create-contact POST /contacts/ # Delete contact Source: https://docs.piriod.com/api-reference/billing/contacts/delete-contact DELETE /contacts/{id}/ # List contacts Source: https://docs.piriod.com/api-reference/billing/contacts/list-contacts GET /contacts/ Returns a paginated list of contacts. A customer is limited to seven contacts per organisation unit (or seven without an org unit). # Partial update contact Source: https://docs.piriod.com/api-reference/billing/contacts/partial-update-contact PATCH /contacts/{id}/ # Retrieve contact Source: https://docs.piriod.com/api-reference/billing/contacts/retrieve-contact GET /contacts/{id}/ # Archive coupon Source: https://docs.piriod.com/api-reference/billing/coupons/archive-coupon DELETE /coupons/{id}/ # Create coupon Source: https://docs.piriod.com/api-reference/billing/coupons/create-coupon POST /coupons/ # List coupons Source: https://docs.piriod.com/api-reference/billing/coupons/list-coupons GET /coupons/ # Partial update coupon Source: https://docs.piriod.com/api-reference/billing/coupons/partial-update-coupon PATCH /coupons/{id}/ # Retrieve coupon Source: https://docs.piriod.com/api-reference/billing/coupons/retrieve-coupon GET /coupons/{id}/ # Create credit note (draft) Source: https://docs.piriod.com/api-reference/billing/creditnotes/create-credit-note-draft POST /creditnotes/ Creates a credit note. If the related invoice or chosen document allows partial credit, the line totals are computed from the request; otherwise the lines mirror the invoice. # Delete credit note (draft only) Source: https://docs.piriod.com/api-reference/billing/creditnotes/delete-credit-note-draft-only DELETE /creditnotes/{id}/ # Finalize credit note Source: https://docs.piriod.com/api-reference/billing/creditnotes/finalize-credit-note GET /creditnotes/{id}/finalize/ Submits the credit note to the tax agency (when applicable) and locks the document. # List credit notes Source: https://docs.piriod.com/api-reference/billing/creditnotes/list-credit-notes GET /creditnotes/ # Partial update credit note (draft only) Source: https://docs.piriod.com/api-reference/billing/creditnotes/partial-update-credit-note-draft-only PATCH /creditnotes/{id}/ # Render credit-note PDF Source: https://docs.piriod.com/api-reference/billing/creditnotes/render-credit-note-pdf GET /creditnotes/{id}/pdf/ # Retrieve credit note Source: https://docs.piriod.com/api-reference/billing/creditnotes/retrieve-credit-note GET /creditnotes/{id}/ # Create customer Source: https://docs.piriod.com/api-reference/billing/customers/create-customer POST /customers/ # Delete customer Source: https://docs.piriod.com/api-reference/billing/customers/delete-customer DELETE /customers/{id}/ Soft-archives the customer (sets `status=archived`) when there are non-draft invoices, terminal subscriptions, valuable sources, or abandoned sources with payments. Otherwise hard-deletes the customer and any draft invoices. # List customers Source: https://docs.piriod.com/api-reference/billing/customers/list-customers GET /customers/ Returns a paginated list of customers in the workspace. # Partial update customer Source: https://docs.piriod.com/api-reference/billing/customers/partial-update-customer PATCH /customers/{id}/ # Retrieve customer Source: https://docs.piriod.com/api-reference/billing/customers/retrieve-customer GET /customers/{id}/ # Create debit note Source: https://docs.piriod.com/api-reference/billing/debitnotes/create-debit-note POST /debitnotes/ # Delete debit note Source: https://docs.piriod.com/api-reference/billing/debitnotes/delete-debit-note DELETE /debitnotes/{id}/ # List debit notes Source: https://docs.piriod.com/api-reference/billing/debitnotes/list-debit-notes GET /debitnotes/ # Partial update debit note Source: https://docs.piriod.com/api-reference/billing/debitnotes/partial-update-debit-note PATCH /debitnotes/{id}/ # Retrieve debit note Source: https://docs.piriod.com/api-reference/billing/debitnotes/retrieve-debit-note GET /debitnotes/{id}/ # Create invoice (draft) Source: https://docs.piriod.com/api-reference/billing/invoices/create-invoice-draft POST /invoices/ Creates an invoice in `draft` status. Totals (`amount`, `tax`, `subtotal`, `total`) are computed server-side from the lines. Call `finalize` to issue the invoice to the tax agency and lock it. # Delete invoice (draft only) Source: https://docs.piriod.com/api-reference/billing/invoices/delete-invoice-draft-only DELETE /invoices/{id}/ Only invoices in `draft` status can be deleted. Linked payments are unlinked. # Finalize invoice Source: https://docs.piriod.com/api-reference/billing/invoices/finalize-invoice GET /invoices/{id}/finalize/ Submits the invoice to the tax agency (when applicable) and locks the document. Requires status `draft` or `pending`. When status is `pending` all linked payments must be `succeeded`. # List invoices Source: https://docs.piriod.com/api-reference/billing/invoices/list-invoices GET /invoices/ Returns a paginated list of invoices. The list excludes draft invoices that belong to a subscription, and (unless filtered by `bulk`) invoices attached to a bulk in `pending`, `processing` or `failed` status. # Partial update invoice (draft only) Source: https://docs.piriod.com/api-reference/billing/invoices/partial-update-invoice-draft-only PATCH /invoices/{id}/ # Render invoice PDF Source: https://docs.piriod.com/api-reference/billing/invoices/render-invoice-pdf GET /invoices/{id}/pdf/ Returns the invoice PDF. Uses the fiscal format when the document type has a local biller; otherwise renders a plain HTML-to-PDF template. # Retrieve invoice Source: https://docs.piriod.com/api-reference/billing/invoices/retrieve-invoice GET /invoices/{id}/ # Toggle uncollectible Source: https://docs.piriod.com/api-reference/billing/invoices/toggle-uncollectible GET /invoices/{id}/uncollectible/ Toggles the invoice between `finalized` and `uncollectible`. Sets or clears the `uncollectible` timestamp accordingly. # Create org unit Source: https://docs.piriod.com/api-reference/billing/orgunits/create-org-unit POST /orgunits/ # Delete org unit Source: https://docs.piriod.com/api-reference/billing/orgunits/delete-org-unit DELETE /orgunits/{id}/ Refuses to delete when there are linked contacts or subscriptions; remove them first. # List organisation units Source: https://docs.piriod.com/api-reference/billing/orgunits/list-organisation-units GET /orgunits/ Returns a paginated list of organisation units. A customer can have at most twelve org units; org units are an optional sub-grouping for contacts and subscriptions. # Partial update org unit Source: https://docs.piriod.com/api-reference/billing/orgunits/partial-update-org-unit PATCH /orgunits/{id}/ # Retrieve org unit Source: https://docs.piriod.com/api-reference/billing/orgunits/retrieve-org-unit GET /orgunits/{id}/ # Create payment receipt (draft) Source: https://docs.piriod.com/api-reference/billing/payment-receipts/create-payment-receipt-draft POST /payment-receipts/ # Delete payment receipt (draft only) Source: https://docs.piriod.com/api-reference/billing/payment-receipts/delete-payment-receipt-draft-only DELETE /payment-receipts/{id}/ # Finalize payment receipt Source: https://docs.piriod.com/api-reference/billing/payment-receipts/finalize-payment-receipt GET /payment-receipts/{id}/finalize/ # List payment receipts Source: https://docs.piriod.com/api-reference/billing/payment-receipts/list-payment-receipts GET /payment-receipts/ # Partial update payment receipt (draft only) Source: https://docs.piriod.com/api-reference/billing/payment-receipts/partial-update-payment-receipt-draft-only PATCH /payment-receipts/{id}/ # Retrieve payment receipt Source: https://docs.piriod.com/api-reference/billing/payment-receipts/retrieve-payment-receipt GET /payment-receipts/{id}/ # Archive plan Source: https://docs.piriod.com/api-reference/billing/plans/archive-plan DELETE /plans/{id}/ # Create plan Source: https://docs.piriod.com/api-reference/billing/plans/create-plan POST /plans/ # List plans Source: https://docs.piriod.com/api-reference/billing/plans/list-plans GET /plans/ # Partial update plan (mutable fields) Source: https://docs.piriod.com/api-reference/billing/plans/partial-update-plan-mutable-fields PATCH /plans/{id}/ # Retrieve plan Source: https://docs.piriod.com/api-reference/billing/plans/retrieve-plan GET /plans/{id}/ # Archive product Source: https://docs.piriod.com/api-reference/billing/products/archive-product DELETE /products/{id}/ Soft-deletes the product (sets `status=archived`). Cannot be reused after archive. # Create product Source: https://docs.piriod.com/api-reference/billing/products/create-product POST /products/ # List products Source: https://docs.piriod.com/api-reference/billing/products/list-products GET /products/ # Partial update product Source: https://docs.piriod.com/api-reference/billing/products/partial-update-product PATCH /products/{id}/ # Retrieve product Source: https://docs.piriod.com/api-reference/billing/products/retrieve-product GET /products/{id}/ # Cancel subscription Source: https://docs.piriod.com/api-reference/billing/subscriptions/cancel-subscription DELETE /subscriptions/{id}/ If the subscription has no non-draft invoices it is hard-deleted; otherwise it is cancelled (`status=cancelled`, `cancelled` timestamp set) and a `cancel_reason` is recorded (defaults to `not_specified`). # Create subscription Source: https://docs.piriod.com/api-reference/billing/subscriptions/create-subscription POST /subscriptions/ # List subscriptions Source: https://docs.piriod.com/api-reference/billing/subscriptions/list-subscriptions GET /subscriptions/ # Partial update subscription Source: https://docs.piriod.com/api-reference/billing/subscriptions/partial-update-subscription PATCH /subscriptions/{id}/ # Pause subscription Source: https://docs.piriod.com/api-reference/billing/subscriptions/pause-subscription POST /subscriptions/{id}/pause/ # Resume subscription Source: https://docs.piriod.com/api-reference/billing/subscriptions/resume-subscription POST /subscriptions/{id}/resume/ # Retrieve subscription Source: https://docs.piriod.com/api-reference/billing/subscriptions/retrieve-subscription GET /subscriptions/{id}/ # List usages Source: https://docs.piriod.com/api-reference/billing/usages/list-usages GET /usages/ # Record usage Source: https://docs.piriod.com/api-reference/billing/usages/record-usage POST /usages/ # List exchange rates Source: https://docs.piriod.com/api-reference/collections/generals/changes/list-exchange-rates GET /generals/changes/ Historical exchange rates between currencies. # List countries Source: https://docs.piriod.com/api-reference/collections/generals/countries/list-countries GET /generals/countries/ Reference catalogue of supported countries. # List currencies Source: https://docs.piriod.com/api-reference/collections/generals/currencies/list-currencies GET /generals/currencies/ Reference catalogue of currencies. Public endpoint — does not require authentication or workspace headers. # List document types Source: https://docs.piriod.com/api-reference/collections/generals/documents/list-document-types GET /generals/documents/ Reference catalogue of fiscal document types per country. # List document reference types Source: https://docs.piriod.com/api-reference/collections/generals/references/list-document-reference-types GET /generals/references/ Reference catalogue of document-reference types (used to link an invoice to a previous document, e.g. credit notes). # List states / provinces Source: https://docs.piriod.com/api-reference/collections/generals/states/list-states-provinces GET /generals/states/ # Error handling Source: https://docs.piriod.com/api-reference/error-handling Status codes and response shapes when something goes wrong. ## Status codes | Code | Meaning | | ----- | ------------------------------------------------------------------------------------- | | `200` | OK. Returned on `GET`, `PATCH`, `PUT` and most action endpoints. | | `201` | Created. Returned on `POST` for new resources. | | `204` | No Content. Returned on `DELETE`. | | `400` | Bad Request. Validation error (see body). | | `401` | Unauthorized. Missing or invalid `Authorization` header. | | `403` | Forbidden. Authenticated but not allowed (e.g. wrong workspace). | | `404` | Not Found. Either the resource does not exist or it does not belong to the workspace. | | `405` | Method Not Allowed. The HTTP verb is not supported by the endpoint. | | `500` | Internal Server Error. Open a support ticket if it persists. | ## Response shapes ### Generic errors For `401`, `403`, `404` and most `500` cases: ```json theme={null} { "detail": "Authentication credentials were not provided." } ``` ### Validation errors For `400`, errors are returned as a field-keyed map. Errors not bound to a single field are grouped under `non_field_errors`: ```json theme={null} { "name": ["This field is required."], "tax_id": ["Invalid format."], "non_field_errors": ["x-simple-workspace header is required."] } ``` ## Common pitfalls * **`x-simple-workspace` missing** → `400` with `non_field_errors: ["x-simple-workspace header is required."]`. * **Wrong workspace ID** → `403` (the user is not a member of that workspace). * **Tax-regulated country, missing `tax_id` or `tax_settings`** → `400` with field-specific errors. * **Trying to delete a customer with active subscriptions** → `400`. Cancel the subscriptions first or the customer is archived instead. ## Retries The API does not currently support an idempotency header. Treat write requests as non-idempotent and avoid blind retries on `5xx` for endpoints that create financial records. # Integration flows Source: https://docs.piriod.com/api-reference/integration-flows End-to-end scenarios for the most common Piriod use cases. This page describes the most common flows. Each step links to the relevant API Reference entry. ## 1. One-shot billing: customer → invoice → payment POST `/customers/` with `name`, `address`, `country`, `state` and (when applicable) `tax_id` + `tax_settings`. The response includes a customer `id` you will reuse below. POST `/invoices/` with the `customer` id and the line items. The invoice starts in `draft` status. Call the `finalize` action on the invoice to send it to the tax agency (when applicable) and lock its content. POST `/payments/` linking the invoice and a reusable `source`, or share a payment link from `/payment_links/links/` for hosted checkout. ## 2. Recurring billing with subscriptions Create products at `/products/`, plans at `/plans/` and optional add-ons or coupons. POST `/subscriptions/` with the customer, the plan and the chosen frequency. Piriod will compute the next billing date. Each cycle Piriod generates the invoice; the matching webhook event lets you react. You can also call the `process` action manually. Use `pause`, `resume` and `DELETE` on the subscription resource. ## 3. Hosted payment links POST `/payment_links/links/` with the amount and currency. Capture the `publishable_key` from the response. Send `/publishable/payment_links/links/{key}/hosted/` to the payer. They complete the checkout in Piriod-hosted UI. The created `intent` exposes status transitions (authorized → captured → finalized) you can poll or listen for via webhook. ## 4. Procurement: receive supplier documents POST `/suppliers/` with their tax identifier and contact info. POST `/purchases/` (or `/purchases/credit-notes/` for credit notes) with the supplier and line items. POST `/retentions/` linked to the purchase when withholding taxes apply. Call `finalize` on each document to submit it to the tax agency. # Introduction Source: https://docs.piriod.com/api-reference/introduction Welcome to the Piriod API. Piriod is a billing, payments, procurement and collections platform. The API exposes the same building blocks our dashboard uses, so you can issue invoices, charge cards, manage subscriptions and reconcile payments programmatically. ## Base URL ```text Production theme={null} https://api.piriod.com ``` ```text Development theme={null} https://api.dev.piriod.com ``` ## Required headers on every request | Header | Required | Description | | -------------------- | -------- | ----------------------------------------------------------- | | `Authorization` | Yes | `Token `. See [Authentication](/authentication). | | `x-simple-workspace` | Yes | The workspace (account) identifier you are operating on. | | `x-piriod-test-mode` | No | `true` to use test-mode data. Defaults to `false`. | ## Hello world ```bash theme={null} curl https://api.piriod.com/customers/ \ -H "Authorization: Token sk_live_xxxxx" \ -H "x-simple-workspace: acc_01H8XYZ123ABC" ``` The response is a paginated list of customers; see [Pagination and filtering](/pagination-filtering). ## What's next * [Integration flows](/integration-flows) walks you through end-to-end scenarios. * [Authentication](/authentication) explains tokens and workspaces. * [Error handling](/error-handling) covers the response shape on failures. * The **API Reference** tab lists every endpoint grouped by section. # Pagination and filtering Source: https://docs.piriod.com/api-reference/pagination-filtering Working with list endpoints: pagination, filters, ordering and search. ## Pagination List endpoints return a paginated payload: ```json theme={null} { "count": 142, "next": "https://api.piriod.com/customers/?page=2", "previous": null, "results": [ /* items of the current page */ ] } ``` Control pagination with query parameters: | Parameter | Type | Default | Notes | | ----------- | ------- | ------- | --------------------------- | | `page` | integer | `1` | 1-indexed page number. | | `page_size` | integer | `20` | Items per page (max `100`). | ```bash theme={null} curl "https://api.piriod.com/customers/?page=2&page_size=50" \ -H "Authorization: Token sk_live_xxxxx" \ -H "x-simple-workspace: acc_..." ``` ## Filtering Filters are exposed as query parameters. Each list endpoint declares the filterable fields in the API Reference (see the Parameters tab). For example, `GET /customers/` accepts `country`, `email`, `name`, `tax_id`, `created`, `subscriptions`, `sources`. Common patterns: ```bash theme={null} # exact match ?status=active # range (date or numeric fields) ?created__gte=2026-01-01&created__lte=2026-01-31 # membership ?status__in=draft,finalized # nested foreign keys ?customer=cus_01H8XYZ123ABC ``` ### Filtering by metadata Resources that expose a `metadata` field accept arbitrary filters using the `metadata__` pattern: ```bash theme={null} ?metadata__order_id=12345 ``` ## Ordering Use `ordering` to sort the results. Prefix the field name with `-` for descending order: ```bash theme={null} ?ordering=name ?ordering=-created ``` Each list endpoint declares its supported ordering fields. ## Search Some endpoints expose `search` for free-text matching across configured fields: ```bash theme={null} ?search=acme ``` # Create ACH adjustment Source: https://docs.piriod.com/api-reference/payments/ach_transfers/adjustments/create-ach-adjustment POST /ach_transfers/adjustments/ # Delete ACH adjustment Source: https://docs.piriod.com/api-reference/payments/ach_transfers/adjustments/delete-ach-adjustment DELETE /ach_transfers/adjustments/{id}/ Reverses the adjustment on the parent transfer. The transfer must be `pending`. # List ACH adjustments Source: https://docs.piriod.com/api-reference/payments/ach_transfers/adjustments/list-ach-adjustments GET /ach_transfers/adjustments/ # Archive ACH transfer Source: https://docs.piriod.com/api-reference/payments/ach_transfers/archive-ach-transfer DELETE /ach_transfers/{id}/ Archives the transfer (status `pending` only). Sets `status=archived` and an `archived` timestamp. # List ACH transfers Source: https://docs.piriod.com/api-reference/payments/ach_transfers/list-ach-transfers GET /ach_transfers/ Lists ACH transfers. By default, archived transfers are excluded; pass `status=archived` to include them. # Retrieve ACH transfer Source: https://docs.piriod.com/api-reference/payments/ach_transfers/retrieve-ach-transfer GET /ach_transfers/{id}/ # Create boleto Source: https://docs.piriod.com/api-reference/payments/boletos/create-boleto POST /boletos/ # Delete boleto Source: https://docs.piriod.com/api-reference/payments/boletos/delete-boleto DELETE /boletos/{id}/ # List boletos Source: https://docs.piriod.com/api-reference/payments/boletos/list-boletos GET /boletos/ # Retrieve boleto Source: https://docs.piriod.com/api-reference/payments/boletos/retrieve-boleto GET /boletos/{id}/ # Authorize payment (publishable) Source: https://docs.piriod.com/api-reference/payments/payments/authorize-payment-publishable POST /payments/{id}/authorize/ Public endpoint used during a checkout flow. Attaches a `source` to the payment and authorizes the gateway transaction. Does **not** require authentication; the payment is found by its ID alone, so its `enable_checkout` flag must be `true`. # Create payment Source: https://docs.piriod.com/api-reference/payments/payments/create-payment POST /payments/ # Delete payment Source: https://docs.piriod.com/api-reference/payments/payments/delete-payment DELETE /payments/{id}/ Refuses to delete payments in `succeeded` or `processing` status, or payments linked to an invoice. # List payments Source: https://docs.piriod.com/api-reference/payments/payments/list-payments GET /payments/ # Retrieve payment Source: https://docs.piriod.com/api-reference/payments/payments/retrieve-payment GET /payments/{id}/ # Create refund Source: https://docs.piriod.com/api-reference/payments/refunds/create-refund POST /refunds/ Issues a refund against a payment. The total of refund amounts cannot exceed the payment's amount. # Create source (publishable) Source: https://docs.piriod.com/api-reference/payments/sources/create-source-publishable POST /sources/ Creates a payment source. This endpoint accepts unauthenticated calls from the browser (publishable flow), so the request is identified by the gateway/customer/payment context rather than a workspace header. # Delete or finalize source Source: https://docs.piriod.com/api-reference/payments/sources/delete-or-finalize-source DELETE /sources/{id}/ For reusable sources: detaches the tokenization at the gateway and either finalizes the source (when it has linked payments) or hard- deletes it. For single-use sources tied to ACH transfers, releases the balance back to the transfer. Refuses to delete other single-use sources. # List sources Source: https://docs.piriod.com/api-reference/payments/sources/list-sources GET /sources/ # Retrieve source Source: https://docs.piriod.com/api-reference/payments/sources/retrieve-source GET /sources/{id}/ # Create cancellation Source: https://docs.piriod.com/api-reference/procurement/cancellations/create-cancellation POST /cancellations/ # List cancellations Source: https://docs.piriod.com/api-reference/procurement/cancellations/list-cancellations GET /cancellations/ # Retrieve cancellation Source: https://docs.piriod.com/api-reference/procurement/cancellations/retrieve-cancellation GET /cancellations/{id}/ # Create order (draft) Source: https://docs.piriod.com/api-reference/procurement/orders/create-order-draft POST /orders/ # Delete order Source: https://docs.piriod.com/api-reference/procurement/orders/delete-order DELETE /orders/{id}/ # Finalize order Source: https://docs.piriod.com/api-reference/procurement/orders/finalize-order GET /orders/{id}/finalize/ # List orders Source: https://docs.piriod.com/api-reference/procurement/orders/list-orders GET /orders/ # Partial update order Source: https://docs.piriod.com/api-reference/procurement/orders/partial-update-order PATCH /orders/{id}/ # Render order PDF Source: https://docs.piriod.com/api-reference/procurement/orders/render-order-pdf GET /orders/{id}/pdf/ # Retrieve order Source: https://docs.piriod.com/api-reference/procurement/orders/retrieve-order GET /orders/{id}/ # Create purchase (draft) Source: https://docs.piriod.com/api-reference/procurement/purchases/create-purchase-draft POST /purchases/ # Create purchase credit note (draft) Source: https://docs.piriod.com/api-reference/procurement/purchases/credit-notes/create-purchase-credit-note-draft POST /purchases/credit-notes/ # Delete purchase credit note (draft only) Source: https://docs.piriod.com/api-reference/procurement/purchases/credit-notes/delete-purchase-credit-note-draft-only DELETE /purchases/credit-notes/{id}/ # Finalize purchase credit note Source: https://docs.piriod.com/api-reference/procurement/purchases/credit-notes/finalize-purchase-credit-note GET /purchases/credit-notes/{id}/finalize/ # List purchase credit notes Source: https://docs.piriod.com/api-reference/procurement/purchases/credit-notes/list-purchase-credit-notes GET /purchases/credit-notes/ # Partial update purchase credit note (draft only) Source: https://docs.piriod.com/api-reference/procurement/purchases/credit-notes/partial-update-purchase-credit-note-draft-only PATCH /purchases/credit-notes/{id}/ # Render purchase credit-note PDF Source: https://docs.piriod.com/api-reference/procurement/purchases/credit-notes/render-purchase-credit-note-pdf GET /purchases/credit-notes/{id}/pdf/ # Retrieve purchase credit note Source: https://docs.piriod.com/api-reference/procurement/purchases/credit-notes/retrieve-purchase-credit-note GET /purchases/credit-notes/{id}/ # Delete purchase (draft only) Source: https://docs.piriod.com/api-reference/procurement/purchases/delete-purchase-draft-only DELETE /purchases/{id}/ # Finalize purchase Source: https://docs.piriod.com/api-reference/procurement/purchases/finalize-purchase GET /purchases/{id}/finalize/ Submits the purchase to the tax agency (when applicable) and locks it. # List purchases Source: https://docs.piriod.com/api-reference/procurement/purchases/list-purchases GET /purchases/ # Partial update purchase (draft only) Source: https://docs.piriod.com/api-reference/procurement/purchases/partial-update-purchase-draft-only PATCH /purchases/{id}/ # Render purchase PDF Source: https://docs.piriod.com/api-reference/procurement/purchases/render-purchase-pdf GET /purchases/{id}/pdf/ # Retrieve purchase Source: https://docs.piriod.com/api-reference/procurement/purchases/retrieve-purchase GET /purchases/{id}/ # Create retention (draft) Source: https://docs.piriod.com/api-reference/procurement/retentions/create-retention-draft POST /retentions/ # Delete retention (draft only) Source: https://docs.piriod.com/api-reference/procurement/retentions/delete-retention-draft-only DELETE /retentions/{id}/ # Finalize retention Source: https://docs.piriod.com/api-reference/procurement/retentions/finalize-retention GET /retentions/{id}/finalize/ # List retentions Source: https://docs.piriod.com/api-reference/procurement/retentions/list-retentions GET /retentions/ # Partial update retention (draft only) Source: https://docs.piriod.com/api-reference/procurement/retentions/partial-update-retention-draft-only PATCH /retentions/{id}/ # Render retention PDF Source: https://docs.piriod.com/api-reference/procurement/retentions/render-retention-pdf GET /retentions/{id}/pdf/ # Retrieve retention Source: https://docs.piriod.com/api-reference/procurement/retentions/retrieve-retention GET /retentions/{id}/ # Create supplier Source: https://docs.piriod.com/api-reference/procurement/suppliers/create-supplier POST /suppliers/ # Delete supplier Source: https://docs.piriod.com/api-reference/procurement/suppliers/delete-supplier DELETE /suppliers/{id}/ # List suppliers Source: https://docs.piriod.com/api-reference/procurement/suppliers/list-suppliers GET /suppliers/ # Partial update supplier Source: https://docs.piriod.com/api-reference/procurement/suppliers/partial-update-supplier PATCH /suppliers/{id}/ # Retrieve supplier Source: https://docs.piriod.com/api-reference/procurement/suppliers/retrieve-supplier GET /suppliers/{id}/ # Julio 2024 Source: https://docs.piriod.com/changelog/2024/julio-2024 ## Previsualización de próxima factura ### Mejora Ahora puedes visualizar cómo será la próxima factura antes de que sea emitida. Esto permite revisar información y validar el resultado del siguiente ciclo de facturación antes de generar el documento final. *** ## Visualización del próximo procesamiento de suscripciones ### Mejora Ahora puedes visualizar la fecha y hora exacta del próximo procesamiento de suscripciones. Esto permite tener mayor visibilidad sobre los próximos intentos de facturación y procesamiento de pagos. *** ## Procesar ahora ### Nueva funcionalidad Se incorporó la opción Procesar ahora para ejecutar manualmente el procesamiento de una suscripción sin esperar el batch automático. La opción permite procesar suscripciones programadas para el día actual o períodos anteriores, facilitando la emisión inmediata de facturas o el procesamiento de pagos. *** ## Planes obligatorios en Signup Forms ### Mejora Ahora puedes definir un plan obligatorio en Signup Forms. Cuando un cliente complete el formulario, el plan configurado aparecerá seleccionado de forma predeterminada y será identificado con la etiqueta Requerido. *** ## Complementos predeterminados en Signup Forms ### Mejora Ahora puedes configurar complementos predeterminados en Signup Forms. Los complementos definidos aparecerán precargados automáticamente al momento de completar el formulario de inscripción. # Septiembre 2024 Source: https://docs.piriod.com/changelog/2024/septiembre-2024 ## Links de Pago ### Nueva funcionalidad Se incorporó soporte para Links de Pago, permitiendo generar enlaces para cobrar pagos de forma rápida y centralizada. Los Links de Pago permiten: * Generar enlaces de pago personalizados. * Definir un monto fijo o permitir que el cliente ingrese el valor a pagar. * Procesar pagos utilizando los procesadores configurados en Piriod. * Generar automáticamente una factura después de un pago exitoso. * Compartir enlaces a través de distintos canales, como sitios web, correo o redes sociales. Consulta la guía de uso para revisar configuración, funcionamiento y opciones disponibles. # Diciembre 2025 Source: https://docs.piriod.com/changelog/2025/diciembre-2025 ## Nueva funcionalidad beta: Documentos de Soporte Se incorporó la primera versión beta de Documentos de Soporte, orientada a centralizar archivos utilizados como respaldo para la emisión de facturas. Consulta más detalles en la sección Funcionalidades Beta. # Enero 2025 Source: https://docs.piriod.com/changelog/2025/enero-2025 ## Ajustes manuales en transferencias ### Mejora Ahora puedes realizar ajustes manuales en transferencias para corregir montos o monedas cuando sea necesario. Esto permite facilitar la conciliación en casos donde el pago recibido no coincide exactamente con la factura original. Los ajustes pueden utilizarse, por ejemplo, para: * Convertir manualmente transferencias recibidas en una moneda distinta a la facturada. * Ajustar diferencias por redondeos, comisiones bancarias o variaciones en el monto recibido. * Corregir montos sin depender de soporte o intervenciones externas. *** ## Configuración de mensajería por cliente ### Mejora Ahora puedes definir qué tipos de correos puede recibir cada cliente directamente desde su configuración. Las opciones disponibles son: * Facturas * Cobranzas * Comprobantes de pago Esto permite controlar el envío automático de correos según la configuración definida para cada cliente. *** ## Pagos parciales y conciliación automática ### Nueva funcionalidad Se incorporó soporte para pagos parciales y nuevos flujos de conciliación automática. Ahora es posible: * Conciliar una factura utilizando múltiples transferencias bancarias. * Registrar pagos parciales mediante transacciones offline. * Combinar transferencias y transacciones offline dentro de un mismo pago. * Conciliar parcialmente transferencias o pagos. * Asociar una transferencia a múltiples facturas. También se incorporó conciliación automática para identificar y asignar transferencias a las facturas correspondientes. Estas mejoras permiten gestionar escenarios de pago más complejos con mayor flexibilidad y menor intervención manual. *** ## Integración con Getnet ### Nueva integración Se incorporó integración con Getnet para procesar pagos en Chile utilizando tarjetas de crédito, débito y prepago. La integración incluye soporte para: ### Getnet Click Permite automatizar cobros recurrentes utilizando tarjetas registradas previamente. ### Getnet Checkout Permite procesar pagos manuales a través del portal de pagos de Piriod o mediante Links de Pago dirigidos a Getnet. Consulta la documentación de integración para revisar configuración, requisitos y funcionamiento de cada modalidad.vvfmvivbfdh # Enero 2026 Source: https://docs.piriod.com/changelog/2026/enero-2026 ## Facturación automática en Links de Pago ### Mejora Ahora los Links de Pago pueden crear automáticamente una factura cuando el pago se completa exitosamente. Al configurar un Link con facturación automática, también se debe definir el tipo de documento que será emitido. ## Nuevo comportamiento El flujo ahora funciona de la siguiente manera: 1. El cliente realiza el pago utilizando el Link. 2. Si el pago es exitoso y el Link tiene facturación automática activa, Piriod crea automáticamente la factura asociada. También se incorporaron mejoras adicionales: * Las facturas creadas con pagos previamente asociados ahora quedan automáticamente marcadas como pagadas al finalizarse. * Se mejoró el control de edición y eliminación de facturas en borrador con pagos relacionados. * Se reforzó el registro de errores en segundo plano para facilitar monitoreo y soporte. *** ## Nuevos modelos de precios ### Nueva funcionalidad Se incorporaron nuevos modelos de precios para permitir configuraciones más flexibles según distintos esquemas de cobro y consumo. Ahora puedes crear planes utilizando: * Precio fijo * Por volumen * Por volumen gradual * Por paquete * Por paquete con excedente También se mejoró la previsualización de planes, permitiendo validar con mayor claridad: * Tramos de cobro * Paquetes y excedentes * Totales estimados según unidades Los planes ahora también pueden configurarse para facturar según consumo utilizando distintos métodos de cálculo: * Suma de registros * Máximo registrado * Último registro del período Los planes existentes continúan funcionando sin cambios y mantienen compatibilidad con la facturación histórica. Consulta la guía completa para revisar ejemplos, configuraciones y casos de uso de cada modelo de precios. # Marzo 2026 Source: https://docs.piriod.com/changelog/2026/marzo- 2026 ## Auditoría de cambios en suscripciones ### Nueva funcionalidad Se incorporó historial de auditoría en suscripciones para visualizar los cambios realizados a lo largo de su ciclo de vida. La auditoría permite consultar: * Cambios realizados en la suscripción. * Fecha y hora de cada modificación. * Usuario responsable de la acción. * Motivo asociado al cambio cuando corresponda. Esta funcionalidad mejora la trazabilidad operativa y facilita procesos de revisión y auditoría. *** ## Pausa y reactivación de suscripciones ### Nueva funcionalidad Ahora es posible pausar y reactivar suscripciones directamente desde Piriod. Al pausar una suscripción, puedes definir opcionalmente una fecha de reactivación automática. Cuando se alcanza la fecha configurada, la suscripción se reactiva automáticamente y continúa su procesamiento de facturación correspondiente. *** ## Archivado y eliminación de clientes ### Nueva funcionalidad Ahora es posible archivar o eliminar clientes directamente desde Piriod. Los clientes con información asociada, como suscripciones, facturas, pagos o tarjetas, pueden ser archivados para mantener su historial y evitar nuevos usos operativos. Los clientes sin registros asociados pueden eliminarse permanentemente desde la plataforma. *** ## Archivado y eliminación de suscripciones ### Nueva funcionalidad Ahora es posible archivar o eliminar suscripciones directamente desde Piriod. Las suscripciones con información asociada permanecen disponibles como historial mediante archivado, evitando su uso en nuevos procesos operativos. Las suscripciones sin registros asociados pueden eliminarse permanentemente desde la plataforma. *** ## Nuevos campos configurables en comprobantes de pago SAT ### Mejora Se incorporaron nuevos campos configurables en comprobantes de pago SAT para entregar mayor control sobre la información emitida. Ahora es posible definir: * Fecha * Forma de pago * Método de pago * Tipo de cambio para clientes extranjeros con moneda distinta a MXN Esta mejora facilita la emisión de comprobantes ajustados a distintos escenarios operativos y tributarios en México. *** ## Soporte para retenciones ISR en facturas (México) ### Mejora Se incorporó soporte para retenciones ISR en ítems de factura para documentos emitidos en México. Ahora es posible configurar y procesar retenciones asociadas a líneas específicas de la factura, permitiendo una emisión más compatible con requerimientos tributarios del SAT. *** ## Reincorporación de comprobantes de cancelación (México) ### Mejora Se reincorporó soporte para comprobantes de cancelación en documentos emitidos para México, permitiendo mantener compatibilidad con procesos tributarios asociados al SAT. *** ## Soporte para complementos de pago parciales (México) ### Mejora Se incorporó soporte para complementos de pago parciales en documentos emitidos para México. Esta mejora permite registrar y procesar pagos parciales asociados a facturas dentro de los flujos compatibles con el SAT. *** ## Importación de facturas vía correo electrónico ### Nueva integración Se incorporó soporte para importar automáticamente facturas electrónicas recibidas por correo electrónico hacia Piriod. La integración permite procesar documentos XML adjuntos desde cuentas Gmail compatibles e importarlos automáticamente a la plataforma. Esta funcionalidad facilita la integración con proveedores de facturación externos y reduce procesos manuales de carga documental. *** ## Creación automática de clientes en importación XML ### Mejora Se incorporó creación automática de clientes durante la importación de facturas XML DTE. Ahora, cuando el cliente asociado no existe previamente en Piriod, la plataforma puede crearlo automáticamente utilizando la información disponible en el documento importado. También se mejoró la validación y visualización de errores durante el proceso de importación. *** ## Nuevas métricas de ARR ### Mejora Se incorporaron nuevas métricas de ARR (Annual Recurring Revenue) dentro de Reportes. Estas métricas permiten visualizar ingresos recurrentes anualizados y complementar el análisis financiero disponible en Piriod. *** ## Mejoras en sistema de métricas ### Mejora Se realizaron mejoras internas en el sistema de métricas para optimizar procesamiento, consistencia y disponibilidad de información en Reportes y Dashboards. *** ## Mejoras en visualización del botón Pagar en correos de factura ### Corrección Se corrigió la visualización del botón Pagar en correos de facturación y recordatorios. Ahora el botón solo se muestra cuando la cuenta tiene métodos de cobro o información de pago configurada en Piriod, evitando confusión en clientes finales al momento de realizar pagos. # Mayo 2026 Source: https://docs.piriod.com/changelog/2026/mayo-2026 ## Impuestos en documentos genéricos ### Mejora Ahora es posible configurar impuestos en documentos genéricos como Invoice y Recibo. La tasa de impuesto puede definirse al crear la factura o la suscripción, permitiendo calcular automáticamente el total correspondiente. Esta mejora aplica para documentos utilizados en países sin facturación electrónica regulada. Los documentos electrónicos de Chile, México y Brasil continúan utilizando las reglas tributarias definidas por cada tipo de documento. *** ## Corrección de duplicados en intercambio de facturas ### Corrección Se mejoró el procesamiento de facturas electrónicas recibidas mediante intercambio en Chile para evitar la creación de documentos duplicados. Ahora, si una factura ya fue procesada previamente, el sistema la identifica correctamente y evita generar registros repetidos. *** ## Nuevas vistas Pendiente e Historial en Customer Base ### Mejora Se incorporaron nuevas vistas en Customer Base para facilitar la visualización de documentos pendientes e históricos. Ahora las facturas se organizan en dos pestañas: * Pendiente: muestra documentos vencidos o próximos a vencer. * Historial: muestra documentos pagados o anulados. Si el cliente no tiene documentos pendientes, la visualización se mantiene como anteriormente. La funcionalidad se encuentra disponible en español, inglés y portugués. *** ## Mejoras en edición de suscripciones sin medio de pago válido ### Mejora Ahora es posible editar suscripciones aunque la tarjeta asociada ya no se encuentre disponible o haya expirado. También se incorporó la opción de eliminar el medio de pago asociado directamente desde la edición de la suscripción. Además, el sistema ahora evita eliminar tarjetas que estén siendo utilizadas por suscripciones activas, pausadas o que requieran atención. *** ## Corrección en edición de tipos de factura en Signup Forms ### Corrección Se corrigió un problema que impedía editar los tipos de factura configurados en Signup Forms. Ahora es posible modificar tipos de factura, visualizar correctamente las monedas disponibles y guardar cambios sin necesidad de recrear el formulario. *** ## Automatización de solicitudes en Documentos de Soporte ### Mejora Documentos de Soporte incorporó nuevas capacidades para automatizar la gestión de órdenes de compra y HES asociadas a procesos de facturación. Ahora es posible: * Gestionar solicitudes desde una vista Kanban. * Enviar solicitudes directamente desde Piriod. * Configurar solicitudes automáticas por cliente. * Realizar seguimiento automático de estados y vencimientos. Consulta la sección Documentos de Soporte para revisar el funcionamiento completo de la funcionalidad. *** ## Nuevo Dashboard principal ### Mejora Se actualizó el Dashboard principal de Piriod incorporando nuevas vistas y navegación por pestañas para facilitar el acceso a métricas operativas y financieras. El Dashboard ahora organiza la información en las siguientes secciones: * Resumen * Ingresos * Suscripciones * Facturación * Dashboard personalizado El Dashboard personalizado permite configurar métricas utilizando las métricas disponibles en Reportes. Esta actualización mejora la visualización de información clave y permite acceder más fácilmente a métricas específicas según el análisis requerido. La vista personalizada permite configurar métricas utilizando las [métricas disponibles en Reportes](/guia/reportes/coleccion-de-metricas). # Crear complemento de pago Source: https://docs.piriod.com/developers/api-templates/mx-create-payment-complement Emitir **complemento de pago** (SAT México) con Piriod requiere 4 llamadas a la API en la siguiente secuencia: 1. Crear Source 2. Autorizar Payment usando el Source previamente creado 3. Crear Payment Receipt (SAT) 4. Finalizar Payment Receipt (SAT) En este paso se registra el **origen del pago** en Piriod. El `Source` representa la fuente de pago y contiene la información clave del monto, cliente, método y contexto (en este caso, un `offline_payment` vía transferencia bancaria en MXN). Aquí todavía **no se está autorizando ni asociando el pago a un pago existente**. Solo se está declarando formalmente el instrumento/origen que luego será utilizado para autorizar el pago. Este paso es obligatorio porque el comprobante SAT se genera a partir de un **pago autorizado**, y ese pago debe tener un `source` válido asociado. **Output clave que debes guardar:** * `source.id` → se utilizará en el Paso 2 ```javascript JavaScript theme={null} const createSource = async function () { const payload = { amount: "116000", description: "Prueba", gateway: "offline_payment", offline_payment: { currency: "MXN", date: "2026-02-24", method: "bank_transfer", }, usage: "single", customer: "cus_xxxxxxxxx", }; const source = await piriod.resource.create("sources", payload); // Guarda el ID para el Paso 2 console.log("source.id:", source?.id); return source; }; ``` ```python Python theme={null} import requests def create_source(): url = f"{BASE_URL}/sources/" payload = { "amount": "116000", "description": "Prueba", "gateway": "offline_payment", "offline_payment": { "currency": "MXN", "date": "2026-02-24", "method": "bank_transfer", }, "usage": "single", "customer": "cus_xxxxxxxxx", } resp = requests.post(url, json=payload, headers=headers, timeout=30) resp.raise_for_status() source = resp.json() print("source.id:", source.get("id")) return source # source = create_source() ``` ```shellscript cURL theme={null} curl https://api.piriod.com/sources/ \ -X POST \ -H "Authorization: your-user-api-key" \ -H "X-Simple-Workspace: your-organization-id" \ -H "Content-Type: application/json" \ -d '{ "amount": "116000", "description": "Prueba", "gateway": "offline_payment", "offline_payment": { "currency": "MXN", "date": "2026-02-24", "method": "bank_transfer" }, "usage": "single", "customer": "cus_xxxxxxxxx" }' ``` En este paso se **autoriza el pago existente**, asociándolo al `Source` creado previamente. La autorización indica que el pago fue validado y aceptado dentro del sistema, cambiando su estado (por ejemplo, a `authorized` o equivalente). Sin este paso, el comprobante SAT no puede generarse, ya que únicamente se permite emitirlo sobre pagos autorizados. Este es el momento en que:​ * ​El pago queda formalmente respaldado por un origen de fondos. * ​El sistema valida que el monto y el método sean consistentes. **Inputs necesarios:** * ​`paymentId` * ​`sourceId` **Output clave a validar:** * ​`payment.status` debe reflejar un estado autorizable (ej: `authorized`). ```javascript JavaScript theme={null} const authorizePayment = async function ({ paymentId, sourceId }) { const payload = { source: sourceId, }; const payment = await piriod.resource.create( `payments/${paymentId}`, payload, "authorize" ); console.log("payment.id:", payment?.id); console.log("payment.status:", payment?.status); return payment; }; ``` ```python Python theme={null} import requests def authorize_payment(payment_id: str, source_id: str): url = f"{BASE_URL}/payments/{payment_id}/authorize/" payload = {"source": source_id} resp = requests.post(url, json=payload, headers=headers, timeout=30) resp.raise_for_status() payment = resp.json() print("payment.id:", payment.get("id")) print("payment.status:", payment.get("status")) return payment # payment = authorize_payment(payment_id="pay_lM2nB28b3Nu2yc70LL", source_id="src_xxxxx") ``` ```shellscript cURL theme={null} curl https://api.piriod.com/payments/:payment_id/authorize/ \ -X POST \ -H "Authorization: your-user-api-key" \ -H "X-Simple-Workspace: your-organization-id" \ -H "Content-Type: application/json" \ -d '{ "source": "src_xxxxxxxxx" }' ``` En este paso se crea el recurso `payment-receipt`, que representa el **comprobante de pago conforme a SAT México (CFDI de complemento de pago)**. Aquí todavía no se timbra ni se finaliza el comprobante; simplemente se genera el registro inicial que vincula el pago autorizado con el documento fiscal correspondiente. Este paso: * ​Valida que el pago esté autorizado. * ​Prepara la estructura fiscal necesaria para el timbrado. * ​Genera un `receipt.id` que será utilizado en el paso siguiente. **Output clave a guardar:** * ​`receipt.id` * ​`receipt.status` (usualmente en estado preliminar o pendiente) ```javascript JavaScript theme={null} const createPaymentReceipt = async function ({ sourceId }) { const payload = { sources: [sourceId], tax_settings: { mx_payment_form: "03", mx_payment_method: "PUE", mx_relation: "partial_payment_invoice" } }; const receipt = await piriod.resource.create("payment-receipts", payload); // Guarda el ID para el Paso 4 console.log("receipt.id:", receipt?.id); console.log("receipt.status:", receipt?.status); return receipt; ``` ```python Python theme={null} import requests def create_payment_receipt(source_id: str): url = f"{BASE_URL}/payment-receipts/" payload = { "sources": [source_id], "tax_settings": { "mx_payment_form": "03", "mx_payment_method": "PUE", "mx_relation": "partial_payment_invoice" } } resp = requests.post(url, json=payload, headers=headers, timeout=30) resp.raise_for_status() receipt = resp.json() print("receipt.id:", receipt.get("id")) print("receipt.status:", receipt.get("status")) return receipt # receipt = create_payment_receipt(payment_id="pay_lM2nB28b3Nu2yc70LL") ``` ```shellscript cURL theme={null} curl https://api.piriod.com/payment-receipts/ \ -X POST \ -H "Authorization: your-user-api-key" \ -H "X-Simple-Workspace: your-organization-id" \ -H "Content-Type: application/json" \ -d '{ "sources": [sou_xxxxxxxxxxxxxx], "tax_settings": { "mx_payment_form": "03", "mx_payment_method": "PUE", "mx_relation": "partial_payment_invoice" } }' ``` ​Este paso ejecuta el proceso de **finalización y timbrado fiscal** del comprobante ante el SAT.​ Al finalizar: * ​El comprobante se valida fiscalmente. * ​Se genera el XML timbrado. * ​Se habilita el PDF (si aplica). * ​El estado cambia a finalizado (`finalized`, `issued` o similar). Este paso es el que convierte el registro preliminar en un documento fiscal válido ante el SAT. Después de esta operación, el comprobante: * ​No debería modificarse. * ​Puede ser descargado o enviado al cliente. * ​Queda registrado oficialmente como CFDI de complemento de pago. **Output esperado:** * ​`receipt.status` final. * ​`xml_url` y/o `pdf_url` (si el API los expone). ```javascript JavaScript theme={null} const finalizePaymentReceipt = async function ({ receiptId }) { const finalized = await piriod.resource.get( "payment-receipts", receiptId, "finalize" ); console.log("finalized.id:", finalized?.id); console.log("finalized.status:", finalized?.status); return finalized; }; ``` ```python Python theme={null} import requests def finalize_payment_receipt(receipt_id: str): url = f"{BASE_URL}/payment-receipts/{receipt_id}/finalize/" resp = requests.get(url, headers=headers, timeout=30) resp.raise_for_status() finalized = resp.json() print("finalized.id:", finalized.get("id")) print("finalized.status:", finalized.get("status")) return finalized # finalized = finalize_payment_receipt(receipt_id="prc_xxxxx") ``` ```shellscript cURL theme={null} curl https://api.piriod.com/payment-receipts/:payment_receipt_id/finalize/ \ -X GET \ -H "Authorization: your-user-api-key" \ -H "X-Simple-Workspace: your-organization-id" \ ``` # Overview Source: https://docs.piriod.com/developers/api-templates/overview foo # Recursos para desarrolladores Source: https://docs.piriod.com/developers/overview > Aprende a usar SDK, claves de API y herramientas de integración. ## Comenzar Usa las referencias de Piriod para crear y administrar tu integración. ## **Herramientas** # Crear un webhook Source: https://docs.piriod.com/developers/webhooks/crear-un-webhook Conoce cómo escribir el código para manejar las notificaciones al webhook. Para agregar webhooks a tu integración debes crear un endpoint para exponerlo en internet a través de una URL (por ejemplo, [https://myproduct.com/webhooks](https://myproduct.com/webhooks)). Crear un endpoint de webhook en tu servidor no es tan diferente a crear cualquier página en su sitio web o aplicación. Puede estar escrito en Ruby, PHP, NodeJS, Python usando o no un framework de Python como Flask. ## Consideraciones En cada activación de un evento, Piriod envía los datos del webhook a su endpoint en formato JSON. * `event` - corresponde al [nombre del evento](https://docs.piriod.com/guide/desarrolladores/webhooks#eventos). * `object_id` - corresponde al id del objeto que activó el evento. Por lo tanto, como mínimo, el endpoint del webhook debe esperar datos a través de una solicitud POST y confirmar la recepción exitosa de esos datos. ## Respuesta HTTP y desactivación automática Tu endpoint debe devolver un código de estado HTTP 2xx a Piriod. Cualquier respuesta fuera de este rango, incluidos los códigos 3xx, indica a Piriod que el evento no se recibió correctamente. Si endpoint devuelve un código de estado distinto de 2xx en **3 llamadas consecutivas**, el webhook se desactiva automáticamente. Deberás volver a activarlo manualmente desde el dashboard de Piriod. Dado que la entrega exitosa es fundamental, su punto final debe devolver una respuesta 2xx antes de ejecutar cualquier lógica de negocio compleja que pueda causar un error o exceder el tiempo de espera de 6 segundos. ## Example code El siguiente ejemplo muestra un endpoint de Python/Flask que confirma la recepción y luego obtiene el objeto Payment completo de la API de Piriod. ```python theme={null} import requests from flask import Flask app = Flask(__name__) PIRIOD_API = 'https://api.piriod.com' credentials = { 'Authorization': f'Token {your_piriod_token}', 'x-simple-workspace': 'your_piriod_organization_id' } @app.route('/webhooks', methods=['POST']) def webhooks(): payload = request.json if not payload: abort(400) if payload.get('event') == 'payment.created': payment = _get_payment(payload.get('id')) # do anything with your new payment return True def _get_payment(id): r = requests.get(f'{PIRIOD_API}/payments/{id}/', headers=credentials) if not r.status_code == requests.codes.ok: abort(r.status_code) return r.json() if __name__ == '__main__': app.run(debug=True) ``` Una vez que tu endpoint esté listo y sea accesible públicamente, el siguiente paso es registrarlo en Piriod. # Recibe notificaciones de eventos en tiempo real con webhooks Source: https://docs.piriod.com/developers/webhooks/overview Los webhooks de Piriod notifican a tu servicio cuando cambian los clientes, las facturas, los pagos o las suscripciones. Configura un endpoint y regístralo en dos pasos. Piriod utiliza webhooks para notificar a tu aplicación cuando se activa un evento específico en tu cuenta. Imagina un endpoint de webhook como un número de teléfono al que Piriod llama para informar sobre sucesos en tiempo real: un nuevo cliente, un pago completado o un cambio de suscripción. Tu endpoint es el código que responde a la llamada y actúa en función de la información recibida. Técnicamente, un endpoint de webhook es un código alojado en tu servidor y expuesto en una URL pública (por ejemplo, [https://myproduct.com/webhooks](https://myproduct.com/webhooks)). Puede estar escrito en Python, PHP, Node.js, Ruby o cualquier otro lenguaje. Cuando se activa un evento, Piriod envía una solicitud POST a tu endpoint con una payload JSON que contiene el nombre del evento y el ID del objeto que lo activó. Tu endpoint utiliza esa información para ejecutar la lógica de negocio correspondiente; por ejemplo, otorgar acceso a un usuario después de un pago exitoso. ## Cuándo usar webhooks Utiliza webhooks cuando tu aplicación necesite actuar tan pronto como ocurra algo en organización de Piriod. Algunos casos de uso comunes incluyen: * Nueva suscripción - otorgar acceso a un usuario en su sistema en el momento en que se crea una suscripción. * Pago fallido - revocar el acceso a su producto o notificar al usuario inmediatamente cuando falle un pago. Las notificaciones de webhook se entregan de forma asíncrona y no se recomiendan para aplicaciones críticas en cuanto al tiempo. Cuando el tiempo es crucial, utilice la API de Piriod para obtener los eventos directamente. ## Configuración en dos pasos Configurar webhooks requiere dos pasos: 1. [Crear un webhook](/guide/desarrolladores/webhooks/crear-un-webhook) en tu servicio. 2. [Registrar un webhook](/guide/desarrolladores/webhooks/registrar-un-webhook) en tu organización de Piriod. ## Eventos disponibles La tabla que aparece a continuación enumera todos los eventos que Piriod puede enviar a tu endpoint. | Event name | Description | | ---------------------- | --------------------------------------------------------------------------- | | `customer.created` | Se activa cuando se crea un cliente. | | `customer.updated` | Triggered when a customer is updated. | | `invoice.created` | Triggered when an invoice is created. | | `invoice.finalized` | Triggered when an invoice is finalized (submitted to the tax authority). | | `invoice.paid` | Triggered when an invoice is paid. | | `invoice.updated` | Triggered when an invoice is updated. | | `payment.created` | Triggered when a payment is created. | | `payment.succeeded` | Triggered when a payment succeeds. | | `payment.updated` | Triggered when a payment is updated. | | `source.created` | Triggered when a payment source is created. | | `source.stored` | Triggered when a payment source (credit/debit card) is successfully stored. | | `source.updated` | Triggered when a payment source is updated. | | `subscription.created` | Triggered when a subscription is created. | | `subscription.updated` | Triggered when a subscription is updated. | # Registrar un webhook Source: https://docs.piriod.com/developers/webhooks/registrar-un-webhook Registra la URL del endpoint de tu servicio en Piriod, selecciona los eventos a los que deseas suscribirlo y gestiona su activación, desactivación o eliminación desde el dashboard. Tras crear el endpoint del webhook en tu servicio, debes registrarlo en Piriod para que la plataforma sepa dónde enviar las notificaciones de eventos. El registro solo tarda unos segundos desde el dashboard de Piriod. ## Agrega el endpoint del webhook en tu organización En tu dashboard de Piriod, ve a **Configuración de la organización → Webhooks**. Click **+ Nuevo webhook** para abrir la configuración de registro. Complete los siguientes campos: * **URL** - ingresa la URL de tu endpoint. Debes usar HTTPS. * **Descripción** - texto opcional para identificar este endpoint. * **Eventos** - selecciona los eventos que deseas que activen este webhook. Haz clic en **Crear webhook** para finalizar el registro. Piriod comenzará a enviar eventos coincidentes a tu endpoint inmediatamente. ## Administrar el webhook Desde la vista de detalles del webhook puedes: * **Deshabilitar** - pausar la entrega de mensajes sin eliminar el endpoint. No se envían eventos mientras esté deshabilitado. * **Habilitar** - reanudar la entrega después de la desactivación. * **Eliminar** - eliminar permanentemente el endpoint. Si tu endpoint devuelve respuestas distintas de 2xx **tres veces seguidas**, Piriod lo desactiva automáticamente. Vuelve a activarlo desde esta misma vista de detalles una vez que se haya resuelto el problema. # Verificar firma Source: https://docs.piriod.com/developers/webhooks/verificar-firma Confirms que las solicitudes de webhook son auténticas calculando una firma HMAC-SHA256 con tu secreto de endpoint y comparándola con el encabezado x-piriod-signature. Piriod firma cada solicitud de webhook que envía, lo que permite confirmar que la solicitud es auténtica y no ha sido falsificada por un tercero. La verificación es opcional, pero se recomienda encarecidamente para los endpoints de producción. ## Obtén tu secreto de webhook Cada webhook registrado tiene su propio secreto único. Ve a **Configuración de la organización → Webhooks** y haz clic en el webhook que deseas verificar. Busca la sección **Secreto** y haz clic en **Copiar secreto**. Guarda este valor de forma segura en tu servidor; nunca lo expongas en el código del cliente. Cada webhook tiene una clave secreta diferente. Si utilizas varios webhooks, recupera y almacena una clave secreta para cada uno por separado. ## Verificar la firma Piriod incluye la firma en el encabezado HTTP `x-piriod-signature` de cada solicitud. Para verificarla, calcula un HMAC-SHA256 sobre los valores del payload de forma concatenada utilizando tu secreto de webhook y, a continuación, compara el resultado con el valor del encabezado. ```python theme={null} import hashlib import hmac from flask import Flask, request, abort app = Flask(__name__) WH_SECRET = 'whsecret_g9En7rfNBZBYFr968pLqPDQ6O302Q1DAI3TXi3aky1eAcUqgJg3EjBP' @app.route('/webhooks', methods=['POST']) def webhooks(): payload = request.json piriod_signature = request.headers.get('x-piriod-signature') if not _signature_is_valid(payload, piriod_signature): abort(400) if not payload: abort(400) if payload.get('event') == 'payment.created': # handle the payment.created event pass return '', 200 def _signature_is_valid(payload, piriod_signature): signature = hmac.new( WH_SECRET.encode(), msg=(''.join(map(str, payload.values()))).encode('UTF-8'), digestmod=hashlib.sha256 ).hexdigest() return signature == piriod_signature if __name__ == '__main__': app.run(debug=True) ``` Si la verificación de la firma falla, devuelve un código de estado `400` y no proceses el evento. Esto protege tu aplicación de solicitudes falsificadas. # Documentos de soporte (Beta) Source: https://docs.piriod.com/funciones beta/documentos-de-soporte Documentos de Soporte permite gestionar archivos y procesos asociados a órdenes de compra (OC), HES y otros documentos utilizados como respaldo en procesos de facturación B2B. La funcionalidad busca centralizar el seguimiento operativo previo a la emisión de facturas y reducir dependencias manuales en la gestión de documentación requerida por clientes corporativos. Actualmente esta funcionalidad se encuentra en etapa beta y continuará incorporando nuevas capacidades en próximas iteraciones. ## Funcionalidades disponibles ### Gestión de documentos Actualmente puedes: * Importar documentos de soporte en formato PDF. * Registrar información asociada al documento, como fechas, cliente y tipo de documento. * Centralizar documentos relevantes directamente en Piriod. El módulo también entrega indicadores operativos para identificar: * Documentos próximos a vencer. * Documentos vencidos. * Documentos cargados que aún no están siendo utilizados. ### Solicitudes de documentos Ahora es posible crear solicitudes de órdenes de compra y HES directamente desde Piriod. Las solicitudes permiten: * Definir destinatarios. * Asociar suscripciones relacionadas. * Configurar fechas límite. * Centralizar el seguimiento de solicitudes desde la plataforma. ### Automatización y seguimiento Documentos de Soporte incorpora automatizaciones para facilitar el seguimiento operativo de documentación requerida antes de facturar. Actualmente es posible: * Configurar solicitudes automáticas por cliente. * Detectar cobros próximos sin documentos asociados. * Enviar solicitudes automáticas según reglas configuradas. * Realizar seguimiento automático de vencimientos y estados. La funcionalidad también incorpora una vista Kanban para visualizar el estado de solicitudes y documentos dentro de un mismo flujo operativo. ## Integración con facturación Los documentos asociados pueden ser utilizados como referencia al momento de emitir facturas, manteniendo continuidad con los procesos de facturación ya configurados en Piriod. ## Próximas iteraciones Las próximas iteraciones consideran automatizaciones adicionales para facilitar la recepción y carga de documentos directamente en la plataforma. ## Sobre esta funcionalidad Documentos de Soporte continuará evolucionando de forma progresiva en base a procesos reales de facturación B2B y flujos operativos de clientes corporativos. # Introducción a funciones beta Source: https://docs.piriod.com/funciones beta/introduccion-a-funciones-beta # Funcionalidades Beta En esta sección encontrarás funcionalidades que actualmente se encuentran en etapa beta dentro de Piriod. Estas funcionalidades están en evolución y pueden incorporar nuevas capacidades, ajustes operativos o cambios en su comportamiento a medida que avanzan sus próximas entregas. El objetivo de esta etapa es validar procesos reales junto a clientes, mejorar la experiencia operativa y evolucionar cada módulo de forma progresiva. Aquí podrás revisar: * Qué funcionalidades están disponibles actualmente. * Qué capacidades se encuentran en desarrollo. * Qué cambios o mejoras serán incorporados próximamente. # Flujos De Trabajo Source: https://docs.piriod.com/guia/comenzar/flujos-de-trabajo ## Flujos de trabajo Los procesos de facturación y cobro pueden variar según el modelo de negocio. Piriod es flexible para adaptarse a distintas formas de operar — desde flujos completamente automatizados hasta procesos manuales. Explora los flujos disponibles y elige el que mejor se ajusta a tu operación. *** ### Suscripción → Facturación → Pago → Cargo automático El flujo estándar del modelo SaaS. El cliente se suscribe, registra su tarjeta y los procesos de facturación y cobro se ejecutan automáticamente en cada ciclo. **Beneficios** * Mínima supervisión * Baja tasa de facturas impagas * El cliente se suscribe de forma autónoma * Cargo automático a la tarjeta **Dificultades** * Obliga a estandarizar los planes de precios (puede convertirse en un beneficio) *** ### Suscripción → Facturación → Pago Similar al anterior, pero el cliente debe realizar el pago manualmente cada vez que recibe una factura periódica. **Beneficios** * El cliente se suscribe de forma autónoma **Dificultades** * Requiere supervisar el cumplimiento del pago * El cliente debe pagar manualmente en cada ciclo * Obliga a estandarizar los planes de precios (puede convertirse en un beneficio) *** ### Facturación → Pago → Cargo Flujo tradicional donde la organización emite la factura y realiza el cargo a la tarjeta del cliente de forma manual. **Beneficios** * Precio de los ítems totalmente flexible * Baja tasa de facturas impagas * La organización controla el momento del cargo **Dificultades** * Poca escalabilidad — el proceso se vuelve insostenible a mayor volumen de clientes *** ### Facturación → Pago Similar al anterior, pero el pago lo realiza el cliente cada vez que recibe una factura. **Beneficios** * Precio de los ítems totalmente flexible **Dificultades** * Poca escalabilidad — el proceso se vuelve insostenible a mayor volumen de clientes * Requiere supervisar el cumplimiento del pago * El cliente debe pagar manualmente en cada ciclo *** ### Pago → Cargo Flujo simplificado que elimina la emisión de facturas. El cobro se realiza directamente a la tarjeta del cliente. Su viabilidad depende de la normativa fiscal del país donde opera el negocio. **Beneficios** * Monto a cobrar totalmente flexible * La organización controla el momento del cargo **Dificultades** * En la mayoría de los casos no cumple con la obligación de emitir factura o recibo * Poca escalabilidad — el proceso se vuelve insostenible a mayor volumen de clientes *** ### Pago El cliente realiza el pago cada vez que recibe un enlace de cobro enviado por la organización. No se emite factura. **Beneficios** * Monto a cobrar totalmente flexible **Dificultades** * Poca escalabilidad — el proceso se vuelve insostenible a mayor volumen de clientes * Requiere supervisar el cumplimiento del pago * El cliente debe pagar manualmente en cada ciclo # Introducción a Piriod Source: https://docs.piriod.com/guia/comenzar/introduccion-a-piriod Piriod es una plataforma que automatiza la gestión de suscripciones, facturación y pagos recurrentes. Permite administrar todo el ciclo de ingresos de tu negocio — desde la creación de clientes y suscripciones, hasta la emisión de documentos y la cobranza. Con Piriod puedes: * Crear y gestionar suscripciones recurrentes * Configurar distintos modelos de cobro (fijo, por volumen, por uso, entre otros) * Emitir documentos automáticamente * Procesar pagos y hacer seguimiento de la cobranza * Centralizar toda la operación en un solo lugar Esta guía te ayudará a configurar Piriod y entender cómo usar cada módulo paso a paso. *** ## **Módulos principales** Piriod está organizado en distintos módulos, cada uno enfocado en una parte del proceso de cobro y gestión de suscripciones. *** | Módulo | Descripción | | :---------------- | :------------------------------------------------------------------ | | **Suscripciones** | Gestión de productos, planes y cobros recurrentes | | **Facturación** | Emisión y seguimiento de documentos | | **Ingresos** | Gestión de pagos y cuentas por cobrar | | **Contactos** | Gestión de clientes, personas y unidades organizativas | | **Componentes** | Formularios de suscripción, portal de autogestión y links de pago | | **Reportes** | Organización y personalización de métricas | | **Integraciones** | Procesadores de facturación, pago y otras integraciones disponibles | *** ## **Primeros pasos** Sigue estos pasos para comenzar a usar Piriod: 1. **Conectar un procesador de pago** — ve a **Integraciones → Procesadores de pago** y conecta uno de los proveedores disponibles para comenzar a recibir pagos. 2. **Configurar facturación** — si operas en un país con facturación electrónica, ve a **Integraciones → Procesadores de facturación** y configura la integración correspondiente. 3. **Crear un cliente** — ve a **Contactos → Clientes → Nuevo** e ingresa la información del cliente. 4. **Crear un producto y plan** — ve a **Suscripciones → Productos → Nuevo** y define el producto, su plan de precios y frecuencia de facturación. 5. **Crear una suscripción** — ve a **Suscripciones → Facturas recurrentes → Nuevo**, selecciona el cliente, el plan y la fecha de inicio. Piriod se encargará automáticamente del resto. *** # Customer Base Source: https://docs.piriod.com/guia/componentes/customer-base Customer Base es un portal de autoservicio que puedes integrar en tu sitio web o aplicación para que tus clientes administren su propia suscripción y facturación — sin que tengas que desarrollarlo tú mismo. Con Customer Base, tus clientes pueden: * Administrar su información de facturación * Ver el resumen y estado de su suscripción * Administrar su tarjeta de pago * Cancelar su suscripción * Ver su historial de facturas pagadas, vencidas y por vencer Captura De Pantalla 2026 04 30 A La(s) 19 08 33 *** ## Configuración Ve a **Componentes → Customer Base → Nuevo portal de cliente**. ### Funcionalidades Activa o desactiva las capacidades que quieres habilitar para tus clientes: * **Administrar información de facturación** * **Cancelar suscripción** * **Administrar tarjeta** * **Visualizar facturación y pagos** ### Método de autenticación Define cómo se autenticarán tus clientes al acceder al portal: **Autenticación con email a través de Piriod** — Piriod gestiona el login enviando un enlace de acceso al email del cliente. No requiere desarrollo adicional. **Integrar con una autenticación existente** — usa tu propio sistema de autenticación. Requiere implementar la creación de sesiones vía API (ver sección de instalación más abajo). ### Redireccionamiento por defecto URL a la que se redirige al cliente cuando su sesión expira. Una vez configurado, haz clic en **Crear y poner en vivo**. Captura De Pantalla 2026 04 30 A La(s) 19 08 54 *** ## Instalación #### 1. Agregar el tag HTML Agrega este elemento en los lugares de tu sitio donde quieres que aparezca el portal: ```html theme={null}
``` #### 2. Agregar el fragmento de JavaScript Pega este script antes del cierre de `` en las páginas donde quieres que Customer Base aparezca: ```html theme={null} ``` #### 3. Crear una sesión para tu cliente Si usas autenticación existente, debes crear una sesión desde tu servidor para cada cliente. La sesión protege la información del cliente y permite autenticarlo con el método que prefieras. Para crear una sesión necesitas el ID del cliente y una `return_url`. Ejemplo en Python: ```python theme={null} import requests url = 'https://api.piriod.com/customer_base/sessions/' headers = { 'Authorization': f'Token {api_key}', 'x-simple-workspace': '{organization_id}' } payload = { 'base': 'bas_aiFqLDu2cUmDpWQjV1', 'customer': 'cus_18NSMz56sIVMsXo6Fy', 'return_url': 'https://dashboard.myproduct.com/', } r = requests.post(url=url, json=payload, headers=headers) ``` La respuesta incluye un atributo `key`. Devuelve ese valor al cliente y pásalo a través de `window.piriodSettings`: ```html theme={null} ``` Consulta la referencia completa en [Create a session](https://docs.piriod.com/api/applications/customer-base/sessions#create-a-session). *** ### Opciones de personalización Usa `piriodSettings.options` para personalizar la apariencia del portal. ```html theme={null} ``` #### `options.locale` Define el idioma del portal. | Valor | Descripción | | :---------------- | :------------------ | | `es_MX` (default) | Español de México | | `en_US` | Inglés | | `po_BR` | Portugués de Brasil | #### `options.backgroundColor` Define el color de fondo del portal. Acepta nombres de color CSS, hex o RGB. | Formato | Ejemplo | | :------------------------- | :------------------- | | Literal (default: `white`) | `black` | | Hexadecimal | `#F8F8F8` | | RGB | `rgb(248, 248, 248)` | # Links Source: https://docs.piriod.com/guia/componentes/links Links te permite crear enlaces de pago personalizados en segundos y comenzar a recibir pagos sin integraciones complejas. Puedes compartir el mismo enlace con múltiples clientes a través de cualquier canal — sitio web, redes sociales, email o código QR. *** ## Crear un link de pago Ve a **Componentes → Links → Nuevo link de pago**. El formulario se divide en tres pasos. En el lado derecho verás una vista previa en tiempo real de cómo quedará la página de pago. #### Paso 1 — Precio Captura De Pantalla 2026 04 30 A La(s) 19 32 41 * **Moneda** — define la moneda del cobro * **Tipo de precio** * **Precio fijo** — defines el monto * **El cliente elige cuánto pagar** — puedes sugerir un monto y opcionalmente definir un mínimo y máximo * **Monto** — visible solo si seleccionaste precio fijo #### Paso 2 — Más opciones Captura De Pantalla 2026 04 30 A La(s) 19 32 48 * **Descripción** — texto visible para el cliente en la página de pago * **Tipo de consumidor** — Empresa, Persona o ambos * **Llamado a la acción** — define el texto del botón: Pagar, Donar o Reserva #### Paso 3 — Después del pago Captura De Pantalla 2026 04 30 A La(s) 19 32 56 Define qué verá el cliente una vez completado el pago: * **Mostrar un mensaje de confirmación** — personaliza el texto que aparece al finalizar * **Redireccionar a mi sitio web** — envía al cliente a una URL específica * **Crear una factura posterior al pago** — activa esta opción para emitir un documento automáticamente Haz clic en **Crear enlace**. Los métodos de pago disponibles dependen de los procesadores conectados en tu cuenta de Piriod. *** ### Compartir el link Una vez creado el link, desde la sección **Compartir** puedes: Captura De Pantalla 2026 04 30 A La(s) 19 33 48 * **Copiar el enlace** — compártelo directamente con tus clientes o publícalo donde quieras * **Código QR** — genera y descarga un QR para compartir de forma digital o presencial. Útil para cobros en persona, reservas, eventos o donaciones * **Layout** — elige entre disposición vertical u horizontal para la página de pago * **Contenido de la página** — personaliza el título y descripción que verá el cliente * **Navegación** — agrega ítems al menú con enlaces a tus redes sociales, sitio web u otros * **Vínculos** — agrega enlaces a términos de uso y políticas de privacidad si corresponde * **Modo de prueba** — actívalo para probar el flujo sin procesar pagos reales *** ## Instalación low-code Incrusta el link directamente en tu sitio o aplicación. Copia el fragmento desde **Compartir → Con código** y pégalo antes del cierre de ``. ```html theme={null}
``` Si usas React, Vue u otro framework, inyecta el script de la forma convencional de cada uno. # Signup Forms Source: https://docs.piriod.com/guia/componentes/signup-forms Signup Forms es el formulario de suscripción de tu negocio. Tus clientes pueden elegir un plan, ingresar sus datos de facturación y configurar su método de pago — todo en un flujo guiado de tres pasos. Puedes instalarlo como una página alojada (sin código) o incrustarlo directamente en tu sitio o aplicación (low-code).