API reference
Every v1 operation, generated from the OpenAPI 3.1 contract.
Base URL https://api.dev.b2b.heru.app/v1 in development, https://api.b2b.heru.app/v1 in production. Each operation page has a playground: pick the environment, paste your client_id and client_secret to get a token, and send. Your credentials stay in your browser tab.
| Prefix | Resource |
|---|---|
cmp_ | Company |
fv_ | Fiscal validation |
ssv_ | Social security validation |
wrk_ | Worker |
sig_ | Signature |
inv_ | Invoice |
rtc_ | Retention certificate |
bat_ | Batch |
mer_ | Merchant |
chg_ | Charge |
evt_ | Webhook event |
req_ | Request (in errors and the X-Request-Id header) |
Authentication
Exchange your client id and secret for a one-hour bearer token, and check what a token can do.
| POST | /oauth/token | Get an access token | Live |
| GET | /me | Get the caller of the token | Live |
Fiscal validation
RFC status, tax regimes, registered name and postal code, and e.firma and CSD validity, from a CURP or an RFC.
| POST | /fiscal-validations | Validate a person's tax status | Live |
| GET | /fiscal-validations | List fiscal validations | Live |
| GET | /fiscal-validations/{id} | Get a fiscal validation | Live |
Social security (IMSS)
Find a person’s NSS, or start their IMSS registration when they have none.
| POST | /social-security-validations | Find or register a person's NSS | Live |
| GET | /social-security-validations | List social security validations | Live |
| GET | /social-security-validations/{id} | Get a social security validation | Live |
Workers
Register a worker, get their consent through the enrollment link, and a compliance view of everyone you work with.
| POST | /workers | Register a worker | Live |
| POST | /workers/{id}/enrollment | Create an enrollment link | Planned |
| DELETE | /workers/{id} | Remove a worker | Live |
| GET | /workers | List workers | Live |
| GET | /workers/{id} | Get a worker | Live |
| GET | /workers/report | Workers compliance feed | Live |
e.firma and CSD
Generate a worker’s CSD from their e.firma, and collect signatures on digital contracts.
| POST | /workers/{id}/csd | Request the worker's CSD | Building |
| POST | /signatures | Sign a document with the worker's e.firma | Planned |
| GET | /signatures/{id} | Get a signature | Planned |
Invoices
CFDI 4.0 invoices from your companies, merchants or workers, with their cancellation and files.
| POST | /invoices | Issue an invoice | Live |
| DELETE | /invoices/{id} | Cancel an invoice | Live |
| GET | /invoices | List invoices | Live |
| GET | /invoices/{id} | Get an invoice | Live |
| GET | /invoices/{id}/download | Get a download link | Live |
Retention certificates
CFDI de retenciones for the ISR and VAT you withhold from workers, merchants or any taxpayer.
| POST | /retention-certificates | Issue a retention certificate | Live |
| DELETE | /retention-certificates/{id} | Cancel a retention certificate | Live |
| GET | /retention-certificates | List retention certificates | Live |
| GET | /retention-certificates/{id} | Get a retention certificate | Live |
| GET | /retention-certificates/{id}/download | Get a download link | Live |
Batches
Invoices and retention certificates from a CSV file, for high volumes.
| POST | /batches | Upload a batch | Building |
| POST | /batches/{id}/process | Process a batch | Building |
| POST | /batches/{id}/pause | Pause a batch | Building |
| POST | /batches/{id}/resume | Resume a batch | Building |
| POST | /batches/{id}/cancel | Cancel a batch | Building |
| GET | /batches/{id} | Get a batch | Building |
Point of sale
Merchants, card charges and a single-use self-invoicing QR per sale.
| POST | /merchants | Add a merchant | Live |
| POST | /merchants/{id}/onboarding | Create an onboarding | Live |
| POST | /merchants/{id}/console-link | Create a console link | Live |
| POST | /charges | Create a charge | Live |
| POST | /charges/{id}/void | Void a charge | Live |
| PUT | /merchants/{id}/csd | Upload the CSD | Live |
| GET | /merchants | List merchants | Live |
| GET | /merchants/{id} | Get a merchant | Live |
| GET | /charges | List charges | Live |
| GET | /charges/{id} | Get a charge | Live |
Branding
The name, colour, help mailbox, footer and logo your merchants show on their invoicing page and emails, inherited from the company when a merchant sets none.
| PUT | /branding/merchants/{id} | Update a merchant's brand | Building |
| PUT | /branding/merchants/{id}/logo | Upload a merchant's logo | Building |
| DELETE | /branding/merchants/{id}/logo | Remove a merchant's logo | Building |
| GET | /branding/merchants/{id} | Get a merchant's brand | Building |
Reports
Monthly retention totals per worker, and your API usage.
| GET | /reports/retentions | Monthly retentions report | Planned |
| GET | /reports/usage | Usage report | Building |
Webhooks
Register URLs to receive signed events. One company can hold up to 10 subscriptions, each with its own secret, a delivery log and replays.
| POST | /webhooks | Create a webhook subscription | Building |
| POST | /webhooks/{id}/secret | Rotate the signing secret | Building |
| POST | /webhooks/{id}/test | Send a test event now | Building |
| POST | /deliveries/{id}/replay | Replay a delivery | Building |
| PATCH | /webhooks/{id} | Update a webhook subscription | Building |
| DELETE | /webhooks/{id} | Delete a webhook subscription | Building |
| GET | /webhooks | List webhook subscriptions | Building |
| GET | /webhooks/{id} | Get a webhook subscription | Building |
| GET | /webhooks/{id}/deliveries | List deliveries of a subscription | Building |
The OpenAPI 3.1 description behind these pages is shared with your team on request, for code generation and testing tools.
Versioning
What can change without notice, and what never will.
Get an access tokenPOST
Exchanges your client credentials for a bearer token valid for one hour (OAuth 2.0 client credentials grant, RFC 6749). Send the token as `Authorization: Bearer <token>` on every other operation. This endpoint lives at the root of the environment, not under `/v1`: `https://api.b2b.heru.app/oauth/token` in production and `https://api.dev.b2b.heru.app/oauth/token` in development. A client only works in the environment it was issued for. Send the client in the form body, as below, or with HTTP Basic; a JSON body with the same fields is accepted too. Leave `scope` out to get every scope of the client, or list the ones you need separated by spaces to get a narrower token. Errors follow RFC 6749: `error` and `error_description`, not the `code` shape of the rest of the API. Responses are never cached.