Emisores de facturas

Un emisor representa una persona física o moral que genera 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 especificas. Este recurso le permite crear, consultar, actualizar y eliminar emisores, así como gestionar sus certificados CSD de manera programática.

Modelos de Negocio Soportados:

  • B2B (Business to Business): Una misma entidad puede actuar tanto como emisor como receptor de facturas.
  • B2C (Business to Customer): Soporte para emisores dedicados que solo generan 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 el sufijo Id corresponden a valores de los catálogos oficiales del SAT. Puedes consultarlos, buscarlos y filtrarlos a través del recurso catalogs.

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 emisor 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 emisor o para cambiar la contraseña de un emisor existente. Cualquier emisor 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 emisor es persona física este campo se deja vacío.

  • Name
    satTaxRegimeId
    Type
    string?
    expandible
    Description

    Código del régimen fiscal del emisor. 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á cuando este emisor 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 del emisor (Tax Identification Number).

  • Name
    zipCode
    Type
    string?
    Description

    Código postal del emisor; 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 emisor en formato base64. Sin fines fiscales y solo con fines informativos.

  • Name
    taxPassword
    Type
    string?
    Description

    Contraseña de los certificados CSD del emisor; debe corresponder con la contraseña asignada por el SAT cuando se generaron los sellos (CSD). Se utiliza para sellar (firmar) las facturas emitidas.

  • Name
    availableBalance
    Type
    number?
    Description

    Saldo disponible en la cuenta del emisor. Atributo de sólo lectura y con fines informativos.

  • Name
    committedBalance
    Type
    number?
    Description

    Saldo en tránsito. (timbres dispersados a cuentas/clientes/empresas hijas). Atributo de sólo lectura y con fines informativos.

  • Name
    tenantId
    Type
    string?
    Description

    ID del tenant al que pertenece el emisor. Atributo de sólo lectura y con fines informativos.

GET/api/v4/people

Listar emisores

Este endpoint devuelve una lista paginada de personas (emisores y/o 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 emisor por ID

Este endpoint te permite obtener un emisor (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 emisor

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

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 emisor 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 emisor o para cambiar la contraseña de un emisor existente. Cualquier emisor 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 emisor es persona física este campo se deja vacío.

  • Name
    satTaxRegimeId
    Type
    string?
    Description

    Código del régimen fiscal del emisor. Catálogo del SAT c_régimenFiscal.

    Type
    enum:
    Values
    "601""603""605"
  • Name
    satCfdiUseId
    Type
    string?
    Description

    Código de uso del CFDI por defecto que se aplicará cuando este emisor 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
    "T""C""U"
  • Name
    tin
    Type
    string?
    Description

    RFC del emisor (Tax Identification Number).

  • Name
    zipCode
    Type
    string?
    Description

    Código postal del emisor; 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 emisor en formato base64. Sin fines fiscales y solo con fines informativos.

  • Name
    taxPassword
    Type
    string?
    Description

    Contraseña de los certificados CSD del emisor; debe corresponder con la contraseña asignada por el SAT cuando se generaron los sellos (CSD). Se utiliza para sellar (firmar) las facturas emitidas.

  • Name
    availableBalance
    Type
    number?
    Description

    Saldo disponible en la cuenta del emisor. Atributo de sólo lectura y con fines informativos.

  • Name
    committedBalance
    Type
    number?
    Description

    Saldo en tránsito. (timbres dispersados a cuentas/clientes/empresas hijas). Atributo de sólo lectura y con fines informativos.

  • Name
    tenantId
    Type
    string?
    Description

    ID del tenant al que pertenece el emisor. Atributo de 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>' \
--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 emisor

Este endpoint te permite actualizar un emisor (persona).

Modelo

  • Name
    id
    Type
    string
    required
    Description

    ID del emisor. (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 emisor 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 emisor o para cambiar la contraseña de un emisor existente. Cualquier emisor 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 emisor es persona física, se deja vacío este campo.

  • Name
    satTaxRegimeId
    Type
    string?
    Description

    Código del régimen fiscal del emisor. Catálogo del SAT c_régimenFiscal.

    Type
    enum:
    Values
    "601""603""605"
  • Name
    satCfdiUseId
    Type
    string?
    Description

    Código de uso del CFDI que se aplicará cuando este emisor 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 emisor (Tax Identification Number).

  • Name
    zipCode
    Type
    string?
    Description

    Código postal del emisor, 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 emisor en formato base64. Sin fines fiscales y solo con fines informativos.

  • Name
    taxPassword
    Type
    string?
    Description

    Contraseña de los certificados CSD del emisor. 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 emisor

Este endpoint te permite eliminar un emisor (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
}

¿Le resultó útil esta página?