Guía API: sincronizar contactos CardDAV

Al terminar

Vas a tener este flujo funcionando.

Listar libretas y contactos accesibles.
Crear una vCard con una clave idempotente.
Actualizar sólo cuando el ETag todavía coincide.

Implementación

Seguí el contrato en este orden.

Leé la fuente vigente

GET /contacts.php devuelve libretas y contactos del usuario autorizado. Usá page y perPage para colecciones grandes.

Guardá identidad y versión

Persistí addressBook, uri y etag. No uses el nombre o el email como identificador estable.

Creá con idempotencia

POST /contacts.php admite Idempotency-Key. El payload puede incluir nombre, email, teléfono, organización y categorías.

Actualizá con ETag

En PATCH enviá la libreta, la URI y el ETag leído. Si otra aplicación cambió la vCard, PietroCal rechaza la escritura concurrente.

Endpoints

Superficie utilizada.

GET /api/v1/contacts.php?page=1&perPage=50 Listar libretas y contactos

POST /api/v1/contacts.php Crear contacto

PATCH /api/v1/contacts.php?addressBook={book}&uri={uri} Actualizar con control de versión

export PIETROCAL_API_TOKEN="pc_live_TU_TOKEN"
export ADDRESS_BOOK_URI="contacts"
export CONTACT_URI="cliente-ejemplo.vcf"
export CONTACT_ETAG="etag-leido-previamente"

curl -sS \
  "https://pietrocal.com/api/v1/contacts.php?page=1&perPage=50" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $PIETROCAL_API_TOKEN"

curl -i -sS -X PATCH \
  "https://pietrocal.com/api/v1/contacts.php?addressBook=$ADDRESS_BOOK_URI&uri=$CONTACT_URI" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PIETROCAL_API_TOKEN" \
  --data-binary "{
    \"addressBook\": \"$ADDRESS_BOOK_URI\",
    \"uri\": \"$CONTACT_URI\",
    \"etag\": \"$CONTACT_ETAG\",
    \"displayName\": \"Cliente Ejemplo\",
    \"email\": \"cliente@example.com\",
    \"organization\": \"Estudio Norte\",
    \"categories\": [\"Cliente\", \"Seguimiento\"]
  }"

Antes de publicar

Lista de verificación.

Usá la libreta devuelta por la API; no inventes una URI.
Conservá el ETag nuevo después de cada escritura exitosa.
Si hay conflicto, releé la vCard y resolvé la diferencia antes de reintentar.
Paginá los listados con un máximo de 100 elementos por página.

Errores esperables

Tratamiento mínimo.

403 api_scope_required

Falta contacts:read o contacts:write.

404

La libreta o la URI ya no existe para el usuario autorizado.

409

El ETag quedó desactualizado por una edición concurrente.

422

Algún campo, categoría o canal no cumple el contrato de la vCard.

Sincronizá contactos sin pisar cambios concurrentes.