Saltar al contenido principal

Registros

El add-on Registros guarda dos tipos de datos de tu integración. Los clientes son las personas para quienes cotizas trabajos, con nombre, teléfono, correo y dirección. Los registros son documentos JSON tuyos, agrupados en colecciones y nombrados con tus propios ids. Ambos viven en Hometown, junto a las estimaciones a las que pertenecen.

El add-on se paga aparte. Suscríbete en el panel, en Facturación, o con POST /v1/billing/checkout y pack: addon_records (ver Créditos y facturación). Sin él, /v1/customers y /v1/records responden 403 con el código scope_missing, y detail nombra el add-on.

Permisos​

PermisoPermite
customers:writeLeer, crear, cambiar y borrar clientes.
records:readLeer y listar registros.
records:writeCrear, reemplazar y borrar registros.

Al activar el add-on, toda llave que ya tenga todos los demás permisos gana estos tres. Las llaves que crees después también los traen.

Clientes​

Crea un cliente con tu propio id en external_id:

curl https://api.wfskills.com/v1/customers \
  -H "Authorization: Bearer $HOMETOWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "crm-2291", "name": "Dana Reyes", "phone": "+16015550123", "email": "dana@example.com", "region_code": "US-MS"}'

La respuesta es el cliente, con un id que empieza con cus_. external_id es único en cada entorno, y uno repetido responde 422 validation_failed con param: external_id. Para encontrar un cliente por tu id, llama a GET /v1/customers?external_id=crm-2291.

Los teléfonos van en formato E.164, como +16015550123. El teléfono y el correo se guardan cifrados. PATCH /v1/customers/{id} cambia solo los campos que envías, y null vacía un campo.

Liga estimaciones a un cliente​

Envía customer_id al crear una estimación:

curl https://api.wfskills.com/v1/estimates \
  -H "Authorization: Bearer $HOMETOWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "Install 100 feet of wood privacy fence"}, "customer_id": "cus_01J9Z6X1M4QK2V7H8T3R5N0BCD"}'

La estimación responde con el mismo customer_id, y sus seguimientos lo conservan. GET /v1/customers/{id}/estimates lista cada estimación ligada al cliente, de la más nueva a la más vieja. Un cliente del entorno de prueba solo se liga a estimaciones de prueba, y lo mismo pasa en live.

DELETE /v1/customers/{id} borra al cliente de inmediato, con su teléfono y su correo. Las estimaciones ligadas a él se quedan, sin el vínculo.

Registros​

Un registro es cualquier objeto JSON de hasta 64 KB, guardado en una colección y con un id que tú eliges. Los nombres de colección usan minúsculas, dígitos y _, y empiezan con una letra. Los ids usan letras, dígitos y . _ : @ -, hasta 120 caracteres.

Escribe un registro con PUT y manda en updated_at_ms la hora en que lo cambiaste:

curl -X PUT https://api.wfskills.com/v1/records/jobs/job-1042 \
  -H "Authorization: Bearer $HOMETOWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"title": "Back fence", "status": "scheduled"}, "updated_at_ms": 1760100000000}'

La primera escritura responde 201 y crea el registro. Una escritura posterior responde 200.

Gana la escritura más reciente​

updated_at_ms es tu reloj, en milisegundos desde la época Unix. Hometown se queda con la escritura de valor más alto. Una escritura con un valor más viejo no cambia nada y responde con el registro guardado. Así, dos dispositivos que sincronizan en cualquier orden terminan con el mismo registro. Repetir un PUT siempre es seguro, por eso no lleva Idempotency-Key.

Lee un registro con GET /v1/records/{collection}/{id}. GET /v1/records/{collection} lista una colección por id en orden ascendente. Pasa el último id de una página en starting_after para pedir la siguiente. DELETE borra un registro de inmediato.

Límites​

Cada entorno guarda hasta 50,000 clientes y registros, contados juntos. Al pasar ese tope, crear uno responde 422 records_cap_reached. Cambiar un cliente o un registro que ya tienes sigue funcionando, y borrar libera espacio.

El add-on se cobra por el conteo live más alto del mes. Hometown cuenta cada noche, y el panel muestra el último conteo. Los datos de prueba no se cobran.

Exporta y borra todo​

El panel tiene dos botones para lo que tus propios clientes pueden pedirte. Export JSON descarga cada cliente y registro de los dos entornos, con el teléfono y el correo legibles. Delete all los borra de una vez, después de que escribes el nombre de la cuenta. Ambos piden tu contraseña, y Hometown registra los dos.

Si el add-on se desactiva, las rutas responden 403 de inmediato y los datos se quedan 30 días. Si lo reactivas en ese tiempo, encuentras todo como estaba. Pasados los 30 días, los datos se borran.

Última actualización en