Google Contacts Sync API — OAuth and Sync Operations

The Google Contacts Sync module lets vacation rental operations teams push guest data directly into a shared Google Contacts account — keeping phone numbers, names, and property details organised without manual copy-paste. When Google is not yet connected, the same sync operations produce a downloadable CSV that can be imported manually into any contact manager. There are two data sources: the connected PMS API (for automated workflows) and a manually uploaded XLSX file (when PMS data is unavailable or when running a back-fill). Each source has its own sync and CSV export endpoint.

All endpoints require Authorization: Bearer <token> except GET /api/contactos/google/callback, which is a browser OAuth redirect target. POST, PUT, PATCH, and DELETE requests also require the X-CSRF-Token header.

GET /api/contactos/google/auth

Generates a Google OAuth 2.0 authorisation URL. Redirect the browser to the returned url to begin the consent flow. A CSRF-protected state parameter is embedded in the URL to prevent OAuth CSRF attacks. Auth required: Yes | Role: admin

Response

boolean

required

true

url

string

required

Full Google OAuth authorisation URL including scope, state, and redirect_uri. Redirect the user’s browser to this URL.

Example

curl https://api.example.com/api/contactos/google/auth \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&state=abc123&scope=..."
}

GET /api/contactos/google/callback

OAuth 2.0 callback endpoint. Google redirects the browser here after the user grants (or denies) consent. Tokens are exchanged server-side and stored encrypted. The browser is then redirected to the front-end profile page. Auth required: No (browser redirect — no JWT)

This endpoint is a browser redirect target, not a JSON API. Do not call it programmatically. If the state parameter is missing or invalid the request is treated as a potential CSRF attack and the user is redirected to the error page.

Query Parameters (set by Google)

code

string

Authorisation code from Google. Present on success.

state

string

Opaque state token set during the auth URL generation. Verified server-side.

error

string

Present when the user denies consent (e.g., access_denied).

Redirect Targets

Outcome	Redirect
Success	`/menu/perfil?google_conectado=true`
User denied	`/menu/perfil?google_error=acceso_denegado`
Invalid state	`/menu/perfil?google_error=estado_invalido`
Token exchange failed	`/menu/perfil?google_error=token_fallido`

GET /api/contactos/google/status

Returns whether the company currently has a Google account connected and, if so, which Google account email is linked. Auth required: Yes | Role: any

Response

boolean

required

true

google

object

required

Google connection status.

Show Google status fields

conectado

boolean

Whether a Google account is currently linked.

string | null

Email address of the linked Google account, or null.

Example

curl https://api.example.com/api/contactos/google/status \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "google": {
    "conectado": true,
    "email": "operaciones@miempresa.com"
  }
}

DELETE /api/contactos/google/conexion

Revokes the Google OAuth tokens and removes the stored credentials. After disconnecting, sync operations will fail until the account is reconnected. Auth required: Yes | Role: admin

Response

200 OK — {"ok": true} 404 Not Found — no Google connection exists for this company.

Example

curl -X DELETE https://api.example.com/api/contactos/google/conexion \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>"

GET /api/contactos/preferencias

Returns the sync preferences for the company, such as which guest fields are included in contacts and whether to overwrite existing entries. Auth required: Yes | Role: any

Response

boolean

required

true

preferencias

object

required

Company sync preferences object. Shape depends on the current configuration.

Example

curl https://api.example.com/api/contactos/preferencias \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "preferencias": {
    "incluir_telefono": true,
    "incluir_apartamento": true,
    "sobrescribir_existentes": false
  }
}

PUT /api/contactos/preferencias

Saves sync preferences for the company. Any user can update preferences (not just admins). Auth required: Yes | Role: any

Request

incluir_telefono

boolean

Include the guest’s phone number in the contact record.

incluir_apartamento

boolean

Include the apartment name as a note or label in the contact record.

sobrescribir_existentes

boolean

Whether to overwrite existing Google Contacts entries when a matching guest is found.

Response

boolean

required

true

preferencias

object

required

The saved preferences object.

Example

curl -X PUT https://api.example.com/api/contactos/preferencias \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"incluir_telefono": true, "incluir_apartamento": true, "sobrescribir_existentes": false}'

POST /api/contactos/sincronizacion

Fetches reservations from the connected PMS for the given date range and syncs each guest as a Google Contact. Requires both a PMS configuration and an active Google connection. Auth required: Yes | Role: any
Rate limit: 10 requests / hour

Request

desde

string

required

Start date in YYYY-MM-DD format.

hasta

string

required

End date in YYYY-MM-DD format.

Response

boolean

required

true

resultado

object

required

Sync summary.

Show resultado fields

creados

integer

New contacts created in Google.

actualizados

integer

Existing contacts updated.

omitidos

integer

Contacts skipped (e.g., missing data).

total

integer

Total reservations processed.

Example

curl -X POST https://api.example.com/api/contactos/sincronizacion \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"desde": "2024-08-01", "hasta": "2024-08-31"}'

{
  "ok": true,
  "resultado": {"creados": 18, "actualizados": 4, "omitidos": 1, "total": 23}
}

POST /api/contactos/exportacion/csv

Fetches reservations from the PMS for the given date range and generates a CSV file formatted for Google Contacts import — for use when Google is not connected. Auth required: Yes | Role: any
Rate limit: 20 requests / hour

Request

desde

string

required

Start date in YYYY-MM-DD format.

hasta

string

required

End date in YYYY-MM-DD format.

Response

200 OK — Content-Type: text/csv; charset=utf-8 The response body is a raw CSV file. The Content-Disposition header is set to attachment; filename=contactos_google.csv.

Example

curl -X POST https://api.example.com/api/contactos/exportacion/csv \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"desde": "2024-08-01", "hasta": "2024-08-31"}' \
  --output contactos_google.csv

POST /api/contactos/xlsx/sincronizacion

Parses an uploaded XLSX file and syncs each row as a Google Contact. Use this when the PMS is not configured but you have a reservation export from another tool. Auth required: Yes | Role: any
Rate limit: 10 requests / hour

Request

Multipart form upload:

file

required

XLSX file containing reservation/guest data. Must have a .xlsx extension.

Response

boolean

required

true

resultado

object

required

Sync summary (same shape as PMS sync).

Example

curl -X POST https://api.example.com/api/contactos/xlsx/sincronizacion \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -F "file=@reservas_agosto.xlsx"

{
  "ok": true,
  "resultado": {"creados": 10, "actualizados": 2, "omitidos": 0, "total": 12}
}

POST /api/contactos/xlsx/exportacion/csv

Parses an uploaded XLSX file and produces a Google Contacts-compatible CSV for manual import — no Google connection required. Auth required: Yes | Role: any
Rate limit: 20 requests / hour

Request

Multipart form upload:

file

required

XLSX file containing reservation/guest data. Must have a .xlsx extension.

Response

200 OK — Content-Type: text/csv; charset=utf-8 Raw CSV download with Content-Disposition: attachment; filename=contactos_google.csv.

Example

curl -X POST https://api.example.com/api/contactos/xlsx/exportacion/csv \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -F "file=@reservas_agosto.xlsx" \
  --output contactos_google.csv

Overview

Endpoints

Google Contacts Sync API — OAuth and Sync Operations

GET /api/contactos/google/auth

Response

Example

GET /api/contactos/google/callback

Query Parameters (set by Google)

Redirect Targets

GET /api/contactos/google/status

Response

Example

DELETE /api/contactos/google/conexion

Response

Example

GET /api/contactos/preferencias

Response

Example

PUT /api/contactos/preferencias

Request

Response

Example

POST /api/contactos/sincronizacion

Request

Response

Example

POST /api/contactos/exportacion/csv

Request

Response

Example

POST /api/contactos/xlsx/sincronizacion

Request

Response

Example

POST /api/contactos/xlsx/exportacion/csv

Request

Response

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/contactos/google/auth

​Response

​Example

​GET /api/contactos/google/callback

​Query Parameters (set by Google)

​Redirect Targets

​GET /api/contactos/google/status

​Response

​Example

​DELETE /api/contactos/google/conexion

​Response

​Example

​GET /api/contactos/preferencias

​Response

​Example

​PUT /api/contactos/preferencias

​Request

​Response

​Example

​POST /api/contactos/sincronizacion

​Request

​Response

​Example

​POST /api/contactos/exportacion/csv

​Request

​Response

​Example

​POST /api/contactos/xlsx/sincronizacion

​Request

​Response

​Example

​POST /api/contactos/xlsx/exportacion/csv

​Request

​Response

​Example

Build docs developers (and LLMs) love

GET /api/contactos/google/auth

Response

Example

GET /api/contactos/google/callback

Query Parameters (set by Google)

Redirect Targets

GET /api/contactos/google/status

Response

Example

DELETE /api/contactos/google/conexion

Response

Example

GET /api/contactos/preferencias

Response

Example

PUT /api/contactos/preferencias

Request

Response

Example

POST /api/contactos/sincronizacion

Request

Response

Example

POST /api/contactos/exportacion/csv

Request

Response

Example

POST /api/contactos/xlsx/sincronizacion

Request

Response

Example

POST /api/contactos/xlsx/exportacion/csv

Request

Response

Example