Receptores de facturas

Un receptor es una persona que recibe facturas. En Fiscalapi, una persona representa cualquier entidad fiscal, ya sea una persona física (individuo) o moral (empresa). Este concepto centralizado permite gestionar otros recursos de su organización como: asignar y remover timbres, administrar certificados (sellos), crear y revocar API-keys y controlar quién puede generar facturas y quien no de forma programática.

Una persona representa:

Empresas (Emisores de facturas CFDI)
Clientes (Receptores de facturas CFDI)
Organizaciones (Fábricas de software que tienen sus propios clientes)
Usuarios (Personas que consumen la API dentro de una organización)

Tip: Una misma persona puede ser un emisor, receptor o usuario en la misma organización y cualquier persona se gestiona desde el recurso único de personas. /api/v4/people

Modelo persona

El modelo persona contiene toda la información de una persona. Las propiedades con el sufijo Id corresponden a valores de los catálogos oficiales del SAT. Puede verlos en la pagina de Catálogos CFDI 4.0 o programáticamente a través de la API catalogs.

Propiedades

Name
id
Type
string?
Description
Identificador único de la persona asignado por Fiscalapi.
Name
legalName
Type
string
required
Description
Razón social de la persona sin régimen de capital. Por ejemplo, si la razón social es MI EMPRESA S.A. de C.V., se debe enviar MI EMPRESA. Si el emisor es persona física, se debe enviar el nombre completo como aparece en la constancia de situación fiscal.
Name
email
Type
string
required
Description
Correo electrónico de la persona.
Name
password
Type
string
required
Description
Contraseña de acceso al dashboard. Las personas (emisores, receptores y usuarios) pueden acceder al dashboard de fiscalapi con su correo y contraseña; la entrega de estas credenciales dependerá de las políticas internas de su organización.
Name
capitalRegime
Type
string?
Description
Régimen de capital de la persona. Por ejemplo: si la razón social de la persona es MI EMPRESA S.A. de C.V., se debe enviar S.A. de C.V., si la persona es persona física este campo se deja vacío.
Name
satTaxRegimeId
Type
string?
expandible
Description
Código de régimen fiscal que se utilizará cuando esta persona actúe como emisor o receptor. Catálogo del SAT c_régimenFiscal.
Type
enum:
Values
"601""603""605"
Name
satCfdiUseId
Type
string?
expandible
Description
Código de uso del CFDI que se utilizará cuando esta persona actúe como receptor. Catálogo del SAT c_UsoCFDI.
Type
enum:
Values
"G01""G02""G03"
Name
userTypeId
Type
string?
expandible
Description
Tipo de persona, solo tiene fines informativos.
Type
enum:
Values
"T""C""U"
Name
tin
Type
string?
Description
RFC de la persona.
Name
zipCode
Type
string?
Description
Código postal de la persona; Debe corresponder con el código postal expresado en su constancia de situación fiscal. Catálogo del SAT c_CodigoPostal
Name
base64Photo
Type
string?
Description
Foto de perfil de la persona en formato base64.
Name
taxPassword
Type
string?
Description
Contraseña de los certificados CSD de la persona que se utilizará para sellar (firmar) las facturas cuando esta persona actúe como emisor.
Name
availableBalance
Type
number?
Description
Timbres disponibles para la persona. Sólo lectura y con fines informativos.
Name
tenantId
Type
string?
Description
ID del tenant al que pertenece la persona. Sólo lectura y con fines informativos.

GET/api/v4/people

Listar receptores

Este endpoint devuelve una lista paginada de personas. De forma predeterminada, se muestran diez personas por página, pero puedes ajustar esto con los parámetros de consulta.

Query parameters

Name
pageNumber
Type
integer | number
required
Description
El número de página que se desea recuperar.
Default:
1
Name
pageSize
Type
integer | number
required
Description
Valor entre 1 y 50 inclusivo para indicar la cantidad de registros devueltos por página.
Default:
10

Request

GET

/api/v4/people

curl --location 'https://test.fiscalapi.com/api/v4/people?pageNumber=1&pageSize=2' \
--header 'X-TENANT-KEY: <tenant>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

    {
    "data": {
        "items": [
            {
                "legalName": "KARLA FUENTE NOLASCO",
                "capitalRegime": null,
                "email": "karla@gmail.com",
                "phoneNumber": null,
                "validTo": null,
                "twoFactorEnabled": false,
                "stripeCustomerId": "cus_RXpxlJC2145W9I",
                "satTaxRegimeId": "626",
                "satTaxRegime": {
                    "id": "626",
                    "description": "Régimen Simplificado de Confianza",
                    "createdAt": "2024-08-10T15:46:30.3730000",
                    "updatedAt": null
                },
                "satCfdiUseId": "G03",
                "satCfdiUse": {
                    "id": "G03",
                    "description": "Gastos en general.",
                    "createdAt": "2024-08-10T15:46:30.3730000",
                    "updatedAt": null
                },
                "userTypeId": "C",
                "userType": {
                    "id": "C",
                    "description": "Cliente",
                    "createdAt": "2024-08-10T15:46:30.3730000",
                    "updatedAt": null
                },
                "tin": "FUNK671228PH6",
                "zipCode": "01160",
                "base64Photo": null,
                "taxPassword": "12345678a",
                "stripePaymentMethodId": null,
                "stripePaymentMethod": null,
                "availableBalance": 13,
                "committedBalance": 0,
                "subscriptionStatus": null,
                "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
                "id": "78d380fd-1b69-4e3c-8bc0-4f57737f7d5f",
                "createdAt": "2025-01-07T15:26:06.9069715",
                "updatedAt": "2025-04-20T09:31:06.1825831"
            }
        ],
        "pageNumber": 1,
        "totalPages": 2,
        "totalCount": 5,
        "hasPreviousPage": false,
        "hasNextPage": true
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/people/<id>

Obtener receptor por ID

Este endpoint te permite obtener una persona por su ID.

Request

GET

/api/v4/people/<id>

curl --location 'https://test.fiscalapi.com/api/v4/people/78d380fd-1b69-4e3c-8bc0-4f57737f7d5f' \
--header 'X-TENANT-KEY: <tenant>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'
--data ''

Response

{
    "data": {
        "legalName": "KARLA FUENTE NOLASCO",
        "capitalRegime": null,
        "email": "karla@gmail.com",
        "phoneNumber": null,
        "validTo": null,
        "twoFactorEnabled": false,
        "stripeCustomerId": "cus_RXpxlJC2145W9I",
        "satTaxRegimeId": "626",
        "satTaxRegime": {
            "id": "626",
            "description": "Régimen Simplificado de Confianza",
            "createdAt": "2024-08-10T15:46:30.3730000",
            "updatedAt": null
        },
        "satCfdiUseId": "G03",
        "satCfdiUse": {
            "id": "G03",
            "description": "Gastos en general.",
            "createdAt": "2024-08-10T15:46:30.3730000",
            "updatedAt": null
        },
        "userTypeId": "C",
        "userType": {
            "id": "C",
            "description": "Cliente",
            "createdAt": "2024-08-10T15:46:30.3730000",
            "updatedAt": null
        },
        "tin": "FUNK671228PH6",
        "zipCode": "01160",
        "base64Photo": null,
        "taxPassword": "12345678a",
        "stripePaymentMethodId": null,
        "stripePaymentMethod": null,
        "availableBalance": 13,
        "committedBalance": 0,
        "subscriptionStatus": null,
        "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
        "id": "78d380fd-1b69-4e3c-8bc0-4f57737f7d5f",
        "createdAt": "2025-01-07T15:26:06.9069715",
        "updatedAt": "2025-04-20T09:31:06.1825831"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

POST/api/v4/people

Crear receptor

Este endpoint te permite crear una persona.

Modelo

Name
legalName
Type
string
required
Description
Razón social de la persona sin régimen de capital. Por ejemplo, si la razón social es MI EMPRESA S.A. de C.V., se debe enviar MI EMPRESA. Si el receptor es persona física, se debe enviar el nombre completo como aparece en la constancia de situación fiscal.
Name
email
Type
string
required
Description
Correo electrónico de la persona.
Name
password
Type
string
required
Description
Contraseña de acceso al dashboard. Las personas (emisores, receptores y usuarios) pueden acceder al dashboard de fiscalapi con su correo y contraseña; la entrega de estas credenciales dependerá de las políticas internas de su organización.
Name
capitalRegime
Type
string?
Description
Régimen de capital de la persona. Por ejemplo: si la razón social de la persona es MI EMPRESA S.A. de C.V., se debe enviar S.A. de C.V., si la persona es persona física este campo se deja vacío.
Name
satTaxRegimeId
Type
string?
expandible
Description
Código de régimen fiscal que se utilizará cuando esta persona actúe como emisor o receptor. Catálogo del SAT c_régimenFiscal.
Type
enum:
Values
"601""603""605"
Name
satCfdiUseId
Type
string?
expandible
Description
Código de uso del CFDI que se utilizará cuando esta persona actúe como receptor. Catálogo del SAT c_UsoCFDI.
Type
enum:
Values
"G01""G02""G03"
Name
userTypeId
Type
string?
expandible
Description
Tipo de persona, solo tiene fines informativos.
Type
enum:
Values
"T""C""U"
Name
tin
Type
string?
Description
RFC de la persona.
Name
zipCode
Type
string?
Description
Código postal de la persona; Debe corresponder con el código postal expresado en su constancia de situación fiscal. Catálogo del SAT c_CodigoPostal
Name
base64Photo
Type
string?
Description
Foto de perfil de la persona en formato base64.
Name
taxPassword
Type
string?
Description
Contraseña de los certificados CSD de la persona que se utilizará para sellar (firmar) las facturas cuando esta persona actúe como emisor.
Name
availableBalance
Type
number?
Description
Timbres disponibles para la persona. Sólo lectura y con fines informativos.
Name
tenantId
Type
string?
Description
ID del tenant al que pertenece la persona. Sólo lectura y con fines informativos.

Request

POST

/api/v4/people

curl --location 'https://test.fiscalapi.com/api/v4/people' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data-raw '{
  "legalName": "EMPRESA",
  "email": "email@domain.com",
  "password": "MiSuperPass123!"
}'

Response

{
    "data": {
        "legalName": "EMPRESA S.A. DE C.V.",
        "capitalRegime": null,
        "email": "email@domain.com",
        "phoneNumber": null,
        "validTo": null,
        "twoFactorEnabled": false,
        "stripeCustomerId": "cus_SEQGzLeM29TIFr",
        "satTaxRegimeId": null,
        "satTaxRegime": null,
        "satCfdiUseId": null,
        "satCfdiUse": null,
        "userTypeId": "T",
        "userType": null,
        "tin": null,
        "zipCode": null,
        "base64Photo": null,
        "taxPassword": null,
        "stripePaymentMethodId": null,
        "stripePaymentMethod": null,
        "availableBalance": 0,
        "committedBalance": 0,
        "subscriptionStatus": null,
        "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
        "id": "d7992a07-4161-48ba-b3bf-558790c9bcdb",
        "createdAt": "2025-05-01T07:44:53.9725097",
        "updatedAt": "2025-05-01T07:44:53.9791644"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

PUT/api/v4/people

Actualizar emisor

Este endpoint te permite actualizar una persona.

Modelo

Name
legalName
Type
string
required
Description
Razón social de la persona sin régimen de capital. Por ejemplo, si la razón social es MI EMPRESA S.A. de C.V., se debe enviar MI EMPRESA. Si el receptor es persona física, se debe enviar el nombre completo como aparece en la constancia de situación fiscal.
Name
email
Type
string
required
Description
Correo electrónico de la persona.
Name
password
Type
string
required
Description
Contraseña de acceso al dashboard. Las personas (emisores, receptores y usuarios) pueden acceder al dashboard de fiscalapi con su correo y contraseña; la entrega de estas credenciales dependerá de las políticas internas de su organización.
Name
capitalRegime
Type
string?
Description
Régimen de capital de la persona. Por ejemplo: si la razón social de la persona es MI EMPRESA S.A. de C.V., se debe enviar S.A. de C.V., si la persona es persona física este campo se deja vacío.
Name
satTaxRegimeId
Type
string?
expandible
Description
Código de régimen fiscal que se utilizará cuando esta persona actúe como emisor o receptor. Catálogo del SAT c_régimenFiscal.
Type
enum:
Values
"601""603""605"
Name
satCfdiUseId
Type
string?
expandible
Description
Código de uso del CFDI que se utilizará cuando esta persona actúe como receptor. Catálogo del SAT c_UsoCFDI.
Type
enum:
Values
"G01""G02""G03"
Name
userTypeId
Type
string?
expandible
Description
Tipo de persona, solo tiene fines informativos.
Type
enum:
Values
"T""C""U"
Name
tin
Type
string?
Description
RFC de la persona.
Name
zipCode
Type
string?
Description
Código postal de la persona; Debe corresponder con el código postal expresado en su constancia de situación fiscal. Catálogo del SAT c_CodigoPostal
Name
base64Photo
Type
string?
Description
Foto de perfil de la persona en formato base64.
Name
taxPassword
Type
string?
Description
Contraseña de los certificados CSD de la persona que se utilizará para sellar (firmar) las facturas cuando esta persona actúe como emisor.
Name
availableBalance
Type
number?
Description
Timbres disponibles para la persona. Sólo lectura y con fines informativos.
Name
tenantId
Type
string?
Description
ID del tenant al que pertenece la persona. Sólo lectura y con fines informativos.

Request

PUT

/api/v4/people/<id>

curl --location --request PUT 'https://test.fiscalapi.com/api/v4/people/d7992a07-4161-48ba-b3bf-558790c9bcdb' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data-raw '{
      "id": "d7992a07-4161-48ba-b3bf-558790c9bcdb",
      "legalName": "ESCUELA KEMPER URGATE",
      "email": "mi.nueva.empresa@gmail.com",
      "password": "SuperPassword1234!",
      "capitalRegime": "SA de CV",
      "taxPassword": "MiSuperPass123!",
      "phoneNumber": "3312345678",
      "satTaxRegimeId": "601",
      "satCfdiUseId": "G01",
      "tin": "XAXX010101001",
      "zipCode": "44620",
      "base64Photo": "base64..."
}'

Response

{
    "data": {
        "legalName": "ESCUELA KEMPER URGATE",
        "capitalRegime": null,
        "email": "mi.nueva.empresa@gmail.com",
        "phoneNumber": "4611234556",
        "validTo": null,
        "twoFactorEnabled": false,
        "stripeCustomerId": "cus_SEQGzLeM29TIFr",
        "satTaxRegimeId": "601",
        "satTaxRegime": null,
        "satCfdiUseId": "G01",
        "satCfdiUse": null,
        "userTypeId": "T",
        "userType": null,
        "tin": "XAXX010101001",
        "zipCode": "44620",
        "base64Photo": "base64...",
        "taxPassword": null,
        "stripePaymentMethodId": null,
        "stripePaymentMethod": null,
        "availableBalance": 0,
        "committedBalance": 0,
        "subscriptionStatus": null,
        "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
        "id": "d7992a07-4161-48ba-b3bf-558790c9bcdb",
        "createdAt": "2025-05-01T07:44:53.9725097",
        "updatedAt": "2025-05-01T07:46:12.7809120"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

DELETE/api/v4/people

Eliminar emisor

Este endpoint te permite eliminar una persona.

Request

DELETE

/api/v4/people/<id>

curl --location --request DELETE 'https://test.fiscalapi.com/api/v4/people/d7992a07-4161-48ba-b3bf-558790c9bcdb' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>' \
--data ''

Response

{
    "data": true,
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}