API Changelog

​

SAT resources

• Added a SAT overview page that explains how SAT resources relate to entities, extractions, and file downloads.
• Added overview pages for credentials, invoice line items, invoice relations, credit notes, tax retentions, tax returns, tax status, electronic accounting records, and SAT certificates.
• Added extraction guidance to SAT resource overviews so each extraction-backed resource explains the extractor to use and where to read the extracted records.
• Updated the Extractions overview to focus on the extraction workflow instead of duplicating extractor-specific option lists.
• Expanded the existing invoice, invoice payment, invoice batch payment, and tax compliance check overviews with clearer resource descriptions.
• Updated endpoint summaries and descriptions to consistently use List and Retrieve wording and entity-based language.
• Added documentation for listing credit notes extracted for an entity.
• Added documentation for invoice relations, tax return PDF downloads, parsed SAT CFDI retrieval, and the top-level tax status list.
• Corrected the documented credit-note retrieve path to use /invoices/credit-notes/{id}.
• Corrected the documented invoice line item retrieve path to use /invoices/line-items/{id}.
• Added field descriptions for SAT certificate, credential, invoice payment, invoice batch payment, invoice line item, tax retention, tax return, tax compliance check, tax status, and tax regime response fields.
• Renamed the SAT certificate documentation pages from get slugs to list and retrieve slugs, with redirects from the previous documentation URLs.

​

Income Statement profit/loss grouping

• In the 2022 format and the audited income-statement formats, each matched Utilidad (profit) and Pérdida (loss) pair is now returned under a single grouping parent row instead of as two top-level rows. The pair appears as two entries inside the parent’s children array, and the parent’s per-year Total reflects the populated side.
• The four pairs that are grouped match the long-standing 2014 format behavior: bruta, de operación, antes de impuestos, and neta. The operaciones continuas pair is intentionally left flat.
• Breaking change for consumers of JSON, CSV, and XLSX exports of the 2022 and audited formats. Integrations that read profit/loss rows by category name at the top level must now read them from the grouping parent’s children array, or sum the parent’s Total directly. The 2014 format response is unchanged.
• The grouping parent itself has no underlying SAT concept path. Its Total is computed from its children, and child rows keep their original categories and totals.

​

Income Statement outflow sign convention

• Cost, expense, loss, tax, and financial-charge lines are now returned as negative values, matching the long-standing 2014 format. Previously these outflow lines were returned positive in the 2022 and audited-financial-statements formats.
• Revenue, profit, and other inflow lines remain positive. Net or mixed sections keep their natural sign.
• Action required: integrations that consumed these formats as positive magnitudes and applied their own sign must stop negating outflows themselves. The values already carry the correct sign. The absolute magnitude of every line is unchanged.

​

Other Resources

• Mexico address lookup has moved from Miscellaneous into Other Resources.
• Shareholders, background checks, and company verification reports now include overview pages that explain the purpose of each resource group.
• Shareholders, background checks, and company verification report endpoint titles now use consistent List, Retrieve, and Download wording, with expanded endpoint and field descriptions.
• Mexico address lookup documentation now explains that Buró de Crédito and Buró Empresas addresses must match the postal-code address catalog, that a postal code can return multiple neighborhoods, and describes the address fields returned by the endpoint.

​

Expenditures and Sales Revenue insights

• The products value has been removed from the allowed values of the options[type] query parameter on both endpoints. Requests that previously sent options[type]=products were already returning the same response as options[type]=total, so existing integrations that rely on that response continue to work without changes.
• For product-level breakdowns, use the Products and Services insight endpoints (GET /entities/{entityId}/insights/products-and-services-bought and GET /entities/{entityId}/insights/products-and-services-sold).
• The dimension and label field descriptions in the response schemas have been updated to reflect that products is no longer a supported grouping.

​

BIL reports

• The API reference now includes the endpoint for listing BIL reports generated for an entity.
• The API reference now includes the endpoint for retrieving a single BIL report by report ID.
• BIL report documentation now describes the main response fields, including the report folio, searched name, maximum grade, parsed vendor response, XML file, and PDF file.

​

Entities, identifiers, tags, and events

• The API reference now includes entity overview and endpoint pages that explain how entities are created, retrieved, updated, deleted, and used as the parent resource for datasource records.
• Entity identifier documentation now explains how RFC and CURP identifiers can be supplied when creating an entity or added later.
• Entity tag and tag documentation now explain how tags can be used for segmentation, extraction scheduler targeting, monitoring, and filtering entities in your own product.
• Entity event documentation now explains how to retrieve events for a specific entity in addition to using webhook delivery.

​

Files and exports

• File documentation now explains file metadata, file types, filenames, MIME types, and when to use the download endpoint for file content.
• Export documentation now explains the asynchronous export workflow from creation through terminal statuses.
• Export documentation now shows that completed exports return a file reference that can be downloaded through the file download endpoint.

​

Extractions, schedulers, and scheduler rules

• Extraction documentation now covers the extraction lifecycle, statuses, retry behavior, duplicate extraction behavior, and datasource-specific extractor descriptions.
• BIL is now included in the documented extractor list.
• Scheduler and scheduler rule documentation now explains recurring extraction behavior in more detail.

​

Guides

• The guides now include entity-based URL guidance that explains entity IDs and legacy RFC-based URL compatibility.
• The environments guide now describes Sandbox and Production behavior across Syntage datasources.
• Request ID and rate limiting guides now include response header examples and troubleshooting use cases.
• Property filtering guidance now includes syntax examples for selecting fields from resources and related objects.
• SAT catalog documentation now includes the catalog areas covered by the API and examples of common CFDI catalog values.
• Webhook validation guidance now includes PHP, JavaScript/TypeScript, and Python examples for verifying request signatures.
• Updated the integration flow guide to explain credential validation, extraction creation, extraction status tracking, webhook delivery, and file retrieval as a connected workflow.
• Clarified that embedded entity onboarding is for integrations that need the onboarding experience inside their own site instead of redirecting to Syntage.
• Kept deprecated widget documentation available for existing widget users while pointing new integrations to embedded entity onboarding.
• Updated introductory documentation to describe Syntage’s API across SAT, RUG, RPC, BIL, Buró de Crédito, Buró Empresas, Infonavit, and more.

​

Invoice

• The amount property has been removed from API responses. Use the total property instead.
• Retrieval by invoice’s uuid at /invoices/{id} is now removed. To retrieve an invoice, use the invoice’s id at the specified endpoint. To find an invoice using its uuid, filter the invoice collection at /taxpayers/{taxpayerId}/invoices?uuid[]={uuid}.
• Previously, the @iri property for an invoice pointed to the resource using uuid, like /invoices/{uuid}. Now, it points using its id, like /invoices/{id}.

​

Link

• Filtering links by status is removed. Use credential.status instead. For example, use GET /links?credential.status[]=active instead of GET /links?status[]=active.

​

Tax Return

• Retrieval by tax return’s operationNumber at /tax-returns/{id} is removed. To retrieve a tax return, use the tax return’s id at the specified endpoint. To find a tax return using its operationNumber, filter the collection at /taxpayers/{taxpayerId}/tax-returns?operationNumber[]={operationNumber}.
• Previously, the @iri property for a tax return pointed to the resource using operationNumber, like /tax-returns/{operationNumber}. Now, it points to its id, like /tax-returns/{id}.

​

Event

• For events associated to a tax-return, the @iri property now points to /tax-returns/{id} instead of the previous /tax-returns/{operationNumber}.
• For events associated to an invoice, the @iri property now points to /invoices/{id} instead of the previous /invoices/{uuid}.

​

Extraction

• The periodFrom property has been removed. Use options.period.from instead.
• The periodTo property has been removed. Use options.period.to instead.

​

File

• For files associated to a tax-return, the @iri property now points to /tax-returns/{id} instead of the previous /tax-returns/{operationNumber}.
• For files associated to an invoice, the @iri property now points to /invoices/{id} instead of the previous /invoices/{uuid}.

​

Test this version

curl -i 'https://api.syntage.com/taxpayers/{taxpayerId}/invoices' \
  --header 'Accept-Version: 2020-06-28' \
  --header 'X-Api-Key: {apiKey}'