Receptores de facturas

Un receptor representa una persona física o moral que recibe facturas electrónicas. En fiscalapi, hemos diseñado este recurso con la flexibilidad necesaria para adaptarse a diferentes modelos de negocio, flujos de trabajo y necesidades de negocio. Este recurso le permite crear, consultar, actualizar y eliminar receptores, así como gestionar sus certificados CSD, éstos últimos para cuando el receptor actue como emisor.

Modelos de Negocio Soportados:

B2B (Business to Business): Una misma entidad puede actuar tanto como receptor y receptor de facturas.
B2C (Business to Customer): Soporte para receptores dedicados que solo reciben facturas, común en negocios orientados al consumidor final.

Modelo persona

El modelo persona contiene toda la información de una persona emisor o receptor, como razón social, correo, régimen de capital, régimen fiscal, uso del CFDI entre otros. A continuación, se muestra el modelo con todas sus propiedades.

Tip: Las propiedades con sufijo Id hacen referencia a catálogos del SAT. Por ejemplo, satTaxRegimeId corresponde al catálogo c_RegimenFiscal.

Propiedades

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 tal cual aparece en la constancia de situación fiscal.
Name
email
Type
string
required
Description
Correo electrónico de la persona. Para enviar la factura desde el dashboard.
Name
password
Type
string
required
Description
Contraseña para acceder al dashboard.
Se utiliza solo al crear un nuevo receptor o para cambiar la contraseña de un receptor existente. Cualquier receptor puede acceder al dashboard de fiscalapi con su correo electrónico y contraseña, dependerá de las políticas de su empresa si se le entregan o no las credenciales de acceso a sus propios clientes.
Name
CapitalRegime
Type
string?
Description
Régimen de capital de la persona. Por ejemplo: si la razón social es Mi Empresa S.A. de C.V., se debe enviar S.A. de C.V., si el receptor es persona física este campo se deja vacío.
Name
satTaxRegimeId
Type
string?
expandible
Description
Código del régimen fiscal del 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 por defecto que se aplicará este 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
"C""U"
Name
tin
Type
string?
Description
RFC del receptor (Tax Identification Number).
Name
zipCode
Type
string?
Description
Código postal del receptor; 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 del receptor en formato base64. Sin fines fiscales y solo con fines informativos.
Name
taxPassword
Type
string?
Description
Contraseña de los certificados CSD del receptor. Se utiliza para firmar las facturas emitidas.
Name
availableBalance
Type
number?
Description
Saldo disponible en la cuenta del receptor. Atributo de sólo lectura y con fines informativos.
Name
committedBalance
Type
number?
Description
Saldo en tránsito. (dispersado a personas hijas del receptor). Atributo de sólo lectura y con fines informativos.
Name
tenantId
Type
string?
Description
ID del tenant al que pertenece el receptor. Atributo de sólo lectura y con fines informativos.

GET/api/v4/people

Listar receptores

Este endpoint devuelve una lista paginada de personas (receptores y receptores). 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
int
required
Description
El número de página que se desea recuperar.
Default:
1
Name
pageSize
Type
int
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": "SERVICIO DE ADMINISTRACIÓN TRIBUTARIA",
        "capitalRegime": "SAT",
        "email": "sat@fiscalapi.com",
        "phoneNumber": null,
        "validTo": null,
        "twoFactorEnabled": false,
        "satTaxRegimeId": "601",
        "satTaxRegime": {
          "id": "601",
          "description": "General de Ley Personas Morales",
          "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": "T",
        "userType": {
          "id": "T",
          "description": "Tenant",
          "createdAt": "2024-08-10T15:46:30.3730000",
          "updatedAt": null
        },
        "tin": "XAXX010101000",
        "zipCode": "06030",
        "base64Photo": null,
        "taxPassword": null,
        "stripePaymentMethodId": null,
        "stripePaymentMethod": null,
        "availableBalance": 0,
        "committedBalance": 0,
        "subscriptionStatus": null,
        "tenantId": "1",
        "id": "-1",
        "createdAt": "2024-08-10T15:46:30.3730000",
        "updatedAt": null
      },
      {
        "legalName": "OSCAR KALA HAAK",
        "capitalRegime": null,
        "email": "oscar@gmail.com",
        "phoneNumber": null,
        "validTo": null,
        "twoFactorEnabled": false,
        "satTaxRegimeId": "621",
        "satTaxRegime": {
          "id": "621",
          "description": "Incorporación Fiscal",
          "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": "T",
        "userType": {
          "id": "T",
          "description": "Tenant",
          "createdAt": "2024-08-10T15:46:30.3730000",
          "updatedAt": null
        },
        "tin": "KAHO641101B39",
        "zipCode": "76074",
        "base64Photo": null,
        "taxPassword": "12345678a",
        "stripePaymentMethodId": "pm_1QfoxUGn1g9xyrRpz5O8Mrhk",
        "stripePaymentMethod": null,
        "availableBalance": 346,
        "committedBalance": 0,
        "subscriptionStatus": "active",
        "tenantId": "<tenant>",
        "id": "3a12e4b6-642b-4a6b-ba73-c814e4c2c873",
        "createdAt": "2025-01-07T14:24:46.4230927",
        "updatedAt": "2025-01-10T16:46:37.2659849"
      }
    ],
    "pageNumber": 1,
    "totalPages": 3,
    "totalCount": 7,
    "hasPreviousPage": false,
    "hasNextPage": true
  },
  "succeeded": true,
  "message": "",
  "details": "",
  "httpStatusCode": 200
}

GET/api/v4/people/{id}

Obtener receptor por ID

Este endpoint te permite obtener un receptor (persona) por su ID.

Request

GET

/api/v4/people/630a41d1-00ce-4750-8f8c-7b36786134d0

  curl --location 'https://test.fiscalapi.com/api/v4/people/3a12e4b6-642b-4a6b-ba73-c814e4c2c873' \
--header 'X-TENANT-KEY: <tenant>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>' \
--data ''

Response

{
  "data": {
    "legalName": "OSCAR KALA HAAK",
    "capitalRegime": null,
    "email": "oscar@gmail.com",
    "phoneNumber": null,
    "validTo": null,
    "twoFactorEnabled": false,
    "stripeCustomerId": "cus_RXoygsPKens9hE",
    "satTaxRegimeId": "621",
    "satTaxRegime": {
      "id": "621",
      "description": "Incorporación Fiscal",
      "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": "T",
    "userType": {
      "id": "T",
      "description": "Tenant",
      "createdAt": "2024-08-10T15:46:30.3730000",
      "updatedAt": null
    },
    "tin": "KAHO641101B39",
    "zipCode": "76074",
    "base64Photo": null,
    "taxPassword": "12345678a",
    "stripePaymentMethodId": "pm_1QfoxUGn1g9xyrRpz5O8Mrhk",
    "stripePaymentMethod": {
      "stripeId": "pm_1QfoxUGn1g9xyrRpz5O8Mrhk",
      "stripeCustomerId": "cus_RXoygsPKens9hE",
      "brand": "visa",
      "brandImage": "img/visa.svg",
      "country": "US",
      "description": null,
      "displayBrand": "visa",
      "expMonth": 4,
      "expYear": 2025,
      "funding": "credit",
      "last4": "4242",
      "created": "0001-01-01T00:00:00.0000000"
    },
    "availableBalance": 346,
    "committedBalance": 0,
    "subscriptionStatus": "active",
    "tenantId": "<tenant>",
    "id": "3a12e4b6-642b-4a6b-ba73-c814e4c2c873",
    "createdAt": "2025-01-07T14:24:46.4230927",
    "updatedAt": "2025-01-10T16:46:37.2659849"
  },
  "succeeded": true,
  "message": "",
  "details": "",
  "httpStatusCode": 200
}

POST/api/v4/people

Crear receptor

Este endpoint te permite crear un receptor (persona). A continuación, se muestra un ejemplo de cómo crear un receptor.

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 tal cual aparece en la constancia de situación fiscal.
Name
email
Type
string
required
Description
Correo electrónico de la persona. Para enviar la factura desde el dashboard.
Name
password
Type
string
required
Description
Contraseña para acceder al dashboard.
Se utiliza solo al crear un nuevo receptor o para cambiar la contraseña de un receptor existente. Cualquier receptor puede acceder al dashboard de fiscalapi con su correo electrónico y contraseña, dependerá de las políticas de su empresa si se le entregan o no las credenciales de acceso a sus propios clientes.
Name
CapitalRegime
Type
string?
Description
Régimen de capital de la persona. Si la razón social es Mi Empresa S.A. de C.V., se debe enviar S.A. de C.V.. Si el receptor es persona física, se deja vacío este campo.
Name
satTaxRegimeId
Type
string?
Description
Código del régimen fiscal del receptor. Catálogo del SAT c_régimenFiscal.
Type
enum:
Values
"601""603""605"
Name
cfdiUseId
Type
string?
Description
Código de uso del CFDI, para cuando este receptor actúe como receptor. Catálogo del SAT c_UsoCFDI.
Type
enum:
Values
"G01""G02""G03"
Name
userTypeId
Type
string?
Description
Tipo de persona, solo tiene fines informativos.
Type
enum:
Values
"C""U"
Name
tin
Type
string?
Description
RFC del receptor (Tax Identification Number).
Name
zipCode
Type
string?
Description
Código postal del receptor; 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 del receptor en formato base64. Sin fines fiscales y solo con fines informativos.
Name
taxPassword
Type
string?
Description
Contraseña de los certificados CSD del receptor. Se utiliza para firmar las facturas emitidas.

Request

POST

/api/v4/people

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

Response

{
    "data": {
        "legalName": "MI EMPRESA",
        "capitalRegime": null,
        "email": "kempler@gmail.com",
        "phoneNumber": null,
        "validTo": null,
        "twoFactorEnabled": false,
        "stripeCustomerId": "cus_RZ1BvJKcObcjhm",
        "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": "<tenant>",
        "id": "30022d4c-42f4-4d3f-bf5d-cfcb402d0b16",
        "createdAt": "2025-01-10T19:05:41.4497696",
        "updatedAt": "2025-01-10T19:05:41.5028668"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

PUT/api/v4/people

Actualizar receptor

Este endpoint te permite actualizar un receptor (persona).

Modelo

Name
id
Type
string
required
Description
ID del receptor. (Persona)
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, tal cual aparece en la constancia de situación fiscal.
Name
email
Type
string
required
Description
Correo electrónico de la persona. Para enviar la factura desde el dashboard.
Name
password
Type
string?
Description
Contraseña para acceder al dashboard.
Se utiliza solo al crear un nuevo receptor o para cambiar la contraseña de un receptor existente. Cualquier receptor puede acceder al dashboard de fiscalapi con su correo electrónico y contraseña, dependerá de las políticas de su empresa si se le entregan o no las credenciales de acceso a sus propios clientes.
Name
CapitalRegime
Type
string?
Description
Régimen de capital de la persona. Si la razón social es Mi Empresa S.A. de C.V., se debe enviar S.A. de C.V.. Si el receptor es persona física, se deja vacío este campo.
Name
satTaxRegimeId
Type
string?
Description
Código del régimen fiscal del receptor. Catálogo del SAT c_régimenFiscal.
Type
enum:
Values
"601""603""605"
Name
cfdiUseId
Type
string?
Description
Código de uso del CFDI que se aplicará cuando este receptor actúe como receptor. Catálogo del SAT c_UsoCFDI.
Type
enum:
Values
"G01""G02""G03"
Name
userTypeId
Type
string?
Description
Tipo de persona, solo tiene fines informativos.
Type
enum:
Values
"C""U"
Name
tin
Type
string?
Description
RFC del receptor (Tax Identification Number).
Name
zipCode
Type
string?
Description
Código postal del receptor, 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 del receptor en formato base64. Sin fines fiscales y solo con fines informativos.
Name
taxPassword
Type
string?
Description
Contraseña de los certificados CSD del receptor. Se utiliza para firmar las facturas emitidas.

Request

PUT

/api/v4/people

curl --location --request PUT 'https://test.fiscalapi.com/api/v4/people/0cd347bb-46cb-4149-afdb-31a8d802360a' \
--header 'X-TENANT-KEY: <tenant>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data-raw '{
      "id": "0cd347bb-46cb-4149-afdb-31a8d802360a",
      "legalName": "ESCUELA KEMPER URGATE",
      "email": "someone@somewhere.com",
      "password": "String1234!",
      "phoneNumber": "4611234556",
      "satTaxRegimeId": "601",
      "satCfdiUseId": "G01",
      "tin": "XAXX010101000",
      "zipCode": "44620",
      "base64Photo": "base64..."
}'

Response

{
    "data": {
        "legalName": "ESCUELA KEMPER URGATE",
        "capitalRegime": null,
        "email": "someone@somewhere.com",
        "phoneNumber": "4611234556",
        "validTo": null,
        "twoFactorEnabled": false,
        "stripeCustomerId": "cus_RYzPJYZNHf2aSf",
        "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": "<tenant>",
        "id": "0cd347bb-46cb-4149-afdb-31a8d802360a",
        "createdAt": "2025-01-10T17:15:50.7999636",
        "updatedAt": "2025-01-11T06:54:44.3695487"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

DELETE/api/v4/people

Eliminar receptor

Este endpoint te permite eliminar un receptor (persona).

Modelo

Request

DELETE

/api/v4/people

curl --location --request DELETE 'https://test.fiscalapi.com/api/v4/people/30022d4c-42f4-4d3f-bf5d-cfcb402d0b16' \
--header 'X-TENANT-KEY: <tenant>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>' \
--data ''

Response

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