Syntage DS MX SAT Credentials API

openapi: 3.2.0
info:
  version: '2020-06-28'
  title: Syntage DS MX SAT Credentials 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 Credentials
paths:
  /credentials:
    post:
      tags:
      - DS MX SAT Credentials
      operationId: CreateCredential
      summary: Create a credential
      description: 'Create a SAT credential for an RFC.

        If the RFC is not already associated with your organization, Syntage creates the related entity association as part of credential creation.'
      requestBody:
        $ref: '#/components/requestBodies/CredentialCreate'
      responses:
        '202':
          $ref: '#/components/responses/Credential'
        '400':
          $ref: '#/components/responses/ConstraintViolation'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      tags:
      - DS MX SAT Credentials
      operationId: ListCredential
      summary: List all credentials
      description: List SAT credentials available to your organization.
      responses:
        '200':
          $ref: '#/components/responses/CredentialCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
      parameters:
      - name: type
        in: query
        description: Filter by type (exact match)
        schema:
          $ref: '#/components/schemas/CredentialType'
      - name: rfc
        in: query
        description: Filter by RFC (Registro Federal de Contribuyentes, partial match)
        schema:
          type: string
          minLength: 12
          maxLength: 13
          example: PEIC211118IS0
      - name: status
        in: query
        description: Filter by status (exact match)
        schema:
          $ref: '#/components/schemas/CredentialStatus'
      - name: deactivatedAt[before]
        in: query
        description: Filter by deactivation date (less than or equal `<=`)
        example: '2020-01-17 11:47:27'
        schema:
          type: string
          format: date-time
      - name: deactivatedAt[strictly_before]
        in: query
        description: Filter by deactivation date (less than `<`)
        example: '2020-01-17 11:47:27'
        schema:
          type: string
          format: date-time
      - name: deactivatedAt[after]
        in: query
        description: Filter by deactivation date (greater than or equal `>=`)
        example: '2020-01-17 11:47:27'
        schema:
          type: string
          format: date-time
      - name: deactivatedAt[strictly_after]
        in: query
        description: Filter by deactivation date (greater than `>`)
        example: '2020-01-17 11:47:27'
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/createdAtBefore'
      - $ref: '#/components/parameters/createdAtStrictlyBefore'
      - $ref: '#/components/parameters/createdAtAfter'
      - $ref: '#/components/parameters/createdAtStrictlyAfter'
      - $ref: '#/components/parameters/orderCreatedAt'
      - $ref: '#/components/parameters/collectionPage'
      - $ref: '#/components/parameters/collectionLimit'
  /credentials/{id}:
    get:
      tags:
      - DS MX SAT Credentials
      operationId: GetCredential
      summary: Retrieve a credential
      description: Retrieve a SAT credential by ID, including its credential type, RFC, and validation status.
      parameters:
      - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          $ref: '#/components/responses/Credential'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - DS MX SAT Credentials
      summary: Delete a credential
      operationId: DeleteCredential
      description: Delete a SAT credential so it can no longer be used for new extraction work.
      parameters:
      - $ref: '#/components/parameters/resourceId'
      responses:
        '204':
          description: Credential resource deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /credentials/{id}/revalidate:
    post:
      tags:
      - DS MX SAT Credentials
      operationId: RevalidateCredential
      summary: Revalidate a credential
      description: Request validation for a SAT credential that is not already valid.
      parameters:
      - $ref: '#/components/parameters/resourceId'
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    collectionPage:
      name: page
      in: query
      required: false
      description: Collection page number
      schema:
        $ref: '#/components/schemas/CollectionPage'
    resourceId:
      name: id
      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'
    createdAtStrictlyAfter:
      name: createdAt[strictly_after]
      in: query
      description: Filter by resource creation date (greater than `>`)
      example: '2020-01-17 11:47:27'
      schema:
        type: string
        format: date-time
    createdAtStrictlyBefore:
      name: createdAt[strictly_before]
      in: query
      description: Filter by resource creation date (less than `<`)
      example: '2020-01-17 11:47:27'
      schema:
        type: string
        format: date-time
    orderCreatedAt:
      name: order[createdAt]
      in: query
      description: Order by resource creation date
      schema:
        $ref: '#/components/schemas/CollectionOrder'
    createdAtBefore:
      name: createdAt[before]
      in: query
      description: Filter by resource creation date (less than or equal `<=`)
      example: '2020-01-17 11:47:27'
      schema:
        type: string
        format: date-time
    createdAtAfter:
      name: createdAt[after]
      in: query
      description: Filter by resource creation date (greater than or equal `>=`)
      example: '2020-01-17 11:47:27'
      schema:
        type: string
        format: date-time
  schemas:
    updatedAt:
      type: string
      description: Date and time the resource was last updated
      example: '2020-01-01T12:15:00.000Z'
    CollectionPage:
      type: integer
      default: 1
    CollectionLimit:
      type: integer
      default: 20
      minimum: 1
      maximum: 1000
    CredentialStatus:
      type: string
      enum:
      - waiting
      - pending
      - valid
      - invalid
      - disabled
      - deactivated
      - error
      x-enumDeprecated:
        deactivated: Legacy status retained for existing records. The `disabled` status is used for credentials that can no longer be used.
      description: 'Credential validation status:


        | Value | Description |

        | --- | --- |

        | `waiting` | Credential validation is temporarily disabled, usually because of an ongoing incident. The credential will be validated later. |

        | `pending` | Credential validation has been requested and is waiting to be processed. |

        | `valid` | The credential was accepted by SAT and can be used for extractions. |

        | `invalid` | SAT rejected the credential during validation. |

        | `disabled` | SAT reported the credential as disabled or otherwise unrecoverable during validation. |

        | `deactivated` | **Deprecated.** Legacy status retained for existing records. The `disabled` status is used for credentials that can no longer be used. |

        | `error` | Credential validation failed because of an unexpected error. |

        '
      example: pending
    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
    CollectionOrder:
      type: string
      enum:
      - asc
      - desc
      example: asc
    CredentialCiecInput:
      type: object
      description: CIEC
      required:
      - type
      - rfc
      - password
      properties:
        type:
          type: string
          description: Credential type
        rfc:
          type: string
          minLength: 12
          maxLength: 13
          description: RFC (Registro Federal de Contribuyentes)
          example: PEIC211118IS0
        password:
          type: string
          minLength: 8
          writeOnly: true
          description: CIEC's password
          example: secret123
    Credential:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: SAT Credential IRI reference
          example: /credentials/91106968-1abd-4d64-85c1-4e73d96fb997
        '@type':
          type: string
          default: Credential
        id:
          type: string
          format: uuid
          description: Credential ID
          example: 91106968-1abd-4d64-85c1-4e73d96fb997
        type:
          $ref: '#/components/schemas/CredentialType'
        rfc:
          $ref: '#/components/schemas/TaxpayerID'
        status:
          $ref: '#/components/schemas/CredentialStatus'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    TaxpayerID:
      type: string
      minLength: 12
      maxLength: 13
      description: RFC (Registro Federal de Contribuyentes)
      example: PEIC211118IS0
    createdAt:
      type: string
      description: Date and time the resource was created
      example: '2020-01-01T12:15:00.000Z'
    CredentialEfirmaInput:
      type: object
      description: e.firma
      required:
      - type
      - certificate
      - privateKey
      - password
      properties:
        type:
          type: string
          description: Credential type
        certificate:
          type: string
          format: base64
          writeOnly: true
          description: Certificate file (.cer) content encoded in Base64
          example: MIIF7zCC...Pl1ai2M=
        privateKey:
          type: string
          format: base64
          writeOnly: true
          description: Private key file (.key) content encoded in Base64
          example: MIIFDjBA...e3Kov54=
        password:
          type: string
          writeOnly: true
          description: Private key password
          example: secret123
    CredentialType:
      type: string
      enum:
      - ciec
      - efirma
      example: ciec
    CredentialCollection:
      allOf:
      - $ref: '#/components/schemas/CursorCollection'
      - type: object
        properties:
          '@context':
            default: /contexts/Credential
          '@id':
            default: /credentials
          hydra:member:
            items:
              $ref: '#/components/schemas/Credential'
  requestBodies:
    CredentialCreate:
      required: true
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/CredentialCiecInput'
            - $ref: '#/components/schemas/CredentialEfirmaInput'
            discriminator:
              propertyName: type
              mapping:
                ciec: '#/components/schemas/CredentialCiecInput'
                efirma: '#/components/schemas/CredentialEfirmaInput'
  responses:
    ConstraintViolation:
      description: Validation error
      content:
        application/ld+json:
          schema:
            type: object
            properties:
              '@context':
                type: string
                default: /contexts/ConstraintViolation
              '@type':
                type: string
                default: ConstraintViolation
              hydra:title:
                type: string
                default: An error occurred
              hydra:description:
                type: string
                description: Concatenated violation messages
                example: 'exampleField: This value should not be blank.'
              violations:
                type: array
                items:
                  type: object
                  properties:
                    propertyPath:
                      type: string
                      description: Property access path
                      example: exampleField
                    message:
                      type: string
                      description: Validaton error message
                      example: This value should not be blank.
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    Credential:
      description: Credential resource response
      content:
        application/ld+json:
          schema:
            allOf:
            - type: object
              properties:
                '@context':
                  type: string
                  default: /contexts/Credential
            - $ref: '#/components/schemas/Credential'
    TooManyRequests:
      description: Too many requests
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Request limit defined for the time window.
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: The number of requests left for the time window.
        X-RateLimit-Reset:
          schema:
            type: string
            format: date-time
          description: The UTC date/time at which the current rate limit window resets.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    CredentialCollection:
      description: Credential collection response
      content:
        application/ld+json:
          schema:
            $ref: '#/components/schemas/CredentialCollection'
    Accepted:
      description: The request has been accepted and there's no content to return.
  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