openapi: 3.1.0 servers: - url: https://www.facturapi.io/v2 info: title: Facturapi version: '2.0' contact: name: Facturapi url: https://www.facturapi.io email: soporte@facturapi.io x-logo: url: https://www.facturapi.io/img/logo.svg altText: Facturapi description: |

On this page, we list all the methods available in the Facturapi API, as well as the complete reference of the parameters you can send. To see the nested properties of an object or an array of objects, you can click on the field name to expand it. The Facturapi API is designed with the [REST](https://developer.mozilla.org/en-US/docs/Glossary/REST) standard in mind. The API endpoints are grouped by resources, have predictable URLs, the responses are in JSON format, and we use standard HTTP response codes, authentication, and verbs. During development, you can use the Facturapi API in the Test environment, and the invoices you issue will not be sent to the SAT (Mexican Tax Authority) and will not have fiscal validity. The secret key you use to authenticate will determine both the environment in which the invoice will be created (Test or Live), as well as the organization to use as the issuer of your invoice or as the owner of the resource you request to create. tags: - name: tools x-displayName: Tools - name: customer x-displayName: Customers - name: product x-displayName: Products - name: invoice x-displayName: Invoices - name: receipt x-displayName: E-Receipts - name: retention x-displayName: Retentions - name: organization x-displayName: Organizations - name: organization_access x-displayName: Organization users and permissions - name: webhooks x-displayName: Webhooks - name: events x-displayName: Events description: > Events occur when Facturapi performs an operation asynchronously, outside the lifecycle of an API request. To receive these events on your server, you can register a listening URL by creating a Webhook from your dashboard: https://dashboard.facturapi.io/integration/webhooks - name: sat_keys x-displayName: Keys from SAT's catálogos description: "These are the main catalogs from SAT, included here for convenience. This is by no means the full list. You can find these and more catalogs on the official SAT website: http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20_version3-3.htm\n\n### Forma de Pago\n\n(Payment Form)\n\nKey | Description (Spanish) | Description (English)\n:---:|:----------------------|:---------------------\n\"01\" | Efectivo | Cash\n\"02\" | Cheque nominativo | Nominal check\n\"03\" | Transferencia electrónica de fondos | Electronic transfer of funds\n\"04\" | Tarjeta de crédito | Credit card\n\"05\" | Monedero electrónico | Electronic wallet\n\"06\" | Dinero electrónico | Mobile payment\n\"08\" | Vales de despensa | Food vouchers\n\"12\" | Dación en pago | Payment in kind\n\"13\" | Pago por subrogación | Subrogation payment\n\"14\" | Pago por consignación | Consignment payment\n\"15\" | Condonación | Debt Forgiveness or Cancellation\n\"17\" | Compensación | Settling Debts with Existing Credits\n\"23\" | Novación | Novation\n\"24\" | Confusión | Confusion\n\"25\" | Remisión de deuda | Remission\n\"26\" | Prescripción o caducidad | Expiration of the term\n\"27\" | A satisfacción del acreedor | Satisfactory payment\n\"28\" | Tarjeta de débito | Debit card\n\"29\" | Servicio | Service payment\n\"30\" | Aplicación de anticipos | Application of advanced payments\n\"31\" | Intermediario pagos | Payment intermediation\n\"99\" | Por definir | Pending definition\n\n### Método de Pago\n\n(Payment Method)\n\nKey | Description (Spanish) | Description (English)\n:-----:|:--------------------|:---------------------\n\"PUE\" | Pago en Una [sola] Exhibición | Payment in a single installment\n\"PPD\" | Pago en Parcialidades o Diferido | Payment in installments or deferred\n\n### Uso del CFDI\n\n(CFDI use)\n\nKey | Description (Spanish) | Description (English) | Allowed Fiscal Regimes\n:-----:|:----------- |:----------- |:-----------\n\"G01\" | Adquisición de mercancías. | Purchase of goods | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"G02\" | Devoluciones, descuentos y bonificaciones. | Returns, discounts and bonuses | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"G03\" | Gastos en general. | General expenses | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"I01\" | Construcciones. | Constructions | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"I02\" | Mobiliario y equipo de oficina por inversiones. | Furniture and office equipment for investments | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"I03\" | Equipo de transporte. | Transportation equipment | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"I04\" | Equipo de computo y accesorios. | Computer equipment and accessories | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"I05\" | Dados, troqueles, moldes, matrices y herramental. | Dies, molds, matrices and tools | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"I06\" | Comunicaciones telefónicas. | Telephone communications | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"I07\" | Comunicaciones satelitales. | Satellite communications | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"I08\" | Otra maquinaria y equipo. | Other machinery and equipment | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626\n\"D01\" | Honorarios médicos, dentales y gastos hospitalarios. | Medical, dental and hospital expenses. | 605, 606, 608, 611, 612, 614, 607, 615, 625\n\"D02\" | Gastos médicos por incapacidad o discapacidad. | Medical expenses for disability. | 605, 606, 608, 611, 612, 614, 607, 615, 625\n\"D03\" | Gastos funerales. | Funeral expenses. | 605, 606, 608, 611, 612, 614, 607, 615, 625\n\"D04\" | Donativos. | Donations. | 605, 606, 608, 611, 612, 614, 607, 615, 625\n\"D05\" | Intereses reales efectivamente pagados por créditos hipotecarios (casa habitación). | Real interest actually paid for mortgage loans (housing). | 605, 606, 608, 611, 612, 614, 607, 615, 625\n\"D06\" | Aportaciones voluntarias al SAR. | Voluntary contributions to the SAR. | 605, 606, 608, 611, 612, 614, 607, 615, 625\n\"D07\" | Primas por seguros de gastos médicos. | Premiums for medical expenses insurance. | 605, 606, 608, 611, 612, 614, 607, 615, 625\n\"D08\" | Gastos de transportación escolar obligatoria. | Mandatory school transportation expenses. | 605, 606, 608, 611, 612, 614, 607, 615, 625\n\"D09\" | Depósitos en cuentas para el ahorro, primas que tengan como base planes de pensiones. | Deposits in savings accounts, premiums based on pension plans. | 605, 606, 608, 611, 612, 614, 607, 615, 625\n\"D10\" | Pagos por servicios educativos (colegiaturas). | Payments for educational services (tuition). | 605, 606, 608, 611, 612, 614, 607, 615, 625\n\"S01\" | Sin efectos fiscales. | Without fiscal effects | 601, 603, 605, 606, 608, 610, 611, 612, 614, 616, 620, 621, 622, 623, 624, 607, 615, 625, 626\n\"CP01\" | Pagos | Payments | 601, 603, 605, 606, 608, 610, 611, 612, 614, 616, 620, 621, 622, 623, 624, 607, 615, 625, 626\n\"CN01\" | Nómina | Payroll | 605\n\n### Catálogos Hidrocarburos Petrolíferos\n\n(Hydrocarbons and Petroleum Catalogs)\n\nPermit key | Description (Spanish) | Description (English)\n:-----:|:-----------|:-----------\n\"PER01\" | Expendio en estaciones de servicio de petrolíferos | Fuel station retail sales\n\"PER02\" | Comercialización | Commercialization\n\"PER03\" | Distribución por otros medios distintos a ducto | Distribution by means other than pipeline\n\"PER04\" | Expendio en estaciones de servicio multimodal de petrolíferos | Multimodal fuel station retail sales\n\"PER05\" | Expendio en estaciones de servicio de petrolíferos | Fuel station retail sales\n\"PER06\" | Comercialización | Commercialization\n\"PER07\" | Distribución por otros medios distintos a ducto | Distribution by means other than pipeline\n\"PER08\" | Expendio en estaciones de servicio multimodal de petrolíferos | Multimodal fuel station retail sales\n\"PER09\" | Comercialización | Commercialization\n\"PER10\" | Comercialización | Commercialization\n\"PER11\" | Comercialización | Commercialization\n\nHYP key | Description (Spanish) | Description (English)\n:-----:|:-----------|:-----------\n\"15101514\" | Gasolina | Gasoline\n\"15101515\" | Diesel | Diesel\n\"15101505\" | Combustibles para barco | Marine fuels\n\nSubproduct HYP | Description (Spanish) | Description (English)\n:-----:|:-----------|:-----------\n\"SP16\" | Gasolina regular menor a 91 octanos | Regular gasoline under 91 octane\n\"SP17\" | Gasolina premium mayor o igual a 91 octanos | Premium gasoline 91 octane or higher\n\"SP18\" | Diésel automotriz | Automotive diesel\n\"SP19\" | Diésel marino | Marine diesel\n\"SP22\" | IFO380 | IFO380\n\"SP23\" | Diésel industrial | Industrial diesel\n\"SP24\" | Diésel de Ultra Bajo Azufre (DUBA) | Ultra low sulfur diesel (ULSD)\n\"SP25\" | Diésel agrícola | Agricultural diesel\n\"SP48\" | Gasóleo doméstico | Domestic gas oil\n\n### Relación entre facturas\n\n(Relation between invoices)\n\nKey | Description (Spanish) | Description (English)\n:-----:|:-----------|:-----------\n\"01\" | Nota de crédito de los documentos relacionados | Credit note of the related documents\n\"02\" | Nota de débito de los documentos relacionados | Debit note of the related documents\n\"03\" | Devolución de mercancía sobre facturas o traslados previos | Return of goods on invoices or previous transfers\n\"04\" | Sustitución de los CFDI previos | Replacement of previous CFDI\n\"05\" | Traslados de mercancias facturados previamente | Transfers of goods previously invoiced\n\"06\" | Factura generada por los traslados previos | Invoice generated by previous transfers\n\"07\" | CFDI por aplicación de anticipo | CFDI by advance payment application\n\"08\" | Factura generada por pagos en parcialidades | Invoice generated by payments in installments\n\"09\" | Factura generada por pagos diferidos | Invoice generated by deferred payments\n\n### Régimen Fiscal\n\n(Fiscal Regimes or Tax Systems)\n\nKey | Description (Spanish) | Description (English)\n:-----:|:-----------|:-----------\n\"601\" |\tGeneral de Ley Personas Morales |\tGeneral Law of Legal Entities\n\"603\" |\tPersonas Morales con Fines no Lucrativos |\tNon-profit Legal Entities\n\"605\" |\tSueldos y Salarios e Ingresos Asimilados a Salarios |\tWages and Salaries and Assimilated Income\n\"606\" |\tArrendamiento |\tRent\n\"608\" |\tDemás ingresos |\tOther income\n\"609\" |\tConsolidación |\tConsolidation\n\"610\" |\tResidentes en el Extranjero sin Establecimiento Permanente en México |\tNon-residents with no Permanent Establishment in Mexico\n\"611\" |\tIngresos por Dividendos (socios y accionistas) |\tDividends (partners and shareholders)\n\"612\" |\tPersonas Físicas con Actividades Empresariales y Profesionales |\tIndividuals with Business and Professional Activities\n\"614\" |\tIngresos por intereses |\tInterest income\n\"616\" |\tSin obligaciones fiscales |\tNo tax obligations\n\"620\" |\tSociedades Cooperativas de Producción que optan por diferir sus ingresos |\tProduction Cooperatives that choose to defer their income\n\"621\" |\tIncorporación Fiscal |\tFiscal Incorporation\n\"622\" |\tActividades Agrícolas, Ganaderas, Silvícolas y Pesqueras |\tAgricultural, Livestock, Forestry and Fishing Activities\n\"623\" |\tOpcional para Grupos de Sociedades |\tOptional for Groups of Companies\n\"624\" |\tCoordinados |\tCoordinated\n\"628\" |\tHidrocarburos |\tHydrocarbons\n\"607\" |\tRégimen de Enajenación o Adquisición de Bienes |\tRegime of Alienation or Acquisition of Goods\n\"629\" |\tDe los Regímenes Fiscales Preferentes y de las Empresas Multinacionales |\tOf Preferential Tax Regimes and Multinational Companies\n\"630\" |\tEnajenación de acciones en bolsa de valores |\tSale of shares on the stock exchange\n\"615\" |\tRégimen de los ingresos por obtención de premios |\tRegime of income from obtaining prizes\n\"625\" |\tRégimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas |\tRegime of Business Activities with income through Technological Platforms\n\"626\" | Régimen Simplificado de Confianza | Simplified Trust Regime\n\n### Meses y bimestres\n\n(Months and bimesters)\n\nKey | Description (Spanish) | Description (English)\n:-----:| ----------- | -----------\n01 | Enero | January\n02 | Febrero | February\n03 | Marzo | March\n04 | Abril | April\n05 | Mayo | May\n06 | Junio | June\n07 | Julio | July\n08 | Agosto | August\n09 | Septiembre | September\n10 | Octubre | October\n11 | Noviembre | November\n12 | Diciembre | December\n13 | Enero-Febrero | January-February\n14 | Marzo-Abril | March-April\n15 | Mayo-Junio | May-June\n16 | Julio-Agosto | July-August\n17 | Septiembre-Octubre | September-October\n18 | Noviembre-Diciembre | November-December\n\n### Tipo de Contrato\n\n(Type of Contract)\n\nKey | Description (Spanish) | Description (English)\n:-----:|:----------- |:-----------\n\"01\" | Contrato de trabajo por tiempo indeterminado | Indefinite term employment contract\n\"02\" | Contrato de trabajo para obra determinada | Employment contract for a specific work\n\"03\" | Contrato de trabajo por tiempo determinado | Employment contract for a fixed term\n\"04\" | Contrato de trabajo por temporada | Seasonal employment contract\n\"05\" | Contrato de trabajo sujeto a prueba | Employment contract subject to trial\n\"06\" | Contrato de trabajo con capacitación inicial | Employment contract with initial training\n\"07\" | Modalidad de contratación por pago de hora laborada | Modality of hiring by payment of hours worked\n\"08\" | Modalidad de trabajo por comisión laboral | Labor commission work modality\n\"09\" | Modalidades de contratación donde no existe relación de trabajo | Hiring modalities where there is no employment relationship\n\"10\" | Jubilación, pensión, retiro. | Retirement, pension, retirement.\n\"99\" | Otro contrato | Other contract\n\n### Tipo de Jornada\n\n(Type of Labor Day)\n\nKey | Description (Spanish) | Description (English)\n:-----:| ----------- | -----------\n\"01\" | Diurna | Daytime\n\"02\" | Nocturna | Night\n\"03\" | Mixta | Mixed\n\"04\" | Por hora | By the hour\n\"05\" | Reducida | Reduced\n\"06\" | Continuada | Continued\n\"07\" | Partida | Split\n\"08\" | Por turnos | By shifts\n\"99\" | Otra Jornada | Other day\n\n### Tipo de Régimen\n\n(Type of Regime)\n\nKey | Description (Spanish) | Description (English)\n:-----:|:----------- |:-----------\n\"02\" | Sueldos (Incluye ingresos señalados en la fracción I del artículo 94 de LISR) | Salaries (Includes income referred to in section I of article 94 of LISR)\n\"03\" | Jubilados | Retirees\n\"04\" | Pensionados | Pensioners\n\"05\" | Asimilados Miembros Sociedades Cooperativas Produccion | Assimilated Members of Production Cooperatives\n\"06\" | Asimilados Integrantes Sociedades Asociaciones Civiles | Assimilated Members of Civil Associations\n\"07\" | Asimilados Miembros Consejos Administración Sociedades Mercantiles | Assimilated Members of the Boards of Directors of Commercial Companies\n\"08\" | Asimilados comisionistas | Assimilated commission agents\n\"09\" | Asimilados Honorarios | Assimilated Fees\n\"10\" | Asimilados acciones | Assimilated shares\n\"11\" | Asimilados otros | Assimilated others\n\"12\" | Jubilados o Pensionados | Retirees or Pensioners\n\"13\" | Indemnización o Separación | Compensation or Separation\n\"99\" | Otro Regimen | Other Regime\n\n### Riesgo del Puesto\n\n(Risk of the Position)\n\nKey | Description (Spanish) | Description (English)\n:-----:| ----------- | -----------\n\"1\" | Clase I | Class I\n\"2\" | Clase II | Class II\n\"3\" | Clase III | Class III\n\"4\" | Clase IV | Class IV\n\"5\" | Clase V | Class V\n\"99\" | No aplica | Does not apply\n\n### Periodicidad del Pago\n\n(Payment Frequency)\n\nKey | Description (Spanish) | Description (English)\n:-----:| ----------- | -----------\n\"01\" | Diario | Daily\n\"02\" | Semanal | Weekly\n\"03\" | Catorcenal | Biweekly\n\"04\" | Quincenal | Fortnightly\n\"05\" | Mensual | Monthly\n\"06\" | Bimestral | Bimonthly\n\"07\" | Unidad obra | Work unit\n\"08\" | Comisión | Commission\n\"09\" | Precio alzado | Fixed price\n\"10\" | Decenal | Ten-day\n\"99\" | Otra Periodicidad | Other Frequency\n\n### Tipo de Percepción\n\n(Type of Earnings)\n\nKey | Description (Spanish) | Description (English)\n:-----:|:----------- |:-----------\n\"001\" | Sueldos, Salarios Rayas y Jornales | Wages, Salaries, Stripes and Wages\n\"002\" | Gratificación Anual (Aguinaldo) | Annual Bonus (Aguinaldo)\n\"003\" | Participación de los Trabajadores en las Utilidades PTU | Participation of Workers in Profits PTU\n\"004\" | Reembolso de Gastos Médicos Dentales y Hospitalarios | Reimbursement of Medical, Dental and Hospital Expenses\n\"005\" | Fondo de Ahorro | Savings Fund\n\"006\" | Caja de ahorro | Savings box\n\"009\" | Contribuciones a Cargo del Trabajador Pagadas por el Patrón | Contributions to be paid by the Worker Paid by the Employer\n\"010\" | Premios por puntualidad | Punctuality Awards\n\"011\" | Prima de Seguro de vida | Life Insurance Premium\n\"012\" | Seguro de Gastos Médicos Mayores | Major Medical Expenses Insurance\n\"013\" | Cuotas Sindicales Pagadas por el Patrón | Union Dues Paid by the Employer\n\"014\" | Subsidios por incapacidad | Disability Subsidies\n\"015\" | Becas para trabajadores y/o hijos | Scholarships for workers and / or children\n\"019\" | Horas extra | Extra hours\n\"020\" | Prima dominical | Sunday premium\n\"021\" | Prima vacacional | Vacation premium\n\"022\" | Prima por antigüedad | Seniority premium\n\"023\" | Pagos por separación | Separation payments\n\"024\" | Seguro de retiro | Retirement insurance\n\"025\" | Indemnizaciones | Indemnities\n\"026\" | Reembolso por funeral | Funeral refund\n\"027\" | Cuotas de seguridad social pagadas por el patrón | Social security fees paid by the employer\n\"028\" | Comisiones | Commissions\n\"029\" | Vales de despensa | Food vouchers\n\"030\" | Vales de restaurante | Restaurant vouchers\n\"031\" | Vales de gasolina | Gasoline vouchers\n\"032\" | Vales de ropa | Clothing vouchers\n\"033\" | Ayuda para renta | Help for rent\n\"034\" | Ayuda para artículos escolares | Help for school supplies\n\"035\" | Ayuda para anteojos | Help for glasses\n\"036\" | Ayuda para transporte | Transportation help\n\"037\" | Ayuda para gastos de funeral | Help for funeral expenses\n\"038\" | Otros ingresos por salarios | Other income from salaries\n\"039\" | Jubilaciones, pensiones o haberes de retiro en una sola exhibición | Retirement, pensions or retirement benefits in a single exhibition\n\"044\" | Jubilaciones, pensiones o haberes de retiro en parcialidades | Retirement, pensions or retirement benefits in installments\n\"045\" | Ingresos en acciones o títulos valor que representan bienes | Income in shares or securities representing goods\n\"046\" | Ingresos asimilados a salarios | Income assimilated to salaries\n\"047\" | Alimentación diferentes a los establecidos en el Art 94 último párrafo LISR | Food other than those established in Art 94 last paragraph LISR\n\"048\" | Habitación | Room\n\"049\" | Premios por asistencia | Attendance awards\n\"050\" | Viáticos | Travel allowances\n\"051\" | Pagos por gratificaciones, primas, compensaciones, recompensas u otros en parcialidades | Payments for bonuses, bonuses, compensations, rewards or others in installments\n\"052\" | Pagos por jubilación en parcialidades derivados de una resolución judicial | Retirement payments in installments derived from a judicial resolution\n\"053\" | Pagos por jubilación en una sola exhibición derivados de la ejecución de una resolución judicial | Retirement payments in a single exhibition derived from the execution of a judicial resolution\n\n### Tipo de Horas\n\n(Type of Hours)\n\nKey | Description (Spanish) | Description (English)\n:-----:| ----------- | -----------\n\"01\" | Dobles | Doubles\n\"02\" | Triples | Triples\n\"03\" | Simples | Singles\n\n### Tipo de Deducción\n\n(Type of Deduction)\n\nKey | Description (Spanish) | Description (English)\n:-----:|:----------- |:-----------\n\"001\" | Seguridad social | Social security\n\"002\" | ISR | ISR (Income Tax)\n\"003\" | Aportaciones a retiro, cesantía en edad avanzada y vejez. | Contributions to retirement, old age and old age.\n\"004\" | Otros | Others\n\"005\" | Aportaciones a Fondo de vivienda | Contributions to Housing Fund\n\"006\" | Descuento por incapacidad | Disability discount\n\"007\" | Pensión alimenticia | Alimony\n\"008\" | Renta | Rent\n\"009\" | Préstamos provenientes del Fondo Nacional de la Vivienda para los Trabajadores | Loans from the National Housing Fund for Workers\n\"010\" | Pago por crédito de vivienda | Payment for housing credit\n\"011\" | Pago de abonos INFONACOT | Payment of INFONACOT installments\n\"012\" | Anticipo de salarios | Salary advance\n\"013\" | Pagos hechos con exceso al trabajador | Payments made in excess to the worker\n\"014\" | Errores | Errors\n\"015\" | Pérdidas | Losses\n\"016\" | Averías | Breakdowns\n\"017\" | Adquisición de artículos producidos por la empresa o establecimiento | Acquisition of items produced by the company or establishment\n\"018\" | Cuotas para la constitución y fomento de sociedades cooperativas y de cajas de ahorro | Fees for the constitution and promotion of cooperative societies and savings banks\n\"019\" | Cuotas sindicales | Union fees\n\"020\" | Ausencia (Ausentismo) | Absence (Absenteeism)\n\"021\" | Cuotas obrero patronales | Worker-employer fees\n\"022\" | Impuestos Locales | Local Taxes\n\"023\" | Aportaciones voluntarias al SAR | Voluntary contributions to the SAR\n\"024\" | Ajuste en Gratificación Anual (Aguinaldo) Exento | Adjustment in Annual Bonus (Aguinaldo) Exempt\n\"025\" | Ajuste en Gratificación Anual (Aguinaldo) Gravado | Adjustment in Annual Bonus (Aguinaldo) Taxed\n\"026\" | Ajuste en Participación de los Trabajadores en las Utilidades PTU Exento | Adjustment in Workers' Participation in Profits PTU Exempt\n\"027\" | Ajuste en Participación de los Trabajadores en las Utilidades PTU Gravado | Adjustment in Workers' Participation in Profits PTU Taxed\n\"028\" | Ajuste en Reembolso de Gastos Médicos Dentales y Hospitalarios Exento | Adjustment in Reimbursement of Medical, Dental and Hospital Expenses Exempt\n\"029\" | Ajuste en Fondo de ahorro Exento | Adjustment in Savings Fund Exempt\n\"030\" | Ajuste en Caja de ahorro Exento | Adjustment in Savings Box Exempt\n\"031\" | Ajuste en Contribuciones a Cargo del Trabajador Pagadas por el Patrón Exento | Adjustment in Contributions to be paid by the Worker Paid by the Employer Exempt\n\"032\" | Ajuste en Premios por puntualidad Gravado | Adjustment in Punctuality Awards Taxed\n\"033\" | Ajuste en Prima de Seguro de vida Exento | Adjustment in Life Insurance Premium Exempt\n\"034\" | Ajuste en Seguro de Gastos Médicos Mayores Exento | Adjustment in Major Medical Expenses Insurance Exempt\n\"035\" | Ajuste en Cuotas Sindicales Pagadas por el Patrón Exento | Adjustment in Union Dues Paid by the Employer Exempt\n\"036\" | Ajuste en Subsidios por incapacidad Exento | Adjustment in Disability Subsidies Exempt\n\"037\" | Ajuste en Becas para trabajadores y/o hijos Exento | Adjustment in Scholarships for workers and / or children Exempt\n\"038\" | Ajuste en Horas extra Exento | Adjustment in Extra hours Exempt\n\"039\" | Ajuste en Horas extra Gravado | Adjustment in Extra hours Taxed\n\"040\" | Ajuste en Prima dominical Exento | Adjustment in Sunday premium Exempt\n\"041\" | Ajuste en Prima dominical Gravado | Adjustment in Sunday premium Taxed\n\"042\" | Ajuste en Prima vacacional Exento | Adjustment in Vacation premium Exempt\n\"043\" | Ajuste en Prima vacacional Gravado | Adjustment in Vacation premium Taxed\n\"044\" | Ajuste en Prima por antigüedad Exento | Adjustment in Seniority premium Exempt\n\"045\" | Ajuste en Prima por antigüedad Gravado | Adjustment in Seniority premium Taxed\n\"046\" | Ajuste en Pagos por separación Exento | Adjustment in Separation payments Exempt\n\"047\" | Ajuste en Pagos por separación Gravado | Adjustment in Separation payments Taxed\n\"048\" | Ajuste en Seguro de retiro Exento | Adjustment in Retirement insurance Exempt\n\"049\" | Ajuste en Indemnizaciones Exento | Adjustment in Indemnities Exempt\n\"050\" | Ajuste en Indemnizaciones Gravado | Adjustment in Indemnities Taxed\n\"051\" | Ajuste en Reembolso por funeral Exento | Adjustment in Funeral refund Exempt\n\"052\" | Ajuste en Cuotas de seguridad social pagadas por el patrón Exento | Adjustment in Social security fees paid by the employer Exempt\n\"053\" | Ajuste en Comisiones Gravado | Adjustment in Commissions Taxed\n\"054\" | Ajuste en Vales de despensa Exento | Adjustment in Food vouchers Exempt\n\"055\" | Ajuste en Vales de restaurante Exento | Adjustment in Restaurant vouchers Exempt\n\"056\" | Ajuste en Vales de gasolina Exento | Adjustment in Gasoline vouchers Exempt\n\"057\" | Ajuste en Vales de ropa Exento | Adjustment in Clothing vouchers Exempt\n\"058\" | Ajuste en Ayuda para renta Exento | Adjustment in Help for rent Exempt\n\"059\" | Ajuste en Ayuda para artículos escolares Exento | Adjustment in Help for school supplies Exempt\n\"060\" | Ajuste en Ayuda para anteojos Exento | Adjustment in Help for glasses Exempt\n\"061\" | Ajuste en Ayuda para transporte Exento | Adjustment in Transportation help Exempt\n\"062\" | Ajuste en Ayuda para gastos de funeral Exento | Adjustment in Help for funeral expenses Exempt\n\"063\" | Ajuste en Otros ingresos por salarios Exento | Adjustment in Other income from salaries Exempt\n\"064\" | Ajuste en Otros ingresos por salarios Gravado | Adjustment in Other income from salaries Taxed\n\"065\" | Ajuste en Jubilaciones, pensiones o haberes de retiro en una sola exhibición Exento | Adjustment in Retirement, pensions or retirement benefits in a single exhibition Exempt\n\"066\" | Ajuste en Jubilaciones, pensiones o haberes de retiro en una sola exhibición Gravado | Adjustment in Retirement, pensions or retirement benefits in a single exhibition Taxed\n\"067\" | Ajuste en Pagos por separación Acumulable | Adjustment in Separation payments Accumulable\n\"068\" | Ajuste en Pagos por separación No acumulable | Adjustment in Separation payments Non-accumulable\n\"069\" | Ajuste en Jubilaciones, pensiones o haberes de retiro en parcialidades Exento | Adjustment in Retirement, pensions or retirement benefits in installments Exempt\n\"070\" | Ajuste en Jubilaciones, pensiones o haberes de retiro en parcialidades Gravado | Adjustment in Retirement, pensions or retirement benefits in installments Taxed\n\"071\" | Ajuste en Subsidio para el empleo (efectivamente entregado al trabajador) | Adjustment in Employment subsidy (effectively delivered to the worker)\n\"072\" | Ajuste en Ingresos en acciones o títulos valor que representan bienes Exento | Adjustment in Income in shares or securities representing goods Exempt\n\"073\" | Ajuste en Ingresos en acciones o títulos valor que representan bienes Gravado | Adjustment in Income in shares or securities representing goods Taxed\n\"074\" | Ajuste en Alimentación Exento | Adjustment in Food Exempt\n\"075\" | Ajuste en Alimentación Gravado | Adjustment in Food Taxed\n\"076\" | Ajuste en Habitación Exento | Adjustment in Room Exempt\n\"077\" | Ajuste en Habitación Gravado | Adjustment in Room Taxed\n\"078\" | Ajuste en Premios por asistencia Exento | Adjustment in Attendance awards Exempt\n\"079\" | Ajuste en Pagos distintos a los listados Exento | Adjustment in Payments other than those listed Exempt\n\"080\" | Ajuste en Viáticos gravados | Adjustment in Taxable travel expenses\n\"081\" | Ajuste en Viáticos (entregados al trabajador) | Adjustment in Travel expenses (delivered to the worker)\n\"082\" | Ajuste en Fondo de ahorro Gravado | Adjustment in Savings Fund Taxed\n\"083\" | Ajuste en Caja de ahorro Gravado | Adjustment in Savings Box Taxed\n\"084\" | Ajuste en Prima de Seguro de vida Gravado | Adjustment in Life Insurance Premium Taxed\n\"085\" | Ajuste en Seguro de Gastos Médicos Mayores Gravado | Adjustment in Major Medical Expenses Insurance Taxed\n\"086\" | Ajuste en Subsidios por incapacidad Gravado | Adjustment in Disability Subsidies Taxed\n\"087\" | Ajuste en Becas para trabajadores y/o hijos Gravado | Adjustment in Scholarships for workers and / or children Taxed\n\"088\" | Ajuste en Seguro de retiro Gravado | Adjustment in Retirement insurance Taxed\n\"089\" | Ajuste en Vales de despensa Gravado | Adjustment in Food vouchers Taxed\n\"090\" | Ajuste en Vales de restaurante Gravado | Adjustment in Restaurant vouchers Taxed\n\"091\" | Ajuste en Vales de gasolina Gravado | Adjustment in Gasoline vouchers Taxed\n\"092\" | Ajuste en Vales de ropa Gravado | Adjustment in Clothing vouchers Taxed\n\"093\" | Ajuste en Ayuda para renta Gravado | Adjustment in Help for rent Taxed\n\"094\" | Ajuste en Ayuda para artículos escolares Gravado | Adjustment in Help for school supplies Taxed\n\"095\" | Ajuste en Ayuda para anteojos Gravado | Adjustment in Help for glasses Taxed\n\"096\" | Ajuste en Ayuda para transporte Gravado | Adjustment in Transportation help Taxed\n\"097\" | Ajuste en Ayuda para gastos de funeral Gravado | Adjustment in Help for funeral expenses Taxed\n\"098\" | Ajuste a ingresos asimilados a salarios gravados | Adjustment to income assimilated to taxed salaries\n\"099\" | Ajuste a ingresos por sueldos y salarios gravados | Adjustment to income for taxed wages and salaries\n\"100\" | Ajuste en Viáticos exentos | Adjustment in Exempt travel expenses\n\"101\" | ISR Retenido de ejercicio anterior | ISR Retained from previous exercise\n\"102\" | Ajuste a pagos por gratificaciones, primas, compensaciones, recompensas u otros gravados | Adjustment to payments for bonuses, bonuses, compensations, rewards or others taxed\n\"103\" | Ajuste a pagos en parcialidades derivados de una resolución judicial gravados | Adjustment to payments in installments derived from a judicial resolution taxed\n\"104\" | Ajuste a pagos en parcialidades derivados de una resolución judicial exentos | Adjustment to payments in installments derived from a judicial resolution exempt\n\"105\" | Ajuste a pagos en una sola exhibición derivados de una resolución judicial gravados | Adjustment to payments in a single exhibition derived from a judicial resolution taxed\n\"106\" | Ajuste a pagos en una sola exhibición derivados de una resolución judicial exentos | Adjustment to payments in a single exhibition derived from a judicial resolution exempt\n\"107\" | Ajuste al Subsidio Causado | Adjustment to Accrued Subsidy\n\n### Tipo de Otro Pago\n\n(Type of Other Payment)\n\nKey | Description (Spanish) | Description (English)\n:-----:|:----------- |:-----------\n\"001\" | Reintegro de ISR pagado en exceso. | Refund of ISR paid in excess.\n\"002\" | Subsidio para el empleo (efectivamente entregado al trabajador). | Employment subsidy (effectively delivered to the worker).\n\"003\" | Viáticos (entregados al trabajador). | Travel expenses (delivered to the worker).\n\"004\" | Aplicación de saldo a favor por compensación anual. | Application of balance in favor by annual compensation.\n\"005\" | Reintegro de ISR retenido en exceso de ejercicio anterior | Refund of ISR retained in excess of previous exercise\n\"006\" | Alimentos en bienes (Servicios de comedor y comida). | Food in goods (Dining and food services).\n\"007\" | ISR ajustado por subsidio. | ISR adjusted by subsidy.\n\"008\" | Subsidio efectivamente entregado que no correspondía. | Subsidy effectively delivered that did not correspond.\n\"009\" | Reembolso de descuentos efectuados para el crédito de vivienda. | Refund of discounts made for housing credit.\n\"999\" | Pagos distintos a los listados. | Payments other than those listed.\n\n### Tipo de Incapacidad\n\n(Type of Disability)\n\nKey | Description (Spanish) | Description (English)\n:-----:|:----------- |:-----------\n\"01\" | Riesgo de trabajo. | Work risk.\n\"02\" | Enfermedad en general. | General illness.\n\"03\" | Maternidad. | Maternity.\n\"04\" | Licencia por cuidados médicos de hijos diagnosticados con cáncer. | License for medical care of children diagnosed with cancer.\n\n### Clave de retención\n\n(Retention Key)\n\nKey | Description (Spanish) | Description (English)\n:-----:|:----------- |:-----------\n\"01\" | Servicios profesionales. | Professional services.\n\"02\" | Regalías por derechos de autor. | Royalties for copyright.\n\"03\" | Autotransporte terrestre de carga. | Land cargo transportation.\n\"04\" | Servicios prestados por comisionistas. | Services provided by commission agents.\n\"05\" | Arrendamiento. | Lease.\n\"06\" | Enajenación de acciones. | Sale of shares.\n\"07\" | Enajenación de bienes objeto de la LIEPS, a través de mediadores, agentes, representantes, corredores, consignatarios o distribuidores. | Sale of goods subject to LIEPS, through mediators, agents, representatives, brokers, consignees or distributors.\n\"08\" | Enajenación de bienes inmuebles consignada en escritura pública. | Sale of real estate consigned in a public deed.\n\"09\" | Enajenación de otros bienes, no consignada en escritura pública. | Sale of other goods, not consigned in a public deed.\n\"10\" | Adquisición de desperdicios industriales. | Acquisition of industrial waste.\n\"11\" | Adquisición de bienes consignada en escritura pública. | Acquisition of goods consigned in a public deed.\n\"12\" | Adquisición de otros bienes, no consignada en escritura pública. | Acquisition of other goods, not consigned in a public deed.\n\"13\" | Otros retiros de AFORE. | Other withdrawals from AFORE.\n\"14\" | Dividendos o utilidades distribuidas. | Dividends or distributed profits.\n\"15\" | Remanente distribuible. | Distributable remnant.\n\"16\" | Intereses. | Interests.\n\"17\" | Arrendamiento en fideicomiso. | Lease in trust.\n\"18\" | Pagos realizados a favor de residentes en el extranjero. | Payments made in favor of residents abroad.\n\"19\" | Enajenación de acciones u operaciones en bolsa de valores. | Sale of shares or operations on the stock exchange.\n\"20\" | Obtención de premios. | Obtaining prizes.\n\"21\" | Fideicomisos que no realizan actividades empresariales. | Trusts that do not carry out business activities.\n\"22\" | Planes personales de retiro. | Personal retirement plans.\n\"23\" | Intereses reales deducibles por créditos hipotecarios. | Real interests deductible for mortgage loans.\n\"24\" | Operaciones Financieras Derivadas de Capital. | Capital Derivative Financial Operations.\n\"25\" | Otro tipo de retenciones. | Other types of retentions.\n\"26\" | Servicios mediante Plataformas Tecnológicas | Services through Technological Platforms\n\n### Validez de obligaciones\n\n(Validity of obligations)\n\n| Validity | Exempt IVA | Rate 0% | Rate 8% Noth Border | Rate 8% South Border | Rate 16%\n|:-------:|:----------:|:-------:|:------------------------:|:----------------------:|:--------\n| \"0\" | The taxpayer is not authorized to issue invoices | The taxpayer is not authorized to issue invoices | The taxpayer is not authorized to issue invoices | The taxpayer is not authorized to issue invoices | The taxpayer is not authorized to issue invoices\n| \"1\" | Yes | Yes | No | No | Yes\n| \"2\" | Yes | Yes | Yes | No | Yes\n| \"3\" | Yes | Yes | No | Yes | Yes\n| \"4\" | Yes | Yes | Yes | Yes | Yes\n\n#### Situación del contribuyente\n\n(Taxpayer situation)\n\n| Value | Description\n|:-----:|:-----------|:-----------\n| \"Previsto\" (Announced) | The taxpayer receives a letter via tax mailbox or notifications by means of a notice board, in which his situation is established and he is asked to demonstrate the materiality of the invoiced operations.\n| \"Presunto\" (Pressumed) | The notified taxpayer is considered presumed when, on its website, the authority issues its data within the list of EFOS, that is, in the SAT's blacklists.\n| \"Desvirtuado\" (Disproved) | In this case, the taxpayer accused of non-existent operations has already provided the authority with the documentation and information necessary to refute the facts that led to the notification.\n| \"Definitivo\" (Definitive) | In this case, the EFO did not respond to the authority's call within 15 days, from the last notification; or could not refute the imputed facts.\n| \"Sentencia favorable\" (Favorable sentence) | Taxpayers EFOS \"definitive\" who are dissatisfied and file some means of defense, which concludes in their favor, are classified in the list of \"favorable judgment\".\n| \"EFOS de información suprimida\" (Redacted information EFOS) | In this category, the EFOS \"presumed\" and \"definitive\" are found that presented some means of defense (amparo, nullity trial) and, therefore, a judge ordered to suppress their data from the list, without being eliminated.\n" - name: carta_porte_keys x-displayName: Carta Porte catalogs description: > Specific catalogs for the Carta Porte 3.1 complement. Useful to validate and build complement values. Each table lists the Key, the original Spanish description used officially and an English translation for reference. ### Customs Regimes (c_RegimenAduanero) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- IMD | Importación definitiva | Definitive import EXD | Exportación definitiva | Definitive export ITR | Tránsito interno de mercancías | Internal transit of goods ITE | Tránsito interno de mercancías para exportación | Internal transit of goods for export ETR | Tránsito externo de mercancías | External transit of goods ETE | Tránsito externo de mercancías para exportación | External transit of goods for export DFI | Depósito fiscal | Fiscal warehouse RFE | Recinto fiscalizado estratégico | Strategic fiscal enclosure RFS | Recinto fiscalizado | Fiscal enclosure TRA | Tránsito aduanero | Customs transit ### Transport Mode (c_MedioTransporte) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- 01 | Autotransporte | Road transport 02 | Transporte Marítimo | Maritime transport 03 | Transporte Aéreo | Air transport 04 | Transporte Ferroviario | Rail transport 05 | Otro | Other ### Station Type (c_TipoEstacion) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- 01 | Origen Nacional | National origin 02 | Intermedia | Intermediate 03 | Destino Final Nacional | National final destination ### SCT Permits (c_PermisoSCT) Key | Description (Spanish) | Description (English) :----:|:---------------------|:--------------------- TPAF01 | Autotransporte Federal de carga general. | Federal motor transport of general cargo. TPAF02 | Transporte privado de carga. | Private cargo transport. TPAF03 | Autotransporte Federal de Carga Especializada de materiales y residuos peligrosos. | Federal specialized transport of hazardous materials and waste. TPAF04 | Transporte de automóviles sin rodar en vehículo tipo góndola. | Transport of automobiles (not driven) on gondola-type vehicle. TPAF05 | Transporte de carga de gran peso y/o volumen de hasta 90 toneladas. | Heavy and/or oversized cargo transport up to 90 tons. TPAF06 | Transporte de carga especializada de gran peso y/o volumen de más 90 toneladas. | Specialized heavy and/or oversized cargo transport over 90 tons. TPAF07 | Transporte Privado de materiales y residuos peligrosos. | Private transport of hazardous materials and waste. TPAF08 | Autotransporte internacional de carga de largo recorrido. | International long‑haul cargo transport. TPAF09 | Autotransporte internacional de carga especializada de materiales y residuos peligrosos de largo recorrido. | International long‑haul specialized hazardous materials transport. TPAF10 | Autotransporte Federal de Carga General cuyo ámbito de aplicación comprende la franja fronteriza con Estados Unidos. | Federal general cargo transport within US border zone. TPAF11 | Autotransporte Federal de Carga Especializada cuyo ámbito de aplicación comprende la franja fronteriza con Estados Unidos. | Federal specialized cargo transport within US border zone. TPAF12 | Servicio auxiliar de arrastre en las vías generales de comunicación. | Auxiliary towing service on federal roads. TPAF13 | Servicio auxiliar de servicios de arrastre, arrastre y salvamento, y depósito de vehículos en las vías generales de comunicación. | Auxiliary towing, recovery and vehicle storage service. TPAF14 | Servicio de paquetería y mensajería en las vías generales de comunicación. | Parcel and courier service. TPAF15 | Transporte especial para el tránsito de grúas industriales con peso máximo de 90 toneladas. | Special transit for industrial cranes up to 90 tons. TPAF16 | Servicio federal para empresas arrendadoras servicio público federal. | Federal public service for rental companies. TPAF17 | Empresas trasladistas de vehículos nuevos. | New vehicle relocation companies. TPAF18 | Empresas fabricantes o distribuidoras de vehículos nuevos. | New vehicle manufacturers or distributors. TPAF19 | Autorización expresa para circular ... tractocamión doblemente articulado. | Express authorization for double‑articulated tractor‑trailers. TPAF20 | Autotransporte Federal de Carga Especializada de fondos y valores. | Federal specialized transport of funds and valuables. TPTM01 | Permiso temporal para navegación de cabotaje | Temporary cabotage navigation permit. TPTA01 | Concesión/ autorización servicio regular nacional/internacional empresas mexicanas | Regular national/international air service concession (Mexican companies). TPTA02 | Permiso servicio aéreo regular empresas extranjeras | Regular air service permit (foreign companies). TPTA03 | Permiso servicio nacional e internacional no regular de fletamento | Charter (non‑regular) national/international air service permit. TPTA04 | Permiso servicio nacional e internacional no regular de taxi aéreo | Non‑regular national/international air taxi permit. TPXX00 | Permiso no contemplado en el catálogo. | Permit not listed in catalog. ### COFEPRIS Sector (c_SectorCOFEPRIS) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- 01 | Medicamento | Medicine 02 | Precursores y químicos de uso dual | Precursors and dual‑use chemicals 03 | Psicotrópicos y estupefacientes | Psychotropic and narcotic substances 04 | Sustancias tóxicas | Toxic substances 05 | Plaguicidas y fertilizantes | Pesticides and fertilizers ### Pharmaceutical Form (c_FormaFarmacéutica) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- 01 | Tableta | Tablet 02 | Cápsulas | Capsules 03 | Comprimidos | Compressed tablets 04 | Grageas | Sugar‑coated pills 05 | Suspensión | Suspension 06 | Solución | Solution 07 | Emulsión | Emulsion 08 | Jarabe | Syrup 09 | Inyectable | Injectable 10 | Crema | Cream 11 | Ungüento | Ointment 12 | Aerosol | Aerosol 13 | Gas medicinal | Medicinal gas 14 | Gel | Gel 15 | Implante | Implant 16 | Óvulo | Ovule 17 | Parche | Patch 18 | Pasta | Paste 19 | Polvo | Powder 20 | Supositorio | Suppository ### Special Conditions (c_CondicionesEspeciales) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- 01 | Congelados | Frozen 02 | Refrigerados | Refrigerated 03 | Temperatura controlada | Controlled temperature 04 | Temperatura ambiente | Room temperature ### Material Type (c_TipoMateria) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- 01 | Materia prima | Raw material 02 | Materia procesada | Processed material 03 | Materia terminada (producto terminado) | Finished material (final product) 04 | Materia para la industria manufacturera | Material for manufacturing industry 05 | Otra | Other ### Customs Document Type (c_TipoDocumentoAduanero) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- 01 | Pedimento | Customs entry (Pedimento) 02 | Autorización de importación temporal | Temporary import authorization 03 | Autorización de importación temporal de embarcaciones | Temporary vessel import authorization 04 | Autorización de importación temporal mercancías p/ mantenimiento y reparación | Temp. import auth. for goods for maintenance/repair 05 | Autorización importación vehículos especializados | Import auth. specialized transformed vehicles 06 | Aviso de exportación temporal | Temporary export notice 07 | Aviso traslado mercancías IMMEX/RFE/Operador Autorizado | Goods transfer notice IMMEX/RFE/Authorized Operator 08 | Aviso traslado autopartes franja fronteriza | Auto parts transfer notice (border region) 09 | Constancia importación temporal/retorno/transferencia contenedores | Constancy temp import/return/transfer of containers 10 | Constancia de transferencia de mercancías | Goods transfer constancy 11 | Autorización donación mercancías Fisco Federal extranjero | Donation authorization (goods abroad) to Federal Treasury 12 | Cuaderno ATA | ATA carnet 13 | Listas de intercambio | Exchange lists 14 | Permiso de Importación Temporal | Temporary import permit 15 | Permiso importación temporal casa rodante | Temporary import permit (RV) 16 | Permiso importación temporal embarcaciones | Temporary import permit (vessels) 17 | Solicitud donación mercancías emergencias/desastres | Donation request (emergencies/disasters) 18 | Aviso de consolidado | Consolidated notice 19 | Aviso de cruce de mercancias | Goods crossing notice 20 | Otro | Other ### Transport Part Type (c_ParteTransporte) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- PT01 | Camión unitario | Single unit truck PT02 | Camión | Truck PT03 | Tractocamión | Tractor truck PT04 | Remolque | Trailer PT05 | Semirremolque | Semi‑trailer PT06 | Vehículo ligero de carga | Light cargo vehicle PT07 | Grúa | Crane PT08 | Aeronave | Aircraft PT09 | Barco o buque | Ship or vessel PT10 | Carro o vagón | Railcar or wagon PT11 | Contenedor | Container PT12 | Locomotora | Locomotive ### Transport Figure (c_FiguraTransporte) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- 01 | Operador | Operator 02 | Propietario | Owner 03 | Arrendador | Lessor 04 | Notificado | Notified party 05 | Integrante de Coordinados | Coordinated group member ### ISTMO Registry (c_RegistroISTMO) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- 01 | Coatzacoalcos I | Coatzacoalcos I 02 | Coatzacoalcos II | Coatzacoalcos II 03 | Texistepec | Texistepec 04 | San Juan Evangelista | San Juan Evangelista 05 | Salina Cruz | Salina Cruz 06 | San Blas Atempa | San Blas Atempa ### Cargo Type Key (c_ClaveTipoCarga) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- CGS | Carga General Suelta | General loose cargo CGC | Carga General Contenerizada | General containerized cargo GMN | Gran Mineral | Bulk mineral GAG | Granel Agrícola | Agricultural bulk OFL | Otros Fluidos | Other fluids PYD | Petróleo y Derivados | Oil and derivatives ### Maritime Configuration (c_ConfiguracionMaritima) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- B01 | Abastecedor | Supplier vessel B02 | Barcaza | Barge B03 | Granelero | Bulk carrier B04 | Porta Contenedor | Container ship B05 | Draga | Dredger B06 | Pesquero | Fishing vessel B07 | Carga General | General cargo B08 | Quimiqueros | Chemical tanker B09 | Transbordadores | Ferry B10 | Carga RoRo | Ro-Ro cargo B11 | Investigación | Research vessel B12 | Tanquero | Tanker B13 | Gasero | Gas carrier B14 | Remolcador | Tug B15 | Extraordinaria especialización | Extraordinary specialization ### Rail Traffic Type (c_TraficoFerroviario) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- TT01 | Tráfico local | Local traffic TT02 | Tráfico interlineal remitido | Forwarded interline traffic TT03 | Tráfico interlineal recibido | Received interline traffic TT04 | Tráfico interlineal en tránsito | Interline traffic in transit ### Container Type (c_TipoContenedor) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- TC01 | Contenedor de 6.1 Mts de longitud | 20' container (6.1 m length) TC02 | Contenedor de 12.2 Mts de longitud | 40' container (12.2 m length) TC03 | Contenedor de 13.7 Mts de longitud | 45' container (13.7 m length) TC04 | Contenedor de 14.6 Mts de longitud | 48' container (14.6 m length) TC05 | Contenedor de 16.1 Mts de longitud | 53' container (16.1 m length) ### Maritime Container Type (c_TipoContenedorMaritimo) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- CM001 | Contenedores refrigerados de 20FT | 20FT refrigerated containers CM002 | Contenedores refrigerados de 40FT | 40FT refrigerated containers CM003 | Contenedores estándar de 8FT | 8FT standard containers CM004 | Contenedores estándar de 10FT | 10FT standard containers CM005 | Contenedores estándar de 20FT | 20FT standard containers CM006 | Contenedores estándar de 40FT | 40FT standard containers CM007 | Contenedores Open Side | Open side containers CM008 | Contenedor Isotanque | ISO tank container CM009 | Contenedor flat racks | Flat rack container CM010 | Buque tanque | Tanker ship CM011 | Ferri | Ferry CM012 | Ferri – Turístico y vacíos | Tourist / empty ferry ### Rail Car Type (c_TipoCarroFerroviario) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- TC01 | Furgón | Boxcar TC02 | Góndola | Gondola TC03 | Tolva | Hopper TC04 | Tanque | Tank car TC05 | Plataforma Intermodal | Intermodal platform car TC06 | Plataforma de Uso General | General purpose flatcar TC07 | Plataforma Automotriz | Automotive platform car TC08 | Locomotora | Locomotive TC09 | Carro Especial | Special car TC10 | Pasajeros | Passenger car TC11 | Mantenimiento de Vía | Track maintenance equipment ### Rail Service Type (c_TipoServicioFerroviario) Key | Description (Spanish) | Description (English) :--:|:----------------------|:--------------------- TS01 | Carros Ferroviarios | Rail cars TS02 | Carros Ferroviarios intermodal | Intermodal rail cars TS03 | Tren unitario de carros ferroviarios | Unit train (rail cars) TS04 | Tren unitario Intermodal | Unit train (intermodal) - name: comercio_exterior_keys x-displayName: Comercio Exterior catalogs description: > Catalogs specific to the Comercio Exterior 2.0 complement. Useful to validate and build correct values for the complement. Each table includes: Key | Description (English) ### Transfer reason (c_MotivoTraslado) Key | Description :--:| ----------- 01 | Shipment of previously invoiced goods 02 | Relocation of own goods 03 | Shipment of goods under consignment contract 04 | Shipment of goods for subsequent sale 05 | Shipment of third-party owned goods 99 | Other ### Incoterm (c_INCOTERM) Key | Description :--:| ----------- CFR | Cost and freight (agreed port of destination). CIF | Cost, insurance and freight (agreed port of destination). CPT | Carriage paid to (agreed place of destination). CIP | Carriage and insurance paid to (agreed place of destination). DAP | Delivered at place. DDP | Delivered duty paid (agreed place of destination). DPU | Delivered at place unloaded. EXW | Ex works (agreed place). FCA | Free carrier (named place). FAS | Free alongside ship (agreed port of shipment). FOB | Free on board (agreed port of shipment). ### Customs Unit (c_UnidadAduana) Key | Description :--:| ----------- 01 | KILO 02 | GRAM 03 | LINEAR METER 04 | SQUARE METER 05 | CUBIC METER 06 | PIECE 07 | HEAD 08 | LITER 09 | PAIR 10 | KILOWATT 11 | THOUSAND 12 | SET 13 | KILOWATT/HOUR 14 | TON 15 | BARREL 16 | NET GRAM 17 | TENS 18 | HUNDREDS 19 | DOZENS 20 | BOX 21 | BOTTLE 22 | CARAT 99 | SERVICE - name: customer_model x-displayName: Customer object description: | - name: product_model x-displayName: Product object description: | - name: invoice_model x-displayName: Invoice object description: | - name: receipt_model x-displayName: Receipt object description: | - name: retention_model x-displayName: Retention object description: | - name: organization_model x-displayName: Organization object description: | x-tagGroups: - name: Resources tags: - customer - product - invoice - receipt - retention - organization - organization_access - name: Tools tags: - tools - sat_keys - carta_porte_keys - comercio_exterior_keys - name: Webhooks tags: - events - webhooks - name: Models tags: - customer_model - product_model - invoice_model - receipt_model - retention_model - organization_model paths: /catalogs/cartaporte/3.1/air-transport-codes: get: tags: - carta_porte_keys summary: Search air transport codes description: > Returns airline codes catalog entries that match the query. Intended for Carta Porte complement. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/cartaporte/3.1/air-transport-codes" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=AMX" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.cartaPorteCatalogs.searchAirTransportCodes({ q: 'AMX', page: 0, limit: 10 }) - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.cartaPorteCatalogs().searchAirTransportCodes( Map.of( "q", "CC", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->CartaPorteCatalogs->searchAirTransportCodes([ "q" => "AMX", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.CartaporteCatalog.SearchAirTransportCodes(new Dictionary { ["q"] = "AMX", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: Prefix to match against `key`, `airline_name` or `icao_designator`. - in: query name: page schema: type: integer minimum: 0 required: false - in: query name: limit schema: type: integer minimum: 1 required: false responses: '200': description: Successful search content: application/json: schema: type: object properties: page: type: integer total_pages: type: integer total_results: type: integer data: type: array items: type: object properties: key: type: string description: type: string /catalogs/cartaporte/3.1/transport-configs: get: tags: - carta_porte_keys summary: Search auto transport configurations description: >- Returns transport configuration entries (e.g., truck/semitrailer setups). x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/cartaporte/3.1/transport-configs" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=CC" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.cartaPorteCatalogs.searchTransportConfigs({ q: 'CC', page: 0, limit: 10 }) - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.cartaPorteCatalogs().searchTransportConfigs( Map.of( "q", "llantas", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->CartaPorteCatalogs->searchTransportConfigs([ "q" => "llantas", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.CartaporteCatalog.SearchTransportConfigs(new Dictionary { ["q"] = "llantas", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: Prefix to match against `key` or `description`. - in: query name: page schema: type: integer minimum: 0 - in: query name: limit schema: type: integer minimum: 1 responses: '200': description: Successful search content: application/json: schema: $ref: '#/components/schemas/SearchKeyDescriptionResult' /catalogs/comercioexterior/2.0/tariff-fractions: get: tags: - comercio_exterior_keys summary: Search tariff fractions description: Returns tariff fractions that match the query. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/comercioexterior/2.0/tariff-fractions" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=0101" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.comercioExteriorCatalogs.searchTariffFractions({ q: '0101', page: 0, limit: 10 }) - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.comercioExteriorCatalogs().searchTariffFractions( Map.of( "q", "0101", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->ComercioExteriorCatalogs->searchTariffFractions([ "q" => "0101", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.ComercioExteriorCatalog.SearchTariffFractions(new Dictionary { ["q"] = "0101", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: Prefix to match against `key` or `description`. - in: query name: page schema: type: integer minimum: 0 required: false - in: query name: limit schema: type: integer minimum: 1 required: false responses: '200': description: Successful search content: application/json: schema: $ref: '#/components/schemas/SearchKeyDescriptionResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /catalogs/cartaporte/3.1/rights-of-passage: get: tags: - carta_porte_keys summary: Search rights of passage description: Returns rail rights of passage matching the query. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/cartaporte/3.1/rights-of-passage" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=CDP001" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.cartaPorteCatalogs.searchRightsOfPassage({ q: 'CDP001', page: 0, limit: 10 }) - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.cartaPorteCatalogs().searchRightsOfPassage( Map.of( "q", "CDP001", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->CartaPorteCatalogs->searchRightsOfPassage([ "q" => "CDP001", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.CartaporteCatalog.SearchRightsOfPassage(new Dictionary { ["q"] = "CDP001", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: >- Prefix to match against `key`, `right_of_passage` or `concessionaire`. - in: query name: page schema: type: integer minimum: 0 - in: query name: limit schema: type: integer minimum: 1 responses: '200': description: Successful search content: application/json: schema: $ref: '#/components/schemas/SearchKeyDescriptionResult' /catalogs/cartaporte/3.1/customs-documents: get: tags: - carta_porte_keys summary: Search customs documents description: Returns customs document types for Carta Porte. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/cartaporte/3.1/customs-documents" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=PEDIMENTO" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.cartaPorteCatalogs.searchCustomsDocuments({ q: 'PEDIMENTO', page: 0, limit: 10 }) - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.cartaPorteCatalogs().searchCustomsDocuments( Map.of( "q", "AMX", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->CartaPorteCatalogs->searchCustomsDocuments([ "q" => "PEDIMENTO", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.CartaporteCatalog.SearchCustomsDocuments(new Dictionary { ["q"] = "PEDIMENTO", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: Prefix to match against `key` or `description`. - in: query name: page schema: type: integer minimum: 0 - in: query name: limit schema: type: integer minimum: 1 responses: '200': description: Successful search content: application/json: schema: $ref: '#/components/schemas/SearchKeyDescriptionResult' /catalogs/cartaporte/3.1/packaging-types: get: tags: - carta_porte_keys summary: Search packaging types description: Returns packaging types for goods in Carta Porte. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/cartaporte/3.1/packaging-types" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=CAJA" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.cartaPorteCatalogs.searchPackagingTypes({ q: 'BOX', page: 0, limit: 10 }) - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.cartaPorteCatalogs().searchPackagingTypes( Map.of( "q", "AMX", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->CartaPorteCatalogs->searchPackagingTypes([ "q" => "BOX", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.CartaporteCatalog.SearchPackagingTypes(new Dictionary { ["q"] = "BOX", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: Prefix to match against `key` or `description`. - in: query name: page schema: type: integer minimum: 0 - in: query name: limit schema: type: integer minimum: 1 responses: '200': description: Successful search content: application/json: schema: $ref: '#/components/schemas/SearchKeyDescriptionResult' /catalogs/cartaporte/3.1/trailer-types: get: tags: - carta_porte_keys summary: Search trailer types description: Returns trailer/semitrailer types (Clave de Remolque). x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/cartaporte/3.1/trailer-types" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=CTR001" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.cartaPorteCatalogs.searchTrailerTypes({ q: 'CTR001', page: 0, limit: 10 }) - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.cartaPorteCatalogs().searchTrailerTypes( Map.of( "q", "AMX", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->CartaPorteCatalogs->searchTrailerTypes([ "q" => "CTR001", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.CartaporteCatalog.SearchTrailerTypes(new Dictionary { ["q"] = "CTR001", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: Prefix to match against `key` or `description`. - in: query name: page schema: type: integer minimum: 0 - in: query name: limit schema: type: integer minimum: 1 responses: '200': description: Successful search content: application/json: schema: $ref: '#/components/schemas/SearchKeyDescriptionResult' /catalogs/cartaporte/3.1/hazardous-materials: get: tags: - carta_porte_keys summary: Search hazardous materials description: Returns hazardous materials catalog entries. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/cartaporte/3.1/hazardous-materials" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=solido" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.cartaPorteCatalogs.searchHazardousMaterials({ q: 'solido', page: 0, limit: 10 }) - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.cartaPorteCatalogs().searchHazardousMaterials( Map.of( "q", "AMX", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->CartaPorteCatalogs->searchHazardousMaterials([ "q" => "solido", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.CartaporteCatalog.SearchHazardousMaterials(new Dictionary { ["q"] = "solido", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: Prefix to match against `key`, `description` or `class_division`. - in: query name: page schema: type: integer minimum: 0 - in: query name: limit schema: type: integer minimum: 1 responses: '200': description: Successful search content: application/json: schema: $ref: '#/components/schemas/SearchKeyDescriptionResult' /catalogs/cartaporte/3.1/naval-authorizations: get: tags: - carta_porte_keys summary: Search naval authorizations description: Returns naval authorization codes (key only). x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/cartaporte/3.1/naval-authorizations" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=SCT418/069/2018" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.cartaPorteCatalogs.searchNavalAuthorizations({ q: 'SCT418/069/2018', page: 0, limit: 10 }) - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.cartaPorteCatalogs().searchNavalAuthorizations( Map.of( "q", "AMX", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->CartaPorteCatalogs->searchNavalAuthorizations([ "q" => "SCT418/069/2018", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.CartaporteCatalog.SearchNavalAuthorizations(new Dictionary { ["q"] = "SCT418/069/2018", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: Prefix to match against `key`. - in: query name: page schema: type: integer minimum: 0 - in: query name: limit schema: type: integer minimum: 1 responses: '200': description: Successful search content: application/json: schema: type: object properties: page: type: integer total_pages: type: integer total_results: type: integer data: type: array items: type: object properties: key: type: string /catalogs/cartaporte/3.1/port-stations: get: tags: - carta_porte_keys summary: Search port stations description: Returns airport/sea/land station entries. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/cartaporte/3.1/port-stations" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=MEX" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.cartaPorteCatalogs.searchPortStations({ q: 'MEX', page: 0, limit: 10 }) - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.cartaPorteCatalogs().searchPortStations( Map.of( "q", "AMX", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->CartaPorteCatalogs->searchPortStations([ "q" => "MEX", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.CartaporteCatalog.SearchPortStations(new Dictionary { ["q"] = "MEX", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: Prefix to match against `key`, `description` or `iata_designator`. - in: query name: page schema: type: integer minimum: 0 - in: query name: limit schema: type: integer minimum: 1 responses: '200': description: Successful search content: application/json: schema: $ref: '#/components/schemas/SearchKeyDescriptionResult' /catalogs/cartaporte/3.1/marine-containers: get: tags: - carta_porte_keys summary: Search marine containers description: Returns marine container types. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/catalogs/cartaporte/3.1/marine-containers" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=FERRI" \ -d "page=0" \ -d "limit=10" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.cartaPorteCatalogs.searchMarineContainers({ q: 'FERRI', page: 0, limit: 10 }) - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.cartaPorteCatalogs().searchMarineContainers( Map.of( "q", "AMX", "page", 0, "limit", 10 ) ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->CartaPorteCatalogs->searchMarineContainers([ "q" => "FERRI", "page" => 0, "limit" => 10 ]); - lang: csharp label: .NET source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.CartaporteCatalog.SearchMarineContainers(new Dictionary { ["q"] = "FERRI", ["page"] = 0, ["limit"] = 10 }); parameters: - in: query name: q schema: type: string required: true description: Prefix to match against `key` or `description`. - in: query name: page schema: type: integer minimum: 0 - in: query name: limit schema: type: integer minimum: 1 responses: '200': description: Successful search content: application/json: schema: $ref: '#/components/schemas/SearchKeyDescriptionResult' /customers: post: operationId: createCustomer tags: - customer summary: Create Customer description: | Register a new customer in Facturapi. This call validates that the fiscal data matches the records of the SAT for that RFC, otherwise the call will return an error indicating the issue. Once the customer is created and a response object is obtained, we recommend saving the ID in your database along with the customer information. Later, you can call the Create Invoice endpoint by passing the customer ID instead of repeating the information. Finally, keep in mind that the customers you create in the Test environment **are not shared** with the Live environment. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/customers \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "legal_name": "Dunder Mifflin", "email": "email@example.com", "tax_id": "ABC101010111", "tax_system": "601", "address": { "zip": "01234" } }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const customer = await facturapi.customers.create({ legal_name: 'Dunder Mifflin', email: 'email@example.com', tax_id: 'ABC101010111', tax_system: '601', address: { zip: '01234' } }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Customer.CreateAsync(new Dictionary { ["legal_name"] = "Dunder Mifflin", ["email"] = "email@example.com", ["tax_id"] = "ABC101010111", ["tax_system"] = "601", ["address"] = new Dictionary { ["zip"] = "01234" } }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var customer = facturapi.customers().create( Map.of( "legal_name", "Mi Empresa SA de CV", "tax_id", "XAXX010101000", "tax_system", "601", "email", "cliente@example.com" ), null ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $customer = $facturapi->Customers->create([ "email" => "email@example.com", "legal_name" => "Dunder Mifflin", "tax_id" => "ABC101010111", "tax_system" => "601", "address" => [ "zip" => "01234" ] ]); requestBody: $ref: '#/components/requestBodies/CustomerCreate' parameters: - in: query name: createEditLink schema: type: boolean required: false description: > If set to `true`, the response will include a link you can share with the customer to allow them to edit their information. This link will be available from the `edit_link` field, will be valid for 7 days and can only be used once. Additionally, setting this parameter to `true` will skip the validation of the customer's fiscal data, allowing you to create customers with incomplete information. security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: A previously-registered `Customer` object with the same information. content: application/json: schema: $ref: '#/components/schemas/Customer' '201': description: New `Customer` object just created content: application/json: schema: $ref: '#/components/schemas/Customer' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' get: operationId: listCustomers tags: - customer summary: List customers description: >- Returns a paginated list of all customers in an organization or performs a search according to parameters. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/customers \ -H "Authorization: Bearer sk_test_API_KEY" \ -G \ -d 'q=Dunder' \ -d 'date[gt]=2021-07-14T06:00:00.000Z' \ -d 'date[lt]=2021-08-14T06:00:00.000Z' \ -d 'page=1' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const searchResult = await facturapi.customers.list({ q: 'Dunder', date: { gt: new Date('2021-07-14T06:00:00.000Z'), lt: new Date('2021-08-14T06:00:00.000Z') }, page: 1 }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var searchResult = await facturapi.Customer.ListAsync(new Dictionary { ["q"] = "Dunder", ["date"] = new Dictionary { ["gt"] = new DateTime("2021-07-14T06:00:00.000Z"), ["lt"] = new DateTime("2021-08-14T06:00:00.000Z") }, ["page"] = 1 }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var searchResult = facturapi.customers().list( Map.of( "page", 0, "limit", 10 ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $searchResult = $facturapi->Customers->all([ "q" => "Dunder", "date" => [ "gt" => new DateTime("2021-07-14T06:00:00.000Z"), "lt" => new DateTime("2021-08-14T06:00:00.000Z") ], "page" => 1 ]); parameters: - in: query name: q schema: type: string description: >- Free text field. Search word matches with `legal_name` or `tax_id` fields. - $ref: '#/components/parameters/SearchDate' - $ref: '#/components/parameters/SearchPage' - $ref: '#/components/parameters/SearchLimit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/CustomerSearchResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /customers/{customer_id}: get: operationId: getCustomer tags: - customer summary: Retrieve customer by ID description: >- Returns the 'Customer' object with the specified ID. If the customer does not exist, a 404 error will be returned. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/customers/590ce6c56d04f840aa8438af \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const customer = await facturapi.customers.retrieve('590ce6c56d04f840aa8438af'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Customer.RetrieveAsync("590ce6c56d04f840aa8438af"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var customer = facturapi.customers().retrieve( "cus_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $customer = $facturapi->Customers->retrieve( "5a3ee743f508333611ad6b3c" ); parameters: - in: path name: customer_id schema: type: string required: true description: Customer ID security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Customer` object' content: application/json: schema: $ref: '#/components/schemas/Customer' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' put: operationId: editCustomer tags: - customer summary: Edit Customer description: >- Updates the information of an existing customer, setting only the values for the paramenters that are sent. Undefined values will not be modified. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/customers/590ce6c56d04f840aa8438af \ -X PUT -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "jdoe@example.com", "address": { "street": "Santa Monica Ave." } }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const customer = await facturapi.customers.update( '590ce6c56d04f840aa8438af', { email: 'jdoe@example.com', address: { street: 'Santa Monica Ave.' } } ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Customer.UpdateAsync( "590ce6c56d04f840aa8438af", new Dictionary { ["email"] = "jdoe@example.com", ["address"] = new Dictionary { ["street"] = "Santa Monica Ave." } } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var customer = facturapi.customers().update( "cus_123", Map.of( "legal_name", "Mi Empresa SA de CV", "email", "cliente@example.com" ), null ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $customer = $facturapi->Customers->update("590ce6c56d04f840aa8438af", [ "email" => "jdoe@example.com", "legal_name" => "Dunder Mifflin", "address" => [ "street" => "Santa Monica Ave." ] ]); parameters: - in: path name: customer_id schema: type: string required: true description: ID of the object to edit - in: query name: createEditLink schema: type: boolean required: false description: > If set to `true`, the response will include a link you can share with the customer to allow them to edit their information. This link will be available from the `edit_link` field, will be valid for 7 days and can only be used once. Setting this parameter to `true` while editing a customer will **not** skip the validation of the customer's fiscal data. requestBody: $ref: '#/components/requestBodies/CustomerEdit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Customer` object edited successfully' content: application/json: schema: $ref: '#/components/schemas/Customer' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: deleteCustomer tags: - customer summary: Delete Customer description: >- Deletes a customer. The invoices linked to the customer will **not** be deleted. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/customers/590ce6c56d04f840aa8438af \ -X DELETE \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const removedCustomer = await facturapi.customers.del('590ce6c56d04f840aa8438af'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Customer.DeleteAsync("590ce6c56d04f840aa8438af"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var customer = facturapi.customers().delete( "cus_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $facturapi->Customers->delete( "5a3fefd9f508333611ad6b43" ); parameters: - in: path name: customer_id schema: type: string required: true description: ID of the object to delete security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Customer` object deleted successfully' content: application/json: schema: $ref: '#/components/schemas/Customer' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /customers/{customer_id}/email-edit-link: post: operationId: sendEditLinkByEmail tags: - customer summary: Send edit link by email description: > Sends a link for the customer to edit their fiscal information. This link will be available in the `edit_link` field, valid for 7 days and can only be used once. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/customers/590ce6c56d04f840aa8438af/email-edit-link \ -H "Authorization: Bearer sk_test_API_KEY" \ -X POST \ -d '{ "email": "email@example.com" }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); await facturapi.customers.sendEditLinkByEmail('67bf1239b15b44fb9269e6a8', { email: 'email@example.com' // Optional, if not provided, the customer's email will be used }); - lang: csharp label: C# source: > await facturapi.Customer.SendEditLinkByEmailAsync("67bf1239b15b44fb9269e6a8", new Dictionary { ["email"] = "email@example.com" // Optional, if not provided, the customer's email will be used }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var response = facturapi.customers().sendEditLinkByEmail( "cus_123", "cliente@example.com" ); - lang: PHP label: PHP source: > $customer = $facturapi->Customers->sendEditLinkByEmail("67bf1239b15b44fb9269e6a8", [ "email" => "email@example.com" // Optional, if not provided, the customer's email will be used ]); parameters: - in: path name: customer_id schema: type: string required: true description: ID of the `Customer` object to edit requestBody: required: false content: application/json: schema: type: object properties: email: type: string description: >- Customer's email. If not provided, the customer's email will be used. security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Edit link sent successfully content: application/json: schema: type: object properties: ok: type: boolean description: Indicates if the link was sent successfully example: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /customers/{customer_id}/tax-info-validation: get: operationId: validateCustomerTaxInfo tags: - customer summary: Validate Customer Tax Info description: > Validates that the customer's fiscal information matches the SAT records. Its main function is to validate that the registered customer data continues to meet the SAT validation. > **Note:** > The operations of creating a customer, editing a customer, and creating an invoice already perform a > validation of the customer's information, so it is **not** necessary to call this endpoint > before performing these operations. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/customers/590ce6c56d04f840aa8438af/tax-info-validation \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const customer = await facturapi.customers.validateTaxInfo('590ce6c56d04f840aa8438af'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Customer.ValidateTaxInfoAsync("590ce6c56d04f840aa8438af"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var validation = facturapi.customers().validateTaxInfo( "cus_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $customer = $facturapi->Customers->validateTaxInfo( "5a3ee743f508333611ad6b3c" ); parameters: - in: path name: customer_id schema: type: string required: true description: ID of the customer security: - SecretLiveKey: [] responses: '200': description: Validation result content: application/json: schema: type: object properties: is_valid: type: boolean description: >- Indicates if the customer's fiscal information matches the SAT records example: true errors: type: array description: List of errors found in the validation items: type: object properties: path: type: string description: Path to the field with the error example: tax_system message: type: string description: Error message example: >- El RégimenFiscal no coincide con el registrado para el RFC en la lista de contribuyentes obligados del SAT. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /products: post: operationId: createProduct tags: - product summary: Create Product description: > Register a new product or service in your Facturapi catalog. You can use the product ID to create invoices without having to send all the product data each time. Keep in mind that the products you create in the Test environment **are not shared** with the Live environment. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/products \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "description": "Ukelele", "product_key": "60131324", "price": 345.60, "sku": "ABC1234" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const product = await facturapi.products.create({ description: 'Ukelele', product_key: '60131324', price: 345.60, sku: 'ABC1234' }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var product = await facturapi.Product.CreateAsync(new Dictionary { ["description"] = "Ukelele", ["product_key"] = "60131324", ["price"] = 345.60, ["sku"] = "ABC1234" }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var product = facturapi.products().create( Map.of( "description", "Producto de ejemplo", "product_key", "01010101", "price", 100.0, "tax_included", false )); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $product = $facturapi->Products->create([ "description" => "Ukelele", "product_key" => "60131324", "price" => 345.60, "sku" => "ABC1234" ]); requestBody: $ref: '#/components/requestBodies/ProductCreate' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: New `Product` object just created content: application/json: schema: $ref: '#/components/schemas/Product' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' get: operationId: listProducts tags: - product summary: List products description: >- Returns a paginated list of all products in an organization or performs a search according to parameters. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/products \ -H "Authorization: Bearer sk_test_API_KEY" \ -G \ -d 'q=ukelele' \ -d 'page=1' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const searchResult = await facturapi.products.list({ q: 'ukelele', page: 1 }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var searchResult = await facturapi.Product.ListAsync(new Dictionary { ["q"] = "ukelele", ["date"] = new Dictionary { ["gt"] = new DateTime("2021-07-14T06:00:00.000Z"), ["lt"] = new DateTime("2021-08-14T06:00:00.000Z") }, ["page"] = 1 }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var searchResult = facturapi.products().list( Map.of( "page", 0, "limit", 10 ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $searchResult = $facturapi->Products->all([ "q" => "ukelele", "page" => 1 ]); parameters: - in: query name: q schema: type: string description: >- Free text field. Search word matches with `description` or `sku` fields. - in: query name: sku schema: type: string description: Search word matches specifically with `sku` field. - $ref: '#/components/parameters/SearchPage' - $ref: '#/components/parameters/SearchLimit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/ProductSearchResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /products/{product_id}: get: operationId: getProduct tags: - product summary: Retrieve product by ID description: >- Returns the `Product` object with the specified ID. If the product does not exist, a 404 error will be returned. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/products/590e22c26d04f840aa8438b2 \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const product = await facturapi.products.retrieve('590e22c26d04f840aa8438b2'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var product = await facturapi.Product.RetrieveAsync("590e22c26d04f840aa8438b2"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var product = facturapi.products().retrieve( "prod_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $product = $facturapi->Product->retrieve( "590e22c26d04f840aa8438b2" ); parameters: - in: path name: product_id schema: type: string required: true description: Product ID security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Product` object' content: application/json: schema: $ref: '#/components/schemas/Product' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' put: operationId: editProduct tags: - product summary: Edit product description: > Updates the information of an existing product, setting only the values for the paramenters that are sent. Undefined values will not be modified. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/products/590e22c26d04f840aa8438b2 \ -X PUT \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "price": 456.70 }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const product = await facturapi.products.update( '590e22c26d04f840aa8438b2', { email: 'jdoe@example.com', address: { street: 'Santa Monica Ave.' } } ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var product = await facturapi.Product.UpdateAsync( "590e22c26d04f840aa8438b2", new Dictionary { ["price"] = 456.70 } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var product = facturapi.products().update("prod_123", Map.of( "description", "Producto actualizado", "price", 120.0 )); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $product = $facturapi->Products->update("590e22c26d04f840aa8438b2", [ "price" => 456.70 ]); parameters: - in: path name: product_id schema: type: string required: true description: Product ID requestBody: $ref: '#/components/requestBodies/ProductEdit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Product` object edited successfully' content: application/json: schema: $ref: '#/components/schemas/Product' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: deleteProduct tags: - product summary: Delete Product description: > Deletes the product from your organization. The invoices linked with the product **will not** be deleted. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/products/590e22c26d04f840aa8438b2 \ -X DELETE \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const removedProduct = await facturapi.products.del('590e22c26d04f840aa8438b2'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var product = await facturapi.Product.DeleteAsync("590e22c26d04f840aa8438b2"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var product = facturapi.products().delete( "prod_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $facturapi->Products->delete( "590e22c26d04f840aa8438b2" ); parameters: - in: path name: product_id schema: type: string required: true description: Product ID to delete security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Product` object deleted successfully' content: application/json: schema: $ref: '#/components/schemas/Product' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /invoices: post: operationId: createInvoice tags: - invoice summary: Create invoice (CFDI 4.0) description: > Creates a new Invoice. If the invoice is created in the Live environment, it will be **stamped and sent to the SAT**. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/invoices \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "customer": { "legal_name": "Dunder Mifflin", "email": "email@example.com", "tax_id": "ABC101010111", "tax_system": "601", "address": { "zip": "85900" } }, "items": [{ "quantity": 2, "product": { "description": "Ukelele", "product_key": "60131324", "price": 345.60 } }], "payment_form": "06", "folio_number": 914, "series": "F" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const invoice = await facturapi.invoices.create({ customer: { legal_name: 'Dunder Mifflin', email: 'email@example.com', tax_id: 'ABC101010111', tax_system: '601', address: { zip: '85900' } }, items: [{ quantity: 2, product: { description: 'Ukelele', product_key: '60131324', price: 345.60 } }], payment_form: Facturapi.PaymentForm.DINERO_ELECTRONICO, folio_number: 914, series: 'F' }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var invoice = await facturapi.Invoice.CreateAsync(new Dictionary { ["customer"] = new Dictionary { ["legal_name"] = "Dunder Mifflin", ["email"] = "email@example.com", ["tax_id"] = "ABC101010111", ["tax_system"] = "601", ["address"] = new Dictionary { ["zip"] = "85900" } }, ["items"] = new Dictionary[] { new Dictionary { ["product"] = new Dictionary { ["description"] = "Ukelele", ["product_key"] = "60131324", ["price"] = 345.60 } } }, ["payment_form"] = Facturapi.PaymentForm.DINERO_ELECTRONICO, ["folio_number"] = 914, ["series"] = "F" }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invoice = facturapi.invoices().create( Map.of( "customer", "cus_123", "items", List.of( Map.of( "quantity", 1, "product", "prod_123" ) ) ), null ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $invoice = $facturapi->Invoices->create([ "customer" => [ "legal_name" => "Dunder Mifflin", "email" => "email@example.com", "tax_id" => "ABC101010111", "tax_system" => "601", "address" => [ "zip" => "85900" ] ], "items" => [ [ "quantity" => 2, "product" => [ "description" => "Ukelele", "product_key" => "60131324", "price" => 420.69, "sku" => "ABC4567" ] ] // Add as many products as you want to include in your invoice ], "payment_form" => \Facturapi\PaymentForm::EFECTIVO, "folio_number" => 581, "series" => "F" ]); requestBody: $ref: '#/components/requestBodies/InvoiceCreate' parameters: - in: query name: async schema: type: boolean required: false description: > Useful for large invoices. If sent `false` or not sent, the call will wait for the SAT to respond by stamping the invoice. If sent `true`, the call will return immediately with the `invoice` object in status `pending`, and its status can be checked for a change to `valid` at a later time. security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Invoice` object' content: application/json: schema: type: object discriminator: propertyName: status mapping: pending: '#/components/schemas/Invoice' draft: '#/components/schemas/InvoiceDraft' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' get: operationId: listInvoices tags: - invoice summary: List invoices description: > Returns a paginated list of all invoices in an organization or performs a search according to parameters. x-codeSamples: - lang: Bash label: cURL source: | # All invoices from the organization curl "https://www.facturapi.io/v2/invoices" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" # All invoices issued to a certain customer curl "https://www.facturapi.io/v2/invoices" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "customer=58e93bd8e86eb318b0197456" # Page 3 of the search results for free text # of invoices issued to a certain customer between 2017 and 2019 curl "https://www.facturapi.io/v2/invoices" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=Aspiradora+Robot&customer=58e93bd8e86eb318b0197456&date[gte]=2017-01-01T00:00:00.000Z&date[lt]=2020-01-01T00:00:00.000Z&page=3&limit=10" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); // All invoices from the organization const invoiceSearch = await facturapi.invoices.list(); // All invoices issued to a certain customer const invoiceSearch = await facturapi.invoices.list({ customer: '590ce6c56d04f840aa8438af' }); // Page 3 of the search results for free text // of invoices issued to a certain customer between 2017 and 2019 const invoiceSearch = await facturapi.invoices.list({ q: 'Aspiradora Robot', customer: '590ce6c56d04f840aa8438af', date: { gte: new Date('2017-01-01T00:00:00.000Z'), lt: new Date('2020-01-01T00:00:00.000Z') }, page: 3, limit: 10, }); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); // All invoices from the organization var searchResult = await facturapi.Invoice.ListAsync(); // Todas las facturas emitidas para cierto cliente var searchResult = await facturapi.Invoice.ListAsync( new Dictionary { ["customer"] = "590ce6c56d04f840aa8438af" } ); // Página 3 de los resultados de búsqueda de texto libre // de facturas emitidas por cierto cliente entre 2017 y 2019 var searchResult = await facturapi.Invoice.ListAsync( new Dictionary { ["q"] = "Aspiradora Robot", ["customer"] = "590ce6c56d04f840aa8438af", ["date"] = new Dictionary { ["gte"] = new DateTime("2017-01-01T00:00:00.000Z"), ["lt"] = new DateTime("2020-01-01T00:00:00.000Z") }, ["page"] = 3, ["limit"] = 10, } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var searchResult = facturapi.invoices().list( Map.of( "page", 0, "limit", 10 ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); // All invoices from the organization $invoices = $facturapi->Invoices->all(); // All invoices issued to a certain customer $invoices = $facturapi->Invoices->all([ customer => "590ce6c56d04f840aa8438af" ]); // Page 3 of the search results for free text // of invoices issued to a certain customer between 2017 and 2019 $invoices = $facturapi->Invoices->all([ q => "Aspiradora Robot", customer => "590ce6c56d04f840aa8438af" date => [ gte => new DateTime("2017-01-01T00:00:00.000Z"), lt => new DateTime("2020-01-01T00:00:00.000Z") ], page => 3, limit => 10, ]); parameters: - in: query name: q schema: type: string description: | Text to search in the invoice. The search will be performed by **partial** matches in the fields: - `items[].product.description` - `customer.legal_name` And by **exact** matches in the fields: - `id` - `uuid` - `customer.tax_id` - `folio_number` - `total` - in: query name: customer schema: type: string description: Filter by customer ID. Exact match. - in: query name: type schema: type: string enum: - I - E - P - 'N' - T description: Filter by invoice type. Exact match. - in: query name: payment_method schema: type: string enum: - PUE - PPD description: Payment method. Exact match. - in: query name: folio_number schema: type: integer minimum: 1 description: Filter by invoice folio number. Exact match. - in: query name: series schema: type: string maxLength: 25 description: Filter by invoice series. Exact match. - in: query name: external_id schema: type: string maxLength: 100 description: Filter by external identifier. Exact match. - in: query name: issuer_type schema: $ref: '#/components/schemas/IssuingType' description: Filter by issuing type. - in: query name: cancellation_status schema: type: array items: $ref: '#/components/schemas/CancellationStatus' description: Filter by one or more cancellation statuses. - in: query name: uuid schema: type: string format: uuid description: Filter by the CFDI UUID. Exact match. - in: query name: payment_status schema: type: string enum: - paid - unpaid description: Filter by payment status. Exact match. - $ref: '#/components/parameters/SearchDate' - $ref: '#/components/parameters/SearchPage' - $ref: '#/components/parameters/SearchLimit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/InvoiceSearchResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /invoices/preview/pdf: post: operationId: previewInvoicePdf tags: - invoice summary: Preview invoice PDF description: > Generates a PDF preview of an invoice **without stamping it**. The PDF will be generated with the default template of your organization. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/invoices/preview/pdf \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "customer": { "legal_name": "Dunder Mifflin", "email": "email@example.com", "tax_id": "ABC101010111", "tax_system": "601", "address": { "zip": "85900" } }, "items": [{ "quantity": 2, "product": { "description": "Ukelele", "product_key": "60131324", "price": 345.60 } }], "payment_form": "06", "folio_number": 914, "series": "F" }' - lang: JavaScript label: Node.js source: | const Facturapi = require('facturapi'); const facturapi = new Facturapi('sk_live_API_KEY'); const pdfStream = await facturapi.invoices.previewPdf({ customer: { legal_name: 'Dunder Mifflin', email: 'email@example.com', tax_id: 'ABC101010111', tax_system: '601', address: { zip: '85900' } }, items: [{ quantity: 2, product: { description: 'Ukelele', product_key: '60131324', price: 345.60 } }], payment_form: Facturapi.PaymentForm.DINERO_ELECTRONICO, folio_number: 914, series: 'F' }); // Save the PDF to a file const fs = require('fs'); const file = fs.createWriteStream('/route/to/save/invoice.pdf'); pdfStream.pipe(file); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_live_API_KEY"); var pdfStream = await facturapi.Invoice.PreviewPdfAsync(new Dictionary { ["customer"] = new Dictionary { ["legal_name"] = "Dunder Mifflin", ["email"] = "email@example.com", ["tax_id"] = "ABC101010111", ["tax_system"] = "601", ["address"] = new Dictionary { ["zip"] = "85900" } }, ["items"] = new Dictionary[] { new Dictionary { ["product"] = new Dictionary { ["description"] = "Ukelele", ["product_key"] = "60131324", ["price"] = 345.60 } } }, ["payment_form"] = Facturapi.PaymentForm.DINERO_ELECTRONICO, ["folio_number"] = 914, ["series"] = "F" }); // Save the PDF to a file var file = new System.IO.FileStream("C:\\route\\to\\save\\invoice.pdf", FileMode.Create); pdfStream.CopyTo(file); file.Close(); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var pdf = facturapi.invoices().previewPdf( Map.of( "customer", "cus_123", "items", List.of( Map.of( "quantity", 1, "product", "prod_123" ) ) )); - lang: PHP source: | $facturapi = new Facturapi("sk_live_API_KEY"); $pdfContent = $facturapi->Invoices->previewPdf([ "customer" => [ "legal_name" => "Dunder Mifflin", "email" => "email@example.com", "tax_id" => "ABC101010111", "tax_system" => "601", "address" => [ "zip" => "85900" ] ], "items" => [ [ "quantity" => 2, "product" => [ "description" => "Ukelele", "product_key" => "60131324", "price" => 345.60, "sku" => "ABC4567" ] ] ], "payment_form" => \Facturapi\PaymentForm::EFECTIVO, "folio_number" => 914, "series" => "F" ]); requestBody: $ref: '#/components/requestBodies/InvoiceCreate' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: PDF binary content content: application/pdf: schema: type: string format: binary '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /invoices/{invoice_id}: get: operationId: getInvoice tags: - invoice summary: Retrieve invoice by ID description: >- Returns the `Invoice` object with the specified ID. If the invoice does not exist, a 404 error will be returned. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const invoice = await facturapi.invoices.retrieve('58e93bd8e86eb318b019743d'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var invoice = await facturapi.Invoice.RetrieveAsync("58e93bd8e86eb318b019743d"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invoice = facturapi.invoices().retrieve( "inv_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $invoice = $facturapi->Invoices->retrieve( "58e93bd8e86eb318b019743d" ); parameters: - in: path name: invoice_id schema: type: string required: true description: ID of the invoice security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Invoice` object' content: application/json: schema: $ref: '#/components/schemas/Invoice' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' put: operationId: updateDraftInvoice tags: - invoice summary: Edit draft invoice description: > Updates the information of a draft invoice, setting only the values for the paramenters that are sent. Undefined values will not be modified. In the `Invoice` response object, Facturapi will automatically assign the `is_ready_to_stamp` field with the value `true` if the invoice passes the minimum validation required to be stamped; otherwise, the `is_ready_to_stamp` field will be `false`. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d \ -X PUT \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "payment_form": "06" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const invoice = await facturapi.invoices.updateDraft( '58e93bd8e86eb318b019743d', { payment_form: Facturapi.PaymentForm.DINERO_ELECTRONICO } ); - lang: csharp label: C# source: | var facturapi = new Facturapi("sk_test_API_KEY"); var invoice = await facturapi.Invoice.UpdateDraftAsync( "58e93bd8e86eb318b019743d", new Dictionary { ["payment_form"] = Facturapi.PaymentForm.DINERO_ELECTRONICO } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invoice = facturapi.invoices().updateDraft("inv_123", Map.of( "items", List.of( Map.of( "quantity", 1, "product", "prod_123" ) ) )); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $invoice = $facturapi->Invoices->updateDraft("58e93bd8e86eb318b019743d", [ "payment_form" => \Facturapi\PaymentForm::EFECTIVO ]); parameters: - in: path name: invoice_id schema: type: string required: true description: ID of the invoice to edit requestBody: $ref: '#/components/requestBodies/InvoiceEdit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Invoice` object edited successfully' content: application/json: schema: $ref: '#/components/schemas/InvoiceDraft' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: cancelInvoice tags: - invoice summary: Cancel invoice description: > Creates a cancellation request to the SAT for the specified invoice, using the **SAT's new cancellation scheme (effective since 2022)**. When using this method, the following results can occur: - The call returns an error with the explanation of why the cancellation could not be completed. - The call is successful and returns an `invoice` object with the property `status: "canceled"` (the cancellation has already been accepted by the SAT). - The call is successful, but the cancellation requires confirmation from your client, in which case the response will be the `invoice` object with the properties `status: "valid"` and `cancellation_status: "pending"`. - The call is successful, but the SAT replies that the request was received and is being validated, in which case the response will be `status: "valid"` and `cancellation_status: "verifying"`. In the `pending` or `verifying` scenarios, the value of `cancellation_status` will be automatically updated by Facturapi when the SAT or your client accepts, rejects, or lets the request expire, so that when you query an invoice (using [Get Invoice](#tag/invoice/operation/getInvoice)), the `cancellation_status` property will reflect the most recent status of the request. Check the possible values of `cancellation_status` below. After the cancellation, the invoice will no longer be valid, the object will change its `status` to `"canceled"` and will still be available for future queries. If the status of the invoice is `draft`, this method will delete it from the database. If the status of the invoice is not `valid`, this method will return an error. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d?motive=02 \ -H "Authorization: Bearer sk_test_API_KEY" \ -X DELETE - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const invoice = await facturapi.invoices.cancel( '58e93bd8e86eb318b019743d', { motive: '02' } ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var invoice = await facturapi.Invoice.CancelAsync( "58e93bd8e86eb318b019743d", new Dictionary { ["motive"] = "02" } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invoice = facturapi.invoices().cancel( "inv_123", Map.of( "motive", "02" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $canceled_invoice = $facturapi->Invoices->cancel( "58e93bd8e86eb318b019743d", [ "motive" => "02" ] ); parameters: - in: path name: invoice_id schema: type: string required: true description: ID of the invoice to cancel - in: query name: motive required: true schema: type: string enum: - '01' - '02' - '03' - '04' description: > Key representing the motive for the cancellation of the invoice. Possible values: - `01`: **Invoice issued with errors with relation**. When the invoice contains any errors in quantities, keys, or any other data and the replacement invoice has already been issued, which should be indicated through the `substitution` attribute. - `02`: **Invoice issued with errors without relation**. When the invoice contains any errors in quantities, keys, or any other data and it is not required to be related to another invoice. - `03`: **Operation not carried out**. When the sale or transaction was not completed. - `04`: **Nominative operation related to the global invoice**. When it is necessary to cancel an invoice to the general public because the customer requests their invoice. - in: query name: substitution required: false schema: type: string description: > ID of the invoice that replaces the invoice being canceled. You can use either the ID assigned by Facturapi or the fiscal folio (UUID). security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Invoice` object after cancellation' content: application/json: schema: $ref: '#/components/schemas/Invoice' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /invoices/{invoice_id}/copy: post: operationId: copyToDraftInvoice tags: - invoice summary: Copy to draft description: > Creates a new draft invoice with the same information as the specified invoice. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/copy \ -H "Authorization: Bearer sk_test_API_KEY" \ -X POST - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const invoice = await facturapi.invoices.copyToDraft('58e93bd8e86eb318b019743d'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var invoice = await facturapi.Invoice.CopyToDraftAsync("58e93bd8e86eb318b019743d"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var draft = facturapi.invoices().copyToDraft( "inv_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $invoice = $facturapi->Invoices->copyToDraft("58e93bd8e86eb318b019743d"); parameters: - in: path name: invoice_id schema: type: string required: true description: ID of the invoice to copy security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Invoice` draft object created successfully' content: application/json: schema: $ref: '#/components/schemas/InvoiceDraft' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /invoices/{invoice_id}/stamp: post: operationId: stampDraftInvoice tags: - invoice summary: Stamp draft invoice description: > Stamps a draft invoice and sends it to the SAT for validation. When using this method, the value of the `is_ready_to_stamp` field (assigned by Facturapi) must be `true`. Otherwise, the call will return an error. To get the value of `is_ready_to_stamp`, use the [Get Invoice](#tag/invoice/operation/getInvoice) method. This method does not allow editing the invoice, only stamping it. If you need to edit information in the invoice before stamping it, use the [Edit Draft Invoice](#tag/invoice/operation/editDraftInvoice) method. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/stamp \ -H "Authorization: Bearer sk_test_API_KEY" \ -X POST - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const stampedInvoice = await facturapi.invoices.stampDraft('58e93bd8e86eb318b019743d'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var stampedInvoice = await facturapi.Invoice.StampDraftAsync("58e93bd8e86eb318b019743d"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invoice = facturapi.invoices().stampDraft( "inv_123", Map.of( ) ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $stamped_invoice = $facturapi->Invoices->stampDraft("58e93bd8e86eb318b019743d"); parameters: - in: path name: invoice_id schema: type: string required: true description: ID of the invoice to stamp - in: query name: async schema: type: boolean required: false description: > Useful for large invoices. If sent `false` or not sent, the call will wait for the SAT to respond by stamping the invoice. If sent `true`, the call will return immediately with the `invoice` object in status `pending`, and its status can be checked for a change to `valid` at a later time. security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Invoice` object stamped successfully' content: application/json: schema: $ref: '#/components/schemas/Invoice' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /invoices/{invoice_id}/cancellation_receipt/{format}: get: operationId: downloadCancellationReceiptXml tags: - invoice summary: Cancellation receipt description: >- Download the cancellation receipt of a canceled invoice in an xml or pdf file. x-codeSamples: - lang: Bash label: cURL source: > # Cancellation receipt xml curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/cancellation_receipt/xml \ -H "Authorization: Bearer sk_test_API_KEY" \ -X GET # Cancellation receipt pdf curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/cancellation_receipt/pdf \ -H "Authorization: Bearer sk_test_API_KEY" \ -X GET - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); // Cancellation receipt xml await facturapi.invoices.downloadCancellationReceiptXml('58e93bd8e86eb318b019743d'); // Cancellation receipt pdf await facturapi.invoices.downloadCancellationReceiptPdf('58e93bd8e86eb318b019743d'); - lang: csharp label: C# source: > // Cancellation receipt xml await facturapi.Invoice.DownloadCancellationReceiptXmlAsync("58e93bd8e86eb318b019743d"); // Cancellation receipt pdf await facturapi.Invoice.DownloadCancellationReceiptPdfAsync("58e93bd8e86eb318b019743d"); - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); byte[] cancellationReceiptXml = facturapi.invoices().downloadCancellationReceiptXml( "58e93bd8e86eb318b019743d" ); byte[] cancellationReceiptPdf = facturapi.invoices().downloadCancellationReceiptPdf( "58e93bd8e86eb318b019743d" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); // Cancellation receipt xml $facturapi->Invoices->downloadCancellationReceiptXml("58e93bd8e86eb318b019743d"); // Cancellation receipt pdf $facturapi->Invoices->downloadCancellationReceiptPdf("58e93bd8e86eb318b019743d"); parameters: - in: path name: invoice_id schema: type: string required: true description: ID of the invoice to download the cancellation receipt - in: path name: format schema: type: string enum: - xml - pdf required: true description: Format of the file to download security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Cancellation receipt file content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /invoices/{invoice_id}/{format}: get: operationId: downloadInvoice tags: - invoice summary: Download invoice description: Download your invoice in PDF, XML, or both in a ZIP file. x-codeSamples: - lang: Bash label: cURL source: > ## Download PDF and XML compressed in a ZIP file curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/zip \ -H "Authorization: Bearer sk_test_API_KEY" ## Download only the PDF curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/pdf \ -H "Authorization: Bearer sk_test_API_KEY" ## Download only the XML curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/xml \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import fs from 'fs'; import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); // Download PDF and XML compressed in a ZIP file const zipStream = await facturapi.invoices.downloadZip('58e93bd8e86eb318b019743d'); const zipFile = fs.createWriteStream('./factura.zip'); zipStream.pipe(zipFile); // Download only the PDF const pdfStream = await facturapi.invoices.downloadPdf('58e93bd8e86eb318b019743d'); const pdfFile = fs.createWriteStream('./factura.pdf'); pdfStream.pipe(pdfFile); // Download only the XML const xmlStream = await facturapi.invoices.downloadXml('58e93bd8e86eb318b019743d'); const xmlFile = fs.createWriteStream('./factura.xml'); xmlStream.pipe(xmlFile); - lang: csharp label: C# source: > // Download PDF and XML compressed in a ZIP file var zipStream = await facturapi.Invoice.DownloadZipAsync("58e93bd8e86eb318b019743d"); // Download only the XML var xmlStream = await facturapi.Invoice.DownloadXmlAsync("58e93bd8e86eb318b019743d"); // Download only the PDF var pdfStream = await facturapi.Invoice.DownloadPdfAsync("58e93bd8e86eb318b019743d"); // Save the streams to a file var file = new System.IO.FileStream("C:\\route\\to\\save\\invoice.zip", FileMode.Create); zipStream.CopyTo(file); file.Close(); - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.io.InputStream; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.StandardCopyOption; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); try (InputStream zipStream = facturapi.invoices().downloadZip("58e93bd8e86eb318b019743d")) { Files.copy(zipStream, Path.of("./factura.zip"), StandardCopyOption.REPLACE_EXISTING); } try (InputStream pdfStream = facturapi.invoices().downloadPdf("58e93bd8e86eb318b019743d")) { Files.copy(pdfStream, Path.of("./factura.pdf"), StandardCopyOption.REPLACE_EXISTING); } try (InputStream xmlStream = facturapi.invoices().downloadXml("58e93bd8e86eb318b019743d")) { Files.copy(xmlStream, Path.of("./factura.xml"), StandardCopyOption.REPLACE_EXISTING); } - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); // Stream containing the ZIP file with the PDF and XML files $zip = $facturapi->Invoices->downloadZip("58e93bd8e86eb318b019743d"); // Stream containing the PDF file $pdf = $facturapi->Invoices->downloadPdf("58e93bd8e86eb318b019743d"); // Stream containing the XML file $xml = $facturapi->Invoices->downloadXml("58e93bd8e86eb318b019743d"); parameters: - in: path name: invoice_id schema: type: string required: true description: ID of the invoice to download - in: path name: format schema: type: string enum: - xml - pdf - zip required: true description: Format of the file to download security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Official CFDI file in the specified format content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /invoices/{invoice_id}/email: post: operationId: sendInvoiceByEmail tags: - invoice summary: Send invoice by email description: > Sends an email to the address of your client with the XML and PDF files attached to the message. x-codeSamples: - lang: Bash label: cURL source: > # Send to the email registered by the client curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/email \ -H "Authorization: Bearer sk_test_API_KEY" \ -X POST # Send to a different email curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/email \ -H "Authorization: Bearer sk_test_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -d '{ "email": "another_email@example.com" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); // Send to the email registered by the client await facturapi.invoices.sendByEmail('58e93bd8e86eb318b019743d'); // Send to a different email await facturapi.invoices.sendByEmail( '58e93bd8e86eb318b019743d', { email: 'another@email.com' } ); // Send to more than one email (max 10) await facturapi.invoices.sendByEmail( '58e93bd8e86eb318b019743d', { email: [ 'first@email.com', 'second@example.com' ] } ); - lang: csharp label: C# source: > // Send to the email registered by the client await facturapi.Invoice.SendByEmailAsync("58e93bd8e86eb318b019743d"); // Send to a different email await facturapi.Invoice.SendByEmailAsync( "58e93bd8e86eb318b019743d", new Dictionary { ["email"] = "another@email.com" } ); // Send to more than one email (max 10) await facturapi.Invoice.SendByEmailAsync( "58e93bd8e86eb318b019743d", new Dictionary { ["email"] = new String[] { "first@email.com", "second@email.com" } } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var response = facturapi.invoices().sendByEmail( "inv_123", Map.of( "to", "cliente@example.com" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); // Send to the email registered by the client $facturapi->Invoices->sendByEmail("58e93bd8e86eb318b019743d"); // Send to a different email $facturapi->Invoices->sendByEmail( "58e93bd8e86eb318b019743d", "another@email.com" ); // Send to more than one email (max 10) $facturapi->Invoices->sendByEmail( "58e93bd8e86eb318b019743d", [ "first@email.com", "second@email.com" ] ); parameters: - in: path name: invoice_id schema: type: string required: true description: ID of the invoice to send requestBody: required: false content: application/json: schema: type: object properties: email: description: > Email address to send the invoice. If not sent, the email registered by the customer will be used. oneOf: - type: string format: email description: Email address to send the invoice. example: another@email.com - type: array example: - first@email.com - second@email.com description: > Array of email addresses to send the invoice. The maximum number of emails is 10. maxLength: 10 items: type: string format: email security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Email sent successfully content: application/json: schema: type: object required: - ok properties: ok: type: boolean description: > `true` if the email was sent successfully, `false` otherwise. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /invoices/{invoice_id}/status: put: operationId: updateInvoiceStatus tags: - invoice summary: | Update invoice status description: > Consults the status of a stamped invoice at the SAT and updates the invoice object with the most recent information. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/status \ -H "Authorization: Bearer sk_test_API_KEY" \ -X PUT - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const invoice = await facturapi.invoices.updateStatus('58e93bd8e86eb318b019743d'); - lang: csharp label: C# source: > var facturapi = new Facturapi var invoice = await facturapi.Invoice.UpdateStatusAsync("58e93bd8e86eb318b019743d"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invoice = facturapi.invoices().updateStatus( "inv_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $invoice = $facturapi->Invoices->updateStatus("58e93bd8e86eb318b019743d"); parameters: - in: path name: invoice_id schema: type: string required: true description: ID of the invoice to update security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Invoice` object updated successfully' content: application/json: schema: $ref: '#/components/schemas/Invoice' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /receipts: post: operationId: createReceipt tags: - receipt summary: Create e-receipt description: > Creates a new e-Receipt, which acts as a sales note. Every receipt will have an auto-generated URL that the client can visit to fill in their fiscal data in a microsite with the organization's branding. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/receipts \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "folio_number": 1234, "payment_form": "03", "items": [{ "quantity": 1, "product": { "description": "Ukelele", "product_key": "60131324", "price": 345.60, "sku": "ABC1234" } }] }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const receipt = await facturapi.receipts.create({ folio_number: 1234, payment_form: Facturapi.PaymentForm.DINERO_ELECTRONICO, items: [{ quantity: 1, product: { description: 'Ukelele', product_key: '60131324', price: 345.60, sku: 'ABC1234' } }] }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var receipt = await facturapi.Receipt.CreateAsync(new Dictionary { ["folio_number"] = 1234, ["payment_form"] = Facturapi.PaymentForm.DINERO_ELECTRONICO, ["items"] = new Dictionary[] { new Dictionary { ["description"] = "Ukelele", ["product_key"] = "60131324", ["price"] = 345.60, ["sku"] = "ABC1234" } } }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var receipt = facturapi.receipts().create( Map.of( "customer", "cus_123", "items", List.of( Map.of( "quantity", 1, "product", "prod_123" ) ) )); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $receipt = $facturapi->Receipts->create([ "folio_number" => 1234, "payment_form" => "03", "items" => [ [ "product" => [ "description" => "Ukelele", "product_key" => "60131324", "price" => 345.60, "sku" => "ABC1234" ] ] ] ]); requestBody: $ref: '#/components/requestBodies/ReceiptCreate' security: - SecretLiveKey: [] - SecretTestKey: [] - SecretUserKey: [] responses: '200': description: New `Receipt` object created content: application/json: schema: $ref: '#/components/schemas/Receipt' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' get: operationId: listReceipts tags: - receipt summary: List e-recipts description: > Returns a paginated list of all the receipts of an organization or performs a search according to parameters. x-codeSamples: - lang: Bash label: cURL source: | # All receipts of the organization curl "https://www.facturapi.io/v2/receipts" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" # Page 3 of search results for free text search # of receipts created between 2017 and 2019 curl "https://www.facturapi.io/v2/receipts" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=Aspiradora+Robot&date[gte]=2017-01-01T00:00:00.000Z&date[lt]=2020-01-01T00:00:00.000Z&page=3&limit=10" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); // All receipts of the organization const receiptSearch = await facturapi.receipts.list(); // Page 3 of search results for free text search // of receipts created between 2017 and 2019 const receiptSearch = await facturapi.receipts.list({ q: 'Aspiradora Robot', date: { gte: new Date('2017-01-01T00:00:00.000Z'), lt: new Date('2020-01-01T00:00:00.000Z') }, page: 3, limit: 10, }); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); // All receipts of the organization var searchResult = await facturapi.Receipt.ListAsync(); // Page 3 of search results for free text search // of receipts created between 2017 and 2019 var searchResult = await facturapi.Receipt.ListAsync( new Dictionary { ["q"] = "Aspiradora Robot", ["date"] = new Dictionary { ["gte"] = new DateTime("2017-01-01T00:00:00.000Z"), ["lt"] = new DateTime("2020-01-01T00:00:00.000Z") }, ["page"] = 3, ["limit"] = 10, } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var searchResult = facturapi.receipts().list( Map.of( "page", 0, "limit", 10 ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); // All receipts of the organization $searchResult = $facturapi->Receipts->all(); // Page 3 of search results for free text search // of receipts created between 2017 and 2019 $searchResult = $facturapi->Receipts->all([ q => "Aspiradora Robot", date => [ gte => new DateTime("2017-01-01T00:00:00.000Z"), lt => new DateTime("2020-01-01T00:00:00.000Z") ], page => 3, limit => 10, ]); parameters: - in: query name: q schema: type: string description: > Search. Text to search in the description of the receipt's items or the SKU. - in: query name: customer schema: type: string minLength: 24 maxLength: 24 description: | ID of the customer associated to the receipt. example: 58e93bd8e86eb318b0197456 - in: query name: payment_form schema: type: string minLength: 2 maxLength: 2 example: '02' description: > Code representing the payment form, according to the [SAT catalog](#forma-de-pago). If included, the receipts will be grouped and listed according to the payment form. - in: query name: date[gte] schema: type: string format: date-time example: '2017-01-01T00:00:00.000Z' description: | Start date to filter receipts by their `date` property (inclusive). - in: query name: date[lte] schema: type: string format: date-time example: '2020-01-01T00:00:00.000Z' description: | End date to filter receipts by their `date` property (inclusive). - in: query name: invoice schema: type: string description: | ID of the invoice associated with the receipt. example: 58e93bd8e86eb318b019743d - $ref: '#/components/parameters/SearchDate' - $ref: '#/components/parameters/SearchPage' - $ref: '#/components/parameters/SearchLimit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/ReceiptSearchResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /receipts/{receipt_id}: get: operationId: getReceipt tags: - receipt summary: Retrieve e-receipt by ID description: | Retrieves an e-Receipt by its ID. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/receipts/58e93bd8e86eb318b019743d \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const receipt = await facturapi.receipts.retrieve('58e93bd8e86eb318b019743d'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var receipt = await facturapi.Receipt.RetrieveAsync("58e93bd8e86eb318b019743d"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var receipt = facturapi.receipts().retrieve( "rec_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $receipt = $facturapi->Receipts->retrieve( "58e93bd8e86eb318b019743d" ); parameters: - in: path name: receipt_id schema: type: string required: true description: ID of the receipt to retrieve security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Objeto `Receipt` content: application/json: schema: $ref: '#/components/schemas/Receipt' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' put: operationId: assignReceiptCustomer tags: - receipt summary: Assign or reassign customer to receipt description: > Assign or reassign an existing customer (by ID) to a receipt, or create a new one by sending the customer object. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/receipts/58e93bd8e86eb318b019743d \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -X PUT \ -d '{ "customer": "58e93bd8e86eb318b0197456" }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); // Assign an existing customer by ID const receipt = await facturapi.receipts.assignCustomer( '58e93bd8e86eb318b019743d', { customer: '58e93bd8e86eb318b0197456' } ); // Or create the customer from payload and assign it to the receipt const receiptWithNewCustomer = await facturapi.receipts.assignCustomer( '58e93bd8e86eb318b019743d', { customer: { legal_name: 'Dunder Mifflin', tax_id: 'XAXX010101000', tax_system: '616', email: 'billing@dundermifflin.com', address: { zip: '01234', country: 'MEX' } } } ); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); // Assign an existing customer by ID var receipt = await facturapi.Receipt.AssignCustomerAsync( "58e93bd8e86eb318b019743d", new Dictionary { ["customer"] = "58e93bd8e86eb318b0197456" } ); // Or create the customer from payload and assign it to the receipt var receiptWithNewCustomer = await facturapi.Receipt.AssignCustomerAsync( "58e93bd8e86eb318b019743d", new Dictionary { ["customer"] = new Dictionary { ["legal_name"] = "Dunder Mifflin", ["tax_id"] = "XAXX010101000", ["tax_system"] = "616", ["email"] = "billing@dundermifflin.com", ["address"] = new Dictionary { ["zip"] = "01234", ["country"] = "MEX" } } } ); - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); // This endpoint is available in the API, but the Java SDK helper is not exposed yet. - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); // Assign an existing customer by ID $receipt = $facturapi->Receipts->assignCustomer("58e93bd8e86eb318b019743d", [ "customer" => "58e93bd8e86eb318b0197456" ]); // Or create the customer from payload and assign it to the receipt $receiptWithNewCustomer = $facturapi->Receipts->assignCustomer("58e93bd8e86eb318b019743d", [ "customer" => [ "legal_name" => "Dunder Mifflin", "tax_id" => "XAXX010101000", "tax_system" => "616", "email" => "billing@dundermifflin.com", "address" => [ "zip" => "01234", "country" => "MEX" ] ] ]); parameters: - in: path name: receipt_id schema: type: string required: true description: ID of the receipt to update requestBody: $ref: '#/components/requestBodies/ReceiptAssignCustomer' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Updated `Receipt` object content: application/json: schema: $ref: '#/components/schemas/Receipt' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: cancelReceipt tags: - receipt summary: Cancel e-receipt description: | Cancel a receipt by changing its `status` property to `"canceled"`. Once canceled, the receipt cannot be invoiced. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/receipts/5ebd8e56f5687a013ca0df46 \ -X DELETE \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const receipt = await facturapi.receipts.cancel('5ebd8e56f5687a013ca0df46'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var receipt = await facturapi.Receipt.CancelAsync("5ebd8e56f5687a013ca0df46"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var receipt = facturapi.receipts().cancel( "rec_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $facturapi->Receipts->cancel("5ebd8e56f5687a013ca0df46"); parameters: - in: path name: receipt_id schema: type: string required: true description: ID of the receipt to cancel security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Receipt object canceled successfully content: application/json: schema: $ref: '#/components/schemas/Receipt' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /receipts/{receipt_id}/pdf: get: operationId: downloadReceiptPdf tags: - receipt summary: Download PDF description: Download the electronic receipt in PDF format. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/receipts/58e93bd8e86eb318b019743d/pdf \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import fs from 'fs'; import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); // Download the electronic receipt in PDF format const pdfStream = await facturapi.receipts.downloadPdf('58e93bd8e86eb318b019743d'); const pdfFile = fs.createWriteStream('./recibo.pdf'); pdfStream.pipe(pdfFile); - lang: csharp label: C# source: > // Download the electronic receipt in PDF format var pdfStream = await facturapi.Receipt.DownloadPdfAsync("58e93bd8e86eb318b019743d"); // Save the stream to a file var file = new System.IO.FileStream("C:\\route\\to\\save\\receipt.pdf", FileMode.Create); pdfStream.CopyTo(file); file.Close(); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); byte[] pdf = facturapi.receipts().downloadPdf( "rec_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); // stream containing the PDF file $pdf = $facturapi->Receipts->downloadPdf("58e93bd8e86eb318b019743d"); parameters: - in: path name: receipt_id schema: type: string required: true description: ID of the receipt to download security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: E-receipt in PDF format content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /receipts/{receipt_id}/email: post: operationId: sendReceiptByEmail tags: - receipt summary: Send e-receipt by email description: > Send the e-receipt by email to the customer. The email sent will be customized with the logo and colors of the organization that created it, and will include a button to invoice the receipt, as well as the receipt attached as a PDF to the message. x-codeSamples: - lang: Bash label: cURL source: > # Send to a different email than the one registered by the customer curl https://www.facturapi.io/v2/receipts/58e93bd8e86eb318b019743d/email \ -H "Authorization: Bearer sk_test_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -d '{ "email": "another_email@example.com" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); # Send to a different email than the one registered by the customer await facturapi.receipts.sendByEmail( '58e93bd8e86eb318b019743d', { email: 'ejemplo@correo.com' } ); # Send to multiple emails (max 10) await facturapi.receipts.sendByEmail( '58e93bd8e86eb318b019743d', { email: [ 'primer@correo.com', 'segundo@correo.com' ] } ); - lang: csharp label: C# source: | // Send to a different email than the one registered by the customer await facturapi.Receipt.SendByEmailAsync( "58e93bd8e86eb318b019743d", new Dictionary { ["email"] = "ejemplo@correo.com" } ); // Send to multiple emails (max 10) await facturapi.Receipt.SendByEmailAsync( "58e93bd8e86eb318b019743d", new Dictionary { ["email"] = new String[] { "primer@correo.com", "segundo@correo.com" } } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var response = facturapi.receipts().sendByEmail( "rec_123", Map.of( "to", "cliente@example.com" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); // Send to a different email than the one registered by the customer $facturapi->Receipts->sendByEmail( "58e93bd8e86eb318b019743d", "ejemplo@correo.com" ); // Send to multiple emails (max 10) $facturapi->Receipts->sendByEmail( "58e93bd8e86eb318b019743d", [ "primer@correo.com", "segundo@correo.com" ] ); parameters: - in: path name: receipt_id schema: type: string required: true description: ID of the e-receipt to send requestBody: required: false content: application/json: schema: type: object required: - email properties: email: description: > Email address to send the e-receipt. If not sent, the email registered by the customer will be used. oneOf: - type: string format: email description: Email address to send the e-receipt. example: other@email.com - type: array example: - first@email.com - second@email.com description: > Array of email addresses to send the e-receipt. The maximum number of emails is 10. maxLength: 10 items: type: string format: email security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Generic response object content: application/json: schema: type: object required: - ok properties: ok: type: boolean description: Indicates if the email was sent successfully '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /receipts/{receipt_id}/invoice: post: operationId: invoiceReceipt tags: - receipt summary: Convert e-receipt to invoice description: > Creates a new invoice from a receipt. Once invoiced, the receipt's `status` will change to `"invoiced_to_customer"`. Only open receipts (`status = "open"`) can be invoiced. If you send `customer`, that customer is used as the invoice recipient and overrides the customer assigned to the receipt. If you omit `customer`, the receipt must already have an assigned customer. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/receipts/5ebd8e56f5687a013ca0df46/invoice \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "customer": "58e93bd8e86eb318b0197456", "folio_number": 914, "series": "F" }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const invoice = await facturapi.receipts.invoice('5ebd8e56f5687a013ca0df46', { customer: '58e93bd8e86eb318b0197456', folio_number: 914, series: 'F' }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var invoice = await facturapi.Receipt.InvoiceAsync("5ebd8e56f5687a013ca0df46", new Dictionary { ["customer"] = "58e93bd8e86eb318b0197456", ["folio_number"] = 914, ["series"] = "F" }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invoice = facturapi.receipts().invoice( "rec_123", Map.of( "customer", "cus_123" ) ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $invoice = $facturapi->Receipts->invoice("5a3f3e35f508333611ad6b3e", [ "customer" => "58e93bd8e86eb318b0197456", "folio_number" => 914, "series" => "F" ]); parameters: - in: path name: receipt_id schema: type: string required: true description: ID of the receipt to invoice requestBody: $ref: '#/components/requestBodies/ReceiptInvoice' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Nuevo `Invoice` object created content: application/json: schema: $ref: '#/components/schemas/Invoice' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /receipts/to-invoice: post: operationId: createToInvoiceFromReceipts tags: - receipt summary: Create invoice from multiple receipts description: > Creates a single invoice from multiple receipts selected by their `key`. If you send `customer`, that customer is used as the invoice recipient and overrides the customer assigned to the included receipts. If you omit `customer`, all receipts must already have the same assigned customer. If `dry_run` is `true`, the endpoint does not create the invoice and returns a summary preview. The `dry_run` validates the same rules as real invoice creation, but does not persist changes. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/receipts/to-invoice \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "keys": ["ticket_1001", "ticket_1002"], "customer": { "legal_name": "Dunder Mifflin", "tax_id": "ABC101010111", "tax_system": "601", "email": "email@example.com", "address": { "zip": "85900" } }, "use": "G03", "payment_form": "03" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const invoice = await facturapi.receipts.toInvoice({ keys: ['ticket_1001', 'ticket_1002'], customer: { legal_name: 'Dunder Mifflin', tax_id: 'ABC101010111', tax_system: '601', email: 'email@example.com', address: { zip: '85900' } }, use: 'G03', payment_form: Facturapi.PaymentForm.TRANSFERENCIA_ELECTRONICA_DE_FONDOS }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var invoice = await facturapi.Receipt.ToInvoiceAsync(new Dictionary { ["keys"] = new[] { "ticket_1001", "ticket_1002" }, ["customer"] = new Dictionary { ["legal_name"] = "Dunder Mifflin", ["tax_id"] = "ABC101010111", ["tax_system"] = "601", ["email"] = "email@example.com", ["address"] = new Dictionary { ["zip"] = "85900" } }, ["use"] = "G03", ["payment_form"] = Facturapi.PaymentForm.TRANSFERENCIA_ELECTRONICA_DE_FONDOS }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invoice = facturapi.receipts().toInvoice( Map.of( "keys", List.of("ticket_1001", "ticket_1002"), "customer", Map.of( "legal_name", "Dunder Mifflin", "tax_id", "ABC101010111", "tax_system", "601", "address", Map.of("zip", "85900") ), "use", "G03", "payment_form", "03" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $invoice = $facturapi->Receipts->toInvoice([ "keys" => ["ticket_1001", "ticket_1002"], "customer" => [ "legal_name" => "Dunder Mifflin", "tax_id" => "ABC101010111", "tax_system" => "601", "email" => "email@example.com", "address" => [ "zip" => "85900" ] ], "use" => "G03", "payment_form" => \Facturapi\PaymentForm::TRANSFERENCIA_ELECTRONICA_DE_FONDOS ]); requestBody: $ref: '#/components/requestBodies/ReceiptCreateToInvoice' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Created `Invoice` object or summary object when `dry_run=true` content: application/json: schema: oneOf: - $ref: '#/components/schemas/Invoice' - $ref: '#/components/schemas/ToInvoiceSummary' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': description: No eligible receipts found for the provided keys content: application/json: schema: $ref: '#/components/schemas/ToInvoiceNotFoundResponse' '500': $ref: '#/components/responses/UnexpectedError' /receipts/to-invoice/preview: post: operationId: previewToInvoiceFromReceipts tags: - receipt summary: Preview PDF for multiple receipts invoice description: > Generates a PDF preview for an invoice built from multiple receipts selected by their `key`. The preview validates the same customer rules as real invoice creation: if you omit `customer`, all receipts must already have the same assigned customer. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/receipts/to-invoice/preview \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "keys": ["ticket_1001", "ticket_1002"], "customer": { "legal_name": "Dunder Mifflin", "tax_id": "ABC101010111", "tax_system": "601", "address": { "zip": "85900" } }, "use": "G03" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' import fs from 'fs' const facturapi = new Facturapi('sk_test_API_KEY'); const pdfStream = await facturapi.receipts.previewToInvoicePdf({ keys: ['ticket_1001', 'ticket_1002'], customer: { legal_name: 'Dunder Mifflin', tax_id: 'ABC101010111', tax_system: '601', address: { zip: '85900' } }, use: 'G03' }); const file = fs.createWriteStream('to_invoice_preview.pdf'); pdfStream.pipe(file); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var pdfStream = await facturapi.Receipt.PreviewToInvoicePdfAsync(new Dictionary { ["keys"] = new[] { "ticket_1001", "ticket_1002" }, ["customer"] = new Dictionary { ["legal_name"] = "Dunder Mifflin", ["tax_id"] = "ABC101010111", ["tax_system"] = "601", ["address"] = new Dictionary { ["zip"] = "85900" } }, ["use"] = "G03" }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var pdf = facturapi.receipts().previewToInvoicePdf( Map.of( "keys", List.of("ticket_1001", "ticket_1002"), "customer", Map.of( "legal_name", "Dunder Mifflin", "tax_id", "ABC101010111", "tax_system", "601", "address", Map.of("zip", "85900") ), "use", "G03" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $pdfBytes = $facturapi->Receipts->previewToInvoicePdf([ "keys" => ["ticket_1001", "ticket_1002"], "customer" => [ "legal_name" => "Dunder Mifflin", "tax_id" => "ABC101010111", "tax_system" => "601", "address" => [ "zip" => "85900" ] ], "use" => "G03" ]); requestBody: $ref: '#/components/requestBodies/ReceiptPreviewToInvoice' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: PDF binary content content: application/pdf: schema: type: string format: binary '204': description: No eligible receipts found for the provided keys '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '500': $ref: '#/components/responses/UnexpectedError' /receipts/global-invoice: post: operationId: createGlobalInvoice tags: - receipt summary: Create global invoice description: > Creates a global invoice that will include all receipts with `status = "open"` from a certain period. Global invoices are issued to the generic `PUBLICO EN GENERAL` customer. Included receipts are associated with that customer and their `status` changes to `"invoiced_globally"`. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/receipts/global-invoice \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "2021-01-01T05:00:00.000Z", "to": "2021-01-31T04:59:59.999Z", "periodicity": "month", "months": "01", "year": 2021, "folio_number": 1234, "series": "G" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const invoice = await facturapi.receipts.createGlobalInvoice({ from: '2020-12-01T05:00:00.000Z', to: '2020-12-31T04:59:59.999Z', periodicity: 'month', months: '01', year: 2021 folio_number: 1234, series: 'G' }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var invoice = await facturapi.Receipt.CreateGlobalInvoiceAsync(new Dictionary { ["from"] = "2020-12-01T05:00:00.000Z", ["to"] = "2020-12-31T04:59:59.999Z", ["periodicity"] = "month", ["months"] = "01", ["year"] = 2021, ["folio_number"] = 1234, ["series"] = "G" }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invoice = facturapi.receipts().createGlobalInvoice( Map.of( "month", 5, "year", 2024 ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $invoice = $facturapi->Receipts->createGlobalInvoice([ "from" => "2020-12-01T05:00:00.000Z", "to" => "2020-12-31T04:59:59.999Z", "periodicity" => "month", "months" => "01", "year" => 2021, "folio_number" => 1234, "series" => "G" ]); requestBody: $ref: '#/components/requestBodies/ReceiptCreateGlobalInvoice' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: New `Invoice` object creaded content: application/json: schema: $ref: '#/components/schemas/Invoice' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /retentions: post: operationId: createRetention tags: - retention summary: Create retention description: > Create a new Retention. If the invoice is created in Live environment, it will be **stamped and sent to SAT**. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/retentions \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "customer": "58e93bd8e86eb318b0197456", "cve_retenc": "26", "periodo": { "mes_ini": 1, "mes_fin": 12, "ejerc": 2020 }, "totales": { "monto_tot_operacion": 244.654321, "monto_tot_exent": 145.123456, "imp_retenidos": [ { "monto_ret": 40, "base_ret": 250 } ] } }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const retention = await facturapi.retentions.create({ customer: '58e93bd8e86eb318b0197456', cve_retenc: '26', periodo: { mes_ini: 1, mes_fin: 12, ejerc: 2020 }, totales: { monto_tot_operacion: 244.654321, monto_tot_exent: 145.123456, imp_retenidos: [ { monto_ret: 40, base_ret: 250 } ] } }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var retention = await facturapi.Retention.CreateAsync(new Dictionary { ["customer"] = "58e93bd8e86eb318b0197456", ["cve_retenc"] = "26", ["periodo"] = new Dictionary { ["mes_ini"] = 1, ["mes_fin"] = 12, ["ejerc"] = 2020 }, ["totales"] = new Dictionary { ["monto_tot_operacion"] = 244.654321, ["monto_tot_exent"] = 145.123456, ["imp_retenidos"] = new Dictionary[] { new Dictionary { ["] ["monto_ret"] = 40, ["base_ret"] = 250 } } } }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var retention = facturapi.retentions().create( Map.of( "receiver", Map.of( "name", "Cliente ejemplo" ), "items", List.of( Map.of( "quantity", 1, "product", "prod_123" ) ) )); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $retention = $facturapi->Retentions->create([ "customer" => "58e93bd8e86eb318b0197456", "cve_retenc" => "26", "periodo" => [ "mes_ini" => 1, "mes_fin" => 12, "ejerc" => 2020 ], "totales" => [ "monto_tot_operacion" => 244.654321, "monto_tot_exent" => 145.123456, "imp_retenidos" => [ [ "impuesto" => "ISR", "monto_ret" => 40, "base_ret" => 250 ] ] ] ]); requestBody: $ref: '#/components/requestBodies/RetentionCreate' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: New `Retention` object created content: application/json: schema: $ref: '#/components/schemas/Retention' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' get: operationId: listRetentions tags: - retention summary: List retentions description: > Returns a paginated list of all the retentions of an organization or performs a search according to parameters. x-codeSamples: - lang: Bash label: cURL source: | # All retentions of the organization curl https://www.facturapi.io/v2/retentions \ -H "Authorization: Bearer sk_test_API_KEY" # All retentions issued for a certain customer curl "https://www.facturapi.io/v2/retentions" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "customer=58e93bd8e86eb318b0197456" # Page 3 of search results for free text search # of retentions issued between 2017 and 2019 curl "https://www.facturapi.io/v2/retentions" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "q=John+Doe6&date[gte]=2017-01-01T00:00:00.000Z&date[lt]=2020-01-01T00:00:00.000Z&page=3&limit=10" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); // All retentions of the organization const retentionSearch = await facturapi.retentions.list(); // All retentions issued for a certain customer const retentionSearch = await facturapi.retentions.list({ customer: '590ce6c56d04f840aa8438af' }); // Page 3 of search results for free text search // of retentions issued between 2017 and 2019 const retentionSearch = await facturapi.retentions.list({ q: 'John Doe', date: { gte: new Date('2017-01-01T00:00:00.000Z'), lt: new Date('2020-01-01T00:00:00.000Z') }, page: 3, limit: 10, }); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); // All retentions of the organization var searchResult = await facturapi.Retention.ListAsync(); // All retentions issued for a certain customer var searchResult = await facturapi.Retention.ListAsync( new Dictionary { ["customer"] = "590ce6c56d04f840aa8438af" } ); // Page 3 of search results for free text search // of retentions issued between 2017 and 2019 var searchResult = await facturapi.Retention.ListAsync( new Dictionary { ["q"] = "John Doe", ["date"] = new Dictionary { ["gte"] = new DateTime("2017-01-01T00:00:00.000Z"), ["lt"] = new DateTime("2020-01-01T00:00:00.000Z") }, ["page"] = 3, ["limit"] = 10, } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var searchResult = facturapi.retentions().list( Map.of( "page", 0, "limit", 10 ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); // All retentions of the organization $retentions = $facturapi->Retentions->all(); // All retentions issued for a certain customer $retentions = $facturapi->Retentions->all([ customer => "590ce6c56d04f840aa8438af" ]); // Page 3 of search results for free text search // of retentions issued between 2017 and 2019 $retentions = $facturapi->Retentions->all([ q => "John Doe", date => [ gte => new DateTime("2017-01-01T00:00:00.000Z"), lt => new DateTime("2020-01-01T00:00:00.000Z") ], page => 3, limit => 10, ]); parameters: - in: query name: q schema: type: string description: >- Text search. Finds retentions with the specified text in the customer's `legal_name` or `tax_id`. - in: query name: customer schema: type: string description: >- ID of the customer to filter by. Only retentions issued to this customer will be returned. - $ref: '#/components/parameters/SearchDate' - $ref: '#/components/parameters/SearchPage' - $ref: '#/components/parameters/SearchLimit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/RetentionSearchResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /retentions/{retention_id}: get: operationId: getRetention tags: - retention summary: Retrieve retention by ID description: | Retrieves a retention by its ID. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/retentions/6062d9fb226600001cd22f71 \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const retention = await facturapi.retentions.retrieve('6062d9fb226600001cd22f71'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var retention = await facturapi.Retention.RetrieveAsync("6062d9fb226600001cd22f71"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var retention = facturapi.retentions().retrieve( "ret_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $retention = $facturapi->Retentions->retrieve( "6062d9fb226600001cd22f71" ); parameters: - in: path name: retention_id schema: type: string required: true description: ID of the retention to retrieve security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Retention` object' content: application/json: schema: $ref: '#/components/schemas/Retention' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: cancelRetention tags: - retention summary: Cancel retention description: > Request a cancellation of a retention from the SAT. Unlike regular invoices, retention cancellations are immediate and do not require authorization from the recipient. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/retentions/6062d9fb226600001cd22f71?motive=01&substitution=UUID_O_ID_DE_RETENCION" \ -H "Authorization: Bearer sk_test_API_KEY" \ -X DELETE - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const canceledRetention = await facturapi.retentions.cancel('6062d9fb226600001cd22f71', { motive: '01', substitution: 'UUID_O_ID_DE_RETENCION' }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var canceledRetention = await facturapi.Retention.CancelAsync("6062d9fb226600001cd22f71", new { motive = "01", substitution = "UUID_O_ID_DE_RETENCION" }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var retention = facturapi.retentions().cancel( "ret_123", Map.of( "motive", "02" ) ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $canceledRetention = $facturapi->Retentions->cancel("6062d9fb226600001cd22f71", [ "motive" => "01", "substitution" => "UUID_O_ID_DE_RETENCION" ]); parameters: - in: path name: retention_id schema: type: string required: true description: ID of the retention to cancel - in: query name: motive required: true schema: type: string enum: - '01' - '02' - '03' - '04' description: > Code representing the reason for the retention cancellation - `01`: **Document issued with errors and replacement**. When the retention contains an error in amounts, codes, or any other data and the replacement document has already been issued, which must be indicated using the `substitution` attribute. - `02`: **Document issued with errors without replacement**. When the retention contains an error in amounts, codes, or any other data and does not need to be related to another retention. - `03`: **The operation did not take place**. When the operation or transaction was not completed. - `04`: **Nominative operation related in the global retention**. When it is necessary to cancel a general public retention because the client requests their document. - in: query name: substitution required: false schema: type: string description: | ID of the retention that replaces the one being canceled. You can use the Facturapi ID or the fiscal folio (UUID). security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Retention` object canceled successfully' content: application/json: schema: $ref: '#/components/schemas/Retention' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /retentions/{retention_id}/{format}: get: operationId: downloadRetention tags: - retention summary: Download retention description: Download a retention in PDF, XML or both in a ZIP file. x-codeSamples: - lang: Bash label: cURL source: > ## Download PDF and XML compressed in a ZIP file curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/zip \ -H "Authorization: Bearer sk_test_API_KEY" ## Download only the PDF curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/pdf \ -H "Authorization: Bearer sk_test_API_KEY" ## Download only the XML curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/xml \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import fs from 'fs'; import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); // Download PDF and XML compressed in a ZIP file const zipStream = await facturapi.retentions.downloadZip('58e93bd8e86eb318b019743d'); const zipFile = fs.createWriteStream('./retencion.zip'); zipStream.pipe(zipFile); // Download only the PDF const pdfStream = await facturapi.retentions.downloadPdf('58e93bd8e86eb318b019743d'); const pdfFile = fs.createWriteStream('./retencion.pdf'); pdfStream.pipe(pdfFile); // Download only the XML const xmlStream = await facturapi.retentions.downloadXml('58e93bd8e86eb318b019743d'); const xmlFile = fs.createWriteStream('./retencion.xml'); xmlStream.pipe(xmlFile); - lang: csharp label: C# source: > // Download PDF and XML compressed in a ZIP file var zipStream = await facturapi.Retention.DownloadZipAsync("58e93bd8e86eb318b019743d"); // Download only the XML var xmlStream = await facturapi.Retention.DownloadXmlAsync("58e93bd8e86eb318b019743d"); // Download only the PDF var pdfStream = await facturapi.Retention.DownloadPdfAsync("58e93bd8e86eb318b019743d"); // Para guardar la descarga en un archivo var file = new System.IO.FileStream("C:\\route\\to\\save\\retention.zip", FileMode.Create); zipStream.CopyTo(file); file.Close(); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); byte[] pdf = facturapi.retentions().downloadPdf( "ret_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); // stream containing the PDF and XML as a ZIP file $zip = $facturapi->Retentions->downloadZip("58e93bd8e86eb318b019743d"); // stream containing the PDF file $pdf = $facturapi->Retentions->downloadPdf("58e93bd8e86eb318b019743d"); // stream containing the XML file $xml = $facturapi->Retentions->downloadXml("58e93bd8e86eb318b019743d"); parameters: - in: path name: retention_id schema: type: string required: true description: ID of the retention to download - in: path name: format schema: type: string enum: - xml - pdf - zip required: true description: Format to download security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Official retention CFDI document in the requested format content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /retentions/{retention_id}/email: post: operationId: sendRetentionByEmail tags: - retention summary: Send retention by email description: > Send an email to the customer's address with the XML and PDF files attached to the message. x-codeSamples: - lang: Bash label: cURL source: > # Send to the customer's email curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/email \ -H "Authorization: Bearer sk_test_API_KEY" \ -X POST # Send to another email address curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/email \ -H "Authorization: Bearer sk_test_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -d '{ "email": "another_email@example.com" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); // Send to the customer's email await facturapi.retentions.sendByEmail('58e93bd8e86eb318b019743d'); // Send to another email address await facturapi.retentions.sendByEmail( '58e93bd8e86eb318b019743d', { email: 'otro@correo.com' } ); // Send to more than one email (max 10) await facturapi.retentions.sendByEmail( '58e93bd8e86eb318b019743d', { email: [ 'primer@correo.com', 'segundo@correo.com' ] } ); - lang: csharp label: C# source: > // Send to the customer's email await facturapi.Retention.SendByEmailAsync("58e93bd8e86eb318b019743d"); // Send to another email await facturapi.Retention.SendByEmailAsync( "58e93bd8e86eb318b019743d", new Dictionary { ["email"] = "otro@correo.com" } ); // Send to more than one email (max 10) await facturapi.Retention.SendByEmailAsync( "58e93bd8e86eb318b019743d", new Dictionary { ["email"] = new String[] { "primer@correo.com", "segundo@correo.com" } } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var response = facturapi.retentions().sendByEmail( "ret_123", Map.of( "to", "cliente@example.com" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); // Send to the customer's email $facturapi->Retentions->sendByEmail("58e93bd8e86eb318b019743d"); // Send to another email $facturapi->Retentions->sendByEmail( "58e93bd8e86eb318b019743d", "otro@correo.com" ); // Send to more than one email (max 10) $facturapi->Retentions->sendByEmail( "58e93bd8e86eb318b019743d", [ "primer@correo.com", "segundo@correo.com" ] ); parameters: - in: path name: retention_id schema: type: string required: true description: ID of the retention to send requestBody: required: false content: application/json: schema: type: object properties: email: description: >- Email address to send the retention. If this parameter is not sent, the retention will be sent to the email that the customer has registered. oneOf: - type: string format: email description: Email address to send the retention. example: another@email.com - type: array example: - first@correo.com - second@correo.com description: > Array of email addresses to send the retention. The maximum number of emails that can be sent is 10. maxLength: 10 items: type: string format: email security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Generic response indicating if the email was sent successfully content: application/json: schema: type: object required: - ok properties: ok: type: boolean description: Indicates if the email was sent successfully '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations: post: operationId: createOrganization tags: - organization summary: Create organization description: > Create a new Organization that will belong to your user account. After creating the organization and before being able to issue invoices with the organization, you will need to finish setting it up by calling the [Update legal data](#tag/organization/operation/editOrganizationLegal) and [Upload certificates (CSD)](#tag/organization/operation/uploadOrganizationCertificate) methods. After creating the organization and before you can issue invoices with the organization, you must finish configuring it by calling the methods [Update legal information](#tag/organization/operation/editOrganizationLegal) and [Upload certificates (CSD)](#tag/organization/operation/uploadOrganizationCertificate), as well as signing the Carta Manifiesto that authorizes our PAC to stamp invoices; you can do this in [your dashboard](https://dashboard.facturapi.io/settings/manifiesto) or in [our public portal](https://www.facturapi.io/manifiesto). You can also embed the signature module (no branding, iframe-ready) https://www.facturapi.io/embedded/manifiesto Remember that the stamps of your subscription can be consumed by any of the organizations registered under your account. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/organizations \ -H "Authorization: Bearer sk_user_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Skynet" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const organization = await facturapi.organizations.create({ name: 'Skynet' }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var organization = await facturapi.Organization.CreateAsync(new Dictionary { ["name"] = "Skynet" }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().create( Map.of( "legal_name", "Mi Empresa SA de CV", "tax_id", "XAXX010101000", "tax_system", "601", "email", "cliente@example.com" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->create([ "name" => "Skynet" ]); requestBody: $ref: '#/components/requestBodies/OrganizationCreate' security: - SecretUserKey: [] responses: '200': description: New `Organization` object created content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' get: operationId: listOrganizations tags: - organization summary: List organizations description: > Returns a paginated list of all the organizations registered under your account, or performs a search according to parameters. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/organizations \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const organizationResults = await facturapi.organizations.list(); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var searchResult = await facturapi.Organization.ListAsync(); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var searchResult = facturapi.organizations().list( Map.of( "page", 0, "limit", 10 ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $organizations = $facturapi->Organizations->all() parameters: - in: query name: q schema: type: string description: >- Free text search. Text to search in `name` (commercial name) or `legal_name` (fiscal name) or `tax_id` (RFC). - $ref: '#/components/parameters/SearchDate' - $ref: '#/components/parameters/SearchPage' - $ref: '#/components/parameters/SearchLimit' security: - SecretUserKey: [] responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/OrganizationSearchResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/me: get: operationId: meOrganization tags: - organization summary: Organization detail description: | Returns the detail of a organization registered under your account. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/organizations/me \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const organizationResults = await facturapi.organizations.me(); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var searchResult = await facturapi.Organization.MeAsync(); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().me( ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $organizations = $facturapi->Organizations->me() security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: The `Organization` object content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/legal: put: operationId: editOrganizationLegal tags: - organization summary: Edit legal data description: > Update the legal information of the organization. If you are looking for how to edit the RFC, remember that the `tax_id` property is automatically assigned when uploading the user's certificates (Certificado de Sello Digital or CSD). x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/legal \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Skynet", "legal_name": "Skynet", "tax_system": "601", "website": "www.sky.net", "phone": "555-555-5555", "address": { "exterior": "1414", "interior": "12", "zip": "44940", "neighborhood": "Villa Toscana", "city": "Guadalajara", "municipality": "Guadalajara", "state": "Jalisco", "country": "México" } }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const organization = await facturapi.organizations.updateLegal( '5a2a307be93a2f00129ea035', { name: 'Skynet', legal_name: 'Skynet', tax_system: Facturapi.TaxSystem.GENERAL_LEY_DE_PERSONAS_MORALES, website: 'www.sky.net', phone: '555-555-5555', address: { exterior: '1414', interior: '12', zip: '44940', neighborhood: 'Villa Toscana', city: 'Guadalajara', municipality: 'Guadalajara', state: 'Jalisco', country: 'México' } } ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var organization = await facturapi.Organization.UpdateLegalAsync( "5a2a307be93a2f00129ea035", new Dictionary { ["name"] = "Skynet", ["legal_name"] = "Skynet", ["tax_system"] = "601", ["website"] = "www.sky.net", ["phone"] = "555-555-5555", ["address"] = new Dictionary { ["exterior"] = "1414", ["interior"] = "12", ["zip"] = "44940", ["neighborhood"] = "Villa Toscana", ["city"] = "Guadalajara", ["municipality"] = "Guadalajara", ["state"] = "Jalisco", ["country"] = "México" } } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().updateLegal( "org_123", Map.of( "legal_name", "Mi Empresa SA de CV", "tax_id", "XAXX010101000" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->updateLegal( "5a2a307be93a2f00129ea035", [ "name" => "Skynet", "legal_name" => "Skynet", "tax_system" => "601", "website" => "www.sky.net", "phone" => "555-555-5555", "address" => [ "exterior" => "1414", "interior" => "12", "zip" => "44940", "neighborhood" => "Villa Toscana", "city" => "Guadalajara", "municipality" => "Guadalajara", "state" => "Jalisco", "country" => "México" ) ] ]; parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization to edit requestBody: $ref: '#/components/requestBodies/OrganizationEditLegal' security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Modified `Organization` object content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/certificate: put: operationId: uploadOrganizationCertificate tags: - organization summary: Upload certificates (CSD) description: > Upload the files of the Digital Seal Certificate (Certificado de Sello Digital or CSD) provided by the SAT. This call should also be used to replace existing certificates in case new ones are requested. When updating your certificates, the RFC will be read and automatically assigned to `legal.tax_id`. > **Don't use this endpoint to upload the FIEL certificate.** > The CSD is different from the FIEL certificate (Firma Electrónica). Please ask your accountant for the CSD. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/certificate \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F 'cer=@/path/to/your/CSD.cer' \ -F 'key=@/path/to/your/CSD.key' \ -F 'password=CONTRASEÑA_DEL_CERTIFICADO' - lang: JavaScript label: Node.js source: > import fs from 'fs'; import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const cerFileStream = fs.createReadStream('/path/to/your/CSD.cer'); const keyFileStream = fs.createReadStream('/path/to/your/CSD.key'); const organization = await facturapi.organizations.uploadCertificate( '5a2a307be93a2f00129ea035', cerFileStream, keyFileStream, 'CONTRASEÑA_DEL_CERTIFICADO' ); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var cerFileStream = File.OpenRead(@"C:\path\to\your\CSD.cer"); var keyFileStream = File.OpenRead(@"C:\path\to\your\CSD.key"); var organization = await facturapi.Organization.UploadCertificateAsync( "5a2a307be93a2f00129ea035", cerFileStream, keyFileStream, "CONTRASEÑA_DEL_CERTIFICADO" ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.io.File; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().uploadCertificate( "org_123", new File("certificate.cer"), new File("certificate.key"), "secret" ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->uploadCertificate( "5a2a307be93a2f00129ea035", [ "cer" => "/path/to/CSD.cer", "key" => "/path/to/CSD.key", "password" => "mYp455w0rD1553cUr3!" ] ); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization to upload certificates requestBody: $ref: '#/components/requestBodies/OrganizationUploadCerts' security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Modified `Organization` object content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: deleteOrganizationCertificate tags: - organization summary: Delete certificates (CSD) description: > Removes the certificates (CSD) from your organization. Deleting the certificates will not affect the invoices already issued, but you will not be able to issue new invoices until you upload new certificates. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/certificate \ -X DELETE \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const organization = await facturapi.organizations.deleteCertificate( '5a2a307be93a2f00129ea035' ); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var organization = await facturapi.Organization.DeleteCertificateAsync("5a2a307be93a2f00129ea035"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().deleteCertificate( "org_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->deleteCertificate("5a2a307be93a2f00129ea035"); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization to delete certificates security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Modified `Organization` object content: application/json: schema: $ref: '#/components/schemas/OrganizationDeleteCerts' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/fiel: put: operationId: uploadOrganizationFiel tags: - organization summary: Upload FIEL certificate description: | Uploads the organization's e.firma (FIEL) files. The e.firma (FIEL) is not required to create CFDI. To stamp CFDI, you only need to upload the Digital Seal Certificate (CSD). The FIEL is required to use bulk CFDI downloads. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/organizations/me/fiel \ -X PUT \ -H "Authorization: Bearer sk_live_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F 'cer=@/path/to/your/FIEL.cer' \ -F 'key=@/path/to/your/FIEL.key' \ -F 'password=CERTIFICATE_PASSWORD' parameters: - in: path name: organization_id schema: type: string required: true description: >- Organization ID. You can also use `me` with the organization's Live Secret Key. requestBody: $ref: '#/components/requestBodies/OrganizationUploadFiel' security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Modified `Organization` object content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/logo: put: operationId: uploadOrganizationLogo tags: - organization summary: Upload logo description: > Upload the organization's logo. The logo will be displayed on the PDFs and emails sent to your customers. The file must be an image in JPG or PNG format and have a size not greater than 500 KB. The recommended dimensions are 800 × 500px. If the organization already has a logo, this call replaces the previous logo. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/logo \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F 'file=@/path/to/your/logo.jpg' - lang: JavaScript label: Node.js source: | import fs from 'fs'; import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const fileStream = fs.createReadStream('/path/to/your/logo.jpg'); const organization = await facturapi.organizations.uploadLogo( '5a2a307be93a2f00129ea035', fileStream ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var fileStream = File.OpenRead(@"C:\path\to\your\logo.jpg"); var organization = await facturapi.Organization.UploadLogoAsync( "5a2a307be93a2f00129ea035", fileStream ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.io.File; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().uploadLogo( "org_123", new File("logo.png") ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->uploadLogo( "5a2a307be93a2f00129ea035", "/path/to/logo.jpg" )); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization requestBody: $ref: '#/components/requestBodies/OrganizationUploadLogo' security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Modified `Organization` object content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/customization: put: operationId: editOrganizationCustomization tags: - organization summary: Edit customization description: > Update the information related to the organization's identity or branding. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/customization \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "color": "#BADA55", "pdf_extra": { "codes": false, "product_key": true } }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const organization = await facturapi.organizations.updateCustomization( '5a2a307be93a2f00129ea035', { color: '#BADA55', pdf_extra: { codes: false, product_key: true } } ); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var organization = await facturapi.Organization.UpdateCustomizationAsync( "5a2a307be93a2f00129ea035", new Dictionary { ["color"] = "#BADA55", ["pdf_extra"] = new Dictionary { ["codes"] = false, ["product_key"] = true } } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().updateCustomization( "org_123", Map.of( "website", "https://facturapi.io" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->updateCustomization( "5a2a307be93a2f00129ea035", [ "color" => "#BADA55", "pdf_extra" => [ "codes" => false, "product_key" => true ] ] ); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization requestBody: $ref: '#/components/requestBodies/OrganizationEditCustomization' security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Modified `Organization` object content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/receipts: put: operationId: editOrganizationReceiptsSettings tags: - organization summary: Edit receipts settings description: | Update the organization's receipts settings. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/receipts \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "invoicing_period": "month", "duration_days": 14, "next_folio_number": 100 }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const organization = await facturapi.organizations.updateReceiptSettings( '5a2a307be93a2f00129ea035', { invoicing_period: "month", duration_days: 14, next_folio_number: 100 } ); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var organization = await facturapi.Organization.UpdateReceiptSettingsAsync( "5a2a307be93a2f00129ea035", new Dictionary { ["invoicing_period"] = "month", ["duration_days"] = 14, ["next_folio_number"] = 100 } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().updateReceiptSettings( "org_123", Map.of( "color", "#4786FF" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->updateReceiptSettings( "5a2a307be93a2f00129ea035", [ "invoicing_period" => "month", "duration_days" => 14, "next_folio_number" => 100 ] ); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization requestBody: $ref: '#/components/requestBodies/OrganizationEditReceiptsSettings' security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Modified `Organization` object content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/self-invoice: put: operationId: editOrganizationSelfInvoiceSettings tags: - organization summary: Edit self-invoice settings description: | Update the self-invoice settings of the organization. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/self-invoice \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "allowed_cfdi_uses": ["G01", "G03"], "apply_resico_isr": false, "support_email": "support@dundermifflin.com" }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const organization = await facturapi.organizations.updateSelfInvoiceSettings( '5a2a307be93a2f00129ea035', { allowed_cfdi_uses: ["G01", "G03"], apply_resico_isr: false, support_email: "support@dundermifflin.com" } ); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var organization = await facturapi.Organization.UpdateSelfInvoiceSettingsAsync( "5a2a307be93a2f00129ea035", new Dictionary { ["allowed_cfdi_uses"] = new List { "G01", "G03" }, ["apply_resico_isr"] = false, ["support_email"] = "support@dundermifflin.com" } ); - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().updateSelfInvoiceSettings("org_123", Map.of( "enabled", true )); - lang: PHP source: > $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->updateSelfInvoiceSettings( "5a2a307be93a2f00129ea035", [ "allowed_cfdi_uses" => ["G01", "G03"], "apply_resico_isr" => false, "support_email" => "support@dundermifflin.com" ] ); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization requestBody: $ref: '#/components/requestBodies/OrganizationEditSelfInvoiceSettings' security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Modified `Organization` object content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/domain-check: get: operationId: checkDomainAvailability tags: - organization summary: Check domain availability description: > Check if an identifier is available to choose as a domain for the autofactura portal. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/domain-check?domain=empresa-demo \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const organization = await facturapi.organizations.checkDomainIsAvailable({ domain: 'empresa-demo' }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var organization = await facturapi.Organization.CheckDomainIsAvailableAsync( new Dictionary { ["domain"] = "empresa-demo" } ); - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var availability = facturapi.organizations().checkDomainAvailability( Map.of( "domain", "facturapi" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->checkDomainAvailability( ["domain" => "empresa-demo"] ); parameters: - in: query name: domain required: true schema: $ref: '#/components/schemas/DomainField' security: - SecretUserKey: [] responses: '200': description: | Response indicating if the domain is available. content: application/json: schema: type: object required: - available properties: available: type: boolean example: true description: Indicates if the domain is available '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/domain: put: operationId: editOrganizationDomain tags: - organization summary: Choose self-invoice domain description: > Choose the domain that this organization will use in its self-invoice microsite. Once you choose the domain, you must contact us if you need to change it. The domain you choose will be the one that appears in the `self_invoice_url` field when creating a new receipt, as follows: `https://factura.space/{DOMAIN}/{RECEIPT_KEY}` x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/domain \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "empresa-demo" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const organization = await facturapi.organizations.updateDomain( '5a2a307be93a2f00129ea035', { domain: 'empresa-demo' } ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var organization = await facturapi.Organization.UpdateDomainAsync( "5a2a307be93a2f00129ea035", new Dictionary { ["domain"] = "empresa-demo" } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().updateDomain( "org_123", Map.of( "domain", "facturapi" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->updateDomain( "5a2a307be93a2f00129ea035", [ "domain" => "empresa-demo" ] ); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization requestBody: $ref: '#/components/requestBodies/OrganizationEditDomain' security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Modified `Organization` object content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}: get: operationId: getOrganization tags: - organization summary: Retrieve organization by ID description: | Retrieve the organization by its ID. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035 \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const organization = await facturapi.organizations.retrieve( '5a2a307be93a2f00129ea035' ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var organization = await facturapi.Organization.RetrieveAsync( "5a2a307be93a2f00129ea035" ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().retrieve( "org_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->retrieve("5a2a307be93a2f00129ea035"); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization security: - SecretLiveKey: [] - SecretTestKey: [] - SecretUserKey: [] responses: '200': description: '`Organization` object' content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: deleteOrganization tags: - organization summary: Delete organization description: | Delete the organization from your Facturapi account. Once deleted, you will not be able to access its resources, such as clients, products, invoices, receipts, or retentions. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035 \ -X DELETE \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const organization = await facturapi.organizations.del( '5a2a307be93a2f00129ea035' ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var organization = await facturapi.Organization.DeleteAsync( "5a2a307be93a2f00129ea035" ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().delete( "org_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->delete( "5a2a307be93a2f00129ea035" ); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization security: - SecretUserKey: [] responses: '200': description: '`Organization` object deleted' content: application/json: schema: $ref: '#/components/schemas/Organization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/apikeys/test: get: operationId: getTestApiKey tags: - organization summary: Retrieve Test API Key description: | Retrieve API Key for the Test environment of the organization. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/apikeys/test \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const apiKeys = await facturapi.organizations.getTestApiKey( '5a2a307be93a2f00129ea035' ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var apiKeys = await facturapi.Organization.GetTestApiKeyAsync( "5a2a307be93a2f00129ea035" ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var apiKey = facturapi.organizations().getTestApiKey( "org_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $organization = $facturapi->Organizations->getTestApiKey( "5a2a307be93a2f00129ea035" ); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization security: - SecretUserKey: [] responses: '200': description: Test API Key content: application/json: schema: type: string example: sk_test_API_KEY '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' put: operationId: renewTestApiKey tags: - organization summary: Renew Test API Key description: > Renew the Test environment secret key of the organization and immediately invalidate the previous one. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/apikeys/test \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const newTestApiKey = await facturapi.organizations.renewTestApiKey( '5a2a307be93a2f00129ea035' ); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var newTestApiKey = await facturapi.Organization.RenewTestApiKeyAsync( "5a2a307be93a2f00129ea035" ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var apiKey = facturapi.organizations().renewTestApiKey( "org_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $new_test_api_key = $facturapi->Organizations->renewTestApiKey( "5a2a307be93a2f00129ea035" ); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization security: - SecretUserKey: [] responses: '200': description: Test API Key content: application/json: schema: type: string example: sk_test_API_KEY '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/apikeys/live: get: operationId: listLiveApiKeys tags: - organization summary: List Live API Keys description: | List secret keys of the organization's Live environment. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/apikeys/live \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const listLiveApiKeys = await facturapi.organizations.listLiveApiKeys( '5a2a307be93a2f00129ea035' ); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var listLiveApiKeys = await facturapi.Organization.ListLiveApiKeysAsync( "5a2a307be93a2f00129ea035" ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var apiKeys = facturapi.organizations().listLiveApiKeys( "org_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $list_live_api_key = $facturapi->Organizations->listLiveApiKeys( "5a2a307be93a2f00129ea035" ); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID security: - SecretUserKey: [] responses: '200': description: Live API Key content: application/json: schema: type: array items: type: object properties: first_12: type: string description: First 12 characters of the secret key created_at: type: string format: date-time description: Creation date of the secret key id: type: string description: ID of the secret key '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' put: operationId: renewLiveApiKey tags: - organization summary: Create Live API Key description: > Generate a new Live environment secret key for the organization. This operation does not invalidate previously generated keys. The endpoint uses `PUT` for historical compatibility, but its behavior is to create a new key. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/apikeys/live \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const newLiveApiKey = await facturapi.organizations.renewLiveApiKey( '5a2a307be93a2f00129ea035' ); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var newLiveApiKey = await facturapi.Organization.RenewLiveApiKeyAsync( "5a2a307be93a2f00129ea035" ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var apiKey = facturapi.organizations().renewLiveApiKey( "org_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $new_live_api_key = $facturapi->Organizations->renewLiveApiKey( "5a2a307be93a2f00129ea035" ); parameters: - in: path name: organization_id schema: type: string required: true description: ID of the organization security: - SecretUserKey: [] responses: '200': description: Live API Key content: application/json: schema: type: string example: sk_live_API_KEY '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/apikeys/live/{id}: delete: operationId: deleteLiveApiKey tags: - organization summary: Revoke Live API Key description: | Revoke the Live API Key of your organization.as x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/apikeys/live/66f2ec798ca5a9b80c97db71 \ -X DELETE \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const hasDeleted = await facturapi.organizations.deleteLiveApiKey( '5a2a307be93a2f00129ea035', '66f2ec798ca5a9b80c97db71' ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var hasDeleted = await facturapi.Organization.DeleteLiveApiKeyAsync( "5a2a307be93a2f00129ea035", "66f2ec798ca5a9b80c97db71" ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var apiKeys = facturapi.organizations().deleteLiveApiKey( "org_123", "key_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $has_deleted = $facturapi->Organizations->deleteLiveApiKey( "5a2a307be93a2f00129ea035", "66f2ec798ca5a9b80c97db71" ); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID - in: path name: id schema: type: string required: true description: ID of the Live API Key security: - SecretUserKey: [] responses: '200': description: Live API Key revoked content: application/json: schema: type: array items: type: object properties: first_12: type: string description: First 12 characters of the secret key created_at: type: string format: date-time description: Creation date of the secret key id: type: string description: ID of the secret key '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/series-group: get: operationId: getSeriesGroup tags: - organization summary: Listado de series description: > Listado de series creadas para la personalización de organización. La cual lleva control de foliaje para cada tipo de factura si está asignada en las personalización de organización. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/series-group \ -X GET \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const seriesList = await facturapi.organizations.getSeries( '5a2a307be93a2f00129ea035' ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var seriesList = await facturapi.Organization.ListSeriesAsync( "5a2a307be93a2f00129ea035" ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var series = facturapi.organizations().listSeriesGroup( "org_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $seriesList = $facturapi->Organizations->getSeries( "5a2a307be93a2f00129ea035" ); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Listado de objetos `Series` creadas previamente content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/OrganizationSeriesGroup' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' post: operationId: createSeriesGroup tags: - organization summary: Create Series description: > Create a new folio series for the organization. Series are useful for keeping track of the forms issued for each type of invoice x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/series-group \ -X POST \ -H "Content-Type: application/json" \ -d '{ "series": "New", "next_folio": 1, "next_folio_test": 1 }' -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const newSeries = await facturapi.organizations.createSeries( '5a2a307be93a2f00129ea035', { series: 'New', next_folio: 1, next_folio_test: 1 } ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var newSeries = await facturapi.Organization.CreateSeriesAsync( "5a2a307be93a2f00129ea035", [ "series" => "New", "next_folio" => 1, "next_folio_test" => 1 ] ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var series = facturapi.organizations().createSeriesGroup( "org_123", Map.of( "name", "A" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $newSeries = $facturapi->Organizations->createSeries( "5a2a307be93a2f00129ea035", { "series": "New", "next_folio": 1, "next_folio_test": 1 } ); requestBody: $ref: '#/components/requestBodies/OrganizationSeriesCreate' parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: New created object `s` content: application/json: schema: $ref: '#/components/schemas/OrganizationSeriesGroup' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/series-group/default-series: put: operationId: updateDefaultSeries tags: - organization summary: Set default series description: | Assigns a default series for the specified invoice type. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/series-group/default-series \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "I", "series": "A" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const result = await facturapi.organizations.updateDefaultSeries( '5a2a307be93a2f00129ea035', { type: 'I', series: 'A' } ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var result = await facturapi.Organization.UpdateDefaultSeriesAsync( "5a2a307be93a2f00129ea035", new Dictionary { ["type"] = "I", ["series"] = "A" } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var response = facturapi.organizations().updateDefaultSeries( "org_123", Map.of( "type", "I", "series", "A" ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $result = $facturapi->Organizations->updateDefaultSeries( "5a2a307be93a2f00129ea035", [ "type" => "I", "series" => "A" ] ); requestBody: $ref: '#/components/requestBodies/OrganizationSeriesDefault' parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Default series updated content: application/json: schema: $ref: '#/components/schemas/OkResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/series-group/{series_name}: put: operationId: updateSeriesGroup tags: - organization summary: Update Series description: > Edit the folio number of the series in the Test and Live environments of the organization. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/series-group/New \ -X PUT \ -H "Authorization: Bearer sk_user_API_KEY" -H "Content-Type: application/json" \ -d '{ "next_folio": 1, "next_folio_test": 1 }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const updatedSeries = await facturapi.organizations.updateSeries( '5a2a307be93a2f00129ea035', 'New', [ "next_folio" => 1, "next_folio_test" => 1 ] ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var updatedSeries = await facturapi.Organization.UpdateSeriesAsync( "5a2a307be93a2f00129ea035", "New", { "next_folio": 1, "next_folio_test": 1 } ); - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var series = facturapi.organizations().updateSeriesGroup("org_123", "A", Map.of( "next_folio", 1 )); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $updatedSeries = $facturapi->Organizations->updateSeries( "5a2a307be93a2f00129ea035", "New", { "next_folio": 1, "next_folio_test": 1 } ); requestBody: $ref: '#/components/requestBodies/OrganizationSeriesUpdate' parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID - in: path name: series_name schema: type: string required: true description: Series name security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Updated object `Series` content: application/json: schema: $ref: '#/components/schemas/OrganizationSeriesGroup' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: deleteSeriesGroup tags: - organization summary: Delete series description: | Delete the series x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/series-group/New \ -X DELETE \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY'); const deletedSeries = await facturapi.organizations.deleteSeries( '5a2a307be93a2f00129ea035', 'New' ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var deletedSeries = await facturapi.Organization.DeleteSeriesAsync( "5a2a307be93a2f00129ea035", "New" ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var series = facturapi.organizations().deleteSeriesGroup( "org_123", "A" ); - lang: PHP source: | $facturapi = new Facturapi("sk_user_API_KEY"); $deletedSeries = $facturapi->Organizations->deleteSeries( "5a2a307be93a2f00129ea035", "New" ); parameters: - in: path name: organization_id schema: type: string required: true description: Organization Id - in: path name: series_name schema: type: string required: true description: Series Name security: - SecretLiveKey: [] - SecretUserKey: [] responses: '200': description: Deleted object `Series` content: application/json: schema: $ref: '#/components/schemas/OrganizationSeriesGroup' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/team: get: operationId: getOrganizationTeam tags: - organization_access summary: List users with organization access description: >- Returns an array of users that currently have access to the organization, including the owner. This endpoint is not paginated. x-codeSamples: - lang: Bash label: cURL source: | curl "https://www.facturapi.io/v2/organizations/ORG_ID/team" \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi'; const facturapi = new Facturapi('sk_test_API_KEY'); const accessList = await facturapi.organizations.listTeamAccess('ORG_ID'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var accessList = await facturapi.Organization.ListTeamAccessAsync("ORG_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var team = facturapi.organizations().listTeamAccess( "org_123" ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $accessList = $facturapi->Organizations->listTeamAccess("ORG_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID security: - SecretUserKey: [] responses: '200': description: >- List of user access entries within the organization, including implicit access such as the owner content: application/json: schema: $ref: '#/components/schemas/OrganizationUserAccessList' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/team/invites: post: operationId: createOrganizationTeamInvite tags: - organization_access summary: Invite user to organization description: > Creates or updates a user invite. By default, invited users get full admin access; to limit access, create a role and send its ID in `role`. Each organization can invite one user at no additional cost. Starting from the second invited user, each additional user will incur a monthly fee. This charge is applied automatically when the user accepts the invitation, whether from the dashboard or via the API. You can check the current pricing on our [pricing page](https://www.facturapi.io/pricing). x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/invites" \ -X POST \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "alex@example.com", "role": "ROLE_ID" }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const invite = await facturapi.organizations.inviteUserToTeam('ORG_ID', { email: 'alex@example.com', role: 'ROLE_ID', }) - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var invite = await facturapi.Organization.InviteUserToTeamAsync( "ORG_ID", new Dictionary { ["email"] = "alex@example.com", ["role"] = "ROLE_ID" } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invite = facturapi.organizations().inviteUserToTeam( "org_123", Map.of( "email", "new.user@example.com", "role", "admin" ) ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $invite = $facturapi->Organizations->inviteUserToTeam("ORG_ID", [ "email" => "alex@example.com", "role" => "ROLE_ID" ]); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID requestBody: $ref: '#/components/requestBodies/OrganizationInviteCreate' security: - SecretUserKey: [] responses: '200': description: Invite created or updated for the requested email content: application/json: schema: $ref: '#/components/schemas/OrganizationInvite' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' get: operationId: listOrganizationTeamInvites tags: - organization_access summary: List sent invites description: Returns invites sent from the organization. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/invites" \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const invites = await facturapi.organizations.listSentTeamInvites('ORG_ID') - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var invites = await facturapi.Organization.ListSentTeamInvitesAsync("ORG_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var invites = facturapi.organizations().listSentTeamInvites( "org_123" ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $invites = $facturapi->Organizations->listSentTeamInvites("ORG_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID security: - SecretUserKey: [] responses: '200': description: List of sent invites that are still active for the organization content: application/json: schema: $ref: '#/components/schemas/OrganizationInviteList' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/team/{access_id}: get: operationId: getOrganizationTeamUser tags: - organization_access summary: Retrieve user access description: >- Returns the access detail for a user within the organization using its `access_id`, including implicit access such as the owner. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/ACCESS_ID" \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const access = await facturapi.organizations.retrieveTeamAccess('ORG_ID', 'ACCESS_ID') - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var access = await facturapi.Organization.RetrieveTeamAccessAsync("ORG_ID", "ACCESS_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var access = facturapi.organizations().retrieveTeamAccess( "org_123", "access_123" ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $access = $facturapi->Organizations->retrieveTeamAccess("ORG_ID", "ACCESS_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID - in: path name: access_id schema: type: string required: true description: Access ID security: - SecretUserKey: [] responses: '200': description: >- Access detail for the user within the organization, including implicit access such as the owner content: application/json: schema: $ref: '#/components/schemas/OrganizationUserAccess' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: removeOrganizationUserAccess tags: - organization_access summary: Remove user access x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/ACCESS_ID" \ -X DELETE \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.organizations.removeTeamAccess('ORG_ID', 'ACCESS_ID') - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.Organization.RemoveTeamAccessAsync("ORG_ID", "ACCESS_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var response = facturapi.organizations().removeTeamAccess( "org_123", "access_123" ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->Organizations->removeTeamAccess("ORG_ID", "ACCESS_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID - in: path name: access_id schema: type: string required: true description: Access ID security: - SecretUserKey: [] responses: '200': description: User removed from the organization content: application/json: schema: $ref: '#/components/schemas/OkResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/team/invites/{invite_key}: delete: operationId: deleteOrganizationTeamInvite tags: - organization_access summary: Cancel sent invite description: Cancels a pending organization invite. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/invites/INVITE_ID" \ -X DELETE \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.organizations.cancelTeamInvite('ORG_ID', 'INVITE_ID') - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.Organization.CancelTeamInviteAsync("ORG_ID", "INVITE_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var response = facturapi.organizations().cancelTeamInvite( "org_123", "invite_123" ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->Organizations->cancelTeamInvite("ORG_ID", "INVITE_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID - in: path name: invite_key schema: type: string required: true description: Public invite key security: - SecretUserKey: [] responses: '200': description: Invite canceled content: application/json: schema: $ref: '#/components/schemas/OkResponse' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/invites/pending: get: operationId: listPendingOrganizationInvites tags: - organization_access summary: List received invites description: Returns received invites for the authenticated user. x-codeSamples: - lang: Bash label: cURL source: | curl "https://www.facturapi.io/v2/organizations/invites/pending" \ -H "Authorization: Bearer sk_user_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY') const pendingInvites = await facturapi.organizations.listReceivedTeamInvites() - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_user_API_KEY"); var pendingInvites = await facturapi.Organization.ListReceivedTeamInvitesAsync(); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var organization = facturapi.organizations().retrieve( "org_123" ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_user_API_KEY"); $pendingInvites = $facturapi->Organizations->listReceivedTeamInvites(); security: - SecretUserKey: [] responses: '200': description: List of invites received by the authenticated user content: application/json: schema: $ref: '#/components/schemas/OrganizationInviteList' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/invites/{invite_key}/response: post: operationId: respondOrganizationInvite tags: - organization_access summary: Respond to invite description: Accepts or declines an invite using its `invite_key`. x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/invites/INVITE_ID/response" \ -X POST \ -H "Authorization: Bearer sk_user_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "accept": true }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_user_API_KEY') const result = await facturapi.organizations.respondTeamInvite('INVITE_ID', { accept: true, }) - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_user_API_KEY"); var result = await facturapi.Organization.RespondTeamInviteAsync( "INVITE_ID", new Dictionary { ["accept"] = true } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var response = facturapi.organizations().respondTeamInvite( "invite_123", Map.of( "response", "accepted" ) ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_user_API_KEY"); $result = $facturapi->Organizations->respondTeamInvite("INVITE_ID", [ "accept" => true ]); parameters: - in: path name: invite_key schema: type: string required: true description: Public invite key requestBody: $ref: '#/components/requestBodies/OrganizationInviteRespond' security: - SecretUserKey: [] responses: '200': description: Invite accepted or declined successfully content: application/json: schema: $ref: '#/components/schemas/OkResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/team/roles: get: operationId: listOrganizationPermissionRoles tags: - organization_access summary: List organization roles x-codeSamples: - lang: Bash label: cURL source: | curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/roles" \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const roles = await facturapi.organizations.listTeamRoles('ORG_ID') - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var roles = await facturapi.Organization.ListTeamRolesAsync("ORG_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var roles = facturapi.organizations().listTeamRoles( "org_123" ); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $roles = $facturapi->Organizations->listTeamRoles("ORG_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID security: - SecretUserKey: [] responses: '200': description: Roles list content: application/json: schema: $ref: '#/components/schemas/OrganizationPermissionRoleList' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' post: operationId: createOrganizationPermissionRole tags: - organization_access summary: Create organization role x-codeSamples: - lang: Bash label: cURL source: | curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/roles" \ -X POST \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Billing analyst" }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const role = await facturapi.organizations.createTeamRole('ORG_ID', { name: 'Billing analyst', }) - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var role = await facturapi.Organization.CreateTeamRoleAsync( "ORG_ID", new Dictionary { ["name"] = "Billing analyst" } ); - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var role = facturapi.organizations().createTeamRole("org_123", Map.of( "name", "Contabilidad", "operations", List.of("createInvoice", "cancelInvoice") )); - lang: PHP label: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $role = $facturapi->Organizations->createTeamRole("ORG_ID", [ "name" => "Billing analyst" ]); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID requestBody: $ref: '#/components/requestBodies/OrganizationPermissionRoleCreate' security: - SecretUserKey: [] responses: '200': description: Role created content: application/json: schema: $ref: '#/components/schemas/OrganizationPermissionRole' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/team/roles/templates: get: operationId: listOrganizationPermissionRoleTemplates tags: - organization_access summary: List role templates x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/roles/templates" \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const templates = await facturapi.organizations.listTeamRoleTemplates('ORG_ID') - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var templates = await facturapi.Organization.ListTeamRoleTemplatesAsync("ORG_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var templates = facturapi.organizations().listTeamRoleTemplates( "org_123" ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $templates = $facturapi->Organizations->listTeamRoleTemplates("ORG_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID security: - SecretUserKey: [] responses: '200': description: Available role templates content: application/json: schema: $ref: '#/components/schemas/OrganizationPermissionRoleTemplateList' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/team/roles/operations: get: operationId: listOrganizationPermissionOperations tags: - organization_access summary: List permission operations x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/roles/operations" \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const operations = await facturapi.organizations.listTeamRoleOperations('ORG_ID') - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var operations = await facturapi.Organization.ListTeamRoleOperationsAsync("ORG_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var operations = facturapi.organizations().listTeamRoleOperations( "org_123" ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $operations = $facturapi->Organizations->listTeamRoleOperations("ORG_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID security: - SecretUserKey: [] responses: '200': description: List of operation codes content: application/json: schema: $ref: '#/components/schemas/OrganizationPermissionOperationList' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/team/roles/{role_id}: get: operationId: getOrganizationPermissionRole tags: - organization_access summary: Retrieve organization role x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/roles/ROLE_ID" \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const role = await facturapi.organizations.retrieveTeamRole('ORG_ID', 'ROLE_ID') - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var role = await facturapi.Organization.RetrieveTeamRoleAsync("ORG_ID", "ROLE_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var role = facturapi.organizations().retrieveTeamRole( "org_123", "role_123" ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $role = $facturapi->Organizations->retrieveTeamRole("ORG_ID", "ROLE_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID - in: path name: role_id schema: type: string required: true description: Role ID security: - SecretUserKey: [] responses: '200': description: Role detail content: application/json: schema: $ref: '#/components/schemas/OrganizationPermissionRole' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' put: operationId: updateOrganizationPermissionRole tags: - organization_access summary: Update organization role x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/roles/ROLE_ID" \ -X PUT \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Senior billing analyst" }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const role = await facturapi.organizations.updateTeamRole('ORG_ID', 'ROLE_ID', { name: 'Senior billing analyst', }) - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var role = await facturapi.Organization.UpdateTeamRoleAsync( "ORG_ID", "ROLE_ID", new Dictionary { ["name"] = "Senior billing analyst" } ); - lang: Java label: Java source: > import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var role = facturapi.organizations().updateTeamRole("org_123", "role_123", Map.of( "name", "Contabilidad", "operations", List.of("createInvoice", "cancelInvoice") )); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $role = $facturapi->Organizations->updateTeamRole("ORG_ID", "ROLE_ID", [ "name" => "Senior billing analyst" ]); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID - in: path name: role_id schema: type: string required: true description: Role ID requestBody: $ref: '#/components/requestBodies/OrganizationPermissionRoleUpdate' security: - SecretUserKey: [] responses: '200': description: Role updated content: application/json: schema: $ref: '#/components/schemas/OrganizationPermissionRole' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: deleteOrganizationPermissionRole tags: - organization_access summary: Delete organization role x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/roles/ROLE_ID" \ -X DELETE \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const result = await facturapi.organizations.deleteTeamRole('ORG_ID', 'ROLE_ID') - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var result = await facturapi.Organization.DeleteTeamRoleAsync("ORG_ID", "ROLE_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var response = facturapi.organizations().deleteTeamRole( "org_123", "role_123" ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->Organizations->deleteTeamRole("ORG_ID", "ROLE_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID - in: path name: role_id schema: type: string required: true description: Role ID security: - SecretUserKey: [] responses: '200': description: Role deleted content: application/json: schema: $ref: '#/components/schemas/OkResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /organizations/{organization_id}/team/{access_id}/role: put: operationId: updateOrganizationTeamUserRole tags: - organization_access summary: Reassign role to user x-codeSamples: - lang: Bash label: cURL source: > curl "https://www.facturapi.io/v2/organizations/ORG_ID/team/ACCESS_ID/role" \ -X PUT \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "role": "ROLE_ID" }' - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY') const access = await facturapi.organizations.updateTeamAccessRole('ORG_ID', 'ACCESS_ID', 'ROLE_ID') - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var access = await facturapi.Organization.UpdateTeamAccessRoleAsync("ORG_ID", "ACCESS_ID", "ROLE_ID"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var access = facturapi.organizations().updateTeamAccessRole( "org_123", "access_123", "admin" ); - lang: PHP label: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $access = $facturapi->Organizations->updateTeamAccessRole("ORG_ID", "ACCESS_ID", "ROLE_ID"); parameters: - in: path name: organization_id schema: type: string required: true description: Organization ID - in: path name: access_id schema: type: string required: true description: Access ID requestBody: $ref: '#/components/requestBodies/OrganizationUserAccessRoleUpdate' security: - SecretUserKey: [] responses: '200': description: User access updated with the new role content: application/json: schema: $ref: '#/components/schemas/OrganizationUserAccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /webhooks: post: operationId: createWebhook tags: - webhooks summary: Create webhook description: > Register a new webhook in your Facturapi organization. Use this call to receive notifications of asynchronous events to the API. Test and live environment webhooks are independent. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/webhooks \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "enabled_events": ["receipt.self_invoice_complete"], "url": "http://webhook_api.com" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const customer = await facturapi.webhooks.create({ "enabled_events": ["receipt.self_invoice_complete"], "url": "http://webhook_api.com" }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Webhook.CreateAsync(new Dictionary { ["enabled_events"] = new Dictionary["receipt.self_invoice_complete"], ["url"] = "http://webhook_api.com" }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var webhook = facturapi.webhooks().create( Map.of( "url", "https://example.com/webhooks", "triggers", List.of("invoice.created") )); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $customer = $facturapi->Webhooks->create([ "enabled_events" => ["receipt.self_invoice_complete"], "url" => "http://webhook_api.com" ]); requestBody: $ref: '#/components/requestBodies/WebhookCreate' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: An existing `Webhook` object with the same URL was found content: application/json: schema: $ref: '#/components/schemas/Webhook' '201': description: New `Webhook` object content: application/json: schema: $ref: '#/components/schemas/Webhook' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' get: operationId: listWebhooks tags: - webhooks summary: List webhooks description: | Returns a list of webhooks created previously for the organization. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/webhooks \ -H "Authorization: Bearer sk_test_API_KEY" \ -G \ -d 'page=1' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const searchResult = await facturapi.webhooks.list({ limit: 0, page: 1 }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var searchResult = await facturapi.Webhook.ListAsync(new Dictionary { ["page"] = 1 ["limit"] = 0, }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var searchResult = facturapi.webhooks().list( Map.of( "page", 0, "limit", 10 ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $searchResult = $facturapi->Webhooks->all([ "page" => 1 ]); parameters: - $ref: '#/components/parameters/SearchPage' - $ref: '#/components/parameters/SearchLimit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/WebhookSearchResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /webhooks/{webhook_id}: get: operationId: getWebhook tags: - webhooks summary: Retrieve webhook by ID description: | Retrieve the webhook subscription by its ID. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/webhooks/590ce6c56d04f840aa8438af \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const customer = await facturapi.webhooks.retrieve('590ce6c56d04f840aa8438af'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Webhook.RetrieveAsync("590ce6c56d04f840aa8438af"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var webhook = facturapi.webhooks().retrieve( "whk_123" ); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $customer = $facturapi->Webhooks->retrieve( "5a3ee743f508333611ad6b3c" ); parameters: - in: path name: webhook_id schema: type: string required: true description: ID of the webhook security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Webhook` object' content: application/json: schema: $ref: '#/components/schemas/Webhook' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' put: operationId: editWebhook tags: - webhooks summary: Edit webhook description: > Update the information of an existing webhook with the parameters you send in the request. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/webhooks/590ce6c56d04f840aa8438af \ -X PUT -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "disabled", "enabled_events": ["receipt.self_invoice_complete"] }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const customer = await facturapi.webhooks.update( '590ce6c56d04f840aa8438af', { "status": "disabled", "enabled_events": ["receipt.self_invoice_complete"] } ); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Webhook.UpdateAsync( "590ce6c56d04f840aa8438af", new Dictionary { ["status"] = "disabled", ["address"] = new Dictionary["receipt.self_invoice_complete"] } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var webhook = facturapi.webhooks().update("whk_123", Map.of( "url", "https://example.com/webhooks", "triggers", List.of("invoice.created") )); - lang: PHP source: > $facturapi = new Facturapi("sk_test_API_KEY"); $customer = $facturapi->Webhooks->update("590ce6c56d04f840aa8438af", [ "status" => "disabled", "address" => ["receipt.self_invoice_complete"] ] ]); parameters: - in: path name: webhook_id schema: type: string required: true description: ID of the webhook requestBody: $ref: '#/components/requestBodies/WebhookEdit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Webhook` object edited successfully' content: application/json: schema: $ref: '#/components/schemas/Webhook' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' delete: operationId: deleteWebhook tags: - webhooks summary: Delete Webhook description: | Deletes the webhook subscription from the organization. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/webhooks/590ce6c56d04f840aa8438af \ -X DELETE \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const removedCustomer = await facturapi.webhooks.del('590ce6c56d04f840aa8438af'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Webhook.DeleteAsync("590ce6c56d04f840aa8438af"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var webhook = facturapi.webhooks().delete( "whk_123" ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $facturapi->Webhooks->delete( "5a3fefd9f508333611ad6b43" ); parameters: - in: path name: webhook_id schema: type: string required: true description: ID of the webhook security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: '`Webhook` object deleted' content: application/json: schema: $ref: '#/components/schemas/Webhook' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /webhooks/validate-signature: post: operationId: validateWebhookSignature tags: - webhooks summary: Validate Webhook Signature description: > Validate the signature of an event object received through a Webhook. Use this operation to verify the authenticity and integrity of the event received, comparing the received signature with the one generated by Facturapi. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/webhooks/validate-signature \ -H "Authorization: Bearer sk_test_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "secret": "wh_sec...", "payload": "Object Response", "signature": "Signature_FROM_HEADER" }' - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const customer = await facturapi.webhooks.validateSignature({ secret: "wh_sec...", payload: "Object Response", signature: "Signature_FROM_HEADER" }); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Webhook.ValidateSignatureAsync(new Dictionary { ["secret"] = "wh_sec...", ["payload"] = new Dictionary["Object Response"], ["signature"] = "Signature_FROM_HEADER" }); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var event = facturapi.webhooks().validateSignature( "webhook_secret", "signature_hex", "{\"id\":\"evt_123\"}" ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $customer = $facturapi->Webhooks->validateSignature([ "secret" => "wh_sec...", "payload" => "Object Response", "signature" => "Signature_FROM_HEADER" ]); requestBody: content: application/json: schema: type: object properties: secret: type: string description: >- Secret key of the webhook, found in the webhook settings or upon creation. payload: type: object description: Event object received through a webhook. signature: type: string description: Signature from the header "Facturapi-Signature". security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Event object successfully validated content: application/json: schema: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: type: type: string description: Type of event example: invoice.status_updated enum: - invoice.status_updated data: type: object properties: type: type: string description: Type of object affected by the event enum: - invoice object: $ref: '#/components/schemas/Invoice' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /check: get: tags: - tools summary: Health check description: | Check the health of the Facturapi API. security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: API is operational content: application/json: schema: type: object properties: ok: type: boolean example: true '401': description: Error de autenticación. Asegúrate de estar usando tu llave secreta. '502': description: Servicio temporalmente no disponible. /tools/tax_id_validation: get: tags: - tools summary: Validate RFC (tax_id) description: > Check the status of an RFC in the list of **EFOS** (Empresas que Facturan Operaciones Simuladas). When appearing in this list, the RFC is or was suspected of engaging in simulated fiscal operations (factureras). The response (detailed below) includes the results of this validation. It includes the boolean property `is_valid`, which Facturapi resolves by interpreting the response. A value of `true` for this property indicates that the RFC has no issues to resolve and is free of problems; and the opposite for `false`. Additionally, you can check the `data` property to see the raw values of the query to the SAT. x-codeSamples: - lang: Bash label: cURL source: > curl https://www.facturapi.io/v2/tools/tax_id_validation?tax_id=BBA830831LJ2 \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: > import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const validation = await facturapi.tools.validateTaxId('BBA830831LJ2'); - lang: csharp label: C# source: > var facturapi = new FacturapiClient("sk_test_API_KEY"); var customer = await facturapi.Tool.ValidateTaxIdAsync("BBA830831LJ2"); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var validation = facturapi.tools().validateTaxId( "XAXX010101000" ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $customer = $facturapi->Tools->validateTaxId("BBA830831LJ2"); parameters: - in: query name: tax_id required: true schema: type: string description: RFC a validar example: BBA830831LJ2 security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Validation result content: application/json: schema: $ref: '#/components/schemas/TaxIdValidationResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /catalogs/products: get: tags: - sat_keys summary: Product/Service Key description: >- Search in the SAT Product/Service catalog, which contains the key to include in the invoice. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/catalogs/products?q=ukelele \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const searchResult = await facturapi.catalogs.searchProducts({ q: 'ukelele' }); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var searchResult = await facturapi.Catalog.SearchProducts( new Dictionary { ["q"] = "ukelele" } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.catalogs().searchProducts( Map.of( "q", "0101", "page", 0, "limit", 10 ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->Catalogs->searchProducts([ "q" => "ukelele" ]); parameters: - in: query name: q schema: type: string description: >- Text search. Text to search in the product/service classification description. - $ref: '#/components/parameters/SearchPage' - $ref: '#/components/parameters/SearchLimit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/ProductCatalogSearchResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' /catalogs/units: get: tags: - sat_keys summary: Units of Measure description: Search in the SAT Units of Measure catalog. x-codeSamples: - lang: Bash label: cURL source: | curl https://www.facturapi.io/v2/catalogs/units?q=pulgada \ -H "Authorization: Bearer sk_test_API_KEY" - lang: JavaScript label: Node.js source: | import Facturapi from 'facturapi' const facturapi = new Facturapi('sk_test_API_KEY'); const searchResult = await facturapi.catalogs.searchUnits({ q: 'pulgada' }); - lang: csharp label: C# source: | var facturapi = new FacturapiClient("sk_test_API_KEY"); var searchResult = await facturapi.Catalog.SearchUnits( new Dictionary { ["q"] = "pulgada" } ); - lang: Java label: Java source: | import io.facturapi.Facturapi; import java.util.List; import java.util.Map; Facturapi facturapi = new Facturapi("sk_test_API_KEY"); var result = facturapi.catalogs().searchUnits( Map.of( "q", "H87", "page", 0, "limit", 10 ) ); - lang: PHP source: | $facturapi = new Facturapi("sk_test_API_KEY"); $result = $facturapi->Catalogs->searchUnits([ "q" => "pulgada" ]); parameters: - in: query name: q schema: type: string description: Query. Text to search in the description of the unit of measure. - $ref: '#/components/parameters/SearchPage' - $ref: '#/components/parameters/SearchLimit' security: - SecretLiveKey: [] - SecretTestKey: [] responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/UnitCatalogSearchResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' x-webhooks: Global invoice created: post: summary: Global invoice created description: | Notifies about the creation of a global invoice from e-Receipts. tags: - events requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: type: type: string description: Type of event example: invoice.global_invoice_created enum: - invoice.global_invoice_created data: type: object properties: type: type: string description: Type of object associated with the event enum: - invoice object: $ref: '#/components/schemas/Invoice' Invoice status updated: post: summary: Invoice status updated description: > Notifies about changes in the `status` field of an invoice. Used in the case of having created the invoice asynchronously (`async` param). tags: - events requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: type: type: string description: Type of event example: invoice.status_updated enum: - invoice.status_updated data: type: object properties: type: type: string description: Type of object associated with the event enum: - invoice object: $ref: '#/components/schemas/Invoice' Invoice created from dashboard: post: summary: Invoice created from dashboard description: | Notifies when an invoice was created from Facturapi Dashboard. tags: - events requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: type: type: string description: Type of event example: invoice.created_from_dashboard enum: - invoice.created_from_dashboard data: type: object properties: type: type: string description: Type of object associated with the event enum: - invoice object: $ref: '#/components/schemas/Invoice' Cancellation status updated: post: tags: - events summary: Cancellation status updated description: | Notifies about changes in the `cancellation_status` field of an invoice. requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: type: type: string description: Type of event enum: - invoice.cancellation_status_updated data: type: object properties: type: type: string description: Type of object associated with the event enum: - invoice object: $ref: '#/components/schemas/Invoice' Self-invoice completed: post: tags: - events summary: Self-invoice completed description: | Notifies about the completion of a self-invoice. requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: type: type: string description: Type of event example: receipt.self_invoice_complete enum: - receipt.self_invoice_complete data: type: object properties: type: type: string description: Type of object associated with the event enum: - receipt object: $ref: '#/components/schemas/Receipt' Receipt status updated: post: tags: - events summary: Receipt status updated description: | Notifies about changes in the `status` field of a receipt. requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: type: type: string description: Type of event enum: - receipt.status_updated data: type: object properties: type: type: string description: Type of object associated with the event enum: - receipt object: $ref: '#/components/schemas/Receipt' components: responses: BadRequest: description: Error in some of the request parameters content: application/json: schema: $ref: '#/components/schemas/GenericError' Unauthenticated: description: Authentication error content: application/json: schema: $ref: '#/components/schemas/GenericError' Conflict: description: > Conflict in the request. The operation that is being attempted cannot be completed due to conflicts in the current state of the resource. content: application/json: schema: $ref: '#/components/schemas/GenericError' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/GenericError' RateLimited: description: Too many requests in a short time window. headers: Retry-After: description: Recommended seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/GenericError' example: message: Too many requests. Please retry shortly. status: 429 ok: false code: rate_limit_exceeded UnexpectedError: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/GenericError' requestBodies: CustomerCreate: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerCreateInput' CustomerEdit: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomerProperties' ProductCreate: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/ProductProperties' ProductEdit: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/ProductProperties' InvoiceCreate: required: true content: application/json: schema: $ref: '#/components/schemas/InvoiceCreateInput' InvoiceCreatePending: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/InvoiceIngresoInput' - $ref: '#/components/schemas/InvoiceEgresoInput' - $ref: '#/components/schemas/InvoicePagoInput' - $ref: '#/components/schemas/InvoiceNominaInput' - $ref: '#/components/schemas/InvoiceTrasladoInput' InvoiceEdit: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/InvoiceIngresoEditInput' - $ref: '#/components/schemas/InvoiceEgresoEditInput' - $ref: '#/components/schemas/InvoicePagoEditInput' - $ref: '#/components/schemas/InvoiceNominaEditInput' - $ref: '#/components/schemas/InvoiceTrasladoEditInput' ReceiptCreate: required: true content: application/json: schema: $ref: '#/components/schemas/ReceiptInput' ReceiptAssignCustomer: required: true content: application/json: schema: $ref: '#/components/schemas/ReceiptAssignCustomerInput' ReceiptInvoice: required: true content: application/json: schema: $ref: '#/components/schemas/InvoiceReceiptInput' ReceiptCreateGlobalInvoice: required: true content: application/json: schema: $ref: '#/components/schemas/GlobalInvoiceInput' ReceiptCreateToInvoice: required: true content: application/json: schema: $ref: '#/components/schemas/ToInvoiceInput' ReceiptPreviewToInvoice: required: true content: application/json: schema: $ref: '#/components/schemas/ToInvoicePreviewInput' RetentionCreate: required: true content: application/json: schema: $ref: '#/components/schemas/RetentionInput' OrganizationCreate: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationCreateInput' OrganizationEditLegal: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationLegalInput' OrganizationUploadCerts: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/OrganizationCertsInput' OrganizationUploadFiel: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/OrganizationFielInput' OrganizationUploadLogo: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/OrganizationLogoInput' OrganizationEditCustomization: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationCustomizationInput' OrganizationEditReceiptsSettings: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationReceiptsInput' OrganizationEditSelfInvoiceSettings: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationSelfInvoiceInput' OrganizationEditDomain: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationDomainInput' OrganizationSeriesCreate: content: application/json: schema: $ref: '#/components/schemas/OrganizationSeriesCreateInput' OrganizationSeriesUpdate: content: application/json: schema: $ref: '#/components/schemas/OrganizationSeriesUpdateInput' OrganizationSeriesDefault: content: application/json: schema: $ref: '#/components/schemas/OrganizationSeriesDefaultInput' OrganizationInviteCreate: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationInviteCreateInput' OrganizationInviteRespond: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationInviteRespondInput' OrganizationPermissionRoleCreate: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationPermissionRoleCreateInput' OrganizationPermissionRoleUpdate: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationPermissionRoleUpdateInput' OrganizationUserAccessRoleUpdate: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationUserAccessRoleUpdateInput' WebhookCreate: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookCreateInput' WebhookEdit: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookCreateEdit' parameters: SearchDate: in: query name: date style: deepObject schema: $ref: '#/components/schemas/DateRange' description: Object with requested date range. SearchPage: in: query name: page schema: type: integer minimum: 1 description: Page of results to return, starting from page 1. SearchLimit: in: query name: limit schema: type: integer minimum: 1 default: 50 maximum: 100 description: >- Number from 1 to 100 representing the maximum amount of results to return for pagination purposes. schemas: EventBase: type: object properties: id: type: string description: ID of the event example: 61f81a81bd4661b11b9b404e created_at: type: string format: date-time description: Creation date and time of the event example: '2022-03-30T00:00:00Z' livemode: type: boolean description: >- Indicates if the event was generated in Test mode (false) or Live mode (true). example: false organization: type: string description: ID of the organization this event is related to example: 61f81a7fbd4661b11b9b3f27 DateRange: type: object properties: gt: type: string format: date-time title: Greater than description: Lower exclusive limit of the date range to request. gte: type: string format: date-time title: Greater than or equals description: Lower inclusive limit of the date range to request. lt: type: string format: date-time title: Lesser than description: Upper exclusive limit of the date range to request. lte: type: string format: date-time title: Lesser than or equals description: Upper inclusive limit of the date range to request. GenericError: type: object properties: message: type: string title: Error description description: >- Indicates what went wrong and may include a suggestion on how to fix the error. status: type: integer format: int32 title: HTTP status code description: HTTP status code for this error response. example: 400 ok: type: boolean description: >- Indicates if the request was successful. Always `false` for error responses. example: false code: type: string description: >- Stable error code for programmatic handling. See the error handling guide for the documented code list. example: invalid_request location: type: string description: Optional location of the data related to the error. enum: - body - query - params - headers - files path: type: string description: Optional path to the field related to the error. errors: type: array description: >- Additional error details. Included only when there are validation errors or relevant external details. items: $ref: '#/components/schemas/ErrorDetail' ErrorDetail: type: object properties: message: type: string description: Human-readable detail message. code: type: string description: >- Detail subcode. Validation errors use codes such as `required` or `invalid_type`; external errors may contain the provider's original code. example: required location: type: string description: Optional location of the data related to this detail. enum: - body - query - params - headers - files path: type: string description: Optional path to the field related to this detail. source: type: string description: Optional source for external details, for example `sat`. IssuingType: type: string description: >- Indicates whether the invoice was issued by your organization or received from a third party. enum: - issuing - receiving CancellationStatus: type: string description: Status of the invoice cancellation request. enum: - none - accepted - pending - rejected - expired SearchResult: type: object properties: page: type: integer example: 1 title: Página description: The current page number within the search results total_pages: type: integer example: 1 title: Total pages description: The total number of pages available in the search results total_results: type: integer example: 1 title: Total results description: The total number of results available in the search ResourceAutoGeneratedProps: type: object required: - id - created_at - livemode properties: id: type: string description: ID of the object example: 590ce6c56d04f840aa8438af created_at: type: string format: date-time description: Creation date and time example: '2017-05-05T20:55:33.468Z' livemode: type: boolean description: >- Indicates if the object was created in Live mode (true) or Test mode (false). example: false TaxIdValidationResult: type: object properties: efos: type: object description: | Result of the validation in the list of Companies that Issue Simulated Operations (factureras or EFOS) of the SAT. properties: is_valid: type: boolean example: true description: | Indicates if the RFC has any issues related to this list. `true`: The RFC is not in the EFOS list or its situation was appealed and resulted in a favorable outcome. `false`: The RFC is registered as "Presumed" or "Definitive" in the EFOS list. data: type: object description: | Object with the result of the search at the SAT. All the information contained in this object comes from the SAT. properties: mensaje: type: string description: | Available only when the RFC was not found in the list, which is good. fechaLista: type: string example: Information updated on September 17, 2023 description: Text indicating the date of the list update. detalles: type: array description: Array with the details of the search in the EFOS list. items: type: object properties: rfc: type: string example: NOR170627727 description: The RFC consulted, as a confirmation. razonSocial: type: string example: NORMANDIA FERRE, description: Taxpayer's fiscal name. situacionContribuyente: type: string example: Definitivo description: > Text indicating the current situation. Check [this table](#situación-del-contribuyente) for details on the possible values. numFechaPresuncion: type: string example: 500-05-2020-23758 de fecha 03 de noviembre de 2020 description: >- Text with identifier and date of the presumption report. pubFechaSatPresuntos: type: string format: DD/MM/YYYY example: 03/11/2020 description: Date of publication of the presumption. numGlobalPresuncion: type: string example: 500-05-2020-23758 de fecha 03 de noviembre de 2020 description: >- Text with identifier and date of publication in the global presumption list. pubFechaDofPresuntos: type: string format: DD/MM/YYYY example: 18/11/2020 description: >- Date of publication in the Official Gazette of the Federation (DOF). pubSatDefinitivos: type: string example: 500-05-2021-151 description: >- Text with identifier of the publication of the "Definitive" status. pubDofDefinitivos: type: string format: DD/MM/YYYY example: 25/05/2021 description: >- Date of publication of the "Definitive" status in the DOF. numFechaSentFav: type: string example: 500-05-2021-15156 de fecha 25 de mayo de 2021 description: Text with identifier and date of favorable sentence. pubSatSentFav: type: string example: 08/06/2021 format: DD/MM/YYYY description: Date of favorable sentence. ProductCatalogResult: type: object properties: key: type: string description: Key from the SAT catalog example: 60131324 description: type: string description: Description example: Ukelele score: type: number description: | Number from 0 to 1 representing the level of match of the result with respect to the search query. example: 0.8 UnitCatalogResult: type: object properties: key: type: string description: Key from the SAT catalog example: INH description: type: string description: Description example: Pulgada score: type: number description: | Number from 0 to 1 representing the level of match of the result with respect to the search query. example: 0.9 ProductCatalogSearchResult: allOf: - $ref: '#/components/schemas/SearchResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/ProductCatalogResult' UnitCatalogSearchResult: allOf: - $ref: '#/components/schemas/SearchResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/UnitCatalogResult' SearchKeyDescriptionResult: allOf: - $ref: '#/components/schemas/SearchResult' - type: object properties: data: type: array items: type: object properties: key: type: string description: Key from the catalog description: type: string description: Description of the catalog entry LocalTax: type: object required: - rate - type properties: rate: type: number example: 0.1 description: Tax rate in decimal format. base: type: number default: 100% of subtotal description: Tax base amount. type: type: string description: Tax name. Free text. withholding: type: boolean default: false description: >- Indicates if it is a withholding tax (`true`) or a transferred tax (`false`). BaseTax: title: Tax type: object required: - rate discriminator: propertyName: type mapping: IVA: '#/components/schemas/BaseTax' ISR: '#/components/schemas/BaseTax' IEPS: '#/components/schemas/IepsTax' properties: rate: type: number example: 0.16 description: Tax rate in decimal format. base: type: number default: 100% of subtotal description: Tax base amount. type: type: string default: IVA description: Type of tax enum: - IVA - ISR - IEPS factor: type: string default: Tasa enum: - Tasa - Cuota - Exento description: Factor type. Tasa (rate), Cuota (amount), or Exento (exempt). withholding: type: boolean default: false description: >- Indicates if it is a withholding tax (`true`) or a transferred tax (`false`). IepsTax: type: object allOf: - $ref: '#/components/schemas/BaseTax' - type: object properties: ieps_mode: type: string default: sum_before_taxes enum: - sum_before_taxes - break_down - unit - subtract_before_break_down description: > Indicates in which way the tax is calculated. `"sum_before_taxes"`: Apply the IEPS to the subtotal first and use the result as the base for the rest of the taxes in the product. `"break_down"`: Charge and break down the IEPS at the same level as the rest of the taxes in the product. `"unit"`: Apply the IEPS before the unit price, and use the original unit price as the base for the rest of the taxes. `"subtract_before_break_down"`: Apply the IEPS only to calculate taxes like IVA de traslado and retentions, and use the original unit price as the base for the rest of the taxes. Consult with your accountant which case applies to your company and product. Stamp: type: object description: Information about the digital stamp added by the PAC. properties: signature: type: string description: Digital signature of the fiscal document. date: type: string format: date-time description: Stamp date in ISO8601 format (UTC String). sat_cert_number: type: string description: SAT certificate serial number used for stamping. sat_signature: type: string description: Digital stamp of the fiscal document. LineItem: type: object properties: quantity: type: number description: Quantity of units included in the same concept. example: 1 discount: type: number description: Total discount amount applied to this concept. example: 0 product: $ref: '#/components/schemas/LineItemProduct' description: | Object with information about the product or service invoiced. parts: $ref: '#/components/schemas/Parts' description: >- Object with information about the parts conforming this item or product. ThirdParty: type: object description: > Object with information about the third-party contributor, on behalf of whom the operation is carried out. Corresponds to the "ACuentaTerceros" field in the CFDI. properties: legal_name: type: string description: Name or business name of the third party. example: The Michael Scott Paper Company tax_id: type: string description: RFC of the third party. example: MIC920101HN7 tax_system: type: string maxLength: 3 minLength: 3 description: Fiscal regime of the third party. example: '601' zip: type: string description: Postal code of the third party. example: '01234' LineItemInput: title: LineItem required: - product type: object description: Concepts included in the document properties: quantity: type: number default: 1 description: Quantity of units included in the same concept. example: 1 discount: type: number description: Total discount amount applied to this concept. default: 0 example: 0 product: description: Object with information about the product or service invoiced. oneOf: - $ref: '#/components/schemas/LineItemProductInput' - type: string title: product_id description: ID of a product previously registered in Facturapi parts: type: array items: $ref: '#/components/schemas/PartInput' customs_keys: type: array items: type: string description: Customs entry numbers (pedimento) associated with this concept. complement: description: >- XML code of your concept-level complement, the Hydrocarbons and Petroleum complement, or the Private Education Institutions complement. oneOf: - type: string format: xml description: XML code of your concept-level complement. - $ref: '#/components/schemas/HidroYPetroComplementInput' - $ref: '#/components/schemas/IeduComplementInput' third_party: allOf: - type: object required: - legal_name - tax_id - tax_system - zip - $ref: '#/components/schemas/ThirdParty' property_tax_account: type: string description: Bank account number for property tax. example: '0102030405' LineItemEgresoInput: title: LineItem required: - product type: object description: Concepts included in the document properties: quantity: type: number default: 1 description: Quantity of units included in the same concept. example: 1 discount: type: number description: Total discount amount applied to this concept. default: 0 example: 0 product: description: Object with information about the product or service invoiced. oneOf: - $ref: '#/components/schemas/LineItemProductEgresoInput' - type: string title: product_id description: ID of a product previously registered in Facturapi parts: type: array items: $ref: '#/components/schemas/PartInput' customs_keys: type: array items: type: string description: Customs entry numbers (pedimento) associated with this concept. complement: description: >- XML code of your concept-level complement, the Hydrocarbons and Petroleum complement, or the Private Education Institutions complement. oneOf: - type: string format: xml description: XML code of your concept-level complement. - $ref: '#/components/schemas/HidroYPetroComplementInput' - $ref: '#/components/schemas/IeduComplementInput' third_party: allOf: - type: object required: - legal_name - tax_id - tax_system - zip - $ref: '#/components/schemas/ThirdParty' LineItemTrasladoInput: title: LineItem required: - product type: object description: Concepts included in the document properties: quantity: type: number default: 1 description: Quantity of units included in the same concept. example: 1 product: description: Object with information about the product or service invoiced. oneOf: - $ref: '#/components/schemas/LineItemTrasladoProductInput' - type: string title: product_id description: ID of a product previously registered in Facturapi customs_keys: type: array items: type: string description: Customs entry numbers (pedimento) associated with this concept. complement: type: string format: xml description: XML code of your concept-level complement. parts: type: array items: $ref: '#/components/schemas/PartInput' third_party: type: object required: - legal_name - tax_id - tax_system - zip properties: legal_name: type: string description: Name or business name of the third party. example: The Michael Scott Paper Company tax_id: type: string description: RFC of the third party. example: STA920101HN7 tax_system: type: string maxLength: 3 minLength: 3 description: Fiscal regime of the third party. example: '601' zip: type: string description: Postal code of the third party. example: '01234' HidroYPetroComplementInput: title: HidroYPetroComplement type: object required: - tipo_permiso - numero_permiso - sub_producto_hyp properties: tipo_permiso: type: string enum: - PER01 - PER02 - PER03 - PER04 - PER05 - PER06 - PER07 - PER08 - PER09 - PER10 - PER11 example: PER01 description: >- Type of permit granted by the competent authority, according to the [Hydrocarbons and Petroleum Catalogs](#cat%C3%A1logos-hidrocarburos-petrol%C3%ADferos). x-enum-descriptions: - Expendio en estaciones de servicio de petroliferos - Comercializacion - Distribucion por otros medios distintos a ducto - Expendio en estaciones de servicio multimodal de petroliferos - Expendio en estaciones de servicio de petroliferos - Comercializacion - Distribucion por otros medios distintos a ducto - Expendio en estaciones de servicio multimodal de petroliferos - Comercializacion - Comercializacion - Comercializacion numero_permiso: type: string minLength: 15 maxLength: 35 description: >- Permit number granted by the competent authority, according to the c_TipoPermiso catalog nomenclature. sub_producto_hyp: type: string enum: - SP16 - SP17 - SP18 - SP19 - SP22 - SP23 - SP24 - SP25 - SP48 example: SP16 description: >- Hydrocarbon or petroleum subproduct, according to the [Hydrocarbons and Petroleum Catalogs](#cat%C3%A1logos-hidrocarburos-petrol%C3%ADferos). x-enum-descriptions: - Gasolina regular menor a 91 octanos - Gasolina premium mayor o igual a 91 octanos - Diésel automotriz - Diésel marino - IFO380 - Diésel industrial - Diésel de Ultra Bajo Azufre (DUBA) - Diésel agrícola - Gasóleo doméstico clave_hyp: type: string enum: - '15101514' - '15101515' - '15101505' example: '15101514' description: > Hydrocarbon and petroleum key, according to the [Hydrocarbons and Petroleum Catalogs](#cat%C3%A1logos-hidrocarburos-petrol%C3%ADferos). You can send it explicitly or let Facturapi derive it from the concept's `product_key` when applicable. x-enum-descriptions: - Gasolina - Diesel - Combustibles para barco IeduComplementInput: title: IeduComplement type: object description: | Private Education Institutions concept-level complement version 1.0. Include it at the concept level in `items[].complement`. required: - nombreAlumno - CURP - nivelEducativo - autRVOE properties: nombreAlumno: type: string description: Student name. example: Juan Perez Lopez CURP: type: string minLength: 18 maxLength: 18 pattern: >- ^[A-Z][AEIOUX][A-Z]{2}[0-9]{2}[0-1][0-9][0-3][0-9][MHX][A-Z]{2}[BCDFGHJKLMNÑPQRSTVWXYZ]{3}[0-9A-Z][0-9]$ description: CURP of the student enrolled in the educational institution. example: PELJ010101HDFRPN09 nivelEducativo: type: string enum: - Preescolar - Primaria - Secundaria - Profesional técnico - Bachillerato o su equivalente example: Primaria description: Educational level the student is enrolled in. autRVOE: type: string minLength: 1 description: >- Work center code or official recognition of studies validity for the private educational institution where the payment is made. example: 15PPR1234A rfcPago: type: string pattern: >- ^[A-ZÑ&]{3,4}[0-9]{2}[0-1][0-9][0-3][0-9][A-Z0-9]?[A-Z0-9]?[0-9A-Z]?$ description: >- RFC of the person making the payment when different from the person receiving the service. example: PELJ800101ABC CustomComplementData: title: string type: string format: xml description: >- XML code of your complement as you want it to be inserted in the XML. It must contain only one root XML node. CustomComplementProperties: title: CustomComplement type: object properties: type: type: string enum: - custom description: Type of complement. data: $ref: '#/components/schemas/CustomComplementData' CustomComplementInput: title: CustomComplement allOf: - type: object required: - type - data - $ref: '#/components/schemas/CustomComplementProperties' NominaComplementDataInput: title: NominaComplementData description: | Object with the information of the payroll complement. allOf: - type: object required: - fecha_inicial_pago - fecha_final_pago - num_dias_pagados - receptor - percepciones - $ref: '#/components/schemas/NominaComplementDataDirectProperties' - $ref: '#/components/schemas/NominaComplementDataNestedInput' NominaComplementDataProperties: description: Payroll (nómina) complement allOf: - $ref: '#/components/schemas/NominaComplementDataDirectProperties' - $ref: '#/components/schemas/NominaComplementDataNestedProperties' NominaComplementDataDirectProperties: type: object properties: tipo_nomina: type: string default: O enum: - O - E description: > Type of payroll. - `"O"` (Ordinary): For payments made in a regular manner, such as salaries. - `"E"` (Extraordinary): For payments outside the ordinary, such as settlements, bonuses, or Christmas bonuses. fecha_pago: type: string format: date default: now description: Payment date of the payroll to the worker. fecha_inicial_pago: type: string format: date description: Initial date of the payment period. fecha_final_pago: type: string format: date description: Final date of the payment period. num_dias_pagados: type: number exclusiveMinimum: 0 description: Number of days paid. It can be an integer or a fraction. NominaComplementDataNestedInput: type: object properties: emisor: $ref: '#/components/schemas/NominaEmisorProperties' receptor: $ref: '#/components/schemas/NominaReceptorInput' percepciones: $ref: '#/components/schemas/NominaPercepcionesInput' deducciones: type: array description: Array of objects where applicable deductions are detailed. items: $ref: '#/components/schemas/NominaDeduccionInput' otros_pagos: type: array description: Array of objects where other applicable payments are detailed. items: title: OtroPago allOf: - $ref: '#/components/schemas/NominaOtroPagoInput' - type: object properties: compensacion_saldos_a_favor: $ref: '#/components/schemas/NominaCompensacionInput' incapacidades: type: array description: Array of objects with information about paid incapacities. items: $ref: '#/components/schemas/NominaIncapacidadInput' NominaComplementDataNestedProperties: type: object properties: emisor: $ref: '#/components/schemas/NominaEmisorProperties' receptor: $ref: '#/components/schemas/NominaReceptorProperties' percepciones: $ref: '#/components/schemas/NominaPercepcionesProperties' deducciones: type: array description: Array of objects where applicable deductions are detailed. items: $ref: '#/components/schemas/NominaDeduccionProperties' otros_pagos: type: array description: Array of objects where other applicable payments are detailed. items: allOf: - $ref: '#/components/schemas/NominaOtroPagoDirectProperties' - type: object properties: compensacion_saldos_a_favor: $ref: '#/components/schemas/NominaCompensacionProperties' incapacidades: type: array description: Array of objects with information about paid incapacities. items: $ref: '#/components/schemas/NominaIncapacidadProperties' NominaIncapacidadInput: title: Incapacidad allOf: - type: object required: - dias_incapacidad - tipo_incapacidad - $ref: '#/components/schemas/NominaIncapacidadProperties' NominaIncapacidadProperties: type: object properties: dias_incapacidad: type: integer description: Number of days the worker was incapacitated in the period. tipo_incapacidad: type: string description: Key from the catalog [Type of incapacity](#tipo-de-incapacidad). importe_monetario: type: number description: Monetary amount of the paid incapacity. NominaOtroPagoInput: title: OtroPago allOf: - type: object required: - tipo_otro_pago - clave - importe - $ref: '#/components/schemas/NominaOtroPagoDirectProperties' - type: object properties: compensacion_saldos_a_favor: $ref: '#/components/schemas/NominaCompensacionInput' NominaOtroPagoDirectProperties: type: object properties: tipo_otro_pago: type: string description: Key from the catalog [Type of Other Payment](#tipo-de-otro-pago). clave: type: string minLength: 3 maxLength: 15 description: >- Key of another payroll payment, specific to each employer's accounting. concepto: type: string description: Alternative description corresponding to the key used. importe: type: number description: Amount for another payment concept. subsidio_causado: type: number description: > Caused subsidy according to the subsidy table for employment published in Annex 8 of the current Fiscal Miscellaneous Resolution. This value will be inserted within the `SubsidioAlEmpleo` node, and is required when the value of `tipo_otro_pago` is `"002"`. NominaCompensacionInput: allOf: - type: object required: - saldo_a_favor - ano - remanente_sal_fav - $ref: '#/components/schemas/NominaCompensacionProperties' NominaCompensacionProperties: type: object description: >- Object with information about the compensation of balances in favor of a worker. properties: saldo_a_favor: type: number description: >- Amount for a balance in favor determined by the employer to the worker in previous periods or exercises. ano: type: integer description: Year in which the balance in favor of the worker was determined. remanente_sal_fav: type: number description: Remaining balance in favor of the worker. NominaDeduccionInput: title: Deduccion allOf: - type: object required: - tipo_deduccion - clave - importe - $ref: '#/components/schemas/NominaDeduccionProperties' NominaDeduccionProperties: type: object properties: tipo_deduccion: type: string description: Key from the catalog [Type of deduction](#tipo-de-deducción). concepto: type: string description: >- Deduction concept. If not sent, the description of the deduction type catalog will be used. clave: type: string minLength: 3 maxLength: 15 description: >- Internal control key assigned by the employer to each deduction (discount) of payroll specific to its accounting. importe: type: number description: Amount of the deduction. NominaPercepcionesInput: type: object title: Percepciones description: Object to indicate the applicable earnings. required: - percepcion properties: percepcion: type: array description: Object with detailed information of each earning. items: $ref: '#/components/schemas/NominaPercepcionInput' jubilacion_pension_retiro: $ref: '#/components/schemas/NominaJubilacionInput' separacion_indemnizacion: $ref: '#/components/schemas/NominaSeparacionInput' NominaPercepcionesProperties: type: object title: Percepciones description: Object to indicate the applicable earnings. properties: percepcion: type: array description: Object with detailed information of each earning. items: $ref: '#/components/schemas/NominaPercepcionProperties' jubilacion_pension_retiro: $ref: '#/components/schemas/NominaJubilacionProperties' separacion_indemnizacion: $ref: '#/components/schemas/NominaSeparacionProperties' NominaSeparacionInput: title: Separacion allOf: - type: object required: - total_pagado - num_anos_servicio - ultimo_sueldo_mens_ord - ingreso_acumulable - ingreso_no_acumulable - $ref: '#/components/schemas/NominaSeparacionProperties' NominaSeparacionProperties: type: object title: Jubilacion description: >- Object with detailed information of payments for separation (dismissal) or compensation. properties: total_pagado: type: number description: Total amount paid for separation or compensation. num_anos_servicio: type: integer description: >- Number of years of service worked by the worker, rounded up to the nearest whole number. ultimo_sueldo_mens_ord: type: number description: Last ordinary monthly salary received by the worker. ingreso_acumulable: type: number description: Amount for accumulable income. ingreso_no_acumulable: type: number description: Amount for non-accumulable income. NominaJubilacionInput: title: Jubilacion allOf: - type: object required: - ingreso_acumulable - ingreso_no_acumulable - $ref: '#/components/schemas/NominaJubilacionProperties' NominaJubilacionProperties: type: object description: >- Object with detailed information of payments for retirement, pensions, or retirement benefits. properties: total_una_exhibicion: type: number description: Total amount paid in a single installment. total_parcialidad: type: number description: Total amount paid in separate installments. monto_diario: type: number description: >- Daily amount received by the worker when the payment is made in installments. ingreso_acumulable: type: number description: Accumulable income received by the worker. ingreso_no_acumulable: type: number description: Non-accumulable income received by the worker. NominaPercepcionProperties: title: Percepcion allOf: - $ref: '#/components/schemas/NominaPercepcionDirectProperties' - $ref: '#/components/schemas/NominaPercepcionNestedProperties' NominaPercepcionInput: title: Percepcion allOf: - type: object required: - tipo_percepcion - clave - importe_gravado - importe_exento - $ref: '#/components/schemas/NominaPercepcionDirectProperties' - $ref: '#/components/schemas/NominaPercepcionNestedInput' NominaPercepcionDirectProperties: type: object properties: tipo_percepcion: type: string description: Key from the catalog [Type of earnings](#tipo-de-percepcion). concepto: type: string description: >- Earnings concept. If not sent, the description of the earnings type catalog will be used. clave: type: string minLength: 3 maxLength: 15 description: >- Internal control key assigned by the employer to each payroll earning specific to its accounting. importe_gravado: type: number description: Taxable amount for the concept indicated in the type of earnings. importe_exento: type: number description: Exempt amount for the concept indicated in the type of earnings. NominaPercepcionNestedInput: type: object properties: acciones_o_titulos: $ref: '#/components/schemas/NominaAccionesInput' horas_extra: type: array description: >- Array of objects to express applicable extra hours. Required when the type of earnings is "019" (Extra hours). items: $ref: '#/components/schemas/NominaHorasExtraInput' NominaPercepcionNestedProperties: type: object properties: acciones_o_titulos: $ref: '#/components/schemas/NominaAccionesProperties' horas_extra: type: array description: >- Array of objects to express applicable extra hours. Required when the type of earnings is "019" (Extra hours). items: $ref: '#/components/schemas/NominaHorasExtraProperties' NominaHorasExtraInput: title: HorasExtra allOf: - type: object required: - dias - tipo_horas - horas_extra - importe_pagado - $ref: '#/components/schemas/NominaHorasExtraProperties' NominaHorasExtraProperties: type: object title: HorasExtra properties: dias: type: integer description: >- Number of days the worker worked extra hours in addition to their normal working day. tipo_horas: type: string description: Key from the catalog [Type of Hours](#tipo-de-Horas). horas_extra: type: integer description: Number of extra hours worked in the period. importe_pagado: type: number description: Amount paid for extra hours. NominaAccionesInput: title: Accion allOf: - type: object required: - valor_mercado - precio_al_otorgarse - $ref: '#/components/schemas/NominaAccionesProperties' NominaAccionesProperties: type: object title: Accion description: >- Object to express earnings from shares or securities representing goods. It is required when there are earnings from salaries derived from the acquisition of shares or securities. properties: valor_mercado: type: number description: >- Market value of the shares or securities when the option is exercised. precio_al_otorgarse: type: number description: >- Price established when the option of income in shares or securities is granted. NominaReceptorProperties: type: object title: Receptor description: Worker information. allOf: - $ref: '#/components/schemas/NominaReceptorDirectProperties' - $ref: '#/components/schemas/NominaReceptorNestedProperties' NominaReceptorInput: type: object title: Receptor description: Worker information. allOf: - type: object required: - curp - tipo_contrato - tipo_regimen - num_empleado - periodicidad_pago - clave_ent_fed - $ref: '#/components/schemas/NominaReceptorDirectProperties' - $ref: '#/components/schemas/NominaReceptorNestedInput' NominaReceptorDirectProperties: type: object properties: curp: type: string description: >- Worker's CURP (Clave Única de Registro de Población) (Unique Population Registry Code). num_seguridad_social: type: string description: Social security number. fecha_inicio_rel_laboral: type: string format: date description: | Start date of the employment relationship between the employer and the employee. antiguedad: oneOf: - type: string - type: boolean default: true description: | Employee's seniority in the format specified by the SAT. If a `string` is sent, it is expected to contain the seniority in the format specified by the SAT. If the boolean value `false` is sent, this field will not be included in the invoice. If the boolean value `true` and `fecha_inicio_rel_laboral` exist, this value will be calculated with the difference between the start date of the employment relationship and the payment date. tipo_contrato: type: string description: Key from the catalog [Type of Contract](#tipo-de-contrato). sindicalizado: type: boolean default: false description: Indicates if the worker is associated with a union. tipo_jornada: type: string description: Key from the catalog [Type of Workday](#tipo-de-jornada). tipo_regimen: type: string description: Key from the catalog [Type of Regime](#régimen-fiscal). num_empleado: type: string minLength: 1 maxLength: 15 description: Internal employee number assigned by the employer. departamento: type: string description: Name of the department or area to which the worker belongs. puesto: type: string description: >- Name of the position assigned to the employee or the name of the activity they perform. riesgo_puesto: type: string description: Key from the SAT catalog [Job Risk](#riesgo-del-puesto). periodicidad_pago: type: string description: >- Key from the SAT catalog [Payment Periodicity](#periodicidad-del-pago). banco: type: string description: >- Key from the SAT catalog "Bancos" that you can consult using our [search tool](https://dashboard.facturapi.io/catalogs/bank). cuenta_bancaria: type: string description: > Bank account number (11 characters) or cell phone number (10 characters) or card number (15 or 16 characters) or CLABE (18 characters) or electronic wallet number where the payroll deposit is made. salario_base_cot_apor: type: number description: >- Amount of the cash remuneration for daily quota, bonuses, perceptions, food, housing, premiums, commissions, benefits in kind, etc. salario_diario_integrado: type: number description: >- Salary that is integrated with payments made in cash for daily quota, bonuses, perceptions, housing, premiums, commissions, benefits in kind, and any other amount or benefit that is delivered to the worker for their work. clave_ent_fed: type: string description: >- Key of the federal entity (state) where the worker provided their services to the employer, which you can consult using our [search tool](https://dashboard.facturapi.io/catalogs/state). NominaReceptorNestedProperties: type: object properties: sub_contratacion: type: array description: >- Array of objects to express information about the company that benefits from the employee's work, in cases where the issuer provides subcontracting services. items: $ref: '#/components/schemas/NominaSubContratacionProperties' NominaReceptorNestedInput: type: object properties: sub_contratacion: type: array description: >- Array of objects to express information about the company that benefits from the employee's work, in cases where the issuer provides subcontracting services. items: allOf: - $ref: '#/components/schemas/NominaSubContratacionRequiredProperties' - $ref: '#/components/schemas/NominaSubContratacionProperties' NominaSubContratacionRequiredProperties: type: object required: - rfc_labora - porcentaje_tiempo NominaSubContratacionProperties: type: object properties: rfc_labora: type: string description: >- RFC of the person or company that subcontracted, that is, the person or company where the worker directly provided their services. porcentaje_tiempo: type: number minimum: 0.001 maximum: 100 description: >- Percentage of time the worker provided their services to the person or company that subcontracted them. NominaEmisorProperties: type: object title: Emisor description: Information of the issuer, if required. properties: curp: type: string minLength: 18 maxLength: 18 description: >- Required when the employer is a natural person. CURP of the employer. registro_patronal: type: string description: >- Employer's registration key assigned by the social security institution to the employer. rfc_patron_origen: minLength: 12 maxLength: 13 type: string description: >- RFC of the person who acted as the employer. It is used when the payment is made through a third party. entidad_sncf: type: object description: >- Information for entities adhered to the National System of Fiscal Coordination to identify the origin of the resources. properties: origen_recurso: type: string enum: - IP - IF - IM description: | Key of the origin of the resource. - `“IP”`: Ingresos Propios (Own income) - `“IF”`: Ingresos Federales (Federal income) - `“IM”`: Ingresos mixtos (Mixed income) monto_recurso_propio: type: number description: > Amount of own resources. Required when the resource origin is mixed income. PagoOrCustomComplementProperties: title: Complement type: object discriminator: propertyName: type mapping: pago: '#/components/schemas/PagoComplementProperties' custom: '#/components/schemas/CustomComplementProperties' properties: type: type: string enum: - pago - custom description: Type of complement PagoOrCustomComplementInput: type: object title: Complement discriminator: propertyName: type mapping: pago: '#/components/schemas/PagoComplementInput' custom: '#/components/schemas/CustomComplementInput' required: - type - data properties: type: type: string enum: - nomina - custom description: Type of complement PagoComplementProperties: allOf: - $ref: '#/components/schemas/NominaOrCustomComplementProperties' - type: object properties: data: $ref: '#/components/schemas/NominaComplementDataProperties' PagoComplementInput: allOf: - $ref: '#/components/schemas/PagoOrCustomComplementInput' - type: object properties: data: $ref: '#/components/schemas/PagoComplementDataInput' PagoComplementDataInput: type: array title: PagoComplementData description: >- Payments to include in this document. The most common is to include only one payment. A case in which more than one must be added is when the payment is made with 2 different payment methods; for example, when one part is paid by card and the other in cash. items: $ref: '#/components/schemas/PaymentInput' NominaOrCustomComplementProperties: title: Complement type: object discriminator: propertyName: type mapping: nomina: '#/components/schemas/NominaComplementProperties' custom: '#/components/schemas/CustomComplementProperties' properties: type: type: string enum: - nomina - custom description: Type of complement NominaOrCustomComplementInput: type: object title: Complement discriminator: propertyName: type mapping: nomina: '#/components/schemas/NominaComplementInput' custom: '#/components/schemas/CustomComplementInput' required: - type - data properties: type: type: string enum: - nomina - custom description: Type of complement NominaComplementProperties: allOf: - $ref: '#/components/schemas/NominaOrCustomComplementProperties' - type: object properties: data: $ref: '#/components/schemas/NominaComplementDataProperties' NominaComplementInput: allOf: - $ref: '#/components/schemas/NominaOrCustomComplementInput' - type: object properties: data: $ref: '#/components/schemas/NominaComplementDataInput' CartaPorteProperties: allOf: - $ref: '#/components/schemas/CartaPorteOrCustomComplementProperties' - type: object properties: data: $ref: '#/components/schemas/CartaPorteDataProperties' CartaPorteInput: allOf: - $ref: '#/components/schemas/CartaPorteOrCustomComplementInput' - type: object properties: data: $ref: '#/components/schemas/CartaPorteDataInput' ComercioExteriorProperties: allOf: - $ref: '#/components/schemas/CartaPorteOrCustomComplementProperties' - type: object properties: data: $ref: '#/components/schemas/ComercioExteriorDataProperties' ComercioExteriorInput: allOf: - $ref: '#/components/schemas/CartaPorteOrCustomComplementInput' - type: object properties: data: $ref: '#/components/schemas/ComercioExteriorDataInput' CartaPorteOrCustomComplementProperties: title: Complement type: object discriminator: propertyName: type mapping: carta_porte: '#/components/schemas/CartaPorteProperties' comercio_exterior: '#/components/schemas/ComercioExteriorProperties' custom: '#/components/schemas/CustomComplementProperties' properties: type: type: string enum: - carta_porte - comercio_exterior - custom description: Type of complement CartaPorteOrCustomComplementInput: title: Complement type: object discriminator: propertyName: type mapping: custom: '#/components/schemas/CustomComplementInput' carta_porte: '#/components/schemas/CartaPorteInput' comercio_exterior: '#/components/schemas/ComercioExteriorInput' required: - type - data properties: type: type: string enum: - carta_porte - comercio_exterior - custom description: Type of complement CartaPorteDataProperties: type: object title: CartaPorte description: Carta Porte complement version 3.1. (Beta) required: - IdCCP - TranspInternac - Ubicaciones - Mercancias properties: IdCCP: type: string description: Unique Carta Porte identifier. TranspInternac: type: string description: Indicates if the transport is international. EntradaSalidaMerc: type: string description: Goods entry or exit. PaisOrigenDestino: type: string description: Origin or destination country. ViaEntradaSalida: type: string description: Entry or exit way. TotalDistRec: type: number description: Total distance traveled. RegistroISTMO: type: string description: ISTMO program registry. UbicacionPoloOrigen: type: string description: Origin pole. UbicacionPoloDestino: type: string description: Destination pole. RegimenesAduaneros: type: object description: Customs regimes object. Ubicaciones: type: array description: Locations array. items: type: object description: Origin/destination location. required: - TipoUbicacion - RFCRemitenteDestinatario - FechaHoraSalidaLlegada properties: TipoUbicacion: type: string description: >- Required attribute to specify whether the location type corresponds to the origin or destination for transporting goods/merchandise across the different means of transport. Allowed values: "Origen" | "Destino". IDUbicacion: type: string description: >- Conditional attribute to record a key identifying the exit or entry point of the goods/merchandise. Format: "OR" or "DE" followed by 6 numeric digits (regex (OR|DE)[0-9]{6}). RFCRemitenteDestinatario: type: string description: >- Required attribute to record the RFC (tax ID) of the sender or receiver of the goods/merchandise. NombreRemitenteDestinatario: type: string description: >- Optional attribute to record the name of the sender or receiver of the goods/merchandise (length 1 to 254 characters). NumRegIdTrib: type: string description: >- Conditional attribute for the foreign tax identification or registry number of the sender or receiver when they are non-residents (length 6 to 40 characters). ResidenciaFiscal: type: string description: >- Conditional attribute to record the country key of fiscal residence of the sender or receiver according to catalog c_Pais (ISO 3166-1). NumEstacion: type: string description: >- Conditional attribute for the station key of origin or destination according to the c_Estaciones catalog of the Carta Porte complement and the transport type. NombreEstacion: type: string description: >- Conditional attribute for the name of the station of origin or destination per the c_Estaciones catalog (length 1 to 50 characters). NavegacionTrafico: type: string description: >- Conditional attribute to indicate the type of maritime port of origin or destination. Allowed values: "Altura" | "Cabotaje". FechaHoraSalidaLlegada: type: string description: >- Required attribute to record the estimated departure or arrival date-time in the format YYYY-MM-DDThh:mm:ss. TipoEstacion: type: string description: >- Conditional attribute to record the station type through which the goods/merchandise pass per catalog c_TipoEstacion. DistanciaRecorrida: type: number description: >- Conditional attribute to record in kilometers the distance traveled between the origin location and the partial or final destination. Domicilio: $ref: '#/components/schemas/CartaPorteDomicilio' Mercancias: $ref: '#/components/schemas/CartaPorteMercancias' FiguraTransporte: type: array description: Transport figures. items: type: object description: Transport figure (operator, owner, lessor, notified party, etc.). required: - TipoFigura - NombreFigura properties: TipoFigura: type: string description: >- Required. Code identifying the type of transport figure (operator, owner, lessor, notified) per the corresponding catalog (c_TipoFigura). RFCFigura: type: string description: >- RFC (tax ID) of the operator/owner/lessor or intervening figure. NumLicencia: type: string description: >- License number of the operator when TipoFigura corresponds to operator. NombreFigura: type: string description: Legal name of the transport figure (required). NumRegIdTribFigura: type: string description: Foreign tax registration number of the figure when applicable. ResidenciaFiscalFigura: type: string description: >- Country code of fiscal residence (c_Pais) when the figure is foreign. PartesTransporte: type: array description: Optional array with the transport parts related to the figure. items: type: object required: - ParteTransporte properties: ParteTransporte: type: string description: >- Code of the transport part per catalog c_ParteTransporte. Domicilio: $ref: '#/components/schemas/CartaPorteDomicilio' description: Address associated to the transport figure. CartaPorteDataInput: allOf: - $ref: '#/components/schemas/CartaPorteDataProperties' ComercioExteriorDataProperties: type: object title: ComercioExterior description: Foreign Trade complement version 2.0. required: - ClaveDePedimento - CertificadoOrigen - TipoCambioUSD - TotalUSD - Mercancias properties: Version: type: string default: '2.0' enum: - '2.0' MotivoTraslado: type: string description: Key from catalog c_MotivoTraslado. ClaveDePedimento: type: string description: Customs entry key (catalog c_ClavePedimento). CertificadoOrigen: type: integer enum: - 0 - 1 description: Indicates if a certificate of origin exists. NumCertificadoOrigen: type: string minLength: 6 maxLength: 40 description: Certificate of origin number. NumeroExportadorConfiable: type: string minLength: 1 maxLength: 50 description: Authorized exporter number. Incoterm: type: string description: INCOTERM key (catalog c_INCOTERM). Observaciones: type: string minLength: 1 maxLength: 300 TipoCambioUSD: type: number minimum: 0 description: USD exchange rate. TotalUSD: type: number minimum: 0 description: Total amount in USD. Emisor: description: >- Information of the issuer of the complement. Its an optional field and by default uses the issuer address and curp from the organization issuing the complement. oneOf: - $ref: '#/components/schemas/ComercioExteriorEmisor' - type: boolean default: true description: >- When `true`, uses the issuer address and curp from the organization issuing the complement. By default is `true`. Propietario: type: array items: oneOf: - $ref: '#/components/schemas/ComercioExteriorPropietario' - $ref: '#/components/schemas/CustomerComercioExterior' Receptor: oneOf: - $ref: '#/components/schemas/ComercioExteriorReceptor' - $ref: '#/components/schemas/CustomerComercioExterior' Destinatario: type: array items: oneOf: - $ref: '#/components/schemas/ComercioExteriorDestinatario' - $ref: '#/components/schemas/CustomerComercioExterior' Mercancias: $ref: '#/components/schemas/ComercioExteriorMercancias' ComercioExteriorDataInput: allOf: - $ref: '#/components/schemas/ComercioExteriorDataProperties' ComercioExteriorDomicilio: type: object required: - Calle - Estado - Pais - CodigoPostal properties: Calle: type: string maxLength: 100 NumeroExterior: type: string maxLength: 20 NumeroInterior: type: string maxLength: 20 Colonia: type: string Localidad: type: string Referencia: type: string maxLength: 150 Municipio: type: string Estado: type: string minLength: 1 maxLength: 30 Pais: type: string description: Key from catalog c_Pais. CodigoPostal: type: string minLength: 1 maxLength: 12 ComercioExteriorEmisor: type: object required: - Domicilio properties: Domicilio: $ref: '#/components/schemas/ComercioExteriorDomicilio' Curp: type: string minLength: 18 maxLength: 18 ComercioExteriorPropietario: type: object required: - NumRegIdTrib - ResidenciaFiscal properties: NumRegIdTrib: type: string minLength: 6 maxLength: 40 ResidenciaFiscal: type: string description: Key from catalog c_Pais. ComercioExteriorReceptor: type: object properties: Domicilio: $ref: '#/components/schemas/ComercioExteriorDomicilio' NumRegIdTrib: type: string minLength: 6 maxLength: 40 ComercioExteriorDestinatario: type: object required: - Domicilio properties: Domicilio: type: array minItems: 1 items: $ref: '#/components/schemas/ComercioExteriorDomicilio' NumRegIdTrib: type: string minLength: 6 maxLength: 40 Nombre: type: string minLength: 1 maxLength: 300 ComercioExteriorDescripcionesEspecificas: type: object required: - Marca properties: Marca: type: string minLength: 1 maxLength: 35 Modelo: type: string minLength: 1 maxLength: 80 SubModelo: type: string minLength: 1 maxLength: 50 NumeroSerie: type: string minLength: 1 maxLength: 40 ComercioExteriorMercancia: type: object required: - NoIdentificacion - ValorDolares properties: DescripcionesEspecificas: type: array items: $ref: '#/components/schemas/ComercioExteriorDescripcionesEspecificas' NoIdentificacion: type: string minLength: 1 maxLength: 100 FraccionArancelaria: type: string description: Key from catalog c_FraccionArancelaria. CantidadAduana: type: number minimum: 0.001 UnidadAduana: type: string description: Key from catalog c_UnidadAduana. ValorUnitarioAduana: type: number minimum: 0 ValorDolares: type: number minimum: 0 ComercioExteriorMercancias: type: object required: - Mercancia properties: Mercancia: type: array minItems: 1 items: $ref: '#/components/schemas/ComercioExteriorMercancia' CartaPorteCantidadTransporta: type: object required: - Cantidad - IDOrigen - IDDestino properties: Cantidad: type: number IDOrigen: type: string IDDestino: type: string CvesTransporte: type: string description: Transportation key. CartaPorteDetalleMercancia: type: object required: - UnidadPesoMerc - PesoBruto - PesoNeto - PesoTara properties: UnidadPesoMerc: type: string description: Weight unit key for the merchandise per SAT catalog. PesoBruto: type: number description: Gross weight including packaging and tare. PesoNeto: type: number description: Net weight excluding packaging and tare. PesoTara: type: number description: Tare weight (containers, packaging) for the merchandise. NumPiezas: type: number description: Number of pieces comprising this merchandise detail. CartaPorteDocumentacionAduanera: type: object properties: TipoDocumento: type: string description: Customs document type (pedimento, guide, bill of lading, etc.). NumPedimento: type: string description: Import/export pedimento number. IdentDocAduanero: type: string description: Alternate identifier for the customs document. RFCImpo: type: string description: RFC of the importer when applicable. CartaPorteGuiaIdentificacion: type: object properties: NumeroGuiaIdentificacion: type: string description: Identification guide number linked to the merchandise. DescripGuiaIdentificacion: type: string description: Detailed description of the identification guide. PesoGuiaIdentificacion: type: number description: Weight covered by the identification guide. CartaPorteMercancia: type: object required: - BienesTransp - Descripcion - Cantidad - ClaveUnidad - PesoEnKg properties: BienesTransp: type: string ClaveSTCC: type: string Descripcion: type: string Cantidad: type: number ClaveUnidad: type: string Unidad: type: string Dimensiones: type: string MaterialPeligroso: type: string CveMaterialPeligroso: type: string Embalaje: type: string DescripEmbalaje: type: string SectorCOFEPRIS: type: string NombreIngredienteActivo: type: string NomQuimico: type: string DenominacionGenericaProd: type: string DenominacionDistintivaProd: type: string Fabricante: type: string FechaCaducidad: type: string LoteMedicamento: type: string FormaFarmaceutica: type: string CondicionesEspTransp: type: string RegistroSanitarioFolioAutorizacion: type: string PermisoImportacion: type: string FolioImpoVUCEM: type: string NumCAS: type: string RazonSocialEmpImp: type: string NumRegSanPlagCOFEPRIS: type: string DatosFabricante: type: string DatosFormulador: type: string DatosMaquilador: type: string UsoAutorizado: type: string PesoEnKg: type: number ValorMercancia: type: number Moneda: type: string FraccionArancelaria: type: string UUIDComercioExt: type: string TipoMateria: type: string DescripcionMateria: type: string DocumentacionAduanera: type: array items: $ref: '#/components/schemas/CartaPorteDocumentacionAduanera' GuiasIdentificacion: type: array items: $ref: '#/components/schemas/CartaPorteGuiaIdentificacion' CantidadTransporta: type: array items: $ref: '#/components/schemas/CartaPorteCantidadTransporta' DetalleMercancia: type: array items: $ref: '#/components/schemas/CartaPorteDetalleMercancia' CartaPorteIdentificacionVehicular: type: object properties: ConfigVehicular: type: string description: Vehicle configuration code (c_ConfigAutotransporte). PesoBrutoVehicular: type: number description: Maximum allowed gross vehicular weight. PlacaVM: type: string description: License plate of the motor vehicle. AnioModeloVM: type: string description: Model year of the motor vehicle. CartaPorteSeguros: type: object properties: AseguraRespCivil: type: string description: Civil liability insurer name. PolizaRespCivil: type: string description: Civil liability policy number. AseguraMedAmbiente: type: string description: Environmental damage insurer. PolizaMedAmbiente: type: string description: Environmental policy number. AseguraCarga: type: string description: Cargo insurer name. PolizaCarga: type: string description: Cargo insurance policy number. PrimaSeguro: type: number description: Total insurance premium. CartaPorteRemolque: type: object properties: SubTipoRem: type: string description: Trailer subtype code (c_SubTipoRem). Placa: type: string description: Trailer license plate. CartaPorteAutotransporte: type: object properties: PermSCT: type: string description: SCT permit key for motor transport. NumPermisoSCT: type: string description: SCT permit number. IdentificacionVehicular: $ref: '#/components/schemas/CartaPorteIdentificacionVehicular' description: Identification data of the primary vehicle. Seguros: $ref: '#/components/schemas/CartaPorteSeguros' description: Applicable insurance information. Remolques: type: array items: $ref: '#/components/schemas/CartaPorteRemolque' description: List of attached trailers. CartaPorteContenedorMaritimo: type: object properties: TipoContenedor: type: string description: Maritime container type (ISO / SAT catalog). MatriculaContenedor: type: string description: Container registration/identifier. NumPrecinto: type: string description: Seal or security lock number. IdCCPRelacionado: type: string description: Related CCP identifier when reusing data. PlacaVMCCP: type: string description: Motor vehicle plate associated (in transshipment cases). FechaCertificacionCCP: type: string description: CCP certification date of the container. RemolquesCCP: type: array items: type: object properties: SubTipoRemCCP: type: string description: Related trailer subtype (CCP context). PlacaCCP: type: string description: Related trailer plate (CCP context). CartaPorteTransporteMaritimo: type: object required: - PermSCT - NumPermisoSCT properties: PermSCT: type: string description: SCT permit key for the vessel. NumPermisoSCT: type: string description: SCT permit number for the vessel. NombreAseg: type: string description: Maritime insurer name. NumPolizaSeguro: type: string description: Maritime insurance policy number. TipoEmbarcacion: type: string description: Vessel type (c_TipoEmbarcacion). Matricula: type: string description: Vessel registration (matrícula). NumeroOMI: type: string description: IMO number of the vessel. AnioEmbarcacion: type: string description: Year the vessel was built. NombreEmbarc: type: string description: Proper name of the vessel. NacionalidadEmbarc: type: string description: Flag or nationality of the vessel. UnidadesDeArqBruto: type: number description: Gross tonnage units. TipoCarga: type: string description: Cargo type (bulk, containers, liquid, etc.). Eslora: type: number description: Length overall (LOA). Manga: type: number description: Maximum beam width. Calado: type: number description: Maximum draft. Puntal: type: number description: Depth/height of the hull (puntal). LineaNaviera: type: string description: Shipping line name. NombreAgenteNaviero: type: string description: Name of shipping agent. NumAutorizacionNaviero: type: string description: Shipping agent authorization number. NumViaje: type: string description: Voyage number. NumConocEmbarc: type: string description: Bill of lading number. PermisoTempNavegacion: type: string description: Temporary navigation permit. Contenedor: type: array items: $ref: '#/components/schemas/CartaPorteContenedorMaritimo' description: List of containers associated with the voyage. CartaPorteTransporteAereo: type: object properties: PermSCT: type: string description: SCT permit key for air transport. NumPermisoSCT: type: string description: SCT permit number. MatriculaAeronave: type: string description: Aircraft registration. NombreAseg: type: string description: Air transport insurer name. NumPolizaSeguro: type: string description: Aircraft insurance policy number. NumeroGuia: type: string description: Air waybill number. LugarContrato: type: string description: Place where the transport contract was executed. CodigoTransportista: type: string description: Air carrier code. RFCEmbarcador: type: string description: RFC of the shipper. NumRegIdTribEmbarc: type: string description: Foreign tax registration of the shipper. ResidenciaFiscalEmbarc: type: string description: Tax residence country of the shipper. NombreEmbarcador: type: string description: Name or corporate name of the shipper. CartaPorteDerechosDePaso: type: object properties: TipoDerechoDePaso: type: string description: Type of rail right-of-way. KilometrajePagado: type: number description: Paid/covered mileage for the right-of-way. CartaPorteContenedorFerroviario: type: object properties: TipoContenedor: type: string description: Rail container type. PesoContenedorVacio: type: number description: Empty container weight. PesoNetoMercancia: type: number description: Net weight of contained merchandise. CartaPorteCarroFerroviario: type: object properties: TipoCarro: type: string description: Railcar type. MatriculaCarro: type: string description: Railcar identifier/registration. GuiaCarro: type: string description: Guide number associated with the railcar. ToneladasNetasCarro: type: number description: Net tons transported in the railcar. Contenedor: type: array items: $ref: '#/components/schemas/CartaPorteContenedorFerroviario' description: Containers associated with the railcar. CartaPorteTransporteFerroviario: type: object properties: TipoDeServicio: type: string description: Type of rail service (regular, intermodal, etc.). TipoDeTrafico: type: string description: Traffic type (national, international, etc.). NombreAseg: type: string description: Rail insurer name. NumPolizaSeguro: type: string description: Rail insurance policy number. DerechosDePaso: type: array items: $ref: '#/components/schemas/CartaPorteDerechosDePaso' description: List of applied rights-of-way. Carro: type: array items: $ref: '#/components/schemas/CartaPorteCarroFerroviario' description: List of railcars involved. CartaPorteDomicilio: type: object description: Address object associated to the location in the Carta Porte complement. required: - Estado - Pais - CodigoPostal properties: Calle: type: string NumeroExterior: type: string NumeroInterior: type: string Colonia: type: string Localidad: type: string Referencia: type: string Municipio: type: string Estado: type: string Pais: type: string CodigoPostal: type: string CartaPorteMercancias: type: object required: - PesoBrutoTotal - UnidadPeso - NumTotalMercancias - Mercancia properties: PesoBrutoTotal: type: number description: Sum of gross weights of all merchandise items. UnidadPeso: type: string description: Standard weight unit key (c_ClaveUnidadPeso). PesoNetoTotal: type: number description: Sum of net weights from each DetalleMercancia. NumTotalMercancias: type: number description: Total number of merchandise nodes. CargoPorTasacion: type: number description: Appraisal charge amount (air transport context). LogisticaInversaRecoleccionDevolucion: type: string description: Indicates reverse logistics, collection or return applicability. Mercancia: type: array items: $ref: '#/components/schemas/CartaPorteMercancia' description: Required array of transported merchandise. Autotransporte: $ref: '#/components/schemas/CartaPorteAutotransporte' description: Federal motor transport details. TransporteMaritimo: $ref: '#/components/schemas/CartaPorteTransporteMaritimo' description: Maritime vessel transport details. TransporteAereo: $ref: '#/components/schemas/CartaPorteTransporteAereo' description: Air transport details. TransporteFerroviario: $ref: '#/components/schemas/CartaPorteTransporteFerroviario' description: Rail transport details. NamespaceRequiredProperties: type: object required: - prefix - uri - schema_location NamespaceProperties: type: object title: Namespace properties: prefix: type: string description: Prefix or name of the namespace. example: iedu uri: type: string format: url description: URL associated with the namespace. example: http://www.sat.gob.mx/iedu schema_location: type: string format: url example: http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd description: URL of the XSD validation schema. CommonAddressProperties: type: object properties: street: type: string description: Street name example: Blvd. Atardecer exterior: type: string description: Exterior number. example: 142 interior: type: string description: Interior number. example: 4 neighborhood: type: string description: Neighborhood example: Centro city: type: string description: City example: Huatabampo municipality: type: string description: Municipality or delegation example: Huatabampo zip: type: string description: Postal code example: 86500 Webhook: title: Webhook object allOf: - $ref: '#/components/schemas/ResourceAutoGeneratedProps' - $ref: '#/components/schemas/WebhookProperties' WebhookSearchResult: allOf: - $ref: '#/components/schemas/SearchResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/Webhook' WebhookProperties: properties: organization: type: string description: | ID of the organization for which the webhook is being created. livemode: type: boolean example: false description: Environment in which the webhook is being created. enabled_events: type: string example: - receipt.cancellation_status description: Events enabled for the webhook to listen to. url: type: string format: email description: Full URL of the webhook listener. example: http://my-website.com/my/webhook status: type: string description: Status of the webhook. enum: - enabled - disabled example: enabled WebhookCreateInput: title: Webhook allOf: - type: object required: - enabled_events - url properties: url: type: string description: Full URL of the webhook listener. example: http://webhook_api.com enabled_events: type: array items: type: string enum: - invoice.global_invoice_created - invoice.status_updated - invoice.cancellation_status_updated - invoice.created_from_dashboard - receipt.self_invoice_complete - receipt.status_updated - receipt.cancellation_status_updated description: Events enabled for the webhook to listen to. example: - receipt.self_invoice_complete WebhookCreateEdit: title: Webhook allOf: - type: object required: - enabled_events properties: status: type: string description: Status of the webhook. enum: - disabled - enabled example: disabled enabled_events: type: array items: type: string enum: - invoice.global_invoice_created - invoice.status_updated - invoice.cancellation_status_updated - receipt.self_invoice_complete - receipt.status_updated - receipt.cancellation_status_updated description: Events enabled for the webhook to listen to. example: - receipt.self_invoice_complete Customer: title: Customer object allOf: - $ref: '#/components/schemas/ResourceAutoGeneratedProps' - $ref: '#/components/schemas/CustomerNonEditableProperties' - $ref: '#/components/schemas/CustomerProperties' CustomerNonEditableProperties: type: object properties: edit_link: type: string description: >- Link to a hosted page where the customer can edit their information once. example: https://auto.facturapi.io/tax-info/abcdWXYZ1234 edit_link_expires_at: type: string format: date-time description: Expiration date of the edit link. example: '2022-12-31T23:59:59Z' sat_validated_at: type: string format: date-time description: Date when the customer's tax information was validated by the SAT. example: '2022-12-31T23:59:59Z' CustomerSearchResult: allOf: - $ref: '#/components/schemas/SearchResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/Customer' CustomerProperties: allOf: - $ref: '#/components/schemas/CustomerCommonProperties' - type: object properties: address: allOf: - $ref: '#/components/schemas/CommonAddressProperties' - type: object description: Fiscal address. properties: state: type: string description: >- If the country is Mexico ("MEX"), it contains the name of the State or Federative Entity. For foreigners, it contains the State code according to the standard [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), which you can consult in our [State Catalog](https://dashboard.facturapi.io/catalogs/state). example: Sonora country: type: string description: >- Country code according to the standard [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3), from the [Country Catalog](https://dashboard.facturapi.io/catalogs/country). example: MEX default: MEX CustomerCommonProperties: type: object properties: legal_name: type: string description: > Legal name or business name of the customer. *without* the corporate regime (e.g.: S.A. de C.V.). example: Dunder Mifflin tax_id: type: string example: ABC101010111 description: > In Mexican clients, it contains the customer's RFC. For foreigners, it is optional and represents the tax identification number, that is, the equivalent to the RFC in the customer's country. tax_system: type: string example: '601' maxLength: 3 minLength: 3 description: > Required for national clients. Key of the customer's tax regime, from the [Tax Regime Catalog](#tax-regime). email: type: string format: email description: Email address to which to send the generated invoices. example: email@example.com phone: type: string description: Customer's phone number. example: 6474010101 default_invoice_use: type: string description: Default CFDI use for the customer. example: G01 CustomerCreateInput: title: Customer allOf: - $ref: '#/components/schemas/CustomerCommonProperties' - type: object required: - legal_name - tax_id - tax_system - address properties: address: allOf: - $ref: '#/components/schemas/CommonAddressProperties' - type: object description: Fiscal address. required: - zip properties: state: type: string description: >- If the country is Mexico ("MEX"), it contains the name of the State or Federative Entity. For foreigners, it contains the State code according to the standard [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), which you can consult in our [State Catalog](https://dashboard.facturapi.io/catalogs/state). example: Sonora country: type: string description: >- Country code according to the standard [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3), from the [Country Catalog](https://dashboard.facturapi.io/catalogs/country). example: MEX default: MEX LineItemProductInput: title: Product allOf: - $ref: '#/components/schemas/ProductProperties' LineItemProductEgresoInput: title: Product allOf: - $ref: '#/components/schemas/ProductEgresoProperties' LineItemTrasladoProductInput: title: Product required: - description type: object properties: description: type: string description: Description of the good or service as it will appear on the invoice. example: Ukelele product_key: type: string description: >- Key from the SAT catalog of products/services. We provide a more convenient way to find it using our [key search tool](https://dashboard.facturapi.io/catalogs/productKey). example: 60131324 unit_key: type: string default: H87 description: > Unit of measure key, from the SAT catalog. The default value `"H87"` (element) is the key to represent a piece or sales unit (pencil, notebook, television, etc). If the unit of your product is kilograms, liters, hours, or any other unit, we provide a convenient way to find the key using our [key search tool](https://dashboard.facturapi.io/catalogs/unit). unit_name: type: string default: Elemento description: > Name of the unit of measure that expresses the quantity. It must be related to the unit key `unit_key`. sku: type: string description: >- Internal identifier designated by the company. It can have any value. LineItemProduct: allOf: - type: object properties: id: type: string description: >- ID of the base product. Only present if a previously saved `Product` object was used as a base. example: 58e93bd8e86eb318b0197454 - $ref: '#/components/schemas/ProductProperties' Parts: type: object properties: description: type: string description: Description of the product or service. product_key: type: string description: >- Key from the SAT catalog of products/services. We provide a more convenient way to find it using our [key search tool](https://dashboard.facturapi.io/catalogs/productKey). quantity: type: number description: Quantity of the product or service. It must be greater than 0. example: 1 sku: type: string description: >- Internal identifier designated by the company. It can have any value. unit_price: type: number description: >- Unit price. This value will represent the price with or without VAT, depending on the value of `tax_included`. unit_name: type: string description: >- Name of the unit of measure used to express the quantity. It must be related to the unit key `unit_key`. customs_keys: type: array items: type: string description: Customs entry number (pedimento aduanal) associated with this part. PartInput: allOf: - type: object required: - description - product_key - $ref: '#/components/schemas/Parts' Product: title: Product object allOf: - $ref: '#/components/schemas/ResourceAutoGeneratedProps' - $ref: '#/components/schemas/ProductProperties' ProductSearchResult: allOf: - $ref: '#/components/schemas/SearchResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/Product' ProductProperties: type: object required: - description - product_key - unit_key - price properties: description: type: string description: Description of the good or service as it will appear on the invoice. example: Ukelele product_key: type: string description: >- Key from the SAT catalog of products/services. We provide a more convenient way to find it using our [key search tool](https://dashboard.facturapi.io/catalogs/productKey). example: 60131324 price: type: number description: > Price per unit of the good or service. This value will represent the price with or without VAT, depending on the value of `tax_included`. example: 345.6 tax_included: type: boolean default: true description: > - `true`: Indicates that all applicable taxes are included in the price (price attribute) and will be automatically broken down when the invoice is issued. - `false`: Indicates that the price attribute does not include taxes, so those taxes to be applied will be added to the final price. taxability: type: string default: '02' enum: - '01' - '02' - '03' - '04' - '05' - '06' - '07' - '08' description: > Code that represents whether the good or service is subject to tax or not. This attribute corresponds to the "ObjetoImp" field in the CFDI. - `01`: Not subject to tax. - `02`: Subject to tax. - `03`: Subject to tax, but not required to break down. - `04`: Subject to tax, but does not cause tax. - `05`: Subject to tax, VAT credit PODEBI. - `06`: Subect to tax IVA, but not IVA transferred. - `07`: Not Subject to tax IVA, but required IEPS breakdown. - `08`: Not Subject to tax IVA, and not required IEPS breakdown. taxes: type: array default: - type: IVA rate: 0.16 example: - type: IVA rate: 0.16 description: > List of taxes that must be applied to this product. Resolution when `taxes` is omitted or `null`: - `taxability` omitted or `"02"`: IVA (VAT) transferred 16% is added. - `taxability` in `"01"`, `"03"`, `"04"`, `"05"`, `"06"`, or `"08"`: `[]` is stored. - `taxability = "07"`: the request is invalid; you must provide at least one transferred IEPS tax and include no IVA taxes. If you send `taxes` explicitly, the provided array is used. items: $ref: '#/components/schemas/BaseTax' local_taxes: type: array description: Array of local taxes (state or municipal), if any. default: [] items: $ref: '#/components/schemas/LocalTax' unit_key: type: string default: H87 description: > Key of the unit of measure, from the SAT catalog. The default value `"H87"` (element) is the key to represent a piece or sales unit (pencil, notebook, television, etc). If the unit of your product is kilograms, liters, hours, or any other unit, we provide a convenient way to find the key using our [key search tool](https://dashboard.facturapi.io/catalogs/unit). unit_name: type: string default: Elemento description: >- Name of the unit of measure used to express the quantity. It must be related to the unit key `unit_key`. sku: type: string description: >- Internal identifier designated by the company. It can have any value. ProductEgresoProperties: type: object properties: description: type: string description: | Description of the operation in a single description. Each of the products that contemplate the discount, return, or bonus applied and that the related invoices contain must be mentioned. If the expense is based on a percentage (such as applying a 30% discount), that percentage must be included in the description along with the name of the corresponding product. example: Ukelele product_key: type: string default: 84111506 description: > Key from the SAT catalog of products/services. We provide a more convenient way to find it using our [key search tool](https://dashboard.facturapi.io/catalogs/productKey). example: 84111506 price: type: number description: | Total amount of the quantity returned, discounted, or bonified. example: 345.6 tax_included: type: boolean default: true description: > - `true`: Indicates that all applicable taxes are included in the price (price attribute) and will be automatically broken down when the invoice is issued. - `false`: Indicates that the price attribute does not include taxes, so those taxes to be applied will be added to the final price. taxability: type: string default: '02' enum: - '01' - '02' - '03' - '04' - '05' - '06' - '07' - '08' description: > Code that represents whether the good or service is subject to tax or not. This attribute corresponds to the "ObjetoImp" field in the CFDI. - `01`: Not subject to tax. - `02`: Subject to tax. - `03`: Subject to tax, but not required to break down. - `04`: Subject to tax, but does not cause tax. - `05`: Subject to tax, VAT credit PODEBI. taxes: type: array default: - type: IVA rate: 0.16 description: > List of taxes that must be applied to this product. Resolution when `taxes` is omitted or `null`: - `taxability` omitted or `"02"`: IVA (VAT) transferred 16% is added. - `taxability` in `"01"`, `"03"`, `"04"`, `"05"`, `"06"`, or `"08"`: `[]` is stored. - `taxability = "07"`: the request is invalid; you must provide at least one transferred IEPS tax and include no IVA taxes. If you send `taxes` explicitly, the provided array is used. items: $ref: '#/components/schemas/BaseTax' local_taxes: type: array description: Array of local taxes (state or municipal), if any. default: [] items: $ref: '#/components/schemas/LocalTax' unit_key: type: string default: ACT description: > Key of the unit of measure, from the SAT catalog. The default value `"ACT"` (activity) is the key to represent a generic activity. Check out all the available keys in our [unit search tool](https://dashboard.facturapi.io/catalogs/unit). unit_name: type: string default: Actividad description: >- Name of the unit of measure used to express the quantity. It must be related to the unit key `unit_key`. required: - description - price PaymentInput: title: Payment required: - payment_form - related_documents type: object properties: payment_form: type: string example: '03' description: >- Payment method code according to the [SAT catalog](#payment-method). You can also use the `PaymentForm` constant included in our libraries. related_documents: type: array description: > Array that includes an element for each related income document to this payment. The most common is that the payment is related to only one income document. A case in which more than one element is added is when a single deposit is received that covers the payment of 2 related invoices. Instead of issuing a payment receipt for each invoice, you must issue only one relating the 2 documents. items: type: object required: - uuid - amount - taxes - installment - last_balance properties: uuid: type: string format: uuid description: | Fiscal folio or UUID of the related income document. amount: type: number description: | Amount of the payment corresponding to the related document, using the payment method indicated in this element of the payment array. This value must be expressed in the currency defined in `related_documents[].currency`. taxes: type: array description: | Array with taxes of the related document that apply to the payment made. items: type: object required: - base - type - rate properties: base: type: number description: | Base amount used for the tax calculation. type: type: string enum: - IVA - ISR - IEPS description: | Type of tax. rate: type: number example: 0.16 description: | Rate of the tax. If the tax is a rate, this value must be expressed as a decimal fraction percentage. If the tax is a fixed amount, this value represents the amount of the tax. factor: type: string default: Tasa enum: - Tasa - Cuota - Exento description: | Factor type. - `Tasa`: Rate - `Cuota`: Fixed amount - `Exento`: Exempt withholding: type: boolean default: false description: >- Indicates if the tax is a withholding (`true`) or a transfer (`false`). taxability: type: string default: > "01" if the `taxes` array is empty; "02" if the `taxes` array has at least one element. enum: - '01' - '02' - '03' - '04' - '05' description: > Code representing whether the good or service is subject to tax or not. This attribute corresponds to the "ObjetoImp" field in the CFDI. - `01`: Not subject to tax. - `02`: Subject to tax. - `03`: Subject to tax, but not required to break down. - `04`: Subject to tax, but does not cause tax. - `05`: Subject to tax, VAT credit PODEBI. installment: type: integer description: | Installment number of the payment. last_balance: type: number description: > Amount that was pending before receiving this payment. This value must be expressed in the currency defined in `related_documents[].currency`. currency: type: string minLength: 3 maxLength: 3 default: MXN description: > Code of the currency used in the related document. If the currency used in the related document is not the national currency (MXN), its value must be specified according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number description: > Required when the currency of the related document is different from the payment currency. Exchange rate between the two currencies at the time of payment. Example: The related income invoice is registered in USD, while the current payment is made in MXN, this attribute should be registered as `0.45` (USD/MXN). folio_number: type: integer description: > Optional. You can include the folio number of the related document. series: type: string description: | Optional. You can include the series of the related document. currency: type: string minLength: 3 maxLength: 3 default: MXN description: > Code of the currency used in the payment. If the currency used in the payment is not the national currency (MXN), its value must be specified according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number default: 1 description: | Exchange rate of the currency used in the payment. It represents the number of Mexican pesos equivalent to one unit of the currency indicated in the `currency` attribute. date: type: string format: date-time default: now description: >- Date on which the payment was received. It is only necessary to include it if the payment was made on a date prior to the issuance of this document. Future dates are not allowed. numOperacion: type: string description: > Number of the check, authorization, reference, SPEI tracking key, capture line, or any reference number that allows identifying the operation corresponding to the payment made. rfcEmisorCtaOrd: type: string description: >- RFC of the entity issuing the source account, that is, the operator, bank, financial institution, issuer of electronic wallet, etc. nomBancoOrdExt: type: string description: Name of the ordering bank. ctaOrdenante: type: string description: Bank account number used to make the payment. rfcEmisorCtaBen: type: string description: >- RFC of the entity of the destination operating account, that is, the operator, bank, financial institution, issuer of electronic wallet, etc. ctaBeneficiario: type: string description: Bank account number where the payment was received. tipoCadPago: type: string enum: - 1 description: > Key of the type of payment chain generated by the receiving entity of the payment. If this field exists, it is mandatory to register the `certPago`, `cadPago`, and `selloPago` fields. certPago: type: string format: base64 description: > Certificate that corresponds to the payment, expressed as a text string in base 64 format. cadPago: type: string description: > Original string (cadena original) of the payment receipt generated by the entity issuing the beneficiary account. selloPago: type: string format: base64 description: > Digital seal associated with the payment expressed as a text string in base 64 format. CustomerInfo: type: object description: > Object with partial information of the customer receiving the document. To obtain the complete `Customer` object, you must consult it with the [Retrieve Customer]('#/operation/getCustomer') method. properties: id: type: string description: >- ID of the `customer` object related to the invoice, in case it has not been deleted. example: 58e93bd8e86eb318b0197456 legal_name: type: string description: > Legal name or business name of the customer. *without* the corporate regime (e.g.: S.A. de C.V.). example: Dunder Mifflin tax_id: type: string description: > In Mexican clients, it contains the customer's RFC. For foreigners, it is optional and represents the tax identification number, that is, the equivalent to the RFC in the customer's country. example: ABC101010111 address: type: object properties: country: type: string format: ISO 3166-1 alpha-3 description: >- Country code according to the standard [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3). example: MEX CustomerComercioExterior: type: object description: >- Objeto con información parcial del cliente receptor del comprobante. Para obtener el objeto `Customer` completo, deberás consultarlo con el método de [Obtener Cliente]('#/operation/getCustomer'). properties: id: type: string description: >- ID del objeto `customer` relacionado a la factura, en caso de no haber sido eliminado example: 58e93bd8e86eb318b0197456 RelatedDocumentInput: allOf: - type: object required: - relationship - related - $ref: '#/components/schemas/RelatedDocument' RelatedDocument: type: object properties: relationship: type: string description: > Relationship key from the SAT catalog (which you can consult in [this table](#relacion-entre-facturas)). It is required when the `related_documents` parameter is sent. documents: type: array default: [] items: type: string description: Fiscal folios (UUID) of related invoices. Invoice: title: Invoice object allOf: - $ref: '#/components/schemas/ResourceAutoGeneratedProps' - $ref: '#/components/schemas/InvoiceProperties' InvoiceDraft: title: Invoice object with draft status allOf: - $ref: '#/components/schemas/ResourceAutoGeneratedProps' - $ref: '#/components/schemas/InvoiceDraftProperties' InvoiceSearchResult: allOf: - $ref: '#/components/schemas/SearchResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/Invoice' InvoiceRequiredProperties: type: object required: - description - invoice_key - price InvoiceProperties: type: object properties: status: type: string enum: - pending - valid - canceled - draft description: | Current status of the invoice. example: valid cancellation_status: type: string enum: - none - verifying - pending - accepted - rejected - expired description: > Current status of the cancellation request, if it has been made. `verifying` means the SAT has received the request and is validating it; Facturapi will keep checking until it changes to a final status. You can read more in the [Cancel Invoice](#tag/invoice/operation/deleteInvoice) section. example: none canceled_at: type: string format: date-time description: Date on which CFDI was canceled, with approximate time. verification_url: type: string format: uri description: >- URL to verify the status of the CFDI on the SAT portal. This link is the same as the one that appears in the QR code on the invoice PDF. example: >- https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw== date: type: string format: date-time default: now description: | Date of issuance of the invoice in ISO8601 format (UTC String). address: allOf: - $ref: '#/components/schemas/CommonAddressProperties' - type: object description: Address where the invoice was issued. properties: state: type: string description: >- If the country is Mexico ("MEX"), it contains the name of the State or Federative Entity. For foreigners, it contains the State code according to the standard [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), which you can consult in our [State Catalog](https://dashboard.facturapi.io/catalogs/state). example: Sonora type: type: string enum: - I - E - P - 'N' - T description: > Type of document. It can have the values `"I"`: Income, `"P"`: Payment, `"E"`: Egress, `"N"`: Payroll, `"T"`: Transfer. customer: $ref: '#/components/schemas/CustomerInfo' total: type: number description: Total amount invoiced. example: 10944.82 uuid: type: string format: uuid description: Fiscal folio of the invoice, assigned by the SAT. example: 39c85a3f-275b-4341-b259-e8971d9f8a94 folio_number: type: integer description: >- Autoincremental folio number for internal control and without fiscal relevance. example: 914 series: type: string description: >- Series. Alphanumeric characters designated by the company for internal control and without fiscal relevance. In the PDF, it is printed next to the folio number. example: F external_id: type: string description: >- Identifier that you can use to relate this invoice to your records to later search by this number. idempotency_key: type: string description: >- Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. payment_form: type: string description: >- Payment form code according to the [Payment Form catalog](#payment-form). example: 6 total_payment_amount: type: number description: Total amount of the Payment complement when the invoice is type P. total_payment_amount_converted: type: number description: >- Total amount paid converted from the payment currency to Mexican Pesos. is_ready_to_stamp: type: boolean description: > This field is automatically assigned by Facturapi. It indicates if an invoice with status `draft` is complete and ready to be stamped. If the value is `true`, you can try to stamp the invoice with the [Stamp Invoice]('#/operation/stampInvoice') method. If the value is `false`, you must use the [Update Invoice]('#/operation/updateDraftInvoice') method to complete the missing fields. In an invoice with a status other than `draft`, this field will always be `false`. items: type: array description: Concepts included in the document. items: $ref: '#/components/schemas/LineItem' related_documents: type: array description: Documents related to the invoice. items: $ref: '#/components/schemas/RelatedDocument' received_payment_ids: type: array items: type: string description: > On invoices with type I (Income) and payment method PPD, this field lists the object IDs of the payment invoices whose related documents array includes the UUID of this invoice. This field is filled in by Facturapi the moment the payment invoice (type P) is created or imported, as long as it belongs to the same organization. default: [] target_invoice_ids: type: array items: type: string description: > On invoices with type P (Payment), this array lists the object IDs of the invoices listed in the related documents array. This field is filled in by Facturapi as long as the related invoice is also registered in Facturapi and belongs to the same organization. default: [] currency: type: string example: MXN description: >- Currency code, according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number minimum: 0 example: 1 description: >- Exchange rate for the currency used. It represents the number of Mexican pesos (MXN) equivalent to one unit of the currency indicated in the `currency` attribute. complements: type: array default: [] items: $ref: '#/components/schemas/NominaOrCustomComplementProperties' description: Complements to include in the invoice. pdf_custom_section: type: string format: html description: >- In case you need to include more information in the PDF, this field allows you to insert HTML code with your own content. addenda: type: string format: xml description: XML code with the Addenda that needs to be added to the invoice. namespaces: type: array description: >- Namespaces to insert in the root node of the invoice. Required for `addenda`. items: $ref: '#/components/schemas/NamespaceProperties' stamp: $ref: '#/components/schemas/Stamp' InvoiceDraftProperties: type: object properties: status: type: string enum: - pending - valid - canceled - draft description: | Current status of the invoice. example: draft cancellation_status: type: string enum: - none - verifying - pending - accepted - rejected - expired description: > Current status of the cancellation request, if it has been made. `verifying` means the SAT has received the request and is validating it; Facturapi will keep checking until it changes to a final status. You can read more in the [Cancel Invoice](#tag/invoice/operation/deleteInvoice) section. example: none verification_url: type: string format: uri description: >- URL to verify the status of the CFDI on the SAT portal. This link is the same as the one that appears in the QR code on the invoice PDF. example: null date: type: string format: date-time example: null description: > Date of issuance of the invoice in ISO8601 format (UTC String). If the status is `draft`, this field is null. address: allOf: - $ref: '#/components/schemas/CommonAddressProperties' - type: object description: Address where the invoice was issued. properties: state: type: string description: >- If the country is Mexico ("MEX"), it contains the name of the State or Federative Entity. For foreigners, it contains the State code according to the standard [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), which you can consult in our [State Catalog](https://dashboard.facturapi.io/catalogs/state). example: Sonora type: type: string enum: - I - E - P - 'N' - T description: > Type of document. It can have the values `"I"`: Income, `"P"`: Payment, `"E"`: Egress, `"N"`: Payroll, `"T"`: Transfer. customer: $ref: '#/components/schemas/CustomerInfo' total: type: number description: Total amount invoiced. example: 0 uuid: type: string format: uuid description: >- Fiscal folio of the invoice, assigned by the SAT. If the invoice has not been stamped, this field is null. example: 0 folio_number: type: integer description: >- Autoincremental folio number for internal control and without fiscal relevance. example: 914 series: type: string description: >- Series. Alphanumeric characters designated by the company for internal control and without fiscal relevance. In the PDF, it is printed next to the folio number. example: F external_id: type: string description: >- Identifier that you can use to relate this invoice to your records to later search by this number. idempotency_key: type: string description: >- Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. payment_form: type: string description: >- Payment form code according to the [Payment Form catalog](#forma-de-pago). example: 6 items: type: array description: Concepts included in the document. items: $ref: '#/components/schemas/LineItem' related_documents: type: array description: Documents related to the invoice. items: $ref: '#/components/schemas/RelatedDocument' currency: type: string example: MXN description: >- Currency code, according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number minimum: 0 example: 1 description: >- Exchange rate for the currency used. It represents the number of Mexican pesos (MXN) equivalent to one unit of the currency indicated in the `currency` attribute. complements: type: array default: [] items: $ref: '#/components/schemas/NominaOrCustomComplementProperties' description: Complements to include in the invoice. pdf_custom_section: type: string format: html description: >- In case you need to include more information in the PDF, this field allows you to insert HTML code with your own content. addenda: type: string format: xml description: XML code with the Addenda that needs to be added to the invoice. namespaces: type: array description: >- Namespaces to insert in the root node of the invoice. Required for `addenda`. items: $ref: '#/components/schemas/NamespaceProperties' is_ready_to_stamp: type: boolean description: > This field is automatically assigned by Facturapi. It indicates if an invoice with status `draft` is complete and ready to be stamped. If the value is `true`, you can try to stamp the invoice with the [Stamp Invoice]('#/operation/stampInvoice') method. If the value is `false`, you must use the [Update Invoice]('#/operation/updateDraftInvoice') method to complete the missing fields. In an invoice with a status other than `draft`, this field will always be `false`. stamp: allOf: - $ref: '#/components/schemas/Stamp' - type: object example: null InvoiceableCommonInput: type: object properties: folio_number: type: integer default: autoincremental description: > Number of folio assigned by the company for internal control. If omitted, the autoincremental value of the organization will be assigned. series: type: string maxLength: 25 description: >- Series. Aplanumeric characters designated by the company for internal control and without fiscal relevance. pdf_custom_section: type: string format: xml description: > In case you need to include more information in the PDF, this field allows you to insert HTML code with your own content. For security reasons, the code you can send is limited to the following tags: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `div`, `p`, `span`, `small`, `br`, `b`, `i`, `ul`, `ol`, `li`, `strong`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, and `td`. Attributes and styles are not allowed. addenda: type: string format: xml description: XML code with the Addenda that needs to be added to the invoice. namespaces: type: array default: [] description: > If you included the `complements` parameter, this field is optional; however, if you included the `addenda` parameter, you must send the necessary information to include these namespaces in the XML document. items: allOf: - $ref: '#/components/schemas/NamespaceRequiredProperties' - $ref: '#/components/schemas/NamespaceProperties' pdf_options: type: object description: > Configure which optional fields you want to show in the PDF. The SAT does not require showing these fields, but they can be activated according to the customer's preference for the current invoice. Use this field for invoice generation requests in which you need to use a different configuration than the pdf_extra field of the organization. properties: codes: type: boolean default: true description: > Show SAT catalog codes next to their descriptions. Example: "KGM Kilogramo". product_key: type: boolean default: true description: | Show the product/service key. address_codes: type: boolean default: true description: | Show standardized state and country codes in the PDF. export_key: type: boolean default: false description: | Show the export key in the PDF. round_unit_price: type: boolean default: false description: > Round the unit price in the PDF to 2 decimals, but keep the 6 decimals in the XML. tax_breakdown: type: boolean default: true description: > Show the tax breakdown in the PDF. If disabled, only the taxes will be shown in the totals, but not in the detail of each concept. ieps_breakdown: type: boolean default: true description: > Show the IEPS breakdown in the PDF. If disabled, only the taxes related to the IVA (VAT) will be shown in the subtotal. combine_ieps_with_subtotal: type: boolean default: false description: | Add IEPS to the subtotal without breaking it down in the PDF. render_carta_porte: type: boolean default: false description: | Render the Carta Porte 3.1 Complement in the pdf. render_iedu: type: boolean default: false description: | Render the Private Education Institutions complement in the PDF. render_hyp_complement: type: boolean default: false description: | Render the hydrocarbons and petroleum complement in the PDF. render_comercio_exterior: type: boolean default: false description: | Render the foreign trade complement in the PDF. repeat_signature: type: boolean default: false description: | Repeat the digital signature on each page of the PDF. payroll_options: type: object properties: tipo_contrato: type: boolean default: false puesto: type: boolean default: false riesgo_puesto: type: boolean default: false antiguedad: type: boolean default: false InvoiceableCommonEditInput: type: object properties: folio_number: type: integer description: > Folio number assigned by the company for internal control. If omitted, the autoincremental value of the organization will be assigned. This field does not have any fiscal relevance. series: type: string maxLength: 25 description: >- Series. Alphanumeric characters designated by the company for internal control and without fiscal relevance. pdf_custom_section: type: string format: xml description: > In case you need to include more information in the PDF, this field allows you to insert HTML code with your own content. For security reasons, the code you can send is limited to the following tags: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `div`, `p`, `span`, `small`, `br`, `b`, `i`, `ul`, `ol`, `li`, `strong`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, and `td`. Attributes and styles are not allowed. addenda: type: string format: xml description: XML code with the Addendum to add to the invoice. namespaces: type: array description: > If you included the `complements` parameter, this field is optional; however, if you included the `addenda` parameter, you must send the necessary information to include these namespaces in the XML document. items: allOf: - $ref: '#/components/schemas/NamespaceRequiredProperties' - $ref: '#/components/schemas/NamespaceProperties' pdf_options: type: object description: > Configure which optional fields you want to show in the PDF. The SAT does not require showing these fields, but they can be activated according to the customer's preference for the current invoice. Use this field for invoice generation requests in which you need to use a different configuration than the pdf_extra field of the organization. properties: codes: type: boolean default: true description: > Show SAT catalog codes next to their descriptions. Example: "KGM Kilogramo". product_key: type: boolean default: true description: | Show the product/service key. address_codes: type: boolean default: true description: | Show standardized state and country codes in the PDF. export_key: type: boolean default: false description: | Show the export key in the PDF. round_unit_price: type: boolean default: false description: > Round the unit price in the PDF to 2 decimals, but keep the 6 decimals in the XML. tax_breakdown: type: boolean default: true description: > Show the tax breakdown in the PDF. If disabled, only the taxes will be shown in the totals, but not in the detail of each concept. ieps_breakdown: type: boolean default: true description: > Show the IEPS breakdown in the PDF. If disabled, only the taxes related to the IVA (VAT) will be shown in the subtotal. combine_ieps_with_subtotal: type: boolean default: false description: | Add IEPS to the subtotal without breaking it down in the PDF. render_carta_porte: type: boolean default: false description: | Render the Carta Porte 3.1 Complement in the pdf. render_iedu: type: boolean default: false description: | Render the Private Education Institutions complement in the PDF. render_hyp_complement: type: boolean default: false description: | Render the hydrocarbons and petroleum complement in the PDF. render_comercio_exterior: type: boolean default: false description: | Render the foreign trade complement in the PDF. repeat_signature: type: boolean default: false description: | Repeat the digital signature on each page of the PDF. payroll_options: type: object properties: tipo_contrato: type: boolean default: false puesto: type: boolean default: false riesgo_puesto: type: boolean default: false antiguedad: type: boolean default: false InvoiceCommonInputProperties: allOf: - type: object properties: customer: description: Customer receiving the invoice. oneOf: - $ref: '#/components/schemas/CustomerCreateInput' - type: string title: customer_id description: >- ID of the `customer` object previously registered in Facturapi. example: 58e93bd8e86eb318b0197456 status: type: string enum: - pending - draft default: pending description: > Initial status of the invoice. If `draft` is sent, the invoice will be saved as a draft and will not be stamped or sent to the SAT. Also, when sending `draft`, all required fields become optional. If omitted, the default status is `pending` and once stamped (in the response) this field will be updated to `valid`. For asynchronous invoices, this field will remain `pending` until the invoice is stamped. example: draft date: type: string format: date-time default: now description: > Date of issuance of the invoice in ISO8601 format (UTC String). It cannot be earlier than 72 hours in the past, nor later than the present. address: allOf: - $ref: '#/components/schemas/CommonAddressProperties' - type: object description: > You can use this parameter to specify the address where the invoice was issued. This field is optional and if not sent, the invoice will be issued with the address of the organization. required: - zip properties: state: type: string description: >- If the country is Mexico ("MEX"), this field should contain the name of the State or Federative Entity. For foreigners, it should contain the State code according to the standard [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), which you can consult in our [State Catalog](https://dashboard.facturapi.io/catalogs/state). example: Sonora external_id: type: string description: > Optional identifier that you can use to relate this invoice to your records and later search by this number. Facturapi does not validate that this field is unique. idempotency_key: type: string description: > Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. If left blank, it will not be taken into account. - $ref: '#/components/schemas/InvoiceableCommonInput' InvoiceCommonEditInputProperties: allOf: - type: object properties: customer: description: Customer receiving the invoice. oneOf: - $ref: '#/components/schemas/CustomerCreateInput' - type: string title: customer_id description: >- ID of the `Customer` object previously registered in Facturapi. example: 58e93bd8e86eb318b0197456 status: type: string enum: - draft description: > Initial status of the invoice. It is only possible to edit an invoice with status `draft`, and it is not possible to change the status when editing, so the only allowed value is `draft`. example: draft date: type: string format: date-time description: > Date of issuance of the invoice in ISO8601 format (UTC String). It cannot be earlier than 72 hours in the past, nor later than the present. address: allOf: - $ref: '#/components/schemas/CommonAddressProperties' - type: object description: > You can use this parameter to specify the address where the invoice was issued. This field is optional and if not sent, the invoice will be issued with the address of the organization. required: - zip properties: state: type: string description: >- If the country is Mexico ("MEX"), this field should contain the name of the State or Federative Entity. For foreigners, it should contain the State code according to the standard [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), which you can consult in our [State Catalog](https://dashboard.facturapi.io/catalogs/state). example: Sonora external_id: type: string description: > Optional identifier that you can use to relate this invoice to your records and later search by this number. Facturapi does not validate that this field is unique. idempotency_key: type: string description: > Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. If left blank, it will not be taken into account. - $ref: '#/components/schemas/InvoiceableCommonEditInput' InvoiceCreateInput: type: object oneOf: - title: Income discriminator: propertyName: status mapping: pending: '#/components/schemas/InvoiceIngresoInput' draft: '#/components/schemas/InvoiceIngresoEditInput' - title: Egress discriminator: propertyName: status mapping: pending: '#/components/schemas/InvoiceEgresoInput' draft: '#/components/schemas/InvoiceEgresoEditInput' - title: Payment discriminator: propertyName: status mapping: pending: '#/components/schemas/InvoicePagoInput' draft: '#/components/schemas/InvoicePagoEditInput' - title: Payroll discriminator: propertyName: status mapping: pending: '#/components/schemas/InvoiceNominaInput' draft: '#/components/schemas/InvoiceNominaEditInput' - title: Transfer discriminator: propertyName: status mapping: pending: '#/components/schemas/InvoiceTrasladoInput' draft: '#/components/schemas/InvoiceTrasladoEditInput' InvoiceIngresoInput: title: Income required: - customer - items - payment_form - use allOf: - type: object properties: type: type: string enum: - I default: I description: | Type of document. The default value is `“I”` (Income). items: type: array maxItems: 5000 description: > Concepts to include in the invoice. The maximum number of elements that you can include in an invoice is 5,000. If you need to issue an invoice with more than 5,000 concepts, you can divide the transaction into several invoices. items: $ref: '#/components/schemas/LineItemInput' payment_form: type: string minLength: 2 maxLength: 2 example: '03' description: >- Código que representa la forma de pago, de acuerdo al [catálogo del SAT](#forma-de-pago). payment_method: type: string default: PUE enum: - PUE - PPD description: > Code of the payment method according to the SAT catalog. - `PUE`: Payment in One Installment (paid in full at the time of the transaction) - `PPD`: Payment in Installments or Deferred (partial or deferred payment) use: type: string default: G01 description: > Code of Use of CFDI according to the SAT catalog. You can see the codes in [this table](#uso-cfdi), or use the constants included in our libraries. For global invoices you must use the code `S01`. currency: type: string default: MXN description: >- Currency code, according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number default: 1 description: | Exchange rate according to the currency used. It represents the number of Mexican pesos (MXN) equivalent to one unit of the currency indicated in the `currency` attribute. conditions: type: string minLength: 1 maxLength: 1000 description: >- Payment conditions. Free text field usually used to specify payment terms, such as the due date. example: 'Fecha límite de pago: 28/feb/2025' related_documents: type: array description: Documents related to the invoice. default: [] items: $ref: '#/components/schemas/RelatedDocumentInput' global: type: object required: - periodicity - months - year description: | Required object when creating a global invoice. properties: periodicity: type: string description: | Periodicity the global invoice covers. - `day`: Daily - `week`: Weekly - `fortnight`: Every half month (quincena) - `month`: Monthly - `two_months`: Once every two months enum: - day - week - fortnight - month - two_months months: type: string description: > Key representing the month or bimester of the invoice. Consult the possible values in the [Months and Bimesters catalog](#meses-y-bimestres). example: '01' year: type: integer description: Year of the invoice. example: 2022 export: type: string default: '01' enum: - '01' - '02' - '03' - '04' description: > Indicates if the invoice covers an export operation. - `01`: Not applicable - `02`: Definitive with key A1 - `03`: Temporary - `04`: Definitive with key different from A1 or when there is no sale in terms of the CFF complements: type: array default: [] items: $ref: '#/components/schemas/CartaPorteOrCustomComplementInput' description: > Complements to include in the invoice. You can include any complement in the invoice if you build the XML node of the complement yourself and use the `custom` type. It is necessary to add the complement information to the PDF separately using the `pdf_custom_section` parameter. - $ref: '#/components/schemas/InvoiceCommonInputProperties' InvoiceEgresoInput: title: Egress allOf: - type: object required: - type - customer - payment_form - items properties: type: type: string enum: - E payment_form: type: string minLength: 2 maxLength: 2 example: '03' description: >- Payment form code according to the [Payment Form catalog](#forma-de-pago). related_documents: type: array description: | Documents related to the credit note. default: [] items: $ref: '#/components/schemas/RelatedDocumentInput' items: type: array maxItems: 5000 description: > Concepts to include in the credit note. The maximum number of elements that you can include in a document is 5,000. If you need to issue a document with more than 5,000 concepts, you can divide the transaction into several documents. items: $ref: '#/components/schemas/LineItemEgresoInput' use: type: string default: G01 description: > Code of Use of CFDI according to the SAT catalog. You can see the codes in [this table](#uso-cfdi), or use the constants included in our libraries. currency: type: string default: MXN description: >- Currency code, according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number default: 1 description: | Exchange rate according to the currency used. It represents the number of Mexican pesos (MXN) equivalent to one unit of the currency indicated in the `currency` attribute. complements: type: array default: [] items: $ref: '#/components/schemas/CustomComplementInput' description: > Complements to include in the credit note. You can include any complement in the credit note if you build the XML node of the complement yourself and use the `custom` type. It is necessary to add the complement information to the PDF separately using the `pdf_custom_section` parameter. - $ref: '#/components/schemas/InvoiceCommonInputProperties' InvoicePagoInput: title: Payment allOf: - type: object required: - type - customer - complements properties: type: type: string enum: - P related_documents: type: array description: Documents related to the invoice. default: [] items: $ref: '#/components/schemas/RelatedDocumentInput' third_party: allOf: - type: object required: - legal_name - tax_id - tax_system - zip - $ref: '#/components/schemas/ThirdParty' complements: type: array default: [] items: $ref: '#/components/schemas/PagoOrCustomComplementInput' description: Complements to include in the invoice. - $ref: '#/components/schemas/InvoiceCommonInputProperties' InvoiceNominaInput: title: Payroll allOf: - type: object required: - type - customer - complements properties: type: type: string enum: - 'N' complements: type: array default: [] items: $ref: '#/components/schemas/NominaOrCustomComplementInput' description: Complements to include in the invoice. related_documents: type: array description: Documents related to the invoice. default: [] items: $ref: '#/components/schemas/RelatedDocumentInput' - $ref: '#/components/schemas/InvoiceCommonInputProperties' InvoiceTrasladoInput: title: Transfer allOf: - type: object required: - type - items - customer properties: type: type: string enum: - T items: type: array maxItems: 5000 description: > Concepts to include in the Transfer invoice. The maximum number of elements that you can include in an invoice is 5,000. If you need to issue an invoice with more than 5,000 concepts, you can divide the transaction into several invoices. items: $ref: '#/components/schemas/LineItemTrasladoInput' complements: type: array default: [] items: $ref: '#/components/schemas/CartaPorteOrCustomComplementInput' description: > Complements to include in the invoice. You can include any complement in the invoice if you build the XML node of the complement yourself and use the `custom` type. It is necessary to add the complement information to the PDF separately using the `pdf_custom_section` parameter. use: type: string default: G01 description: > Code of Use of CFDI according to the SAT catalog. You can see the codes in [this table](#uso-cfdi), or use the constants included in our libraries. currency: type: string default: MXN description: >- Currency code, according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number default: 1 description: | Exchange rate according to the currency used. It represents the number of Mexican pesos (MXN) equivalent to one unit of the currency indicated in the `currency` attribute. related_documents: type: array description: Documents related to the invoice. default: [] items: $ref: '#/components/schemas/RelatedDocumentInput' - $ref: '#/components/schemas/InvoiceCommonInputProperties' InvoiceIngresoEditInput: title: Income allOf: - type: object properties: type: type: string enum: - I - E - P - 'N' - T description: > Type of document. It can have the values `"I"`: Income, `"P"`: Payment, `"E"`: Egress, `"N"`: Payroll, `"T"`: Transfer. items: type: array maxItems: 5000 description: > Concepts to include in the invoice. The maximum number of elements that you can include in an invoice is 5,000. If you need to issue an invoice with more than 5,000 concepts, you can divide the transaction into several invoices. items: $ref: '#/components/schemas/LineItemInput' payment_form: type: string minLength: 2 maxLength: 2 example: '03' description: >- Payment form code according to the [Payment Form catalog](#forma-de-pago). payment_method: type: string enum: - PUE - PPD description: > Code of the payment method according to the SAT catalog. - `PUE`: Payment in One Installment (paid in full at the time of the transaction) - `PPD`: Payment in Installments or Deferred (partial or deferred payment) use: type: string example: G01 description: > Code of Use of CFDI according to the SAT catalog. You can see the codes in [this table](#uso-cfdi), or use the constants included in our libraries. For global invoices you must use the code `S01`. currency: type: string example: MXN description: >- Currency code, according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number description: > Echange rate for the currency used. It represents the number of pesos mexicanos (MXN) equivalent to one unit of the currency indicated in the `currency`. conditions: type: string minLength: 1 maxLength: 1000 description: >- Payment conditions. Free text field usually used to specify payment terms, such as the due date. example: 'Fecha límite de pago: 28/feb/2025' related_documents: type: array description: Documents related to the invoice. items: $ref: '#/components/schemas/RelatedDocumentInput' global: type: object required: - periodicity - months - year description: | Object required when creating a global invoice. properties: periodicity: type: string description: | Periodicity the global invoice covers. - `day`: Daily - `week`: Weekly - `fortnight`: Every half month (quincena) - `month`: Monthly - `two_months`: Once every two months enum: - day - week - fortnight - month - two_months months: type: string description: > Key representing the month or bimester of the invoice. Consult the possible values in the [Months and Bimesters catalog](#meses-y-bimestres). example: '01' year: type: integer description: Year of the invoice. example: 2022 export: type: string enum: - '01' - '02' - '03' - '04' description: > Indicates if the invoice covers an export operation. - `01`: Not applicable - `02`: Definitive with key A1 - `03`: Temporary - `04`: Definitive with key different from A1 or when there is no sale in terms of the CFF complements: type: array items: $ref: '#/components/schemas/CustomComplementInput' description: > Complements to include in the invoice. You can include any complement in the invoice if you build the XML node of the complement yourself and use the `custom` type. It is necessary to add the complement information to the PDF separately using the `pdf_custom_section` parameter. - $ref: '#/components/schemas/InvoiceCommonEditInputProperties' InvoiceEgresoEditInput: title: Egress allOf: - type: object properties: type: type: string enum: - I - E - P - 'N' - T description: > Type of document. It can have the values `"I"`: Income, `"P"`: Payment, `"E"`: Egress, `"N"`: Payroll, `"T"`: Transfer. payment_form: type: string minLength: 2 maxLength: 2 example: '03' description: >- Payment form code according to the [Payment Form catalog](#forma-de-pago). related_documents: type: array description: | Documents related to the credit note. items: $ref: '#/components/schemas/RelatedDocumentInput' items: type: array maxItems: 5000 description: > Concepts to include in the credit note. The maximum number of elements that you can include in a document is 5,000. If you need to issue a document with more than 5,000 concepts, you can divide the transaction into several documents. items: $ref: '#/components/schemas/LineItemEgresoInput' use: type: string example: G01 description: > Code of Use of CFDI according to the SAT catalog. You can see the codes in [this table](#uso-cfdi), or use the constants included in our libraries. currency: type: string example: MXN description: >- Currency code, according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number description: > Exchange rate according to the currency used. It represents the number of pesos mexicanos (MXN) equivalent to one unit of the currency indicated in the `currency`. complements: type: array items: $ref: '#/components/schemas/CustomComplementInput' description: > Complements to include in the credit note. You can include any complement in the credit note if you build the XML node of the complement yourself and use the `custom` type. It is necessary to add the complement information to the PDF separately using the `pdf_custom_section` parameter. - $ref: '#/components/schemas/InvoiceCommonInputProperties' InvoicePagoEditInput: title: Payment allOf: - type: object properties: type: type: string enum: - I - E - P - 'N' - T description: > Type of document. It can have the values `"I"`: Income, `"P"`: Payment, `"E"`: Egress, `"N"`: Payroll, `"T"`: Transfer. related_documents: type: array description: Documents related to the invoice. items: $ref: '#/components/schemas/RelatedDocumentInput' third_party: allOf: - type: object required: - legal_name - tax_id - tax_system - zip - $ref: '#/components/schemas/ThirdParty' complements: type: array items: $ref: '#/components/schemas/PagoOrCustomComplementInput' description: Complements to include in the invoice. - $ref: '#/components/schemas/InvoiceCommonEditInputProperties' InvoiceNominaEditInput: title: Payroll allOf: - type: object properties: type: type: string enum: - I - E - P - 'N' - T description: > Type of document. It can have the values `"I"`: Income, `"P"`: Payment, `"E"`: Egress, `"N"`: Payroll, `"T"`: Transfer. complements: type: array items: $ref: '#/components/schemas/NominaOrCustomComplementInput' description: Complements to include in the invoice. related_documents: type: array description: Documents related to the invoice. items: $ref: '#/components/schemas/RelatedDocumentInput' - $ref: '#/components/schemas/InvoiceCommonEditInputProperties' InvoiceTrasladoEditInput: title: Transfer allOf: - type: object properties: type: type: string enum: - I - E - P - 'N' - T description: > Type of document. It can have the values `"I"`: Income, `"P"`: Payment, `"E"`: Egress, `"N"`: Payroll, `"T"`: Transfer. items: type: array maxItems: 5000 description: > Concepts to include in the Transfer invoice. The maximum number of elements that you can include in an invoice is 5,000. If you need to issue an invoice with more than 5,000 concepts, you can divide the transaction into several invoices. items: $ref: '#/components/schemas/LineItemTrasladoInput' complements: type: array items: $ref: '#/components/schemas/CustomComplementInput' description: > Complements to include in the invoice. You can include any complement in the invoice if you build the XML node of the complement yourself and use the `custom` type. It is necessary to add the complement information to the PDF separately using the `pdf_custom_section` parameter. use: type: string example: G01 description: > Code of Use of CFDI according to the SAT catalog. You can see the codes in [this table](#uso-cfdi), or use the constants included in our libraries. currency: type: string example: MXN description: >- Currency code, according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number description: > Exchange rate for the currency used. It represents the number of pesos mexicanos (MXN) equivalent to one unit of the currency indicated in the `currency` attribute. related_documents: type: array description: Documents related to the invoice. items: $ref: '#/components/schemas/RelatedDocumentInput' - $ref: '#/components/schemas/InvoiceCommonEditInputProperties' Receipt: title: Receipt object allOf: - $ref: '#/components/schemas/ResourceAutoGeneratedProps' - $ref: '#/components/schemas/ReceiptProperties' ReceiptProperties: allOf: - type: object properties: date: type: string format: date-time example: '2021-09-10T15:21:23.456Z' description: | Date of issuance of the receipt in ISO8601 format (UTC String). expires_at: type: string format: date-time example: '2021-09-17T15:21:23.456Z' description: > Expiration date in ISO8601 format (UTC String). It is the deadline for the customer to invoice their receipt on the autofactura portal. It is calculated automatically from the organization's receipt settings. status: type: string enum: - open - canceled - invoiced_to_customer - invoiced_globally description: Estado actual del recibo. self_invoice_url: type: string format: url example: https://factura.space/empresa-demo/r9YqYarL description: > URL to the self-invoice portal. It includes the `key` of the receipt. You can use it to generate a button or a QR code for your customers to invoice their receipts. total: type: number example: 356.78 description: Total amount of the operation invoice: type: string example: 614496b471d422de4b6cfcc4 description: ID of the associated invoice, if invoiced. customer: type: string example: 58e93bd8e86eb318b0197456 description: ID of the customer associated to the receipt, if assigned. key: type: string example: r9YqYarL description: > Auto-generated. Short alphanumeric unique identifier, useful for accessing the self-invoice from your microsite on factura.space. items: type: array description: | Sale items included in the receipt. items: $ref: '#/components/schemas/LineItem' external_id: type: string description: > Optional identifier that you can use to relate this receipt to your records and later search by this number. Facturapi does not validate that this field is unique. idempotency_key: type: string description: > Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. If left blank, it will not be taken into account. - $ref: '#/components/schemas/ReceiptEditableProperties' ReceiptInput: allOf: - type: object required: - items - payment_form properties: customer: description: > Customer associated to the receipt. You can send the ID of an existing customer or a customer object to create it. oneOf: - type: string minLength: 24 maxLength: 24 example: 58e93bd8e86eb318b0197456 - $ref: '#/components/schemas/CustomerCreateInput' items: type: array maxItems: 5000 description: > Concepts to include in the receipt. The maximum number of elements that you can include in a receipt is 5,000. If you need to issue a receipt with more than 5,000 concepts, you can divide the transaction into several receipts. items: $ref: '#/components/schemas/LineItemInput' - $ref: '#/components/schemas/ReceiptEditableProperties' - type: object properties: idempotency_key: type: string description: > Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. If left blank, it will not be taken into account. ReceiptEditableProperties: type: object properties: date: type: string format: date-time example: '2021-09-10T15:21:23.456Z' description: | Date of issuance of the receipt in ISO8601 format (UTC String). payment_form: type: string example: '03' description: >- Payment form code according to the [Payment Form catalog](#forma-de-pago). folio_number: type: integer example: 120 description: > Autoincremental. Number of the receipt for internal control and without fiscal relevance. currency: type: string example: MXN description: >- Currency code, according to the standard [ISO 4217](https://es.wikipedia.org/wiki/ISO_4217). exchange: type: number minimum: 0 example: 1 description: > Exchange rate according to the currency used. It represents the number of Mexican pesos (MXN) equivalent to one unit of the currency indicated in the `currency` attribute. branch: type: string description: Name of the branch where the receipt was issued. external_id: type: string description: > Optional identifier that you can use to relate this receipt to your records and later search by this number. Facturapi does not validate that this field is unique. ReceiptAssignCustomerInput: type: object required: - customer properties: customer: description: > Customer to assign or reassign to the receipt. You can send the ID of an existing customer or a customer object to create it. oneOf: - type: string minLength: 24 maxLength: 24 example: 58e93bd8e86eb318b0197456 - $ref: '#/components/schemas/CustomerCreateInput' ReceiptSearchResult: allOf: - $ref: '#/components/schemas/SearchResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/Receipt' InvoiceReceiptInput: type: object allOf: - type: object properties: customer: description: > Customer receiving the invoice. You can send the customer object directly or the ID of a previously registered customer in Facturapi. If you omit it, the receipt must already have an assigned customer. oneOf: - $ref: '#/components/schemas/CustomerCreateInput' - type: string title: customer_id description: >- ID of the 'customer' object previously registered in Facturapi. example: 58e93bd8e86eb318b0197456 use: type: string default: G01 description: > Code of Use of CFDI according to the SAT catalog. You can see the codes in [this table](#uso-cfdi), or use the constants included in our libraries. conditions: type: string minLength: 1 maxLength: 1000 description: >- Payment conditions. Free text field usually used to specify payment terms, such as the due date. - $ref: '#/components/schemas/InvoiceableCommonInput' GlobalInvoiceInput: type: object required: - periodicity properties: from: type: string format: date default: Start of the last period example: '2022-01-01T00:00:00.000' description: > Initial date of the receipts that will be included in the global invoice. By default, this value is the start of the last period (day, week, fortnight, or month), according to the value of "Periodicity" (`periodicity`) in the receipts configuration of your organization. This value is required when the `receipts` field is sent. to: type: string format: date default: End of the last period example: '2022-31-01T23:59:59.999' description: > End date of the receipts that will be included in the global invoice. By default, this value is the end of the last period (day, week, fortnight, or month), according to the value of "Periodicity" (`periodicity`) in the receipts configuration of your organization. This value is required when the `receipts` field is sent. periodicity: type: string default: >- `periodicity` property from the organization's receipt configuration. enum: - day - week - fortnight - month - two_months description: > Periodicity that corresponds to the range of dates used. If omitted, the organization's receipt configuration will be used. If you omit sending the `from` and `to` fields, the default dates will depend on the value of `periodicity`. months: type: string default: Month contained in the range of dates used. description: > Key representing the month or bimester of the invoice. Consult the possible values in the [Months and Bimesters catalog](#meses-y-bimestres). example: '01' folio_number: type: integer default: autoincremental description: > Number of the folio assigned by the company for internal control. If omitted, the incremental value of the organization will be assigned. series: type: string maxLength: 25 description: >- Series. Alphanumeric characters designated by the company for internal control and without fiscal validity. example: F date: type: string format: date default: Value of the `to` field example: '2022-01-01T00:00:00.000' description: > Date of issuance of the invoice. By default, it takes the value of the `to` field. payment_form: type: string minLength: 2 maxLength: 2 example: '02' description: > Payment form code according to the [Payment Form catalog](#forma-de-pago). If included, the receipts will be grouped and the global invoice will be created by the payment form. receipts: type: array description: > Receipts to include in the global invoice. If this parameter is included, the `from` and `to` parameters will be required and must comply with the `periodicity` field. items: type: string format: hex minLength: 24 maxLength: 24 description: ID of a receipt previously registered in Facturapi. example: 614496b471d422de4b6cfcc4 ToInvoiceInput: type: object required: - keys properties: keys: type: array minItems: 1 maxItems: 1000 description: List of receipt keys to include in the invoice. items: type: string description: Receipt key. example: ticket_1001 customer: oneOf: - $ref: '#/components/schemas/CustomerCreateInput' - type: string title: customer_id description: ID of a customer previously registered in Facturapi. example: 58e93bd8e86eb318b0197456 description: > Customer receiving the invoice. If you send it, it overrides the customer assigned to the included receipts. If you omit it, all receipts must already have the same assigned customer. This rule also applies when `dry_run` is `true`. use: type: string default: G01 description: CFDI Use code according to SAT catalog. dry_run: type: boolean default: false description: >- If `true`, only validates data and returns a summary without creating the invoice. payment_form: type: string nullable: true minLength: 2 maxLength: 2 example: '03' description: > Payment form code according to the [Payment Form catalog](#forma-de-pago). ToInvoicePreviewInput: type: object required: - keys properties: keys: type: array minItems: 1 maxItems: 1000 description: List of receipt keys to include in the preview. items: type: string description: Receipt key. example: ticket_1001 customer: nullable: true oneOf: - $ref: '#/components/schemas/CustomerCreateInput' - type: string title: customer_id description: ID of a customer previously registered in Facturapi. example: 58e93bd8e86eb318b0197456 description: > Optional customer used for preview rendering. If you omit it, all receipts must already have the same assigned customer. use: type: string default: G01 description: CFDI Use code according to SAT catalog. ToInvoiceSummary: type: object description: Summary object returned when `dry_run=true`. ToInvoiceNotFoundResponse: type: object required: - invoice - summary - missingKeys properties: invoice: nullable: true type: object description: Always `null` when no invoice was created. summary: nullable: true type: object description: Summary preview when available. missingKeys: type: array description: Receipt keys that were not found or not eligible. items: type: string Retention: title: Retention object allOf: - $ref: '#/components/schemas/ResourceAutoGeneratedProps' - $ref: '#/components/schemas/RetentionReadOnlyProperties' - $ref: '#/components/schemas/RetentionProperties' RetentionReadOnlyProperties: type: object properties: status: type: string enum: - valid - canceled description: | Current status of the document. example: valid verification_url: type: string format: uri description: >- URL to verify the status of the retention on the SAT portal. This link is the same as the one that appears in the QR code on the retention PDF. example: >- https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw== type: type: string enum: - Retención example: Retención description: Type of document. uuid: type: string format: uuid description: | Fiscal folio of the retention, assigned by the SAT. example: 39c85a3f-275b-4341-b259-e8971d9f8a94 stamp: $ref: '#/components/schemas/Stamp' customer: $ref: '#/components/schemas/CustomerInfo' RetentionProperties: type: object properties: cve_retenc: type: string example: 1 description: > Key of the retention or payment information according to the SAT catalog. fecha_exp: type: string format: date-time example: '2021-09-15T06:03:23.000Z' description: Date of issuance of the document in ISO8601 format (UTC String). desc_retenc: type: string description: > If the retention key is "25" (Other types of retentions), this field is used to register the description of the retention. folio_int: type: string description: >- Alphanumeric identifier for internal control of the company and without fiscal relevance. periodo: type: object description: Information about the retention period. properties: mes_ini: type: integer minimum: 1 maximum: 12 description: Initial month of the retention period. mes_fin: type: integer minimum: 1 maximum: 12 description: Final month of the retention period. ejerc: type: integer description: Fiscal year in which the retention was made. totales: type: object description: >- Information about the total of retentions made in the corresponding period. properties: monto_tot_operacion: type: number minimum: 0 description: >- Total amount of the operation, with precision of up to 6 decimals. monto_tot_grav: type: number minimum: 0 description: Total amount taxed. monto_tot_exent: type: number minimum: 0 description: Total amount exempt. monto_tot_ret: type: number minimum: 0 description: Sum of the amounts of taxes withheld. imp_retenidos: type: array description: Collection of withheld taxes. items: type: object properties: base: type: number minimum: 0 description: Base amount on which the tax was calculated. impuesto: type: string enum: - IVA - ISR example: IVA description: | Key of the type of tax withheld, from the SAT catalog. - `IVA`: Value Added Tax - `ISR`: Income Tax monto: type: number minimum: 0 description: Amount of the tax withheld. tipo_pago_ret: type: string enum: - 1 - 2 - 3 - 4 description: | Key of the type of payment according to the SAT catalog. - `01`: Definitive IVA (VAT) payment - `02`: Definitive IEPS payment - `03`: Definitive ISR Platforms payment - `04`: Provisional ISR payment external_id: type: string description: > Optional identifier that you can use to relate this retention to your records and later search by this number. Facturapi does not validate that this field is unique. idempotency_key: type: string description: > Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. If left blank, it will not be taken into account. complements: type: array default: [] items: $ref: '#/components/schemas/CustomComplementData' description: > Array of complements to include in the retention. Each element contains a `string` with the XML code of the complement. pdf_custom_section: type: string format: html description: > In case you need to include more information in the PDF, this field allows you to insert HTML code with your own content. addenda: type: string format: xml description: XML code with the Addenda that needs to be added to the invoice. namespaces: type: array description: >- Namespaces to insert in the root node of the invoice. Required for `addenda`. items: $ref: '#/components/schemas/NamespaceProperties' RetentionSearchResult: allOf: - $ref: '#/components/schemas/SearchResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/Retention' RetentionInput: type: object required: - customer - cve_retenc - periodo - totales properties: customer: description: Customer receiving the invoice. oneOf: - $ref: '#/components/schemas/CustomerCreateInput' - type: string title: customer_id description: ID of the 'customer' object previously registered in Facturapi. example: 58e93bd8e86eb318b0197456 cve_retenc: type: string example: 26 description: >- Key of the retention or payment information according to the [SAT catalog](#clave-de-retencion). fecha_exp: type: string format: date-time example: '2021-09-15T06:03:23.000Z' description: Date of issuance of the document in ISO8601 format (UTC String). desc_retenc: type: string description: > If the retention key is "25" (Other types of retentions), this field is used to register the description of the retention. folio_int: type: string example: R123 description: >- Alphanumeric identifier for internal control of the company and without fiscal relevance. periodo: type: object description: Information about the retention period. required: - mes_ini - mes_fin - ejerc properties: mes_ini: type: integer minimum: 1 maximum: 12 example: 9 description: Initial month of the retention period. mes_fin: type: integer minimum: 1 maximum: 12 example: 9 description: Final month of the retention period. ejerc: type: integer example: 2021 description: Fiscal year in which the retention was made. totales: type: object description: >- Information about the total of retentions made in the corresponding period. required: - monto_tot_operacion - monto_tot_exent - imp_retenidos properties: monto_tot_operacion: type: number minimum: 0 description: >- Total amount of the operation, with precision of up to 6 decimals. monto_tot_grav: type: number minimum: 0 description: Total amount taxed. monto_tot_exent: type: number minimum: 0 description: Total amount exempt. monto_tot_ret: type: number minimum: 0 description: Sum of the amounts of taxes withheld. imp_retenidos: type: array description: Collection of withheld taxes. required: - monto_ret items: type: object required: - monto_ret - tipo_pago_ret properties: base_ret: type: number minimum: 0 description: Base amount on which the tax was calculated. impuesto: type: string enum: - IVA - ISR example: IVA description: | Key of the type of tax withheld, from the SAT catalog. - `IVA`: Value Added Tax - `ISR`: Income Tax monto_ret: type: number minimum: 0 description: Amount of the tax withheld. tipo_pago_ret: type: string enum: - 1 - 2 - 3 - 4 description: | Key of the type of payment according to the SAT catalog. - `01`: Definitive IVA (VAT) payment - `02`: Definitive IEPS payment - `03`: Definitive ISR Platforms payment - `04`: Provisional ISR payment external_id: type: string description: > Optional identifier that you can use to relate this retention to your records and later search by this number. Facturapi does not validate that this field is unique. idempotency_key: type: string description: > Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. complements: type: array default: [] items: $ref: '#/components/schemas/CustomComplementData' description: > Array of complements to include in the retention. Each element contains a `string` with the XML code of the complement, as you want it to be inserted in the XML of the CFDI. Only one root XML node is allowed per element. pdf_custom_section: type: string format: html description: > In case you need to include more information in the PDF, this field allows you to insert HTML code with your own content. addenda: type: string format: xml description: XML code with the Addenda that needs to be added to the invoice. namespaces: type: array description: >- Namespaces to insert in the root node of the invoice. Required for `addenda`. items: allOf: - $ref: '#/components/schemas/NamespaceRequiredProperties' - $ref: '#/components/schemas/NamespaceProperties' OrganizationAddress: allOf: - $ref: '#/components/schemas/CommonAddressProperties' - type: object description: Fiscal address of the issuing organization. properties: state: type: string description: Name of the State or Federative Entity. example: Sonora OrganizationSearchResult: allOf: - $ref: '#/components/schemas/SearchResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/Organization' Organization: title: Organization object type: object properties: id: type: string description: ID of the organization, assigned by Facturapi. example: 5a2a307be93a2f00129ea035 created_at: type: string format: date-time description: Date and time of creation of the organization. example: '2017-05-05T20:55:33.468Z' logo_url: type: string format: uri description: URL of the organization's logo. example: >- https://storage.googleapis.com/cdn.facturapi.io/organization/6c100efa5c6f5d7db0379ca643476a4183526007/logo.jpg timezone: type: string description: Time zone of the organization, in IANA format. example: America/Mexico_City is_production_ready: type: boolean description: >- Indicates if the organization has the necessary information to issue invoices in the Live environment. pending_steps: type: array description: >- List of steps that need to be completed for this organization to issue valid invoices in the Live environment. items: type: object properties: type: type: string enum: - legal - logo - certificate - manifiesto description: > Code that represents the type of step that needs to be completed. description: type: string description: >- Text that describes the step that needs to be completed and that you can use to show it to the user. legal: type: object description: Fiscal information of the organization. properties: name: type: string description: Commercial name of the organization. legal_name: type: string description: > Fiscal or Legal Name of the organization, *without* the corporate regime (e.g.: S.A. de C.V.). tax_system: type: string example: '601' maxLength: 3 minLength: 3 description: Fiscal Regime Code, from the [SAT catalog](#régimen-fiscal). website: type: string description: >- Website of the organization, which will be referenced when sending the invoice by email. phone: type: string description: >- Phone number of the organization, which will appear in the invoice PDF. address: allOf: - type: object description: Fiscal address of the organization. - $ref: '#/components/schemas/OrganizationAddress' customization: type: object description: > Organization customization settings, which will be used to reflect the branding and PDF preferences of the organization. This data can be updated at any time. properties: has_logo: type: boolean description: Indicates if the organization already has a logo uploaded. color: type: string format: hex example: BADA55 description: > Distinctive color of the brand in Hexadecimal RGB representation of 6 characters. next_folio_number: type: integer example: 123 description: >- Folio number that will be assigned to the next invoice in the Live environment (and that will be automatically incremented for each new invoice). next_folio_number_test: type: integer example: 123 description: > Folio number that will be assigned to the next invoice in the Test environment (and that will be automatically incremented for each new invoice). pdf_extra: type: object description: > Configure which optional fields you want to show in the PDF. The SAT does not require these fields to be shown, but they can be activated according to the organization's preference. properties: codes: type: boolean default: true description: > Show SAT catalog codes next to their descriptions. Example: "KGM Kilogramo". address_codes: type: boolean default: true description: > Show standardized state and country codes in the PDF. Example: "SON" for Sonora, "MX" for Mexico. product_key: type: boolean default: true description: | Show the product-service key. export_key: type: boolean default: false description: | Show the export key in the PDF. round_unit_price: type: boolean default: false description: > Round the unit price in the PDF to 2 decimals, but keep the 6 decimals in the XML. tax_breakdown: type: boolean default: true description: > Show the tax breakdown in the PDF. If disabled, only the taxes will be shown in the totals, but not in the detail of each concept. ieps_breakdown: type: boolean default: true description: > Show the breakdown of IEPS in the PDF. If disabled, only the taxes related to IVA (VAT) will be shown in the subtotal. combine_ieps_with_subtotal: type: boolean default: false description: > Add IEPS to the subtotal without breaking it down in the PDF. render_carta_porte: type: boolean default: false description: | Render the Carta Porte 3.1 Complement in the pdf. repeat_signature: type: boolean default: false description: | Repeat the digital signature on each page of the PDF. render_iedu: type: boolean default: false description: > Render the Private Education Institutions complement in the PDF. render_hyp_complement: type: boolean default: false description: | Render the hydrocarbons and petroleum complement in the PDF. render_comercio_exterior: type: boolean default: false description: | Render the foreign trade complement in the PDF. payroll_options: type: object properties: tipo_contrato: type: boolean default: false puesto: type: boolean default: false riesgo_puesto: type: boolean default: false antiguedad: type: boolean default: false certificate: type: object description: > Useful information about the organization's Digital Stamp Certificate (CSD), which will be used to sign the invoices. properties: has_certificate: type: boolean description: >- Indicates if the organization already has the Digital Stamp Certificate (CSD) uploaded. updated_at: type: string format: date-time example: '2023-05-05T20:55:33.468Z' description: Date of the last update of the certificate. expires_at: type: string format: date-time example: '2025-05-05T20:55:33.468Z' description: Expiration date of the certificate. serial_number: type: string example: '20001000000300000000' description: Serial number of the certificate. fiel: type: object description: > Useful information about the organization's FIEL certificate, which is used for the bulk CFDI download service. properties: has_certificate: type: boolean description: >- Indicates if the organization already has the FIEL certificate uploaded. updated_at: type: string format: date-time example: '2023-05-05T20:55:33.468Z' description: Date of the last update of the FIEL certificate. expires_at: type: string format: date-time example: '2025-05-05T20:55:33.468Z' description: Expiration date of the FIEL certificate. serial_number: type: string example: '20001000000300000000' description: Serial number of the FIEL certificate. receipts: type: object description: > Settings for receipts and the issuance of global invoices from receipts. properties: periodicity: type: string default: month enum: - day - week - fortnight - month - two_months description: > Periodicity with which the company decides to issue a global invoice (to the general public) for all the receipts not invoiced. This value is used as the default when creating a global invoice. duration_days: type: integer default: 7 description: > Maximum number of days to invoice through the self-invoicing portal after the receipt is issued and before the last day of the period. next_folio_number: type: integer example: 123 description: >- Folio number that will be assigned to the next receipt. It will be automatically incremented for each new receipt. next_folio_number_test: type: integer example: 123 description: > Folio number that will be assigned to the next receipt in the Test environment. It will be automatically incremented for each new receipt. self_invoice: type: object description: > Settings for the self-invoicing portal, which allows customers to invoice their receipts through a microsite. properties: allowed_cfdi_uses: type: array description: > List of CFDI uses allowed for self-invoicing. If this field is empty, all CFDI uses will be allowed. items: type: string example: G01 description: CFDI use code according to the [CFDI Use catalog](#uso-cfdi). apply_resico_isr: type: boolean description: > Indicates if the organization applies the ISR under the RESICO regime. If true, the ISR will be calculated according to the RESICO regime. If false, the ISR will be calculated according to the general regime. support_email: type: string description: >- Email address for clarifications. It will appear in the self-invoice portal. support_email_verified: type: boolean description: >- Indicates if the support email has been verified. If false, the email used in the self-invoice portal will be the main account's email. OrganizationDeleteCerts: type: object properties: updated_at: type: string format: date-time description: Date of deletion of the CSD certificate. OrganizationCreateInput: type: object required: - name properties: name: type: string maxLength: 100 description: Commercial name of the organization. OrganizationLegalInput: type: object required: - name - legal_name - tax_system - address properties: name: type: string maxLength: 100 description: Commercial name of the organization. legal_name: type: string maxLength: 100 description: > Fiscal or Legal Name of the organization, *without* the corporate regime (e.g.: S.A. de C.V.). tax_system: type: string maxLength: 3 minLength: 3 example: '601' description: Fiscal Regime Code, from the [SAT catalog](#régimen-fiscal). website: type: string description: >- Website of the organization, which will be referenced when sending the invoice by email. support_email: type: string description: > Email address for clarifications. It will appear in the invoice PDF and emails. phone: type: string description: >- Phone number of the organization, which will appear in the invoice PDF and emails. address: allOf: - type: object description: Fiscal address of the issuing organization. required: - zip - $ref: '#/components/schemas/OrganizationAddress' OrganizationCertsInput: type: object required: - cer - key - password properties: cer: type: string format: binary description: >- Binary content of the file with extension `.cer` of the CSD certificate. key: type: string format: binary description: >- Binary content of the file with extension `.key` of the CSD certificate. password: type: string description: Password of the certificate key. OrganizationFielInput: type: object required: - cer - key - password properties: cer: type: string format: binary description: Binary content of the e.firma (FIEL) file with extension `.cer`. key: type: string format: binary description: Binary content of the e.firma (FIEL) file with extension `.key`. password: type: string description: Password for the e.firma (FIEL) private key. OrganizationLogoInput: type: object required: - file properties: file: type: string format: binary description: | Binary content of the file with the image to be used as a logo. Supported formats: - jpg - png - svg OrganizationCustomizationInput: type: object properties: color: type: string format: hex example: BADA55 description: > Distinctive color of the brand in Hexadecimal RGB representation of 6 characters. next_folio_number: type: integer example: 123 description: >- Folio number that will be assigned to the next invoice created in this organization in the Live environment. It will be automatically incremented for each new invoice. next_folio_number_test: type: integer example: 123 description: > Folio number that will be assigned to the next invoice created in this organization in the Test environment. It will be automatically incremented for each new invoice. pdf_extra: type: object description: > Configure which optional fields you want to show in the PDF. The SAT does not require these fields to be shown, but they can be activated according to the organization's preference. properties: codes: type: boolean default: true description: > Show SAT catalog codes next to their descriptions. Example: "KGM Kilogramo". product_key: type: boolean default: true description: | Show the product-service key. address_codes: type: boolean default: true description: | Show standardized state and country codes in the PDF. export_key: type: boolean default: false description: | Show the export key in the PDF. round_unit_price: type: boolean default: false description: > Round the unit price in the PDF to 2 decimals, but keep the 6 decimals in the XML. tax_breakdown: type: boolean default: true description: > Show the tax breakdown in the PDF. If disabled, only the taxes will be shown in the totals, but not in the detail of each concept. ieps_breakdown: type: boolean default: true description: > Show the breakdown of IEPS in the PDF. If disabled, only the taxes related to IVA (VAT) will be shown in the subtotal. combine_ieps_with_subtotal: type: boolean default: false description: | Add IEPS to the subtotal without breaking it down in the PDF. render_carta_porte: type: boolean default: false description: | Render the Carta Porte 3.1 Complement in the pdf. render_iedu: type: boolean default: false description: | Render the Private Education Institutions complement in the PDF. render_hyp_complement: type: boolean default: false description: | Render the hydrocarbons and petroleum complement in the PDF. render_comercio_exterior: type: boolean default: false description: | Render the foreign trade complement in the PDF. repeat_signature: type: boolean default: false description: | Repeat the digital signature on each page of the PDF. payroll_options: type: object properties: tipo_contrato: type: boolean default: false puesto: type: boolean default: false riesgo_puesto: type: boolean default: false antiguedad: type: boolean default: false OrganizationReceiptsInput: type: object properties: periodicity: type: string default: month enum: - day - week - fortnight - month - two_months description: > Periodicity with which the company decides to issue a global invoice (to the general public) for all the receipts not invoiced. This value is used as the default when creating a global invoice. duration_days: type: integer default: 7 description: > Maximum number of days to invoice through the self-invoicing portal after the receipt is issued and before the last day of the period defined by the `periodicity` attribute. The value `0` deactivates this option, making the receipts always expire on the last day of the period. next_folio_number: type: integer description: >- Folio number that will be assigned to the next receipt created in this organization in the Live environment. next_folio_number_test: type: integer description: > Folio number that will be assigned to the next receipt created in this organization in the Test environment. OrganizationSelfInvoiceInput: type: object properties: allowed_cfdi_uses: type: array description: > List of CFDI uses allowed for self-invoicing. If this field is empty, all CFDI uses will be allowed. items: type: string example: G01 description: | CFDI use code according to the [CFDI Use catalog](#uso-cfdi). apply_resico_isr: type: boolean description: > Indicates if the organization applies the ISR under the RESICO regime. If true, the ISR will be calculated according to the RESICO regime. If false, the ISR will be calculated according to the general regime. support_email: type: string description: > Email address for clarifications. It will appear in the self-invoice portal. If the email is not verified, the main account's email will be used. DomainField: type: string maxLength: 50 minLength: 4 pattern: ^[a-z][a-z0-9-_]{2,48}[a-z0-9]$ description: | Domain name. Alphanumeric characters are allowed, only lowercase, hyphen (-) and underscore (_). It must start with a letter and end in a letter or number. OrganizationDomainInput: type: object required: - domain properties: domain: $ref: '#/components/schemas/DomainField' OrganizationSeriesCreateInput: type: object required: - series - next_folio - next_folio_test properties: series: type: string maxLength: 55 description: Series name next_folio: type: integer description: >- Folio number that will be assigned to the next invoice in the Live environment (and will automatically increase with each new invoice). next_folio_test: type: integer description: >- Folio number that will be assigned to the next invoice in the Test environment (and will automatically increase with each new invoice). OrganizationSeriesUpdateInput: type: object properties: next_folio: type: integer description: >- Folio number that will be assigned to the next invoice in the Live environment (and will automatically increase with each new invoice). next_folio_test: type: integer description: >- Folio number that will be assigned to the next invoice in the Test environment (and will automatically increase with each new invoice). OrganizationSeriesDefaultInput: type: object required: - type - series properties: type: type: string enum: - I - E - P - 'N' - T description: > Invoice type. Possible values: `I` (Income), `E` (Expense), `P` (Payment), `N` (Payroll), `T` (Transfer). series: type: string minLength: 1 maxLength: 25 description: Series name. OrganizationSeriesGroup: title: Objeto Series type: object properties: series: type: string description: Series Name. example: New next_folio: type: integer description: >- Folio number that will be assigned to the next invoice in the Live environment (and will automatically increase with each new invoice). example: 123 next_folio_test: type: integer description: >- Folio number that will be assigned to the next invoice in the Test environment (and will automatically increase with each new invoice). example: 123 OkResponse: type: object required: - ok properties: ok: type: boolean example: true OrganizationInvite: type: object properties: id: type: string description: Unique invite identifier. created_at: type: string format: date-time description: Date and time when the invite was created. email: type: string format: email description: Email address the invite was sent to. organization_name: type: string description: Name of the organization that sent the invite. role: type: string nullable: true description: ID of the role assigned in the invite, if any. role_name: type: string nullable: true description: Name of the role assigned in the invite, if any. roles: type: array description: >- List of visible roles that describes the access granted by the invite. items: type: string expires_at: type: string format: date-time nullable: true description: Date and time when the invite expires. OrganizationInviteList: type: array description: List of organization invites. items: $ref: '#/components/schemas/OrganizationInvite' OrganizationPermissionRole: type: object properties: id: type: string description: Unique role identifier. name: type: string description: Role name. template_code: type: string nullable: true description: Base template code for the role, if it comes from a system template. organization: type: string nullable: true description: ID of the organization the role belongs to. used_by: type: integer description: Number of users currently using this role. overrides_add: type: array description: Operations added to the role beyond those defined by its template. items: type: string overrides_remove: type: array description: Operations removed from the role relative to its template. items: type: string operations: type: array description: Final list of operations allowed by this role. items: type: string created_at: type: string format: date-time nullable: true description: Date and time when the role was created. updated_at: type: string format: date-time nullable: true description: Date and time when the role was last updated. OrganizationPermissionRoleList: type: array description: List of configurable roles for the organization. items: $ref: '#/components/schemas/OrganizationPermissionRole' OrganizationPermissionRoleTemplate: type: object properties: code: type: string enum: - org-admin - org-readonly - org-billing - org-developer - org-team-manager description: Internal role template code. label: type: string description: Visible name of the role template. operations: type: array description: Operations included by default in the template. items: type: string OrganizationPermissionRoleTemplateList: type: array description: List of available role templates for the organization. items: $ref: '#/components/schemas/OrganizationPermissionRoleTemplate' OrganizationPermissionOperationList: type: array description: List of available organization-level permission operations. items: type: string OrganizationUserAccess: type: object properties: id: type: string description: >- Identifier of the user's access within the organization. For the owner, this value is `owner` because the access is implicit. full_name: type: string description: User full name. email: type: string format: email description: User email address. role: type: string nullable: true description: >- ID of the role assigned to the user, if any. For the owner, this value is `null` because the access is implicit. role_name: type: string nullable: true description: >- Name of the assigned role or of the user's implicit access. For the owner, this value is `owner`. organization: type: string nullable: true description: ID of the organization this access belongs to. operations: type: array description: Final list of operations allowed for the user. items: type: string created_at: type: string format: date-time description: >- Date and time when the access was created. For the owner, this corresponds to when the organization was created. updated_at: type: string format: date-time description: >- Date and time when the access was last updated. For the owner, this corresponds to when the organization was created because the access is implicit. OrganizationUserAccessList: type: array description: >- List of user access entries in the organization, including implicit access such as the owner. items: $ref: '#/components/schemas/OrganizationUserAccess' OrganizationInviteCreateInput: type: object required: - email properties: email: type: string format: email description: Email address of the user to invite. role: type: string description: ID of a custom organization role. OrganizationInviteRespondInput: type: object required: - accept properties: accept: type: boolean description: >- Indicates whether the invite should be accepted (`true`) or declined (`false`). OrganizationPermissionRoleCreateInput: type: object required: - name properties: name: type: string description: Role name. template_code: type: string nullable: true enum: - org-admin - org-readonly - org-billing - org-developer - org-team-manager description: Base template code used to initialize the role, if any. add: type: array description: Additional operations that will be added to the role. items: type: string remove: type: array description: Operations that will be removed from the role. items: type: string OrganizationPermissionRoleUpdateInput: type: object properties: name: type: string description: New role name. template_code: type: string nullable: true enum: - org-admin - org-readonly - org-billing - org-developer - org-team-manager description: New base template code for the role, if any. add: type: array description: Full list of extra operations the role should keep. items: type: string remove: type: array description: Full list of removed operations the role should keep. items: type: string OrganizationUserAccessRoleUpdateInput: type: object required: - role properties: role: type: string description: ID of the role that will be assigned to the user. securitySchemes: SecretLiveKey: type: http scheme: bearer bearerFormat: sk_live_XXXXXXXXXXXX description: > Unique per organization. Allows you to create, retrieve, and manage resources in the Live environment for a specific organization. SecretTestKey: type: http scheme: bearer bearerFormat: sk_test_XXXXXXXXXXXX description: > Unique per organization. Allows you to create, retrieve, and manage resources in the Test environment for a specific organization. SecretUserKey: type: http scheme: bearer bearerFormat: sk_user_XXXXXXXXXXXX description: > Unique per account. Allows you to create and configure organizations belonging to the user's account