Listar documentos

This endpoint is cached by default with a TTL of 60 seconds.

Listar documentos

GET https://api.zapsign.com.br/api/v1/docs/?page=1

Este endpoint permite listar todos los documentos de su cuenta. Por defecto, los resultados se devuelven de forma paginada.

---

Parámetros de URL (Query Params)

Parámetro	Tipo	Descripción
page	integer	Número de página para la navegación (ej: ?page=2).
status	string	Filtra por estado: pending (en curso), signed (firmado) o refused (rechazado).
folder_path	string	Filtra documentos en una carpeta específica. Use / para la raíz.
deleted	boolean	true para listar solo eliminados; false para activos.
signer_email	string	Filtra documentos que tengan un firmante con este correo electrónico.
created_from	string	Fecha inicial (formato YYYY-MM-DD).
created_to	string	Fecha final (formato YYYY-MM-DD).
sort_order	string	Orden por fecha de creación: asc (antiguos) o desc (nuevos).
include_signers	boolean	(Nuevo) Use true, 1 o yes para incluir el array de firmantes en cada documento.

---

Headers (Encabezados)

Nombre	Tipo	Descripción
Authorization*	string	API token precedido por la palabra "Bearer". Ej: Bearer c7f35c84-7893-4087-b4fb-d1f06c23

---

Detalles del parámetro include_signers

Al activar este parámetro, la API devolverá el campo signers dentro de cada documento, con información detallada:

• Campos incluidos: Nombre, email, teléfono, modo de autenticación (auth_mode), flag de certificado digital, timestamps de interacción, URL de firma y orden de firma (si el orden está activo).
• Estado del Firmante: Expuesto a través de un enum estable:

  • nao_abriu (no abrió)
  • abriu (abrió)
  • assinou (firmó)
  • recusou (rechazó)
  • expirou (expiró)
  • cancelado (cancelado)

    (Nota: Los estados a nivel de documento tienen precedencia sobre el estado individual cuando corresponda).

---

Notas importantes

• Consistencia JSON: Los strings vacíos se normalizan a null en la respuesta de la API.
• Rendimiento Optimizado: El endpoint utiliza prefetch_related para evitar problemas de consultas N+1 al solicitar los firmantes, garantizando respuestas rápidas incluso en listados voluminosos.
• Enlaces Temporales: Los campos original_file y signed_file devuelven enlaces que expiran en 60 minutos.
• Caché: Existe un caché de 60 segundos para este endpoint. Si acaba de crear un documento, puede tardar hasta un minuto en aparecer en esta lista.

---

Ejemplos de Respuesta (JSON)

Ejemplo con include_signers = True

{
    "count": 120,
    "next": "https://api.zapsign.com.br/api/v1/docs/?page=2",
    "previous": null,
    "results": [
        {
            "token": "4f9e-a1b2-c3d4",
            "name": "Contrato de Prestación de Servicios",
            "status": "pending",
            "original_file": "https://s3.amazonaws.com/...",
            "signed_file": null,
            "created_at": "2024-03-25T14:30:00Z",
            "folder_path": "/",
            "signers": [
                {
                    "name": "Juan Pérez",
                    "email": "[e-mail]",
                    "status": "abriu",
                    "auth_mode": "assinatura_tela",
                    "signing_url": "https://zapsign.com.br/sign/...",
                    "has_certificate": false,
                    "order": 1
                }
            ]
        }
    ]
}

Consejo: En lugar de consultar los documentos varias veces al día, utilice nuestros Webhooks. Además de ahorrar capacidad computacional en nuestros servidores y los suyos, podrá dar feedback en tiempo real a su usuario.

Atención: Los enlaces devueltos en original_file y signed_file son temporales y duran 60 minutos. Si su sistema necesita guardar estos enlaces, se recomienda descargarlos en una CDN propia o consultar este endpoint siempre para asegurar que el usuario reciba un enlace válido.