Convenciones de la API

Las rutas de esta sección son relativas a /v1/workspaces/{workspaceId}. Usa Content-Type: application/json en escrituras con JSON. Los nombres usan camelCase; los campos y parámetros desconocidos o repetidos se rechazan.

Respuestas y fechas

Un recurso devuelve {data, requestId}. Un listado devuelve {data: [], nextCursor, requestId}. Los errores usan application/problem+json y un code estable; conserva también X-Request-Id para diagnóstico.

Los instantes son strings UTC con Z, por ejemplo 2026-10-18T15:30:00.123456Z, con precisión máxima de microsegundos. Se rechaza precisión que se perdería al persistir. Fechas civiles como cumpleaños usan YYYY-MM-DD. La zona de un perfil usa un nombre IANA o UTC.

Paginación y filtros

limit admite enteros de 1 a 100, con 50 por defecto. Usa nextCursor como cursor sin modificarlo y conserva recurso, workspace y filtros. Termina cuando sea null; no hay paginación por número de página.

Contactos admite email, emailSubscriptionStatus y archived; emails admite purpose, contactId y submissionStatus. Los recursos con archivo muestran activos por defecto. La analítica tiene su propio contrato de filtros, sin cursor.

Idempotencia en mutaciones

Envía Idempotency-Key en cada mutación; debe ser no vacía y tener hasta 128 caracteres. Genera una por operación lógica y conserva cuerpo y precondición exactos al reintentar una solicitud cuya respuesta se perdió.

La misma identidad, operación y clave devuelve el resultado guardado si la entrada coincide. Cambiar cuerpo o revisión produce 409 idempotency_conflict. Una operación nueva necesita una clave nueva. La autorización vigente se comprueba incluso al repetir una operación.

Ediciones con revisión

Lee el recurso y conserva su ETag. Envíalo sin cambios en If-Match para PATCH de contactos y comandos que exigen revisión, como guardar campos o audiencias y archivar/restaurar recursos.

If-Match: "contact-CONTACT_ID-r3"
Idempotency-Key: profile-update-unique-operation

Contactos usa un ETag ligado al ID; otros recursos revisados usan "rN". Falta de precondición devuelve 428; revisión obsoleta, 412. Vuelve a leer, reconcilia los cambios y crea otra operación. El upsert por email no exige revisión y aplica los campos aportados por orden de commit.

Trabajo asíncrono y capacidad

Un 202 confirma admisión, no finalización. Usa el ID y, cuando se incluya, Location para consultar estado. Envíos reservan cuota del producto y mes UTC originales; aceptación del transporte consume, rechazo conocido libera e incertidumbre conserva la reserva. Consulta errores y consumo.