ConverterHQDevelopers
API v1

Convenciones de la API

Reglas HTTP, identificadores, paginación, fechas y cabeceras comunes de API v1.

Una integración robusta se apoya en convenciones estables para estados, IDs opacos, cursores y metadatos, no en detalles accidentales de un endpoint.

HTTP y códigos de estado

Las creaciones asíncronas devuelven 202 Accepted mientras el trabajo continúa; las lecturas correctas usan 200. Los errores siguen Problem Details y un code estable.

Identificadores y tiempo

Trata file_..., job_..., task_... y project_id como cadenas opacas. Los tiempos son ISO 8601 UTC; no deduzcas semántica del orden lexicográfico de los IDs.

Paginación por cursor

Las listas usan cursores opacos. Reenvía next_cursor sin modificar, conserva los filtros y nunca construyas un cursor en el cliente.

Cabeceras operativas

Envía Idempotency-Key en creaciones reintentables y guarda X-Request-ID. Respeta Retry-After y RateLimit-* antes de reintentar.