heruAPI
Retention certificates

List retention certificates

LiveServed by the v1 API in development with the same checks as production; production opens on the same contract. The capabilities from before v1 keep running in production at the path your account team gives you.

GET
/retention-certificates

Most recent first. For the monthly reconciliation, filter by period and page through with cursor; add status=stamped to leave out cancellations.

Needs the retention_certificates:read scope.

Authorization

oauth2 retention_certificates:read
headerAuthorizationBearer <token>

OAuth 2.0 client credentials. Exchange your client_id and client_secret at /oauth/token of the environment for a bearer token valid for one hour. The playground of every operation asks for your own client and keeps it in your browser tab only.

Scope: retention_certificates:read

Query parameters

period?string

Certificates whose period covers this month, YYYY-MM.

Match^[0-9]{4}-(0[1-9]|1[0-2])$
receiver_rfc?string

Filter by the receiver's RFC.

worker_id?string

Filter by worker.

Match^wrk_[0-7][0-9a-hjkmnp-tv-z]{25}$
merchant_id?string

Filter by merchant, as issuer or receiver.

Match^mer_[0-7][0-9a-hjkmnp-tv-z]{25}$
customer_id?string

Filter by customer.

Match^cus_[0-7][0-9a-hjkmnp-tv-z]{25}$
company_id?string

Filter by the issuing company.

Match^cmp_[0-7][0-9a-hjkmnp-tv-z]{25}$
external_id?string

Filter by your id.

status?string

Filter by status.

Value in"stamped""cancellation_requested""cancelled"
created_from?string

Created on or after this date (YYYY-MM-DD).

created_to?string

Created on or before this date (YYYY-MM-DD).

cursor?string

From next_cursor of the previous page.

limit?integer

1 to 500.

Default100

Response body

OK

application/json
  1. response
data*array<>
next_cursor*|null
curl -X GET 'https://api.dev.b2b.heru.app/v1/retention-certificates?period=2026-09&receiver_rfc=HEGL900101K44'
{  "data": [    {      "id": "rtc_01m55c7k2qe8rbd4wz9m3tn6xa",      "external_id": "RET-2026-000021",      "status": "stamped",      "uuid": "E3470709-8519-454D-9A10-4D3D3836683E",      "verification_url": "https://prodretencionverificacion.clouda.sat.gob.mx/?id=E3470709-8519-454D-9A10-4D3D3836683E&re=PDE180514R21&rr=TAD190521KX1&tt=61500.00&fe=qP2XnQ==",      "stamp": {        "sat_certificate_number": "00001000000509465028",        "issuer_certificate_number": "00001000005687795825",        "pac_rfc": "SPR190613I52",        "issuer_seal": "lrjJx7FEaBb8OBnify/Gd3vU+lcV/XitNFexl8611q5snNKl6almF7Yf30saawkO5q4McxX0Ug+f3ee88MadezBrdM/EwFW7F10JoIyui412NxIL43dT/q/2gu99otQfI6nOVY63mxpuAQzozfrM9D2G65wPnxgKpn3wP2lAu8Dp/kg/kg5HAiyiSvZtlqdjd0GY6per1MGoJ8ykM79Uz6J1TZmHoZTNeBm1GuUFUMvrk7KeglpcewONDc/xkmZjDXr5qzPY4cv4rPqMV4tDyzsu4dH23OkM43wI9cMIxwensdqZaIFkFhe/7dsRk0mFFFTLdm0anMmEWyjvqP2XnQ==",        "sat_seal": "OZdpc57B2TjP4nCTODN7h0KU2hybF9+tQ+zqOmBK4/KpLil0xlJiQBcO+CKukzMIEfvvv7yR3LYi2MEyy+1OGIaBK3GsUjHb34T8og6j3AZHsXUFW9JMH8ahYXf+tZUYz4YKyLfmu6zrqAlI/f9qeJTcQev7ENUoJqPuO/EWYCFsOvHWwWS0savUGUuYiMMp0f+njdXoUWTaU+r9RW4JCqcS0gTGf1qxyCWxVSwQK8RSLx40A2RcgIgJHL6WmNSELcZqsQmEnnR6RENY7VxBt+wZvRydHJ/fwQkyO3gMHqGTcYZK8uZQt9hRLw2r2X0DIxZzwgzSGW24pX8cmyGGIg==",        "original_chain": "||1.1|E3470709-8519-454D-9A10-4D3D3836683E|2026-10-16T19:03:07|SPR190613I52|lrjJx7FEaBb8OBnify/Gd3vU+lcV/XitNFexl8611q5snNKl6almF7Yf30saawkO5q4McxX0Ug+f3ee88MadezBrdM/EwFW7F10JoIyui412NxIL43dT/q/2gu99otQfI6nOVY63mxpuAQzozfrM9D2G65wPnxgKpn3wP2lAu8Dp/kg/kg5HAiyiSvZtlqdjd0GY6per1MGoJ8ykM79Uz6J1TZmHoZTNeBm1GuUFUMvrk7KeglpcewONDc/xkmZjDXr5qzPY4cv4rPqMV4tDyzsu4dH23OkM43wI9cMIxwensdqZaIFkFhe/7dsRk0mFFFTLdm0anMmEWyjvqP2XnQ==|00001000000509465028||"      },      "issuer": {        "rfc": "PDE180514R21",        "name": "PLATAFORMA DEMO",        "tax_regime": "601",        "postal_code": "11000"      },      "receiver": {        "rfc": "TAD190521KX1",        "name": "TACOS EL ALIADO DEMO",        "tax_regime": "601",        "postal_code": "03100",        "email": null      },      "place_of_issue": "11000",      "period": {        "start_month": "09",        "end_month": "09",        "year": "2026"      },      "retention_code": "26",      "description": null,      "amounts": {        "total": "61500.00",        "taxable": "61500.00",        "exempt": "0.00"      },      "withheld_taxes": [        {          "tax": "ISR",          "base": "59350.00",          "rate": "0.025",          "amount": "1483.75",          "payment_type": "04"        },        {          "tax": "VAT",          "base": "9496.00",          "rate": "0.5",          "amount": "4748.00",          "payment_type": "01"        }      ],      "total_withheld": "6231.75",      "related_certificates": [],      "platform": {        "service_type": "05",        "periodicity": "02",        "isr_payment_type": "04",        "period": {          "from": "2026-09-01",          "to": "2026-09-30"        },        "services": [          {            "date": "2026-09-07",            "payment_form": "03",            "price_without_vat": "18450.00",            "vat_rate": "0.16",            "vat": "2952.00",            "commission": {              "base": "18450.00",              "rate": "0.25",              "amount": "4612.50"            },            "government_contribution": null          }        ],        "totals": {          "services": 4,          "price_without_vat": "61500.00",          "vat_transferred": "9840.00",          "vat_withheld": "4748.00",          "isr_withheld": "1483.75",          "vat_delivered": "4748.00",          "platform_fees": "15375.00",          "government_contributions": "0.00"        }      },      "cancellation": null,      "metadata": {},      "created_at": "2026-10-16T19:03:07Z",      "stamped_at": "2026-10-16T19:03:07Z",      "updated_at": "2026-10-16T19:03:07Z"    },    {      "id": "rtc_01m4rdmjy8fr1tn1re492c0z4j",      "external_id": "RET-2026-000013",      "status": "stamped",      "uuid": "59C6F5BE-075D-4079-AD15-0B23A967A6C0",      "verification_url": "https://prodretencionverificacion.clouda.sat.gob.mx/?id=59C6F5BE-075D-4079-AD15-0B23A967A6C0&re=PDE180514R21&rr=HEGL900101K44&tt=9450.00&fe=bHhBKA==",      "stamp": {        "sat_certificate_number": "00001000000509465028",        "issuer_certificate_number": "00001000005687795825",        "pac_rfc": "SPR190613I52",        "issuer_seal": "qRXkuhx3RbYWauYlV3UAv8YYRvjAV0OeqDp8SEn2X5tYPZCbrQjOF9GvnTOUnTBr53h8COzlm4WlGNXHZnKMrSMP2KRbn3und/dzobPgK1mE27mgvpG9+prdYtgZ1vbnVecKX7PB8FiGUOJVbnGadEeyHT5GL/f+UO9IGz0Y2kho3p7UZDJS0XEp0HHfvQ3+YNCX/ysZq/KMyXBfJH7FFnTkPJ0YuzUZKEfu/oYXkCWGImuUJ8GiNS01jL4efi6KMhx6IV3FmIBGUxfm6minHYGuZjOxVh4ueD3rCvehLd2WEfYXaZjfR2HPG3XBvqzZUC1rMeNKAqMRBLcHbHhBKA==",        "sat_seal": "id2m4j4hIMaLas7/UwcOfOaio62Zqf3HcmaE3p+GKIGYsX9ufiHiWyE6skSMwahtHqoccsgNyRswrrEBThzy9y041zLKaVl0cWNKdxbDTANj/Kh6MFrWrGityN2hUf0USvdD+MJvZKvVliajw7v/Az5W7PrgQSCC6Iz68oMU6/mbcFwdXVT82IJwNxM8E/944wi3mUG1Idcov035HY+sGIpMbLPZrfWa5LF5cH57hglwXcOXajvGLe433OKJSody7tZ81lXdzXoLYb4FEHha/JbqRyJuDTcTOb3MlqUMpHOYJwranp7KQn3kq7qncDEKiQrYOT6I0ts6JET4s93W7A==",        "original_chain": "||1.1|59C6F5BE-075D-4079-AD15-0B23A967A6C0|2026-10-16T19:03:07|SPR190613I52|qRXkuhx3RbYWauYlV3UAv8YYRvjAV0OeqDp8SEn2X5tYPZCbrQjOF9GvnTOUnTBr53h8COzlm4WlGNXHZnKMrSMP2KRbn3und/dzobPgK1mE27mgvpG9+prdYtgZ1vbnVecKX7PB8FiGUOJVbnGadEeyHT5GL/f+UO9IGz0Y2kho3p7UZDJS0XEp0HHfvQ3+YNCX/ysZq/KMyXBfJH7FFnTkPJ0YuzUZKEfu/oYXkCWGImuUJ8GiNS01jL4efi6KMhx6IV3FmIBGUxfm6minHYGuZjOxVh4ueD3rCvehLd2WEfYXaZjfR2HPG3XBvqzZUC1rMeNKAqMRBLcHbHhBKA==|00001000000509465028||"      },      "issuer": {        "rfc": "PDE180514R21",        "name": "PLATAFORMA DEMO",        "tax_regime": "601",        "postal_code": "11000"      },      "receiver": {        "rfc": "HEGL900101K44",        "name": "JOSE LUIS HERNANDEZ GARCIA",        "tax_regime": "625",        "postal_code": "06600",        "email": null      },      "place_of_issue": "11000",      "period": {        "start_month": "09",        "end_month": "09",        "year": "2026"      },      "retention_code": "26",      "description": null,      "amounts": {        "total": "9450.00",        "taxable": "9450.00",        "exempt": "0.00"      },      "withheld_taxes": [        {          "tax": "ISR",          "base": "9450.00",          "rate": "0.021",          "amount": "198.45",          "payment_type": "04"        },        {          "tax": "VAT",          "base": "1432.00",          "rate": "0.5",          "amount": "716.00",          "payment_type": "01"        }      ],      "total_withheld": "914.45",      "related_certificates": [],      "platform": {        "service_type": "02",        "periodicity": "02",        "isr_payment_type": "04",        "tips": "640.00",        "period": {          "from": "2026-09-01",          "to": "2026-09-30"        },        "services": [          {            "date": "2026-09-06",            "payment_form": "03",            "price_without_vat": "2850.00",            "vat_rate": "0.16",            "vat": "456.00",            "commission": {              "base": "2850.00",              "rate": "0.10",              "amount": "285.00"            },            "government_contribution": null          }        ],        "totals": {          "services": 4,          "price_without_vat": "9450.00",          "vat_transferred": "1432.00",          "vat_withheld": "716.00",          "isr_withheld": "198.45",          "vat_delivered": "716.00",          "platform_fees": "895.00",          "government_contributions": "0.00"        }      },      "cancellation": null,      "metadata": {},      "created_at": "2026-10-16T19:03:07Z",      "stamped_at": "2026-10-16T19:03:07Z",      "updated_at": "2026-10-16T19:03:07Z"    }  ],  "next_cursor": null}

Cancel a retention certificateDEL

Asks the SAT to cancel the certificate. Retention certificates need no acceptance from the receiver: the answer is `202` with status `cancellation_requested`, the SAT confirms within seconds and `retention_certificate.cancelled` fires with status `cancelled`. To correct a certificate, issue the new one first with the old one in `related_certificates` (relationship 04), then cancel the old one with reason `01` and the new folio fiscal in `replacement_uuid`. heru checks that the replacement is stamped and relates this one. The cancelled certificate is not deleted: it keeps its files and its `cancellation`. Needs the `retention_certificates:cancel` scope.

Get a retention certificateGET

Returns the certificate with its status, the withheld taxes, the complement and the folio fiscal. Needs the `retention_certificates:read` scope.

© 2026 Kuarto Inc. (heru)heru.appQuestions about your integration? Contact your heru account team.