Emisores de facturas

Un emisor es una persona que genera facturas. En Fiscalapi, una persona es cualquier entidad fiscal, ya sea persona física (un individuo) o moral (una empresa). Sobre la persona se gestionan los demás recursos de tu organización: le asignas y retiras timbres, administras sus certificados (CSD), creas y revocas sus API keys y decides si puede generar facturas.

Qué representa una persona

Una misma persona puede ser emisor, receptor, empleado, empleador o usuario en la misma organización, y cualquier persona se gestiona desde un solo recurso, /api/v4/people. Puede representar una empresa que emite facturas o un cliente que las recibe, un empleado o la empresa que lo contrata, una organización con sus propios clientes, un holding con filiales o subsidiarias, un usuario que consume la API dentro de una organización o una persona física.

Emisor en facturas de nómina

Cuando un emisor actúa como empleador (patrón) en facturas de nómina, debe tener registrados sus datos de empleador. Si el emisor es persona física, también debe tener su CURP en sus datos fiscales.

Owner del tenant

El owner del tenant es la persona que creó el tenant al registrarse en Fiscalapi, y las respuestas de personas lo identifican con isOwner: true. Los ejemplos de esta documentación usan su API key. Las demás personas del tenant usan la API con su propia API key y entran al dashboard solo si el owner les da el acceso al portal (loginEnabled).

Las credenciales de una persona son su correo (email), su contraseña de acceso (password) y la contraseña de su llave privada (taxPassword). El owner modifica a cualquier persona del tenant, incluidas sus credenciales, y cada persona se modifica a sí misma, también sus credenciales. Para lo demás rigen estas reglas:

Operación	Quién puede hacerla
Modificar los datos de una persona que no es el owner, por ejemplo sus datos fiscales.	Cualquier persona del tenant.
Crear o eliminar una persona que no es el owner.	Cualquier persona del tenant.
Cambiar las credenciales de otra persona.	Solo el owner.
Modificar al owner con Actualizar emisor o en sus datos de empleador o de empleado.	Solo el owner.
Eliminar al owner.	Nadie: Eliminar emisor con el id del owner responde 403.
Gestionar las API keys y los certificados de otra persona.	Solo el owner.
Crear, actualizar o eliminar las reglas de descarga de la persona owner y las reglas de reporte asignadas al owner.	Solo el owner.
Dar o quitar el acceso al portal (`loginEnabled`) a una persona.	Solo el owner. Al owner nadie se lo quita.

Cuenta como cambio de credenciales enviar una contraseña de acceso con valor, o un correo o una contraseña de la llave privada distintos de los guardados. Reenviar el mismo correo o la misma contraseña de la llave privada no es un cambio. En el correo, cambiar solo mayúsculas por minúsculas (o al revés) en las letras de la A a la Z tampoco cuenta; cualquier otro carácter distinto sí.

Errores

Cuando una petición rompe estas reglas, el endpoint responde 403 con el mensaje en details del modelo de respuesta.

Estado	Cuándo ocurre	Mensaje
403	Otra persona modifica al owner con Actualizar emisor, en sus datos de empleador o de empleado, o en sus reglas de descarga o de reporte.	Solo el propietario de la cuenta puede modificar al propietario de la cuenta.
403	Una persona que no es el owner cambia las credenciales de otra persona.	Solo el propietario de la cuenta puede gestionar las credenciales de otra persona: correo, contraseña, API keys y certificados.
403	Una persona que no es el owner da o quita el acceso al portal, también el suyo.	Solo el propietario de la cuenta puede dar o quitar el acceso al portal.

Modelo persona

El modelo persona contiene los datos de una persona. Las propiedades con el sufijo Id son claves de los catálogos del SAT: consúltalas en Catálogos CFDI 4.0 o desde la API, en catálogos.

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: para "MI EMPRESA S.A. de C.V.", envía MI EMPRESA. Si es persona física, envía su nombre completo como aparece en su constancia de situación fiscal.
Name
email
Type
string
required
Description
Correo electrónico de la persona, único en Fiscalapi: ninguna otra persona, de esta ni de otra cuenta, puede tener el mismo. Se compara sin distinguir mayúsculas ni los espacios de los extremos, y se guarda sin esos espacios. Solo admite letras sin acento de la A a la Z, en mayúsculas o minúsculas, dígitos y los caracteres -._@+; Fiscalapi rechaza cualquier otro carácter, como la ñ, una vocal acentuada, un apóstrofo o un espacio intermedio.
Name
phoneNumber
Type
string?
Description
Teléfono de la persona.
Name
password
Type
string?
Description
Contraseña para iniciar sesión en el dashboard. Es opcional, salvo al crear una persona con loginEnabled: true o al darle el acceso al portal a una persona que aún no tiene contraseña. Fiscalapi nunca la devuelve.
Name
satTaxRegimeId
Type
string?
expandible
Description
Régimen fiscal de la persona cuando actúa como emisor o receptor. Catálogo del SAT c_RegimenFiscal. Para actuar como empleador en facturas de nómina, la persona también necesita sus datos de empleador, con su información patronal.
Type
enum:
Values
"601""603""605"
Name
satCfdiUseId
Type
string?
expandible
Description
Uso del CFDI de la persona cuando actúa como receptor. Catálogo del SAT c_UsoCFDI.
Type
enum:
Values
"G01""G02""G03"
Name
userTypeId
Type
string?
expandible
Description
Tipo de persona, con fines informativos.
Type
enum:
Values
"C""U""T"
Name
tin
Type
string?
Description
RFC de la persona.
Name
curp
Type
string?
Description
CURP de la persona. Fiscalapi la usa en el CFDI de nómina.
Name
zipCode
Type
string?
Description
Código postal de la persona. Debe coincidir con el de su constancia de situación fiscal. Catálogo del SAT c_CodigoPostal.
Name
countryId
Type
string?
Description
Clave del país de residencia fiscal de la persona cuando reside en el extranjero. Catálogo del SAT c_Pais (por ejemplo, USA). Si la persona es el receptor de una factura por referencias, Fiscalapi la usa como ResidenciaFiscal del receptor.
Name
foreignTin
Type
string?
Description
Número de registro de identidad fiscal de la persona en su país de residencia, cuando reside en el extranjero. Máximo 40 caracteres. Si la persona es el receptor de una factura por referencias, Fiscalapi lo usa como NumRegIdTrib del receptor.
Name
country
Type
CatalogDto?
Description
País de residencia fiscal expandido (countryId con su descripción). Solo lectura.
Name
base64Photo
Type
string?
Description
Foto de perfil de la persona en formato base64.
Name
taxPassword
Type
string?
Description
Contraseña de la llave privada (.key) de los certificados CSD que la persona guarda en su perfil. Máximo 24 caracteres. Fiscalapi no la usa para sellar las facturas: al timbrar usa la contraseña de los certificados registrados, en el modo por referencias, o la de taxCredentials, en el modo por valores. Solo la propia persona y el owner del tenant la reciben con valor en las respuestas; cualquier otra persona recibe null.
Name
availableBalance
Type
number?
Description
Timbres disponibles para la persona: el saldo del tipo de crédito 1 de balances. Solo lectura y con fines informativos.
Name
availableValidationBalance
Type
number?
Description
Créditos de validación disponibles para la persona, independientes de los timbres: el saldo del tipo de crédito 2 de balances. Solo lectura y con fines informativos.
Name
committedBalance
Type
number?
Description
Campo heredado que Fiscalapi no calcula: siempre vale 0. Solo lectura: Fiscalapi lo ignora si lo envías al crear o actualizar.
Para conocer el saldo, usa availableBalance, availableValidationBalance o balances.
Name
balances
Type
array?
Description
Saldos de la persona por tipo de crédito, ordenados por creditType. Solo lectura y con fines informativos. Cada elemento trae el tipo de crédito y su saldo disponible (available). Ver timbres.
El tipo 1 son timbres, el tipo 2 créditos de validación y el tipo 3 créditos de ticket. Solo aparecen los tipos de crédito que la persona ha tenido: un tipo ausente no tiene saldo. Pueden aparecer tipos de crédito nuevos; ignora los que tu integración no conozca.
Name
tenantId
Type
string?
Description
ID del tenant al que pertenece la persona. Solo lectura y con fines informativos.
Name
isOwner
Type
boolean?
Description
true si la persona es el owner del tenant (la persona que lo creó al registrarse). Solo lectura. Ver Owner del tenant.
Name
loginEnabled
Type
boolean?
Description
Acceso al portal de la persona. Con true, la persona inicia sesión en el dashboard. El owner siempre tiene acceso, así que su valor es true. Solo el owner da o quita este acceso. No afecta a la API key: la persona usa la API con su API key tenga o no acceso al portal.
Name
validTo
Type
date?
Description
Fecha de fin de vigencia de la persona. Solo lectura: la asigna Fiscalapi, que la ignora si la envías al crear o actualizar. En la mayoría de las personas es null; algunas personas antiguas conservan una fecha histórica. Es informativa: no limita el timbrado ni el acceso a la API.
Name
manifestStatusId
Type
string?
expandible
Description
Estado del manifiesto de la persona: indica si se le invitó a firmarlo y si ya lo firmó.
Type
enum:
Values
"NotInvited""Unsigned""Signed"

GET/api/v4/people

Listar emisores

Este endpoint devuelve las personas de tu cuenta paginadas, de la más antigua a la más reciente por fecha de creación. Cada filtro aplica solo si lo envías.

Query parameters

Name
search
Type
string?
Description
Texto a buscar, de 2 a 100 caracteres, sin distinguir mayúsculas: las personas cuya razón social (legalName), RFC (tin) o correo (email) lo contiene.
Name
userTypeId
Type
string?
Description
Tipo de persona: T (tenant), U (usuario) o C (cliente), en mayúsculas. No es el tipo fiscal. Las personas sin tipo guardado no salen con ningún valor.
Name
pageNumber
Type
integer | number?
Description
Número de página, desde 1.
Default:
1
Name
pageSize
Type
integer | number?
Description
Personas por página, de 1 a 50.
Default:
50

Errores

Cada falla llega como falla de validación en el parámetro. En los mensajes, <valor> es el valor recibido.

Estado	Cuándo ocurre	Mensaje
400	El texto de search tiene 1 carácter o más de 100.	'search' debe tener entre 2 y 100 caracteres.
400	Un tipo de persona no existe.	'userTypeId' no admite '<valor>': usa T, U, C.
400	El tamaño de página no está entre 1 y 50.	'pageSize' debe estar entre 1 y 50.
400	El número de página está fuera de rango.	'pageNumber' debe estar entre 1 y 42949672.

Request

GET

/api/v4/people?search=<texto>&userTypeId=C&pageNumber=1&pageSize=50

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

Response

    {
    "data": {
        "items": [
            {
                "legalName": "KARLA FUENTE NOLASCO",
                "email": "karla@gmail.com",
                "phoneNumber": null,
                "validTo": null,
                "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
                },
                "manifestStatusId": "Unsigned",
                "manifestStatus": {
                    "id": "Unsigned",
                    "description": "No Firmado",
                    "createdAt": "2024-08-10T15:46:30.373",
                    "updatedAt": null
                },
                "tin": "FUNK671228PH6",
                "zipCode": "01160",
                "base64Photo": null,
                "taxPassword": null,
                "curp": "XEXX010101HNEXXXA4",
                "countryId": null,
                "country": null,
                "foreignTin": null,
                "availableBalance": 13,
                "committedBalance": 0,
                "availableValidationBalance": 0,
                "balances": [
                    {
                        "creditType": 1,
                        "available": 13
                    }
                ],
                "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
                "isOwner": false,
                "loginEnabled": false,
                "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 emisor por ID

Este endpoint obtiene una persona por su ID.

Errores

En el mensaje, <id> es el id que enviaste. El mensaje llega en details del modelo de respuesta.

Estado	Cuándo ocurre	Mensaje
404	La persona no existe en tu tenant.	No such resource for the given Id: <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",
        "email": "karla@gmail.com",
        "phoneNumber": null,
        "validTo": null,
        "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
        },
        "manifestStatusId": "Unsigned",
        "manifestStatus": {
            "id": "Unsigned",
            "description": "No Firmado",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "tin": "FUNK671228PH6",
        "zipCode": "01160",
        "base64Photo": null,
        "taxPassword": null,
        "curp": "XEXX010101HNEXXXA4",
        "countryId": null,
        "country": null,
        "foreignTin": null,
        "availableBalance": 13,
        "committedBalance": 0,
        "availableValidationBalance": 0,
        "balances": [
            {
                "creditType": 1,
                "available": 13
            }
        ],
        "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
        "isOwner": false,
        "loginEnabled": false,
        "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 emisor

Este endpoint crea una persona.

Modelo

Name
legalName
Type
string
required
Description
Razón social de la persona, sin régimen de capital: para "MI EMPRESA S.A. de C.V.", envía MI EMPRESA. Si es persona física, envía su nombre completo como aparece en su constancia de situación fiscal.
Name
email
Type
string
required
Description
Correo electrónico de la persona, único en Fiscalapi: ninguna otra persona, de esta ni de otra cuenta, puede tener el mismo. Se compara sin distinguir mayúsculas ni los espacios de los extremos, y se guarda sin esos espacios. Solo admite letras sin acento de la A a la Z, en mayúsculas o minúsculas, dígitos y los caracteres -._@+; Fiscalapi rechaza cualquier otro carácter, como la ñ, una vocal acentuada, un apóstrofo o un espacio intermedio.
Name
phoneNumber
Type
string?
Description
Teléfono de la persona.
Name
password
Type
string?
Description
Contraseña para iniciar sesión en el dashboard. Obligatoria solo si envías loginEnabled: true. Mínimo 6 caracteres, con al menos una mayúscula de la A a la Z, una minúscula de la a a la z, un dígito y un carácter que no sea letra ni dígito. Las letras con acento y la ñ no cuentan como mayúsculas ni minúsculas, pero sí como carácter que no es letra ni dígito.
Name
loginEnabled
Type
boolean?
Description
true para que la persona pueda iniciar sesión en el dashboard. Sin él, la persona nace sin acceso al portal; puede usar la API con una API key. Solo el owner lo da.
Default:
false
Name
satTaxRegimeId
Type
string?
expandible
Description
Régimen fiscal de la persona cuando actúa como emisor o receptor. Catálogo del SAT c_RegimenFiscal. Fiscalapi rechaza cualquier valor que no esté en el catálogo.
Type
enum:
Values
"601""603""605"
Name
satCfdiUseId
Type
string?
expandible
Description
Uso del CFDI de la persona cuando actúa como receptor. Catálogo del SAT c_UsoCFDI. Fiscalapi rechaza cualquier valor que no esté en el catálogo.
Type
enum:
Values
"G01""G02""G03"
Name
userTypeId
Type
string?
expandible
Description
Tipo de persona, con fines informativos. Si no lo envías, Fiscalapi guarda C. Fiscalapi rechaza cualquier valor fuera de esta lista, incluido T (Tenant), que está reservado para la persona que crea el tenant al registrarse.
Type
enum:
Values
"C""U"
Name
tin
Type
string?
Description
RFC de la persona.
Name
curp
Type
string?
Description
CURP de la persona. Fiscalapi la usa en el CFDI de nómina.
Name
zipCode
Type
string?
Description
Código postal de la persona. Debe coincidir con el de su constancia de situación fiscal. Catálogo del SAT c_CodigoPostal.
Name
countryId
Type
string?
Description
Clave del país de residencia fiscal de la persona cuando reside en el extranjero. Catálogo del SAT c_Pais (por ejemplo, USA). Fiscalapi rechaza cualquier valor que no esté en el catálogo. Si la persona es el receptor de una factura por referencias, Fiscalapi la usa como ResidenciaFiscal del receptor.
Name
foreignTin
Type
string?
Description
Número de registro de identidad fiscal de la persona en su país de residencia, cuando reside en el extranjero. Máximo 40 caracteres. Si la persona es el receptor de una factura por referencias, Fiscalapi lo usa como NumRegIdTrib del receptor.
Name
base64Photo
Type
string?
Description
Foto de perfil de la persona en formato base64.
Name
taxPassword
Type
string?
Description
Contraseña de la llave privada (.key) de los certificados CSD que la persona guarda en su perfil. Máximo 24 caracteres. Fiscalapi no la usa para sellar las facturas: al timbrar usa la contraseña de los certificados registrados, en el modo por referencias, o la de taxCredentials, en el modo por valores.
Name
availableBalance
Type
number?
Description
Timbres disponibles para la persona. Solo lectura y con fines informativos.
Name
availableValidationBalance
Type
number?
Description
Créditos de validación disponibles para la persona, independientes de los timbres. Solo lectura y con fines informativos.
Name
tenantId
Type
string?
Description
ID del tenant al que pertenece la persona. Solo lectura y con fines informativos.

Errores

En los mensajes, <valor> es el valor que enviaste.

Estado	Cuándo ocurre	Mensaje
403	Quien no es el owner crea una persona con `loginEnabled` en `true`.	Solo el propietario de la cuenta puede dar o quitar el acceso al portal.
400	Se crea una persona con `loginEnabled` en `true` y sin `password`. Llega como falla de validación en Password.	'Password' no debería estar vacío.
400	El correo ya pertenece a otra persona. Llega como falla de validación en Email.	The email is already registered.
400	El correo tiene un carácter no permitido. Llega como falla de validación en Email, con `errorCode` `InvalidUserName`. El mensaje nombra los caracteres rechazados; el de la tabla es el de una ñ.	The email contains characters that are not allowed: 'ñ'. Allowed characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._@+
400	La contraseña no cumple las reglas. Llega como una sola falla de validación en Password, con el `errorCode` del primer requisito que no se cumple, por ejemplo `PasswordTooShort` o `PasswordRequiresUpper`.	Un texto que enumera las reglas de la contraseña.
400	El régimen fiscal no existe en el catálogo. Llega como falla de validación en SatTaxRegimeId.	El régimen fiscal '<valor>' no existe en el catálogo c_RegimenFiscal del SAT.
400	El uso de CFDI no existe en el catálogo. Llega como falla de validación en SatCfdiUseId.	El uso de CFDI '<valor>' no existe en el catálogo c_UsoCFDI del SAT.
400	El tipo de persona es `T` o un valor distinto de `C` y `U`. Llega como falla de validación en UserTypeId.	UserTypeId debe ser uno de: C, U. 'T' está reservado y solo se permite cuando la persona ya es Tenant.
400	El país no existe en el catálogo. Llega como falla de validación en CountryId.	El país '<valor>' no existe en el catálogo c_Pais del SAT.

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",
        "email": "email@domain.com",
        "phoneNumber": null,
        "validTo": null,
        "satTaxRegimeId": null,
        "satTaxRegime": null,
        "satCfdiUseId": null,
        "satCfdiUse": null,
        "userTypeId": "C",
        "userType": null,
        "manifestStatusId": "NotInvited",
        "manifestStatus": null,
        "tin": null,
        "zipCode": null,
        "base64Photo": null,
        "taxPassword": null,
        "curp": null,
        "countryId": null,
        "country": null,
        "foreignTin": null,
        "availableBalance": 0,
        "committedBalance": 0,
        "availableValidationBalance": 0,
        "balances": [],
        "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
        "isOwner": false,
        "loginEnabled": false,
        "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/<id>

Actualizar emisor

Este endpoint actualiza una persona.

Solo el owner del tenant y la propia persona cambian sus credenciales (email, password y taxPassword), y nadie más que el owner modifica al owner; en otro caso, el endpoint responde 403. Solo el owner da o quita el acceso al portal.

Si otra petición modifica a la persona mientras se procesa esta, no se guarda nada y el endpoint responde 409. Cuenta cualquier escritura a la persona; por ejemplo, un inicio de sesión con su correo, exitoso o fallido, o un cambio en su suscripción. Vuelve a consultar la persona y repite la petición.

Modelo

Name
legalName
Type
string
required
Description
Razón social de la persona, sin régimen de capital: para "MI EMPRESA S.A. de C.V.", envía MI EMPRESA. Si es persona física, envía su nombre completo como aparece en su constancia de situación fiscal.
Name
email
Type
string
required
Description
Correo electrónico de la persona, único en Fiscalapi: ninguna otra persona, de esta ni de otra cuenta, puede tener el mismo. Se compara sin distinguir mayúsculas ni los espacios de los extremos, y se guarda sin esos espacios. Solo admite letras sin acento de la A a la Z, en mayúsculas o minúsculas, dígitos y los caracteres -._@+; Fiscalapi rechaza cualquier otro carácter, como la ñ, una vocal acentuada, un apóstrofo o un espacio intermedio. El correo actual de la persona que se actualiza no cuenta como repetido.
Name
phoneNumber
Type
string?
Description
Teléfono de la persona.
Name
password
Type
string?
Description
Contraseña de acceso al dashboard. Opcional: si no la envías, o la envías en null o vacía, se conserva la contraseña actual. Con valor, la reemplaza y sigue las mismas reglas que al crear: mínimo 6 caracteres, con al menos una mayúscula de la A a la Z, una minúscula de la a a la z, un dígito y un carácter que no sea letra ni dígito. Solo el owner del tenant cambia la contraseña de otra persona. Ver Owner del tenant.
Name
loginEnabled
Type
boolean?
Description
Acceso al portal de la persona. Opcional: si no lo envías o lo envías en null, se conserva el acceso actual. Solo el owner lo cambia, nunca la propia persona. Quitarlo cierra la sesión de la persona. Para dárselo a una persona sin contraseña, envía password en la misma petición. Al owner nadie le quita el acceso.
Name
satTaxRegimeId
Type
string?
expandible
Description
Régimen fiscal de la persona cuando actúa como emisor o receptor. Catálogo del SAT c_RegimenFiscal. Fiscalapi rechaza cualquier valor que no esté en el catálogo.
Type
enum:
Values
"601""603""605"
Name
satCfdiUseId
Type
string?
expandible
Description
Uso del CFDI de la persona cuando actúa como receptor. Catálogo del SAT c_UsoCFDI. Fiscalapi rechaza cualquier valor que no esté en el catálogo.
Type
enum:
Values
"G01""G02""G03"
Name
userTypeId
Type
string?
expandible
Description
Tipo de persona, con fines informativos. Si no lo envías o lo envías en null, Fiscalapi conserva el tipo guardado. Acepta T (Tenant) solo si la persona ya es T y rechaza cualquier otro valor fuera de esta lista.
Type
enum:
Values
"C""U"
Name
tin
Type
string?
Description
RFC de la persona.
Name
curp
Type
string?
Description
CURP de la persona. Fiscalapi la usa en el CFDI de nómina.
Name
zipCode
Type
string?
Description
Código postal de la persona. Debe coincidir con el de su constancia de situación fiscal. Catálogo del SAT c_CodigoPostal.
Name
countryId
Type
string?
Description
Clave del país de residencia fiscal de la persona cuando reside en el extranjero. Catálogo del SAT c_Pais (por ejemplo, USA). Fiscalapi rechaza cualquier valor que no esté en el catálogo. Si la persona es el receptor de una factura por referencias, Fiscalapi la usa como ResidenciaFiscal del receptor.
Name
foreignTin
Type
string?
Description
Número de registro de identidad fiscal de la persona en su país de residencia, cuando reside en el extranjero. Máximo 40 caracteres. Si la persona es el receptor de una factura por referencias, Fiscalapi lo usa como NumRegIdTrib del receptor.
Name
base64Photo
Type
string?
Description
Foto de perfil de la persona en formato base64.
Name
taxPassword
Type
string?
Description
Contraseña de la llave privada (.key) de los certificados CSD que la persona guarda en su perfil. Máximo 24 caracteres. Fiscalapi no la usa para sellar las facturas: al timbrar usa la contraseña de los certificados registrados, en el modo por referencias, o la de taxCredentials, en el modo por valores. Si no la envías o la envías en null, se conserva la contraseña guardada; con "" se borra.
Name
availableBalance
Type
number?
Description
Timbres disponibles para la persona. Solo lectura y con fines informativos.
Name
availableValidationBalance
Type
number?
Description
Créditos de validación disponibles para la persona, independientes de los timbres. Solo lectura y con fines informativos.
Name
tenantId
Type
string?
Description
ID del tenant al que pertenece la persona. Solo lectura y con fines informativos.

Errores

En los mensajes, <id> es el id de la persona y <valor> es el valor que enviaste. Los mensajes de 403, 404 y 409 llegan en details del modelo de respuesta.

Estado	Cuándo ocurre	Mensaje
404	La persona no existe en tu tenant.	No such resource for the given Id: <id>
403	Quien hace la petición no es el owner y la persona que se actualiza es el owner.	Solo el propietario de la cuenta puede modificar al propietario de la cuenta.
403	Quien hace la petición no es el owner ni la propia persona, y la petición cambia sus credenciales.	Solo el propietario de la cuenta puede gestionar las credenciales de otra persona: correo, contraseña, API keys y certificados.
403	Quien hace la petición no es el owner y envía `loginEnabled` con un valor que cambia el acceso.	Solo el propietario de la cuenta puede dar o quitar el acceso al portal.
400	Se da el acceso al portal a una persona sin contraseña y no se envía `password`. Llega como falla de validación en Password.	Para dar el acceso al portal a una persona sin contraseña, envía password en la misma petición.
400	Se quita el acceso al portal al owner. Llega como falla de validación en LoginEnabled.	El propietario de la cuenta siempre tiene acceso al portal.
409	Otra petición modificó a la persona mientras se procesaba esta.	The person was modified by another request (for example, a failed sign-in). Reload it and try again.
400	El correo ya pertenece a otra persona. Llega como falla de validación en Email.	The email is already registered.
400	El correo tiene un carácter no permitido. Llega como falla de validación en Email, con `errorCode` `InvalidUserName`. El mensaje nombra los caracteres rechazados; el de la tabla es el de una ñ.	The email contains characters that are not allowed: 'ñ'. Allowed characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._@+
400	La contraseña no cumple las reglas. Llega como una sola falla de validación en Password, con el `errorCode` del primer requisito que no se cumple, por ejemplo `PasswordTooShort` o `PasswordRequiresUpper`.	Un texto que enumera las reglas de la contraseña.
400	El régimen fiscal no existe en el catálogo. Llega como falla de validación en SatTaxRegimeId.	El régimen fiscal '<valor>' no existe en el catálogo c_RegimenFiscal del SAT.
400	El uso de CFDI no existe en el catálogo. Llega como falla de validación en SatCfdiUseId.	El uso de CFDI '<valor>' no existe en el catálogo c_UsoCFDI del SAT.
400	El tipo de persona es `T` y la persona no es Tenant, o es un valor distinto de `C` y `U`. Llega como falla de validación en UserTypeId.	UserTypeId debe ser uno de: C, U. 'T' está reservado y solo se permite cuando la persona ya es Tenant.
400	El país no existe en el catálogo. Llega como falla de validación en CountryId.	El país '<valor>' no existe en el catálogo c_Pais del SAT.

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!",
      "taxPassword": "MiSuperPass123!",
      "phoneNumber": "3312345678",
      "satTaxRegimeId": "601",
      "satCfdiUseId": "G01",
      "tin": "XAXX010101001",
      "curp": "XEXX010101HNEXXXA4",
      "zipCode": "44620",
      "base64Photo": "base64..."
}'

Response

{
    "data": {
        "legalName": "ESCUELA KEMPER URGATE",
        "email": "mi.nueva.empresa@gmail.com",
        "phoneNumber": "3312345678",
        "validTo": null,
        "satTaxRegimeId": "601",
        "satTaxRegime": {
            "id": "601",
            "description": "General de Ley Personas Morales",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satCfdiUseId": "G01",
        "satCfdiUse": {
            "id": "G01",
            "description": "Adquisición de mercancías.",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "userTypeId": "C",
        "userType": {
            "id": "C",
            "description": "Cliente",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "manifestStatusId": "NotInvited",
        "manifestStatus": {
            "id": "NotInvited",
            "description": "No invitado",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "tin": "XAXX010101001",
        "zipCode": "44620",
        "base64Photo": "base64...",
        "taxPassword": null,
        "curp": "XEXX010101HNEXXXA4",
        "countryId": null,
        "country": null,
        "foreignTin": null,
        "availableBalance": 0,
        "committedBalance": 0,
        "availableValidationBalance": 0,
        "balances": [],
        "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
        "isOwner": false,
        "loginEnabled": false,
        "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/<id>

Eliminar emisor

Este endpoint elimina una persona y, en la misma operación, revoca sus API keys: dejan de autenticar (responden 401), no aparecen en el listado de API keys y consultarlas por id responde 404. No se puede eliminar al owner del tenant: el endpoint responde 403.

Errores

En el mensaje, <id> es el id de la persona. Los mensajes llegan en details del modelo de respuesta.

Estado	Cuándo ocurre	Mensaje
404	La persona no existe en tu tenant.	No such resource for the given Id: <id>
409	Otra petición modificó a la persona mientras se procesaba esta.	The person was modified by another request (for example, a failed sign-in). Reload it and try again.

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
}