Syntage DS MX SAT Invoice Line Items API

openapi: 3.2.0
info:
  version: '2020-06-28'
  title: Syntage DS MX SAT Invoice Line Items API
  contact:
    name: Email
    email: support@syntage.com
  description: '# Introduction


    The Syntage API is organized around REST.'
servers:
- url: https://api.syntage.com
  description: Production
- url: https://api.sandbox.syntage.com
  description: Sandbox
security:
- ApiKey: []
tags:
- name: DS MX SAT Invoice Line Items
paths:
  /invoices/line-items/{id}:
    get:
      tags:
      - DS MX SAT Invoice Line Items
      summary: Retrieve an invoice line item
      operationId: GetInvoiceLineItem
      description: Retrieve an invoice line item by ID, including product, quantity, amount, and tax details.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: Invoice Line Item ID
          example: 91106968-1abd-4d64-85c1-4e73d96fb997
      responses:
        '200':
          description: Invoice Line Items response
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/InvoiceLineItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices/{invoiceId}/line-items:
    get:
      tags:
      - DS MX SAT Invoice Line Items
      summary: List an invoice's line items
      description: List line items from the requested invoice.
      operationId: ListInvoiceLineItems
      parameters:
      - $ref: '#/components/parameters/invoiceId'
      - $ref: '#/components/parameters/collectionCursorNextPageParam'
      - $ref: '#/components/parameters/collectionCursorPreviousPageParam'
      - $ref: '#/components/parameters/collectionLimit'
      responses:
        '200':
          description: Invoice's Line Items collection response
          content:
            application/ld+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CursorCollection'
                - type: object
                  properties:
                    '@context':
                      default: /contexts/InvoiceLineItem
                    '@id':
                      default: /invoices/line-items
                    hydra:member:
                      items:
                        $ref: '#/components/schemas/InvoiceLineItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /entities/{entityId}/invoices/line-items:
    get:
      tags:
      - DS MX SAT Invoice Line Items
      summary: List an entity's invoice line items
      description: List invoice line items extracted for an entity.
      operationId: ListEntityInvoiceLineItems
      parameters:
      - $ref: '#/components/parameters/entityId'
      - $ref: '#/components/parameters/collectionCursorNextPageParam'
      - $ref: '#/components/parameters/collectionCursorPreviousPageParam'
      - $ref: '#/components/parameters/collectionLimit'
      responses:
        '200':
          description: Entity's Invoice Line Items collection response
          content:
            application/ld+json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CursorCollection'
                - type: object
                  properties:
                    '@context':
                      default: /contexts/InvoiceLineItem
                    '@id':
                      example: /entities/91ab5678-1234-5678-9abc-def012345678/invoices/line-items
                    hydra:member:
                      items:
                        $ref: '#/components/schemas/InvoiceLineItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    InvoicePaymentTerms:
      type:
      - string
      - 'null'
      enum:
      - immediate_payment
      - net_0
      - net_15
      - net_30
      - net_45
      - net_90
      - net_120
      example: immediate_payment
      description: Payment terms
    InvoiceIssuerTaxRegime:
      type:
      - number
      - 'null'
      enum:
      - 601
      - 603
      - 605
      - 606
      - 607
      - 608
      - 609
      - 610
      - 611
      - 612
      - 614
      - 615
      - 616
      - 620
      - 621
      - 622
      - 623
      - 624
      - 625
      - 626
      - 628
      - 629
      - 630
      description: Tax regime code from the [c_RegimenFiscal](/guides/catalogs#c_regimenfiscal) catalog
      example: 601
      externalDocs:
        url: https://syntage.com/docs/catalogs#c_regimenfiscal
    InvoiceCollectionItem:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: Invoice IRI reference
          example: /invoices/91106968-1abd-4d64-85c1-4e73d96fb997
        '@type':
          type: string
          default: Invoice
        id:
          $ref: '#/components/schemas/InvoiceID'
        uuid:
          $ref: '#/components/schemas/InvoiceUUID'
        version:
          $ref: '#/components/schemas/InvoiceVersion'
        reference:
          $ref: '#/components/schemas/InvoiceReference'
        internalIdentifier:
          $ref: '#/components/schemas/InvoiceInternalIdentifier'
        type:
          $ref: '#/components/schemas/InvoiceType'
        usage:
          $ref: '#/components/schemas/InvoiceUsage'
        paymentType:
          $ref: '#/components/schemas/InvoicePaymentType'
        paymentMethod:
          $ref: '#/components/schemas/InvoicePaymentMethod'
        paymentTerms:
          $ref: '#/components/schemas/InvoicePaymentTerms'
        placeOfIssue:
          $ref: '#/components/schemas/InvoicePlaceOfIssue'
        issuer:
          $ref: '#/components/schemas/InvoiceIssuer'
        isIssuer:
          $ref: '#/components/schemas/InvoiceIsIssuer'
        receiver:
          $ref: '#/components/schemas/InvoiceReceiver'
        isReceiver:
          $ref: '#/components/schemas/InvoiceIsReceiver'
        currency:
          $ref: '#/components/schemas/InvoiceCurrency'
        discount:
          $ref: '#/components/schemas/InvoiceDiscount'
        tax:
          $ref: '#/components/schemas/InvoiceTax'
        subtotal:
          $ref: '#/components/schemas/InvoiceSubtotal'
        creditedAmount:
          $ref: '#/components/schemas/InvoiceCreditedAmount'
        subtotalCreditedAmount:
          $ref: '#/components/schemas/InvoiceSubtotalCreditedAmount'
        total:
          $ref: '#/components/schemas/InvoiceTotal'
        exchangeRate:
          $ref: '#/components/schemas/InvoiceExchangeRate'
        paidAmount:
          $ref: '#/components/schemas/InvoicePaidAmount'
        dueAmount:
          $ref: '#/components/schemas/InvoiceDueAmount'
        lastPaymentDate:
          $ref: '#/components/schemas/InvoiceLastPaymentDate'
        fullyPaidAt:
          $ref: '#/components/schemas/InvoiceFullyPaidAt'
        paymentTermsRaw:
          $ref: '#/components/schemas/InvoicePaymentTermsRaw'
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        pac:
          $ref: '#/components/schemas/InvoicePac'
        issuedAt:
          $ref: '#/components/schemas/InvoiceIssuedAt'
        certifiedAt:
          $ref: '#/components/schemas/InvoiceCertifiedAt'
        cancellationStatus:
          $ref: '#/components/schemas/InvoiceCancellationStatus'
        cancellationProcessStatus:
          $ref: '#/components/schemas/InvoiceCancellationStatusProcess'
        canceledAt:
          $ref: '#/components/schemas/InvoiceCanceledAt'
        relations:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceRelation'
        xml:
          $ref: '#/components/schemas/InvoiceHasXML'
        pdf:
          $ref: '#/components/schemas/InvoiceHasPDF'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    InvoiceVersion:
      type:
      - number
      - 'null'
      format: float
      enum:
      - 3.2
      - 3.3
      - 4.0
      description: CFDI version
      example: 3.3
    updatedAt:
      type: string
      description: Date and time the resource was last updated
      example: '2020-01-01T12:15:00.000Z'
    InvoiceReceiver:
      type: object
      properties:
        rfc:
          $ref: '#/components/schemas/TaxpayerID'
        name:
          $ref: '#/components/schemas/TaxpayerName'
        blacklistStatus:
          $ref: '#/components/schemas/TaxpayerBlacklistStatus'
    CollectionLimit:
      type: integer
      default: 20
      minimum: 1
      maximum: 1000
    RetainedTaxes:
      type: object
      properties:
        valueAddedTax:
          type: number
          format: double
          description: Retained value-added tax amount
          example: 0
        incomeTax:
          type: number
          format: double
          description: Retained income tax amount
          example: 0
        sinTax:
          type: number
          format: double
          description: Retained special tax on production and services amount
          example: 0
    InvoiceIsIssuer:
      type: boolean
      description: '`true` if the invoice issuer is the entity''s RFC

        '
      example: true
    InvoiceReference:
      type:
      - string
      - 'null'
      description: An open field for internal identification. Commonly used to identify a branch
      maxLength: 25
      example: Branch-A
    InvoiceIssuer:
      type: object
      properties:
        rfc:
          $ref: '#/components/schemas/TaxpayerID'
        name:
          $ref: '#/components/schemas/TaxpayerName'
        taxRegime:
          $ref: '#/components/schemas/InvoiceIssuerTaxRegime'
        blacklistStatus:
          $ref: '#/components/schemas/TaxpayerBlacklistStatus'
      example:
        rfc: AOM920820BEA
        name: APPLE OPERATIONS MEXICO S.A. DE C.V.
        taxRegime: 601
        blacklistStatus: null
    InvoiceDiscount:
      type: number
      format: float
      description: Discount amount
      example: 3324
    InvoicePaidAmount:
      type: number
      format: float
      description: For a deferred invoice this field state the paid amount. (Applies only for "PPD" invoices).
      example: 53249.8
    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
    Tag:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: Resource tag IRI reference
          example: /tags/91106968-1abd-4d64-85c1-4e73d96fb997
        '@type':
          type: string
          description: JSON-LD resource type
          default: Tag
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          description: Display name for the tag
          example: To be reviewed
        resourceType:
          type: string
          description: Resource type this tag can be applied to
          example: invoice
        color:
          type:
          - string
          - 'null'
          description: Lowercase 7-character hexadecimal color used to display the tag (`#RRGGBB`). Defaults to `#a3aab5` when a tag is created without a color.
          example: '#22c558'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    InvoiceIssuedAt:
      type: string
      format: date-time
      description: Invoice issue date
      example: '2019-01-03T21:10:40.000Z'
    InvoiceID:
      type: string
      format: uuid
      description: Invoice ID
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
    InvoiceCancellationStatus:
      type: string
      enum:
      - Cancelable sin aceptación
      - Cancelable con aceptación
      - No cancelable
      description: Whether or not the invoice can be canceled
      example: Cancelable con aceptación
    TagCollection:
      type: array
      items:
        $ref: '#/components/schemas/Tag'
    InvoiceFullyPaidAt:
      type:
      - string
      - 'null'
      format: date-time
      description: This field is populated when the total debt is paid. (Applies only for "PPD" invoices).
    TaxpayerName:
      type: string
      minLength: 1
      maxLength: 254
      description: Taxpayer name
      example: Pedro Infante Cruz
    InvoiceCanceledAt:
      type:
      - string
      - 'null'
      format: date-time
      description: Set when *status* is `CANCELADO`
    InvoiceLineItem:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: Invoice Line Item IRI reference
          example: /invoices/line-items/91106968-1abd-4d64-85c1-4e73d96fb997
        '@type':
          type: string
          default: InvoiceLineItem
        id:
          type: string
          format: uuid
          description: Invoice line item ID
          example: 91106968-1abd-4d64-85c1-4e73d96fb997
        invoice:
          $ref: '#/components/schemas/Invoice'
        identificationNumber:
          type:
          - string
          - 'null'
          description: Seller-provided item or SKU identifier
        productIdentification:
          type: string
          description: SAT product or service code from the [c_ClaveProdServ](/guides/catalogs#c_claveprodserv) catalog
          example: '50121537'
        description:
          type: string
          description: Line item description from the CFDI
          example: Apple iPhone
        unitAmount:
          type: number
          format: double
          description: Unit price before quantity is applied
          example: 70
        unitCode:
          type: string
          description: SAT unit code from the [c_ClaveUnidad](/guides/catalogs#c_claveunidad) catalog
          example: KGM
        quantity:
          type: number
          format: double
          description: Quantity billed for this line item
          example: 60
        discountAmount:
          type: number
          format: double
          description: Discount amount applied to this line item
          example: 0
        totalAmount:
          type: number
          format: double
          description: Total line item amount after quantity and discounts
          example: 4200
        retainedTaxes:
          $ref: '#/components/schemas/RetainedTaxes'
        transferredTaxes:
          $ref: '#/components/schemas/TransferredTaxes'
        taxes:
          type: array
          description: Deprecated raw CFDI tax breakdown; use `retainedTaxes` and `transferredTaxes` when possible
          deprecated: true
          items:
            type: object
            additionalProperties: true
          example:
          - type: transferred
            tax: '002'
            factor:
              type: Tasa
              amount: 0.16
            amount: 672
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    InvoiceTotal:
      type: number
      format: float
      description: Invoice total amount
      example: 53249.8
    InvoicePaymentMethod:
      type:
      - string
      - 'null'
      enum:
      - '01'
      - '02'
      - '03'
      - '04'
      - '05'
      - '06'
      - 08
      - '12'
      - '13'
      - '14'
      - '15'
      - '17'
      - '23'
      - '24'
      - '25'
      - '26'
      - '27'
      - '28'
      - '29'
      - '30'
      - '31'
      - '99'
      example: '04'
      description: Payment method code from the [c_FormaPago](/guides/catalogs#c_formapago) catalog
      externalDocs:
        url: https://syntage.com/docs/catalogs#c_formapago
    InvoiceHasPDF:
      type: boolean
      description: '`true` when the CFDI is available in the PDF format. The file can be downloaded through the [retrieve an invoice CFDI](#operation/GetInvoiceCFDI) operation

        '
    InvoiceHasXML:
      type: boolean
      description: '`true` when the CFDI is available in the XML format. The file can be downloaded through the [retrieve an invoice CFDI](#operation/GetInvoiceCFDI) operation

        '
    InvoiceInternalIdentifier:
      type:
      - string
      - 'null'
      description: An open field for internal identification. Commonly used to identify an invoice
      maxLength: 40
      example: '00001'
    TaxpayerBlacklistStatus:
      type:
      - string
      - 'null'
      description: Show the blacklist status if a taxpayer is found in the list 69-B from SAT
      example: presumed
      enum:
      - presumed
      - dismissed
      - definitive
      - favorable
    InvoicePac:
      type: string
      minLength: 12
      maxLength: 12
      description: Certification provider tax ID (Proveedor Autorizado de Certificación)
      example: SAT970701NN3
    InvoiceSubtotal:
      type: number
      format: float
      description: Subtotal amount
      example: 51349.8
    InvoicePaymentType:
      type:
      - string
      - 'null'
      enum:
      - PUE
      - PPD
      description: Payment type code from the [c_MetodoPago](/guides/catalogs#c_metodopago) catalog
      example: PUE
      externalDocs:
        url: https://syntage.com/docs/catalogs#c_metodopago
    TaxpayerID:
      type: string
      minLength: 12
      maxLength: 13
      description: RFC (Registro Federal de Contribuyentes)
      example: PEIC211118IS0
    InvoiceLastPaymentDate:
      type:
      - string
      - 'null'
      format: date-time
      description: This field is populated with the last related payment date (Applies only for "PPD" invoices).
    InvoiceUUID:
      type: string
      format: uuid
      description: Invoice UUID (Folio fiscal)
      example: def404af-5eef-4112-aa99-d1ec8493b89a
    createdAt:
      type: string
      description: Date and time the resource was created
      example: '2020-01-01T12:15:00.000Z'
    InvoiceRelationRelatedInvoice:
      type:
      - string
      - 'null'
      format: iri-reference
      description: Invoice IRI reference
      example: /invoices/92106967-2abd-5d64-95c2-4e73d96fb998
    InvoiceIsReceiver:
      type: boolean
      description: '`true` if the invoice receiver is the entity''s RFC

        '
      example: false
    InvoiceCancellationStatusProcess:
      type:
      - string
      - 'null'
      enum:
      - En proceso
      - Solicitud rechazada
      - Cancelado sin aceptación
      - Cancelado con aceptación
      - Plazo vencido
      description: Set when the cancellation process starts
      example: En proceso
    InvoiceUsage:
      type:
      - string
      - 'null'
      enum:
      - G01
      - G02
      - G03
      - I01
      - I02
      - I03
      - I04
      - I05
      - I06
      - I07
      - I08
      - D01
      - D02
      - D03
      - D04
      - D05
      - D06
      - D07
      - D08
      - D09
      - D10
      - S01
      - P01
      - CP01
      - CN01
      example: G03
      description: Invoice usage code from the [c_UsoCFDI](/guides/catalogs#c_usocfdi) catalog
      externalDocs:
        url: https://syntage.com/docs/catalogs/#c_usocfdi
    Invoice:
      allOf:
      - $ref: '#/components/schemas/InvoiceCollectionItem'
      - type: object
      properties:
        tags:
          $ref: '#/components/schemas/TagCollection'
    InvoiceTax:
      type: number
      format: float
      description: Tax amount
      example: 5224
    InvoiceExchangeRate:
      type:
      - number
      - 'null'
      format: float
      description: Set when *currency* is different than MXN (Mexican Peso).
      example: 19.8
    InvoiceCreditedAmount:
      type:
      - number
      - 'null'
      format: float
      description: Credited amount
      example: 31.32
    InvoiceCurrency:
      type:
      - string
      - 'null'
      description: ISO 4217 alphabetic currency code
      minLength: 3
      maxLength: 3
      example: MXN
    InvoicePlaceOfIssue:
      type: string
      example: '01210'
      description: Postal code of the place of issue
    InvoiceStatus:
      type: string
      enum:
      - VIGENTE
      - CANCELADO
      description: Whether the invoice is active or canceled
      example: VIGENTE
    InvoiceSubtotalCreditedAmount:
      type:
      - number
      - 'null'
      format: float
      description: Subtotal credited amount
      example: 27
    InvoiceRelationRelatedInvoiceUuid:
      type: string
      format: uuid
      description: The related Invoice UUID (Folio fiscal)
      example: def404af-5eef-4112-aa99-d1ec8493b89a
    InvoicePaymentTermsRaw:
      type:
      - string
      - 'null'
      example: Tarjeta de crédito
      description: The invoice payment terms text exactly as it comes from the invoice, i.e. immediate, 30 days, cash, credit card, etc
    InvoiceRelationInvoice:
      type: string
      format: iri-reference
      description: Invoice IRI reference
      example: /invoices/92106967-2abd-5d64-95c2-4e73d96fb998
    InvoiceRelationID:
      type: string
      format: uuid
      description: Invoice relation ID
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
    InvoiceDueAmount:
      type: number
      format: float
      description: For a deferred invoice this field state the due amount. (Applies only for "PPD" invoices).
      example: 0
    InvoiceRelation:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: Invoice Relation IRI reference
          example: /invoices/relations/93a197e7-6baa-5dc5-bf8d-fb1645a770c1
        '@type':
          type: string
          default: InvoiceRelation
        id:
          $ref: '#/components/schemas/InvoiceRelationID'
        type:
          $ref: '#/components/schemas/InvoiceRelationType'
        invoice:
          $ref: '#/components/schemas/InvoiceRelationInvoice'
        relatedInvoice:
          $ref: '#/components/schemas/InvoiceRelationRelatedInvoice'
        relatedInvoiceUuid:
          $ref: '#/components/schemas/InvoiceRelationRelatedInvoiceUuid'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    InvoiceType:
      type: string
      enum:
      - I
      - E
      - P
      - N
      - T
      description: Invoice type code from the [c_TipoDeComprobante](/guides/catalogs#c_tipodecomprobante) catalog
      externalDocs:
        url: https://syntage.com/docs/catalogs/#c_tipodecomprobante
    TransferredTaxes:
      type: object
      properties:
        valueAddedTax:
          type: number
          format: double
          description: Transferred value-added tax amount
          example: 0
        sinTax:
          type: number
          format: double
          description: Transferred special tax on production and services amount
          example: 0
    InvoiceCertifiedAt:
      type: string
      format: date-time
      description: Invoice certification date
      example: '2019-01-03T21:10:41.000Z'
    uuid:
      type: string
      format: uuid
      example: e0a24894-7fbf-48ae-bfb0-efaae30a6319
    InvoiceRelationType:
      type: number
      enum:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      - 9
      description: Invoice relation type code from the [c_TipoRelacion](/guides/catalogs#c_tiporelacion) catalog
      example: 7
      externalDocs:
        url: https://syntage.com/docs/catalogs/#c_tiporelacion
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  parameters:
    invoiceId:
      name: id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/InvoiceID'
    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
    entityId:
      name: entityId
      in: path
      required: true
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      schema:
        type: string
        format: uuid
    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
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Your API key is available in the [Production](https://app.syntage.com/settings/api-keys) and [Sandbox](https://app.sandbox.syntage.com/settings/api-keys) dashboards.

        '
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true