GraphQL API

API GraphQL para interactuar con Xipher. GraphQL proporciona una interfaz más flexible y eficiente que REST, permitiendo solicitar exactamente los datos que necesitas.

Endpoint

https://api.xipher.app/prd/graphql

En desarrollo, GraphiQL está habilitado automáticamente para explorar la API de forma interactiva.

Autenticación

Mediante Bearer Token en el Header (igual que la REST API):

Authorization: Bearer NTJjMTUyM2QzMzBkYTY0M2UyYzkxZmY5N2M0OTVmOWI6ODcxYzZiNjg4YjAzODE3MTJhNjRkNGQxM2NkMmYyZTY=

Ventajas de GraphQL

• Solicita solo los datos que necesitas: Evita over-fetching y under-fetching
• Una sola petición: Obtén múltiples recursos en una sola consulta
• Tipado fuerte: Schema bien definido con validación automática
• Paginación eficiente: Cursor-based pagination para grandes conjuntos de datos
• Filtrado flexible: Múltiples opciones de filtrado combinables

Queries

Documentos Recibidos

Obtiene la lista de documentos recibidos con paginación. Si no se proporcionan fechas, se usa por defecto desde ayer hasta hoy.

query {
  receivedDocuments(
    accountId: "your_account_id"
    filter: {
      fromDate: "2024-01-01"
      toDate: "2024-01-31"
      docType: "01"
      docNumber: "001-001-000000040"
    }
    pagination: {
      limit: 20
      cursor: "507f1f77bcf86cd799439011"
    }
  ) {
    documents {
      id
      accessKey
      type
      sriType
      number
      authorization
      authorizationDate
      issueDate
      environment
      nif
      legalName
      nifPartner
      legalNamePartner
      status
      subtotal
      tax
      total
    }
    pageInfo {
      hasNextPage
      nextCursor
      limit
      totalCount
    }
  }
}

Parámetros de filtro:

• fromDate (opcional): Fecha de inicio. Default: ayer
• toDate (opcional): Fecha de fin. Default: hoy
• docType (opcional): Tipo de documento (01, 03, 04, 05, 06, 07)
• docNumber (opcional): Número de documento (formato: 001-001-000000040)

Parámetros de paginación:

• limit (opcional): Límite de resultados (default: 200, max: 500)
• cursor (opcional): Cursor para paginación (ObjectId del último documento de la página anterior)

Documentos Emitidos

Obtiene la lista de documentos emitidos con paginación:

query {
  issuedDocuments(
    accountId: "your_account_id"
    filter: {
      fromDate: "2024-01-01"
      toDate: "2024-01-31"
      docType: "01"
      docStatus: "AUTORIZADO"
    }
    pagination: {
      limit: 20
      cursor: "507f1f77bcf86cd799439011"
    }
  ) {
    documents {
      id
      accessKey
      type
      number
      authorization
      authorizationDate
      issueDate
      environment
      nif
      legalName
      nifPartner
      legalNamePartner
      status
    }
    pageInfo {
      hasNextPage
      nextCursor
      totalCount
    }
  }
}

Parámetros de filtro adicionales:

• docStatus (opcional): Estado del documento (AUTORIZADO, RECIBIDA, etc.)

Obtener PDF de Documento

query {
  documentPDF(accessKey: "2412202301171645368100110010010000000405913672311")
}

Respuesta: String base64 del PDF

Obtener XML de Documento

query {
  documentXML(accessKey: "2412202301171645368100110010010000000405913672311")
}

Respuesta: String base64 del XML

Obtener PDF de Documento Recibido

query {
  receivedDocumentPDF(
    accountId: "your_account_id"
    accessKey: "2412202301171645368100110010010000000405913672311"
  )
}

Obtener XML de Documento Recibido

query {
  receivedDocumentXML(
    accountId: "your_account_id"
    accessKey: "2412202301171645368100110010010000000405913672311"
  )
}

Mutations

Firmar Documento

Firma un documento XML electrónico:

mutation {
  signDocument(input: {
    xml: "base64_encoded_xml_string"
    userId: "your_user_id"
  }) {
    signedXml
  }
}

Validar Documento

Firma y envía el documento al SRI para validación:

mutation {
  validateDocument(input: {
    xml: "base64_encoded_xml_string"
    userId: "your_user_id"
  }) {
    signedXml
    estado
    accessKey
    identificador
    mensaje
    informacionAdicional
    tipo
  }
}

Respuesta exitosa:

{
  "signedXml": "base64_encoded_signed_xml",
  "estado": "RECIBIDA",
  "accessKey": "clave_de_acceso"
}

Respuesta con error:

{
  "signedXml": "base64_encoded_signed_xml",
  "estado": "DEVUELTA",
  "accessKey": "clave_de_acceso",
  "identificador": "codigo_error",
  "mensaje": "mensaje_de_error",
  "tipo": "tipo_error",
  "informacionAdicional": "informacion_adicional"
}

Autorizar Documento (GET)

Obtiene el estado de autorización de un documento:

mutation {
  authorizeDocument(
    accessKey: "2412202301171645368100110010010000000405913672311"
    forceSriResponse: false
  ) {
    estado
    authXml
    numeroAutorizacion
    fechaAutorizacion
    identificador
    mensaje
    tipo
    informacionAdicional
  }
}

Parámetros:

• accessKey (requerido): Clave de acceso del documento
• forceSriResponse (opcional): Si es true, fuerza la consulta al SRI incluso si el documento ya está autorizado

Autorizar Documento (POST)

Versión POST del endpoint de autorización:

mutation {
  authorizeDocumentPost(input: {
    clave: "2412202301171645368100110010010000000405913672311"
    userId: "your_user_id"
  }) {
    estado
    authXml
    numeroAutorizacion
    fechaAutorizacion
    identificador
    mensaje
    tipo
    informacionAdicional
  }
}

Tipos de Documentos

Los códigos de tipo de documento son:

• 01: FACTURA
• 03: LIQUIDACIÓN DE COMPRA
• 04: NOTA DE CRÉDITO
• 05: NOTA DE DÉBITO
• 06: GUÍA DE REMISIÓN
• 07: COMPROBANTE DE RETENCIÓN

Variables

Puedes usar variables para hacer las consultas más dinámicas:

query GetDocuments($accountId: String!, $limit: Int, $cursor: String) {
  receivedDocuments(
    accountId: $accountId
    pagination: {
      limit: $limit
      cursor: $cursor
    }
  ) {
    documents {
      id
      accessKey
      type
    }
    pageInfo {
      hasNextPage
      nextCursor
    }
  }
}

Variables JSON (primera página):

{
  "accountId": "your_account_id",
  "limit": 20,
  "cursor": null
}

Variables JSON (página siguiente, usando nextCursor de la respuesta anterior):

{
  "accountId": "your_account_id",
  "limit": 20,
  "cursor": "507f1f77bcf86cd799439011"
}

Nota: El cursor es el ObjectId del último documento de la página anterior. Se obtiene del campo nextCursor en la respuesta pageInfo.

Errores

GraphQL devuelve errores en un formato estándar:

{
  "errors": [
    {
      "message": "Clave de acceso inválida",
      "path": ["authorizeDocument"]
    }
  ],
  "data": {
    "authorizeDocument": null
  }
}

Notas Importantes

• Fechas: Todos los campos de fecha usan formato ISO 8601 (YYYY-MM-DD o YYYY-MM-DDTHH:mm:ss.sssZ)
• Base64: XML y PDF se devuelven como strings codificados en base64
• Autenticación: El userId se extrae automáticamente del token de autenticación
• Fechas por defecto: Al consultar documentos recibidos sin especificar fechas, se usa desde ayer hasta hoy
• Paginación: El cursor es un ObjectId (ID del documento) del último elemento de la página anterior. Se obtiene del campo nextCursor en la respuesta pageInfo
• Límites: El límite máximo para documentos recibidos es 500, para emitidos es 20 por defecto

GraphiQL

En modo desarrollo, puedes acceder a GraphiQL en:

https://api.xipher.app/dev/graphql

GraphiQL proporciona:

• Exploración interactiva del schema
• Autocompletado
• Validación de queries
• Documentación integrada
• Ejecución de queries y mutations

Comparación con REST API

Característica	REST API	GraphQL
Over-fetching	Sí	No
Múltiples requests	Sí	No (una sola query)
Tipado	Manual	Automático
Documentación	OpenAPI	Schema integrado
Versionado	URL-based	Schema-based
Paginación	Query params	Cursor-based

Ejemplos de Uso

Ejemplo 1: Obtener documentos recibidos y emitidos en una sola petición

query Dashboard($accountId: String!) {
  receivedDocuments(
    accountId: $accountId
    pagination: { limit: 10 }
  ) {
    documents {
      id
      type
      number
      total
      authorizationDate
    }
    pageInfo {
      totalCount
    }
  }
  
  issuedDocuments(
    accountId: $accountId
    pagination: { limit: 10 }
  ) {
    documents {
      id
      type
      number
      authorizationDate
      status
    }
    pageInfo {
      totalCount
    }
  }
}

Ejemplo 2: Flujo completo de documento

# 1. Firmar documento
mutation Sign($xml: String!, $userId: String!) {
  signDocument(input: {
    xml: $xml
    userId: $userId
  }) {
    signedXml
  }
}

# 2. Validar documento
mutation Validate($xml: String!, $userId: String!) {
  validateDocument(input: {
    xml: $xml
    userId: $userId
  }) {
    signedXml
    estado
    accessKey
  }
}

# 3. Autorizar documento
mutation Authorize($accessKey: String!) {
  authorizeDocument(accessKey: $accessKey) {
    estado
    numeroAutorizacion
    fechaAutorizacion
  }
}

# 4. Obtener PDF
query GetPDF($accessKey: String!) {
  documentPDF(accessKey: $accessKey)
}