Heru Logo
API docs by Redocly

Heru B2B API (1.0.0)

Download OpenAPI specification:

Heru Support: soporte@heru-app.com URL: https://www.heru.app/ License: MIT

On this page, we list all available methods in the Heru B2B API, as well as the complete reference of parameters that each one accepts. To view nested properties of an object or array of objects, you can click on the field name and expand it.

The Heru API is designed with the REST standard in mind. API endpoints are grouped by resources, have predictable URLs, responses are in JSON format, and we use standard HTTP response codes, authentication, and verbs.

During development, you can use the Heru API in Sandbox environment and the invoices you issue will not be sent to SAT nor will they have fiscal validity.

The secret key you use to authenticate will determine both the environment in which the invoice will be created (Sandbox or Production), as well as the organization to use as the issuer of your invoice, or as the owner of the resource you request to create.

Invoicing

Electronic invoice (CFDI) operations

Create invoice

Generates a new CFDI electronic invoice with the provided issuer, receiver, and line items data.

Authorizations:
BearerAuth
Request Body schema: application/json
required
One of
type
required
string
Value: "I"

Fiscal receipt type (I=Income).

object (Issuer)

Invoice issuer information.

required
object (Receiver)

Invoice receiver information.

object (ThirdParty)

Third-party information (optional, for accounts payable to third parties).

required
Array of objects (InvoiceItem) non-empty

List of line items included in the invoice (all fields required).

periodicity
string

Periodicity key according to SAT catalog (required only in global invoices).

months
string^(0[1-9]|1[0-2])$

Month(s) covered by the invoice (required only in global invoices).

year
string^\d{4}$

Year of the invoice (required only in global invoices).

payment_method
required
string
Enum: "PUE" "PPD"

Payment method according to SAT catalog (PUE=One-time payment, PPD=Partial or deferred payment).

payment_form
required
string

Payment form according to SAT catalog (99=To be defined).

cfdi_use
required
string
Default: "G03"

CFDI use key according to SAT catalog (default G03, use S01 for global invoices).

vat_rate
required
string^0\.\d{2}$

Transferred VAT rate.

object

Custom additional information (optional).

Responses

Request samples

Content type
application/json
Example

Invoice where the partner is the issuer and invoices a specific receiver.

{
  • "type": "I",
  • "issuer": {
    },
  • "receiver": {
    },
  • "items": [
    ],
  • "payment_method": "PUE",
  • "payment_form": "99",
  • "cfdi_use": "G03",
  • "vat_rate": "0.16",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Request created successfully",
  • "data": {
    }
}

Cancel invoice

Cancels an existing CFDI electronic invoice using its fiscal UUID.

Authorizations:
BearerAuth
Request Body schema: application/json
required
invoice_uuid
required
string <uuid>

Fiscal UUID of the invoice to cancel.

Responses

Request samples

Content type
application/json

Request to cancel an existing invoice by its UUID.

{
  • "invoice_uuid": "12345678-e89b-12d3-a456-426614174000"
}

Response samples

Content type
application/json
{
  • "message": "Request created successfully",
  • "data": {
    }
}

Get invoice details

Retrieves the details and status of an invoice using its fiscal UUID or requestId.

Authorizations:
BearerAuth
query Parameters
uuid
string <uuid>
Example: uuid=12345678-1234-1234-1234-123456789012

Fiscal UUID of the invoice.

request_id
string <uuid>
Example: request_id=e4567890-e89b-12d3-a456-426614174000

Invoice request ID.

Responses

Response samples

Content type
application/json
Example

Detail of an invoice that was issued correctly.

{}

Certification

Retention certificate (CFDI Retención) operations

Create certification

Creates a new Retention (Retención). If the document is created in Live environment, it will be stamped and sent to SAT.

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object
required
object
required
object
withholding_description
required
string

Description of the retention.

Responses

Request samples

Content type
application/json

Example of a certification request with all required fields.

{
  • "receiver": {
    },
  • "period": {
    },
  • "totals": {
    },
  • "withholding_description": "Monthly retention for professional services"
}

Response samples

Content type
application/json
{
  • "message": "Request created successfully",
  • "data": {
    }
}

Get certification by ID

Retrieves the details of a specific certification using the certification_id or request_id.

Authorizations:
BearerAuth
query Parameters
certification_id
string <uuid>

Certification UUID

request_id
string <uuid>

Request ID UUID

Responses

Response samples

Content type
application/json
{}

Delete certification

Deletes a specific certification by its ID.

Authorizations:
BearerAuth
path Parameters
certification_id
required
string <uuid>

Certification UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Operation completed"
}

Nss Validation

Social Security Number validation

NSS validation

Initiates the NSS validation process (Social Security Number). If a CURP does not have an NSS and the is_register_candidate parameter is true, Heru will automatically initiate the registration process (IMSS Registration) on behalf of the citizen.

Important note: The process is asynchronous. Results will be sent to your registered webhook.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
national_id
required
string (CURP) ^[A-Z]{4}\d{6}[HM][A-Z]{5}[0-9A-Z]\d$

Unique Population Registry Code (CURP) of 18 characters

internal_partner_id
required
string

Partner's internal identifier for the user

is_register_candidate
required
boolean
Default: false

If true and there is no NSS, the registration process will start automatically

object

Partner's address (required if is_register_candidate is true)

Responses

Request samples

Content type
application/json
Example

NSS validation request without authorization for automatic registration

{
  • "national_id": "CAME900425HNLRRD03",
  • "internal_partner_id": "12345",
  • "is_register_candidate": false
}

Response samples

Content type
application/json
{
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "status": "received",
  • "message": "Request successfully accepted for processing",
  • "created_at": "2024-03-15T10:30:00-06:00"
}

Get NSS validation by ID or CURP

Retrieves the status and result of a specific validation using the request_id or the national_id.

Authorizations:
ApiKeyAuth
query Parameters
request_id
string <uuid>

Validation request ID

national_id
string^[A-Z]{4}\d{6}[HM][A-Z]{5}[0-9A-Z]\d$

Citizen's CURP

Responses

Response samples

Content type
application/json
Example

Citizen with a valid NSS that was successfully validated

{
  • "request_data": {
    },
  • "response_body": {}
}

List NSS validations

Retrieves all validation requests with pagination and optional filters.

Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1

Page number

pageSize
integer [ 1 .. 100 ]
Default: 50

Items per page

status
string
Enum: "processing" "completed" "retrying" "failed"

Filter by status

complementary_code
string
Enum: "001" "002" "003" "004"

Filter by complementary code

from_date
string <date-time>

Start date (ISO8601)

to_date
string <date-time>

End date (ISO8601)

Responses

Response samples

Content type
application/json
{
  • "page": 0,
  • "pageSize": 0,
  • "totalItems": 0,
  • "totalPages": 0,
  • "items": [
    ]
}

Full Fiscal Validation

Complete asynchronous fiscal data validation through B2B API

Full Fiscal Validation

Initiates a new fiscal validation process for a taxpayer. Validates tax data, digital certificates, and third-party invoicing eligibility.

Important note: The process is asynchronous. Results will be sent to your registered webhook.

Recommendation: Whenever possible, send the national_id (CURP) to guarantee a 97% success rate in information gathering.

Authorizations:
ApiKeyAuth
path Parameters
partner
required
string

Partner identifier (e.g., "tpc")

Request Body schema: application/json
required
national_id
string (CURP) ^[A-Z]{4}\d{6}[HM][A-Z]{5}[0-9A-Z]\d$

Unique Population Registry Code (CURP) of 18 characters

internal_partner_id
required
string

Partner's internal identifier

tax_id
string (RFC) ^[A-ZÑ&]{3,4}\d{6}[A-Z0-9]{2,3}$

Federal Taxpayer Registry (RFC) of 12 or 13 characters.

Responses

Request samples

Content type
application/json
Example

Fiscal validation request using CURP (recommended)

{
  • "national_id": "ROHM800825HDFDGR09",
  • "internal_partner_id": "12345",
  • "tax_id": ""
}

Response samples

Content type
application/json
{
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "status": "received",
  • "message": "Request successfully accepted for processing",
  • "created_at": "2019-08-24T14:15:22Z"
}

Get Full Fiscal Validation result

Retrieves the result of a specific full fiscal validation.

Authorizations:
ApiKeyAuth
path Parameters
partner
required
string

Partner identifier

query Parameters
national_id
string

Taxpayer's CURP

internal_partner_id
string

Partner's internal ID

tax_id
string

Taxpayer's RFC

request_id
string <uuid>

Request ID

Responses

Response samples

Content type
application/json
Example

Fiscal validation completed with all data

{
  • "request_data": {
    },
  • "response_body": {
    }
}

List Full Fiscal Validations

Retrieves all fiscal validations with pagination and filters.

Authorizations:
ApiKeyAuth
path Parameters
partner
required
string

Partner identifier

query Parameters
page
integer
Default: 1
limit
integer <= 100
Default: 50
status
string
Enum: "received" "processing" "completed" "partially_completed" "failed"
from_date
string <date-time>
to_date
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

RFC Validation

RFC validation against SAT registry

RFC Validation

Validates an RFC against the SAT registry. Verifies if the RFC exists, is active, and is on the Required Taxpayers List (LCO).

Information returned:

  • LCO: Whether the taxpayer is on the Required Taxpayers List
  • estatus: Whether the RFC is active in SAT
Authorizations:
ApiKeyAuth
path Parameters
rfc
required
string (RFC) ^[A-ZÑ&]{3,4}\d{6}[A-Z0-9]{2,3}$
Example: XAXX010101000

RFC to validate (12 or 13 characters)

query Parameters
partner_id
integer
Default: 3

Partner ID (optional, default 3)

Responses

Response samples

Content type
application/json
Example

RFC exists and is active in SAT

{
  • "lco": true,
  • "status": true,
  • "error": false
}

Tax Data Validation 4.0

Tax data validation for CFDI 4.0 compliance

Tax Data Validation 4.0

Validates taxpayer fiscal data for CFDI 4.0 issuance. Verifies RFC, name, postal code, tax regime, and CFDI use against tax authorities.

Validations performed:

  • RFC format and validity
  • Taxpayer name or business name
  • Postal code (5 digits)
  • Tax regime associated with RFC
  • CFDI use
  • Email (optional)
  • Cell phone (optional, 10 digits)

Note: If validacionFC3 is true, an asynchronous advanced validation process will be initiated for third-party invoicing.

Authorizations:
ApiKeyAuth
query Parameters
rfc
required
string (RFC) ^[A-ZÑ&]{3,4}\d{6}[A-Z0-9]{2,3}$
Example: rfc=XAXX010101000

RFC to validate (12 or 13 characters)

firstName
required
string
Example: firstName=Juan

Taxpayer's first name(s)

lastName
required
string
Example: lastName=Pérez López

Taxpayer's last name(s)

domicilioFiscal
required
string^\d{5}$
Example: domicilioFiscal=12000

Tax address postal code (5 digits)

regimenFiscal
string
Example: regimenFiscal=625

Tax regime code (optional)

usoCfdi
string
Example: usoCfdi=G03

CFDI use code (optional)

email
string <email>
Example: email=juan@example.com

Taxpayer's email (optional)

cellphone
string^\d{10}$
Example: cellphone=5512345678

10-digit cell phone number (optional)

validacionFC3
string
Default: "false"
Enum: "true" "false"

Whether advanced FC3 validation should be performed

Responses

Response samples

Content type
application/json
Example

All fields are correct

{
  • "rfc": "XAXX010101000",
  • "name": "JUAN PÉREZ LÓPEZ",
  • "tax_address": "12000",
  • "tax_regime": "625",
  • "cfdi_use": "G03",
  • "code": "000",
  • "code_meaning": "All fields are correct",
  • "description": null,
  • "fc3_validation": false,
  • "message": "It is valid."
}

E.Signature & CSD Validation

E.Signature and CSD validation

E.Signature & CSD Validation

It allows you to consult and verify the existence, status and validity of the digital certificates of e.firma and Digital Seal Certificate (CSD) linked to the RFC consulted, according to the information available in official or authorized access sources.

Note: The process is asynchronous. Results will be sent to your registered webhook.

Authorizations:
ApiKeyAuth
query Parameters
rfc
required
string (RFC) ^[A-ZÑ&]{3,4}\d{6}[A-Z0-9]{2,3}$
Example: rfc=XAXX010101000

RFC to validate (12 or 13 characters)

Responses

Response samples

Content type
application/json
{
  • "message": "RFC has been sent for validation processing"
}