Paginar y reintentar lecturas
Recorre colecciones completas con filtros estables y maneja fallos temporales sin duplicar escrituras.
Una integración que sincroniza documentos necesita leer más de una página y responder a interrupciones. Este ejemplo recorre sobres pendientes con consultas secuenciales y reintenta solamente lecturas GET.
Define el alcance de la consulta
Mantén los mismos filtros en todas las páginas. page empieza en 1 y perPage admite de 1 a 100. El máximo de página es un parámetro del contrato, no una cuota de consumo de la API.
El ejemplo usa type=DOCUMENT, status=PENDING, perPage=20 y orden ascendente por createdAt. Ajusta el tamaño de página a las necesidades de tu aplicación.
# GET admite reintentos; estas opciones no se trasladan a las escrituras.
curl --fail-with-body --retry 3 --retry-delay 1 --get \
'https://business.digito.do/api/v2/envelope' \
-H "Authorization: $DIGITO_API_TOKEN" \
--data-urlencode 'type=DOCUMENT' \
--data-urlencode 'status=PENDING' \
--data-urlencode 'page=1' \
--data-urlencode 'perPage=20' \
--data-urlencode 'orderByColumn=createdAt' \
--data-urlencode 'orderByDirection=asc'Repite la misma consulta con page=currentPage+1 mientras currentPage < totalPages. cURL respeta Retry-After en los errores que reintenta; los tres reintentos son una política de este ejemplo.
El tipo local describe una selección del contrato y no valida el JSON. Para trabajos muy grandes, almacena los IDs procesados en tu base de datos en lugar de conservarlos todos en memoria.
La colección puede cambiar
La paginación por página no promete una instantánea inmutable. Si otro proceso crea, distribuye o completa documentos mientras recorres la colección, los resultados pueden moverse. La deduplicación por id evita procesar dos veces un elemento recibido; no garantiza detectar un elemento que cambió de página.
Para sincronizaciones recurrentes, usa operaciones locales que puedan repetirse sin duplicar efectos y vuelve a reconciliar el conjunto. Guarda un resultado solamente después de completar su procesamiento.
No reutilices el reintento para escrituras
El helper anterior realiza GET; no recibe un método arbitrario. Una solicitud de creación o distribución puede haberse aplicado aunque la respuesta no llegue. Antes de repetir una escritura:
- Conserva el ID conocido y la referencia local del proceso.
- Consulta el sobre o verifica el resultado en Business.
- Decide si falta realmente una operación.
- Repite solo cuando puedas evitar borradores o comunicaciones duplicados.
externalId ayuda a relacionar un proceso, pero no garantiza idempotencia. No inventes una cabecera de deduplicación.
Parámetros de listado · Errores y diagnóstico · Límites y reintentos.