Syntage DS MX SAT Tax Returns API

openapi: 3.2.0
info:
  version: '2020-06-28'
  title: Syntage Accounts Payable Insight DS MX SAT Tax Returns API
  contact:
    name: Email
    email: support@syntage.com
  description: "# Introduction\n\nThe Syntage API is organized around [REST](https://en.wikipedia.org/wiki/Representational_State_Transfer).\nOur API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns [JSON-LD](https://json-ld.org) responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Environments\n\n| Name | Description | Base URL |\n|------|-------------|----------|\n| **Sandbox** | The Sandbox environment is dedicated to development and testing. In this environment, no real taxpayer credentials are required and all interaction with the SAT is simulated generating life-like data, allowing you to pull test data from all endpoints. | https://api.sandbox.syntage.com |\n| **Production** | The Production environment is dedicated to live applications with real connections to the SAT. In this environment, real taxpayer credentials are required, and you will pull real fiscal data directly from the SAT. | https://api.syntage.com |\n\nEach environment has a different API Key for [authentication](#section/Authentication).\n\n# Request IDs\n\nEach API request has an associated request identifier.\nYou can find this value in the response headers, under `X-Request-ID`:\n\n```curl\ncurl -i https://api.syntage.com\nHTTP/1.1 200 OK\nDate: Sun, 29 Nov 2020 19:21:21 GMT\nX-Request-ID: Root=1-6532dcae-169bf139354cd48959f55c55\n```\n\nIf you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.\n\n# Rate Limiting\n\nOur API employs a number of safeguards against bursts of incoming traffic to help maximize its stability.\nThe returned HTTP headers of any API request show your current rate limit status:\n\n```curl\ncurl -i https://api.syntage.com\nHTTP/1.1 200 OK\nDate: Sun, 29 Nov 2020 19:21:21 GMT\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 56\nX-RateLimit-Reset: 1606678044\n```\n\n| Header Name           | Description |\n|-----------------------|------------------------------------------------------------------------------|\n| X-RateLimit-Limit     | The maximum number of requests you're permitted to make.                     |\n| X-RateLimit-Remaining | The number of requests remaining in the current rate limit window.           |\n| X-RateLimit-Reset     | The time at which the current rate limit window resets in UTC epoch seconds. |\n\nIf you exceed the rate limit, a [429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) response is returned:\n\n```http\nHTTP/1.1 429 Too Many Requests\nDate: Sun, 29 Nov 2020 19:21:21 GMT\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nX-RateLimit-Reset: 1606678044\n```\n\nWe may reduce limits to prevent abuse, or increase limits to enable high-traffic operations.\nYou can check your current limits in the [dashboard](https://app.syntage.com/settings/usage).\nTo request an increased rate limit, please [contact support](https://support.syntage.com/).\n# Pagination\nWhen issuing a GET request on a collection containing more than 1 page (e.g. [/events](#operation/ListEvent)),  a collection is returned. Links to the first, the last, previous and the next page in the collection are displayed as well as the  number of total items in the collection.\nAll endpoints that support this operation have a query parameter defined by:\n  - `itemsPerPage` The number of items per page (default: 20, max: 1000)\n  - `page` The collection page number\n\n```bash\n  \"hydra:totalItems\": 1,\n  \"hydra:view\": {\n    \"@id\": \"/events?page=1\",\n    \"@type\": \"hydra:PartialCollectionView\",\n    \"hydra:first\": \"/events?page=1\",\n    \"hydra:next\": \"/events?page=2\",\n    \"hydra:last\": \"/events?page=3\"\n  },\n```\n## Cursor Pagination\nCursor pagination is a technique used for navigating through large datasets efficiently. It allows you to retrieve a specific subset of results from a collection by using a cursor value that represents the position within the collection. The cursor serves as a reference point for fetching the next or previous set of results.\n### Benefits of Cursor Pagination:\n1. **Efficient Navigation:** Cursor pagination eliminates the need to fetch the entire dataset at once, making it more scalable and faster. You can retrieve data in smaller, manageable chunks based on the cursor values.\n2. **Consistent Results:** Each page of results in cursor pagination is stable and doesn't change even if new items are added or removed from the collection. This ensures that you get consistent and reliable results.\n3. **Flexibility:** Cursors can be used to navigate forwards and backwards in the collection without impacting performance.\n\n### How to Use Cursor Pagination:\nTo use cursor pagination with our API, follow these instructions:\n1. Make a request to retrieve the initial page of results. The response will be a JSON-LD document that includes a `hydra:next` attribute with the URI for the next page. The URI already includes the cursor attribute.\n2. To retrieve the next page of results, make a GET request to the URI provided in the `hydra:next` attribute. This URI will automatically include the cursor value for the next page.\n3. If you want to navigate to the previous page, you can use the `hydra:previous` attribute in the JSON-LD response. It will contain the URI for the previous page, including the cursor value.\n4. You can continue making requests to the `hydra:next` and `hydra:previous` URIs to navigate through the paginated results, based on your requirements.\nMake sure to update your request headers to include the necessary headers for JSON-LD content negotiation, such as `Accept: application/ld+json` or `Content-Type: application/ld+json`.\nBy following these instructions, you can effectively navigate through the paginated results using the cursor values provided in the `hydra:next` and `hydra:previous` attributes, without the need to manually include the cursor in your requests. This simplifies the pagination process and enhances the usability of our API.\n\n### Considerations About Cursor Pagination:\n\n  - By default, the API uses offset-based pagination (except for a few endpoints that we will list below). If you want to switch to cursor pagination, you need to include an additional header in your request. Set the `X-Pagination-Style` header with the value `\"cursor\"` to enable cursor pagination. If not specified, the API will assume offset-based pagination.\n\n  - After enabling cursor pagination, the API response will no longer include the `hydra:totalItems` field by default. Retrieving the total count can be resource intensive and impact response times, especially for large datasets. However, if you need the `hydra:totalItems` information, you can include an additional header in your request. Set the `X-Pagination-Enable-Partial` header with the value `0` to indicate that the response should include extra information, including the `hydra:totalItems` count. Please be aware that enabling this feature may impact API response times, as the backend needs to perform a count operation on the dataset.\n\nIf you require the `hydra:totalItems` count, please consider the potential impact on API response times.\n### Example\n```bash\n  curl -i 'https://api.syntage.com/entities/{entityId}/invoices?itemsPerPage=10' \\\n    --header 'Accept: application/ld+json' \\\n    --header 'X-Api-Key: {apiKey}' \\\n    --header 'X-Pagination-Style: cursor' \\\n    --header 'X-Pagination-Enable-Partial: 0'\n```\n**Note:** We only support cursor pagination for the following endpoints:\n - `GET /entities/{entityId}/invoices`\n - `GET /entities/{entityId}/invoices/line-items`\n - `GET /entities/{entityId}/invoices/{invoiceId}/line-items`\n - `GET /invoices/{invoiceId}/line-items`\n - `GET /entities/{entityId}/invoices/payments`\n\nFeel free to reach out if you have any further questions or need additional assistance!\n\n# Property Filtering\nThe property filter adds the possibility to select the properties for GET operations.\nSyntax: `?properties[]=<property>&properties[<relation>][]=<property>`\nYou can add as many properties as you need. The following example shows how to select `paymentType` and  `issuer.rfc` when fetching a list of invoices.\n```curl\n  curl -i https://api.syntage.com/entities/{entityId}/invoices?properties[]=paymentType&properties[issuer]=rfc\n```\n# Filtering\n**Warning:** Collection endpoints only apply the filter query parameters documented for that endpoint. If you send an unsupported or misspelled filter query parameter, the API ignores it and processes the request as if that parameter was not sent.\n\n# API Versioning Guide\nGuidance on changes between versions.\n## Version: 2020-01-01 to 2020-06-28\n### **Invoice**\n_**Affected Endpoints:** `GET /invoices/{id}` and `GET /entities/{entityId}/invoices`_\n- The `amount` property has been removed from API responses. Use the `total` property instead.\n- 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 `/entities/{entityId}/invoices?uuid[]={uuid}`.\n- 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}`.\n\n### **Entity (Formerly Link)**\n_**Affected Endpoint:** `GET /entities`_\n- Filtering entities by `status` is removed. Use `credential.status` instead. For example, utilize `GET /entities?credential.status[]=active` instead of `GET /entities?status[]=active`.\n\n### **Tax Return**\n_**Affected Endpoints:** `GET /tax-returns/{id}` and `GET /entities/{entityId}/tax-returns`_\n- 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 mentioned endpoint. To find a tax return using its `operationNumber`, filter the collection at `/entities/{entityId}/tax-returns?operationNumber[]={operationNumber}`.\n- Previously, the `@iri` property for a tax return pointed to the resource using `operationNumber`, like `/tax-returns/{operationNumber}`. Now, it directs to its `id`, like `/tax-returns/{id}`.\n\n### **Event**\n_**Affected Endpoints:** `GET /events` and `GET /events/{id}`_\n- For events associated to an `tax-return`, the `@iri` property now directs to `/tax-returns/{id}` instead of the previous `/tax-returns/{operationNumber}`.\n- For events associated to an `invoice`, the `@iri` property now directs to `/invoices/{id}` instead of the previous `/invoices/{uuid}`.\n\n### **Extraction**\n_**Affected Endpoints:** `GET /extractions` and `GET /extractions/{id}`_\n- The `periodFrom` property has been removed. Use `options.period.from` instead.\n- The `periodTo` property has been removed. Use `options.period.to` instead.\n\n### **File**\n_**Affected Endpoint:** `GET /file/{id}`_\n- For files associated to an `tax-return`, the `@iri` property now directs to `/tax-returns/{id}`, instead of the previous `/tax-returns/{operationNumber}`.\n- For files associated to an `invoice`, the `@iri` property now directs to `/invoices/{id}`, instead of the previous `/invoices/{uuid}`.\n\n### Trying Out This Version\nIf you want to test this version, you can do so by making any request with the `Accept-Version` header pointing to the latest version:\n```curl\n  curl -i 'https://api.syntage.com/entities/{entityId}/invoices' \\\n    --header 'Accept-Version: 2020-06-28' \\\n    --header 'X-Api-Key: {apiKey}'\n```\n"
servers:
- url: https://api.syntage.com
  description: Production
- url: https://api.sandbox.syntage.com
  description: Sandbox
security:
- ApiKey: []
tags:
- name: DS MX SAT Tax Returns
paths:
  /tax-returns/{id}:
    get:
      tags:
      - DS MX SAT Tax Returns
      operationId: GetTaxReturn
      summary: Retrieve a tax return
      description: 'Retrieve a tax return by ID, including filing metadata, payment information, file references, and ISSIF availability.

        '
      parameters:
      - $ref: '#/components/parameters/taxReturnId'
      responses:
        '200':
          $ref: '#/components/responses/TaxReturn'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tax-returns/{id}/pdf:
    get:
      tags:
      - DS MX SAT Tax Returns
      operationId: DownloadTaxReturnPdf
      summary: Download a tax return PDF
      description: 'Download the SAT transcript PDF for a tax return.

        '
      parameters:
      - $ref: '#/components/parameters/taxReturnId'
      responses:
        '200':
          description: Tax return PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
              example: <pdf-binary-data>
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tax-returns/{id}/data:
    get:
      tags:
      - DS MX SAT Tax Returns
      operationId: GetTaxReturnData
      summary: Retrieve tax return data
      description: 'Retrieve extracted data from a tax return.


        For annual tax returns, there are two available formats:

        - Financial statements 2022 format - This is available for non-pfae tax returns. Data will only be returned if the SAT provides the XLSX financial statements document.

        - Financial statements 2014 format - This is available for pfae annual tax returns from 2014 to now, and all other annual tax returns from 2014-2021, as long as we are able to retrieve the PDF.


        For provisional (monthly) tax returns, the response contains extracted financial variables including sales revenue, cash inflow, cash outflow, number of employees, and payroll amount. The available variables depend on the tax regime (601, 612, 626).


        The response format here may change if SAT changes the categories or other formatting in the files they provide.

        '
      parameters:
      - $ref: '#/components/parameters/taxReturnId'
      responses:
        '200':
          $ref: '#/components/responses/TaxReturnData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /entities/{entityId}/tax-returns:
    get:
      tags:
      - DS MX SAT Tax Returns
      operationId: ListTaxpayerTaxReturn
      summary: List an entity's tax returns
      description: 'List tax returns extracted for an entity.

        '
      parameters:
      - $ref: '#/components/parameters/entityId'
      - name: operationNumber
        in: query
        description: Filter by operation number (partial match)
        schema:
          $ref: '#/components/schemas/TaxReturnOperationNumber'
      - name: type
        in: query
        description: Filter by type (exact match)
        schema:
          $ref: '#/components/schemas/TaxReturnType'
      - name: intervalUnit
        in: query
        description: Filter by interval unit (exact match)
        schema:
          $ref: '#/components/schemas/TaxReturnIntervalUnit'
      - name: complementary
        in: query
        description: Filter by interval unit (partial match)
        schema:
          $ref: '#/components/schemas/TaxReturnComplementary'
      - name: captureLine
        in: query
        description: Filter by payment code (partial match)
        schema:
          $ref: '#/components/schemas/TaxReturnCaptureLine'
      - name: period
        in: query
        description: Filter by period (exact match)
        schema:
          $ref: '#/components/schemas/TaxReturnPeriod'
      - name: presentedAt[before]
        in: query
        description: Filter by filing date (less than or equal `<=`)
        schema:
          $ref: '#/components/schemas/TaxReturnPresentedAt'
      - name: presentedAt[strictly_before]
        in: query
        description: Filter by filing date (less than `<`)
        schema:
          $ref: '#/components/schemas/TaxReturnPresentedAt'
      - name: presentedAt[after]
        in: query
        description: Filter by filing date (greater than or equal `>=`)
        schema:
          $ref: '#/components/schemas/TaxReturnPresentedAt'
      - name: presentedAt[strictly_after]
        in: query
        description: Filter by filing date (greater than `>`)
        schema:
          $ref: '#/components/schemas/TaxReturnPresentedAt'
      - name: fiscalYear
        in: query
        description: Filter by fiscal year (exact match)
        schema:
          $ref: '#/components/schemas/TaxReturnFiscalYear'
      - name: order[period]
        in: query
        description: Order by period
        schema:
          $ref: '#/components/schemas/CollectionOrder'
      - name: order[presentedAt]
        in: query
        description: Order by filing date
        schema:
          $ref: '#/components/schemas/CollectionOrder'
      - $ref: '#/components/parameters/collectionCursorNextPageParam'
      - $ref: '#/components/parameters/collectionCursorPreviousPageParam'
      - $ref: '#/components/parameters/collectionLimit'
      responses:
        '200':
          $ref: '#/components/responses/TaxpayerTaxReturnCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    taxReturnId:
      name: id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/TaxReturnID'
    collectionLimit:
      name: itemsPerPage
      in: query
      required: false
      description: Number of items per page
      schema:
        $ref: '#/components/schemas/CollectionLimit'
    collectionCursorNextPageParam:
      name: id[lt]
      in: query
      required: false
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      description: Collection cursor pointer to the next page
      schema:
        type: string
    entityId:
      name: entityId
      in: path
      required: true
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      schema:
        type: string
        format: uuid
    collectionCursorPreviousPageParam:
      name: id[gt]
      in: query
      required: false
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      description: Collection cursor pointer to the previous page
      schema:
        type: string
  schemas:
    TaxReturnComplementary:
      type:
      - string
      - 'null'
      description: Set when *type* is `complementaria*`
      enum:
      - Declaración no Presentada
      - Dejar sin Efecto Declaración
      - Dejar sin Efecto Obligación
      - Esquema Anterior
      - Modificación de Declaración
      - Modificación de Obligaciones
      - Obligación no presentada
      example: Modificación de Obligaciones
    updatedAt:
      type: string
      description: Date and time the resource was last updated
      example: '2020-01-01T12:15:00.000Z'
    TaxReturnIssifObligation:
      type:
      - boolean
      - 'null'
      description: 'Indicates whether the taxpayer is obligated to file the

        Informative Statement on Tax Situation (ISSIF/DISIF) under

        Article 32-H of the Mexican Federal Tax Code (CFF). Derived

        from the annual return PDF, either from the 32-H obligation

        question or from a referenced ISSIF artifact (the `ARCHIVO

        ISSIF` section or a `.sb2x` filename).


        When `true`, financial statements for this return are filed

        separately via SIPRED and therefore are not present in the

        standard annual-return Excel.


        Only set on annual returns for Personas Morales filed from

        fiscal year 2018 onward; older returns always return `false`.

        '
      example: false
    TaxReturnPeriod:
      type: string
      description: Fiscal period. For an annual tax return, it is a year and for monthly tax return it is a month
      example: Diciembre
    TaxReturnIntervalUnit:
      type: string
      enum:
      - Anual
      - Mensual
      - RIF
      example: Mensual
    TaxReturn:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: Tax Return IRI reference
          example: /tax-returns/91106968-1abd-4d64-85c1-4e73d96fb997
        '@type':
          type: string
          default: TaxReturn
        id:
          $ref: '#/components/schemas/TaxReturnID'
        taxpayer:
          $ref: '#/components/schemas/Taxpayer'
        operationNumber:
          $ref: '#/components/schemas/TaxReturnOperationNumber'
        intervalUnit:
          $ref: '#/components/schemas/TaxReturnIntervalUnit'
        period:
          $ref: '#/components/schemas/TaxReturnPeriod'
        fiscalYear:
          $ref: '#/components/schemas/TaxReturnFiscalYear'
        type:
          $ref: '#/components/schemas/TaxReturnType'
        complementary:
          $ref: '#/components/schemas/TaxReturnComplementary'
        presentedAt:
          $ref: '#/components/schemas/TaxReturnPresentedAt'
        captureLine:
          $ref: '#/components/schemas/TaxReturnCaptureLine'
        files:
          $ref: '#/components/schemas/TaxReturnFiles'
        issifObligation:
          $ref: '#/components/schemas/TaxReturnIssifObligation'
        payment:
          $ref: '#/components/schemas/TaxReturnPayment'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    TaxReturnType:
      type: string
      enum:
      - Complementaria
      - Complementaria Corrección Fiscal
      - Complementaria Dictamen
      - Normal
      - Normal por Corrección Fiscal
      example: Complementaria
    File:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: File IRI reference
          example: /files/91106968-1abd-4d64-85c1-4e73d96fb997
        '@type':
          type: string
          description: JSON-LD resource type
          default: File
          example: File
        id:
          type: string
          format: uuid
          description: Unique file ID
          example: 91106968-1abd-4d64-85c1-4e73d96fb997
        type:
          type: string
          description: File category, such as an invoice CFDI XML or PDF
          example: invoice.cfdi.xml
        resource:
          type: string
          description: IRI of the resource that produced or owns the file
          example: /invoices/7c45e9c6-8f7f-4d0e-b6e5-65fef6c8c2f9
        mimeType:
          type: string
          description: Media type of the file content
          example: text/xml
        extension:
          type: string
          description: File extension for the stored content
          example: xml
        size:
          type: integer
          description: File size in bytes
          example: 40544
        filename:
          type: string
          description: Suggested filename for the file content
          example: 6f3c5312-2849-4525-86f6-c48a54c64c60.xml
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    createdAt:
      type: string
      description: Date and time the resource was created
      example: '2020-01-01T12:15:00.000Z'
    CollectionOrder:
      type: string
      enum:
      - asc
      - desc
      example: asc
    TaxReturnPresentedAt:
      type: string
      format: date-time
      description: Tax return filing date
    CursorCollection:
      type: object
      properties:
        '@context':
          type: string
        '@id':
          type: string
        '@type':
          type: string
          default: hydra:Collection
        hydra:member:
          type: array
          items:
            type: object
        hydra:view:
          type: object
          description: Pagination information
          properties:
            '@id':
              type: string
              format: iri-reference
              description: Current page IRI reference
            '@type':
              type: string
              default: hydra:PartialCollectionView
            hydra:next:
              type: string
              example: /entity/2a15f539-3251-48e1-aaeb-a154dc9c6edb/resource?id[lt]=9b8e5365-0b36-45f5-9c76-fbe439632367
              description: Next page IRI reference; omitted when there is no pagination
            hydra:last:
              type: string
              example: /entity/2a15f539-3251-48e1-aaeb-a154dc9c6edb/resource?id[gt]=9b8e5365-0b36-45f5-9c76-fbe439632367
              description: Last page IRI reference; omitted when there is no pagination
        hydra:search:
          type: object
          properties:
            '@type':
              type: string
            hydra:template:
              type: string
            hydra:variableRepresentation:
              type: string
            hydra:mapping:
              type: array
              items:
                type: object
                properties:
                  '@type':
                    type: string
                  variable:
                    type: string
                  property:
                    type: string
                  required:
                    type: boolean
    TaxpayerTaxReturnCollection:
      allOf:
      - $ref: '#/components/schemas/CursorCollection'
      - type: object
        properties:
          '@context':
            default: /contexts/TaxReturn
          '@id':
            default: /entities/{entityId}/tax-returns
            example: /entities/91106968-1abd-4d64-85c1-4e73d96fb997/tax-returns
          hydra:member:
            items:
              $ref: '#/components/schemas/TaxReturn'
    TaxReturnFiscalYear:
      type: string
      example: 2019
      description: Fiscal year
    TaxReturnFiles:
      type: array
      description: Tax return PDF files (ack receipt, transcript and payment receipt)
      items:
        $ref: '#/components/schemas/File'
    TaxpayerName:
      type: string
      minLength: 1
      maxLength: 254
      description: Taxpayer name
      example: Pedro Infante Cruz
    TaxReturnCaptureLine:
      type:
      - string
      - 'null'
      description: Set when the an amount should be paid back to SAT
      example: 042007HZ795527888246
    TaxpayerID:
      type: string
      minLength: 12
      maxLength: 13
      description: RFC (Registro Federal de Contribuyentes)
      example: PEIC211118IS0
    TaxpayerPersonType:
      type: string
      enum:
      - physical
      - legal
      example: physical
    TaxReturnID:
      type: string
      format: uuid
      description: Tax Return ID
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
    TaxReturnOperationNumber:
      type: number
      example: 200100172932
      description: Tax return operation code generated by SAT (Número de operación)
    CollectionLimit:
      type: integer
      default: 20
      minimum: 1
      maximum: 1000
    TaxReturnPayment:
      description: Payment
      type: object
      properties:
        dueAmount:
          type: number
          format: float
          description: Amount due for the tax return payment
          example: 53249.8
        dueDate:
          type: string
          format: date-time
          description: Payment due date
          example: '2019-01-03T21:10:40.000Z'
        code:
          description: Payment code
          type: string
          example: '0777555544443332222'
        bank:
          description: Payer bank
          type: string
          example: BBVA Bancomer, S.A.
        paidAmount:
          type: number
          format: float
          description: Tax return paid amount
        date:
          type: string
          format: date-time
          description: Payment date
        operationNumber:
          type: string
          description: Bank operation number for the payment
          example: '123456'
    Taxpayer:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: Taxpayer IRI reference
          example: /taxpayers/PEIC211118IS0
        '@type':
          type: string
          default: Taxpayer
        id:
          $ref: '#/components/schemas/TaxpayerID'
        personType:
          $ref: '#/components/schemas/TaxpayerPersonType'
        registrationDate:
          type: string
          format: date
          description: Taxpayer registration date
        name:
          $ref: '#/components/schemas/TaxpayerName'
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    TaxpayerTaxReturnCollection:
      description: Taxpayer tax return collection response
      content:
        application/ld+json:
          schema:
            $ref: '#/components/schemas/TaxpayerTaxReturnCollection'
    TaxReturnData:
      description: Extracted data from tax returns
      content:
        application/json:
          schema:
            type: object
          examples:
            financial_statements_2022:
              summary: Financial statements 2022 format
              value:
                ESTADO DE RESULTADOS:
                  Pérdida neta:
                    Notas: This field may contains a comment from the respective line
                    Total: 123
                    Partes Relacionadas: null
                    Partes No Relacionadas: null
                  Utilidad neta:
                    Notas: null
                    Total: null
                    Partes Relacionadas: null
                    Partes No Relacionadas: null
                  Ingresos Netos:
                    Notas: null
                    Total: 123
                    Sin Ingresos:
                      Notas: null
                      Total: null
                      Partes Relacionadas: null
                      Partes No Relacionadas: null
                    Otros Ingresos:
                      Notas: null
                      Total: null
                      Partes Relacionadas: null
                      Partes No Relacionadas: null
                    Primas cedidas:
                      Notas: null
                      Total: null
                      Partes Relacionadas: null
                      Partes No Relacionadas: null
                    Primas emitidas:
                      Notas: null
                      Total: null
                      Partes Relacionadas: null
                      Partes No Relacionadas: null
                    Partes Relacionadas: 0
                    Gastos por intereses:
                      Notas: null
                      Total: null
                      Partes Relacionadas: null
                      Partes No Relacionadas: null
                    Ingresos por intereses:
                      Notas: null
                      Total: null
                      Partes Relacionadas: null
                      Partes No Relacionadas: null
                    Partes No Relacionadas: 123
                    Ventas y/o servicios nacionales:
                      Notas: null
                      Total: 123
                      Partes Relacionadas: 0
                      Partes No Relacionadas: 123
                    Ventas y/o servicios extranjeros:
                      Notas: null
                      Total: null
                      Partes Relacionadas: null
                      Partes No Relacionadas: null
                    Estimación preventiva para riesgos crediticios:
                      Notas: null
                      Total: null
                      Partes Relacionadas: null
                      Partes No Relacionadas: null
                    Devoluciones, descuentos y bonificaciones nacionales:
                      Notas: null
                      Total: null
                      Partes Relacionadas: null
                      Partes No Relacionadas: null
                    Devoluciones, descuentos y bonificaciones extranjeras:
                      Notas: null
                      Total: null
                      Partes Relacionadas: null
                      Partes No Relacionadas: null
                    Estimación preven

# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/syntage/refs/heads/main/openapi/syntage-ds-mx-sat-tax-returns-api-openapi.yml