Development environment
Try every live operation against api.dev.b2b.heru.app with your own credentials.
The development environment is the heru API on test data: the same services, contract and checks as production, with CFDI stamped by the SAT test environment, so nothing you issue there has fiscal validity. Every operation labeled Live is served at https://api.dev.b2b.heru.app/v1; the rest answer 404 at the gateway until they open.
Your credentials
Your account team issues a client (client_id and client_secret) per environment, with the scopes of your contract. The Try it of every operation in the API reference asks for it: pick Development or Production, paste the client and press Get token. The browser exchanges it at /oauth/token of that environment and sends the token on your requests. The token and the client id stay in your browser tab (session storage) and the secret in memory; nothing is stored on this site or sent anywhere else. Close the tab and they are gone.
The development and production tokens are not interchangeable: each environment has its own issuer and keys, so a token only ever goes to the environment it came from.
Good to know
- Real lookups can happen in development with your own keys. Send real identities only with the person's consent, as you would in production.
- Validations, invoices and retention certificates follow the contract as written, including every SAT rule. A
422in development is the same422you would get in production. - The SAT test environment checks the receiver of a CFDI against its registry. Issue to the general public (
XAXX010101000), or to a worker or company registered with their real data. - Rate limits apply per credential, as in production.
Runnable cases
The cases below run against the development environment from this page, with the credential you type here: each shows every request and response, and the status transitions on the way.
Retention certificates
These cases call https://api.dev.b2b.heru.app/v1, which stamps with the SAT test environment, with your own development client. The SAT checks the receiver against its registry even there, so the certificates go to the general public (XAXX010101000) or to a worker you register with their real data. Dates are the current month. Every certificate carries metadata.source = developers.heru.app. Cancellation, replacement and batches are not covered by these cases yet.
https://api.dev.b2b.heru.app. Kept in this browser tab only. Needs retention_certificates:write, retention_certificates:read, workers:read, workers:write.Postal code of your company: preloaded with the demo company's, change it if yours differs. Five digits; the general public receiver takes it.
The browser posts grant_type=client_credentials to https://api.dev.b2b.heru.app/oauth/token. The token and the client id stay in this tab's session; the secret only in memory, to request tokens with fewer scopes. Nothing is stored anywhere else. No client for this environment yet? Ask your account team.
| What it does | Receiver | Expected result | |
|---|---|---|---|
| General public: two weekly deliveries, ISR 20 % and all the VAT Receiver XAXX010101000 with regime 616 and the postal code of your company. On $5,970.00 heru withholds 20 % of ISR ($1,194.00) and 100 % of the $955.20 of VAT. Tips are printed, not taxed. | XAXX010101000 | 201 stamped · withheld $2149.20 | |
| A service dated in the previous month Every service must fall inside the month of period. Nothing is stamped. | XAXX010101000 | 422 · VALIDATION_FAILED | |
| VAT withholding calculated on the price The base of the VAT withholding is the VAT transferred ($955.20 at rate 1), not the price. heru answers with the values the SAT expects. | XAXX010101000 | 422 · VALIDATION_FAILED | |
| The same external_id twice The first request stamps. The second, with the same external_id and a new Idempotency-Key, answers 409 with the id of the first: only one CFDI exists. | XAXX010101000 | 409 · EXTERNAL_ID_ALREADY_USED | |
| The same Idempotency-Key with a different body The first request stamps. The second reuses its Idempotency-Key with another external_id and answers 409: a key is one request. | XAXX010101000 | 409 · IDEMPOTENCY_KEY_REUSED | |
| Rejected by the SAT: the receiver is not in the SAT registry The RFC looks right but its check digit is wrong on purpose, so the SAT has never issued it. The PAC asks the SAT and the SAT rejects the certificate. Nothing is stamped. | HEGL900101K44 | 422 · SAT_REJECTED | |
| POST without Idempotency-Key Every POST needs the header, unique per operation. Nothing is validated or stamped. | XAXX010101000 | 400 · IDEMPOTENCY_KEY_REQUIRED | |
| Token without retention_certificates:write Gets a token narrowed to retention_certificates:read with your client id and secret, then tries to issue. Needs the client id and secret, not a pasted token. | XAXX010101000 | 403 · INSUFFICIENT_SCOPE | |
| Issue to your registered worker Pick a worker you registered with POST /workers from the Worker menu above. The certificate names receiver.worker_id and heru fills their RFC, name, regime and postal code; the PDF goes to the email of the registered worker. A persona física gets ISR 2.1 % and half the VAT: $602.97 on these two services. | your worker | 201 stamped · withheld $602.97 | |
| Worker id that does not exist The id is well formed but heru has no such worker for your company: the SAT is never asked. Nothing is stamped. | wrk_… | 422 · VALIDATION_FAILED | |
| Register your own worker, then issue to them Type the SAT data of a real worker you may issue to (with their consent). POST /workers registers them; the certificate then names receiver.worker_id and heru fills their RFC, name, regime and postal code. A persona física gets ISR 2.1 % and half the VAT: $602.97 on these two services. The data stays in this page and is never saved. | your worker | 201 stamped · withheld $602.97 |