Listar documentos por estado

Este endpoint lista los documentos que creaste en una carpeta de trabajo. Con el filtro sign_status puedes traer solo los firmados, solo los pendientes o cualquier combinación de estados.

Método: GET https://api.digitafirma.com/v1/documents

Query Parameters

Campo	Tipo	Requerido	Descripción
company_id	string	Sí	ID de la carpeta de trabajo (consulta Listar carpetas de trabajo).
searchName	string	Sí	Texto que debe contener el nombre del archivo. Envíalo vacío (searchName=) para no filtrar por nombre.
sign_status	integer	No	Estado de firma del documento. Puedes enviar varios. Si lo omites, regresa todos los estados.
page	integer	No	Página a consultar. Empieza en 0.
size	integer	No	Documentos por página. Por defecto 20.
sort	string	No	Orden de los resultados, por ejemplo createdAt,desc para ver primero los más recientes.

---

Estados de firma (sign_status)

Valor	Estado	Significa
1	Sin firmar	Ningún firmante ha firmado todavía.
2	Firmado parcialmente	Al menos un firmante ya firmó, pero faltan otros.
3	Firmado	Todos los firmantes firmaron.
4	Rechazado	Un firmante rechazó el documento.

Cada documento de la respuesta trae su estado en attributes.sign_status. El atributo attributes.signed es true solo cuando sign_status es 3.

Filtros más comunes

Quiero listar…	Parámetros
Firmados	sign_status=3
Pendientes de firma (sin firmar y parciales)	sign_status=1&sign_status=2
Sin ninguna firma	sign_status=1
Rechazados	sign_status=4
Todos	(omite sign_status)

Varios estados a la vez

Para filtrar por varios estados repite el parámetro (sign_status=1&sign_status=2) o sepáralos con comas (sign_status=1,2). Las dos formas dan el mismo resultado.

---

Qué incluye el listado

Solo tus documentos

Regresa los documentos que creó el usuario de la X-Api-Key en esa carpeta. Los que crearon otros miembros de la carpeta no aparecen.

Sin archivados ni eliminados

Los documentos archivados se consultan en Listar documentos archivados. Los eliminados ya no aparecen en ningún listado.

Documentos donde eres firmante

Si otra cuenta te invitó a firmar, esos documentos se consultan en Listar documentos invitados.

Paginado

La respuesta trae una página a la vez. Revisa meta para saber cuántas páginas y documentos hay en total.

---

Paginación

La información de paginación viene en meta[0].page:

Campo	Descripción
total	Total de páginas.
totalItems	Total de documentos que cumplen el filtro.
initialItem	Posición del primer documento de la página, calculada como page × 20.

initialItem asume páginas de 20

initialItem siempre se calcula con 20 documentos por página, aunque envíes otro size. Si cambias size, calcula la posición tú mismo con page × size.

Para recorrer todos los resultados, pide page=0, page=1… hasta llegar a total - 1.

---

Ejemplo de integración

Firmados

curl --location 'https://api.digitafirma.com/v1/documents?company_id={company_id}&searchName=&sign_status=3&sort=createdAt,desc' \
--header 'X-Api-Key: {X-API-KEY}'

Pendientes

curl --location 'https://api.digitafirma.com/v1/documents?company_id={company_id}&searchName=&sign_status=1&sign_status=2&sort=createdAt,desc' \
--header 'X-Api-Key: {X-API-KEY}'

Respuesta Exitosa (200 OK)

Cada documento tiene la misma estructura que en Mostrar un documento. Aquí se muestran solo algunos atributos.

{
  "data": [
    {
      "type": "documents",
      "id": "ac110005-9df4-1d1b-819d-f60440bc003c",
      "links": {
        "self": "/documents/ac110005-9df4-1d1b-819d-f60440bc003c"
      },
      "attributes": {
        "file_name": "contrato-servicios.pdf",
        "sign_status": 3,
        "signed": true,
        "owner": "Juan Pérez <juan.perez@ejemplo.com>",
        "isOwner": true,
        "signed_at": "2026-05-06T10:15:32.481920",
        "created_at": "2026-05-04T20:42:47.172839"
      },
      "relationships": {
        "signatories": {
          "data": [
            {
              "type": "signatures",
              "id": "ac110005-9df4-1d1b-819d-f60440c7003d",
              "attributes": {
                "name": "María López",
                "email": "maria.lopez@ejemplo.com",
                "sign_status": "SIGNED"
              }
            }
          ]
        }
      }
    }
  ],
  "meta": [
    {
      "page": {
        "total": 3,
        "initialItem": 0,
        "totalItems": 47
      }
    }
  ],
  "links": {
    "self": "/documents"
  }
}

Error (400)

{
  "errors": [
    {
      "status": 400,
      "title": "Domain Error",
      "detail": "La compañia no pudo ser encontrada"
    }
  ]
}

---

Errores comunes

Código	Mensaje	Causa
400	La compañia no pudo ser encontrada	El company_id no existe.
400	—	Falta company_id o searchName en la petición.
401	—	Falta la X-Api-Key o no es válida.