A veces la red corta una solicitud y no queda claro si llegó. Para repetir un POST sin ejecutar (ni pagar) el trabajo dos veces, envíe el encabezado Idempotency-Key: un valor único por operación lógica. Un UUID es una buena opción.
curl -X POST https://developers.grem.capital/api/v1/valuation/express \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f1c8a90-1e2b-4c77-9a10-2b6d0f9e4a11" \
-d '{"propertyCategory":"apartment","addressText":"Torstraße 12, Berlin","totalArea":64}'
Cómo funciona
- La primera solicitud con una clave se ejecuta con normalidad; su respuesta correcta se guarda.
- Una repetición con la misma clave devuelve la respuesta guardada: la herramienta no se ejecuta de nuevo ni se cobra de nuevo.
- Mientras la primera solicitud sigue en curso, una segunda solicitud con la misma clave recibe
409contitle: idempotency_conflict. Espere y repita con la misma clave. - Si la primera solicitud terminó con error, la clave se libera: una repetición se ejecuta de nuevo. Una solicitud que nunca llegó al servicio (conexión rechazada) también libera la clave.
- Tras un tiempo de espera agotado (
502 provider_error) de una herramienta, de la creación de un inmueble o de la creación de un lead, la clave queda reservada 15 minutos para que una repetición no ejecute el trabajo dos veces. Compruebe el resultado antes de repetir:GET /workspara las herramientas,GET /objectsyGET /leadspara las creaciones. Los resultados de la mejora de fotos, del sitio y del borrador no se guardan enGET /works: compruébelos en el panel o entre sus inmuebles. Una repetición pasados los 15 minutos vuelve a ejecutar el trabajo (y su cobro). - La excepción es la valoración exprés: tras un tiempo de espera agotado la clave se libera; repítala enseguida con la misma clave, una valoración terminada se devuelve gratis: no se vuelve a cobrar ni la valoración ni la llamada a la API.
- Una clave se guarda 24 horas y pertenece a su clave de API y a la operación, es decir, al método y a la ruta real: valores iguales con claves de API distintas, la misma clave en otra herramienta, o
POST /objects/propertyyPOST /objects/rental, son solicitudes distintas.
El cuerpo de la repetición no se compara con la primera solicitud. Si envía otra solicitud con una clave ya usada, recibirá la respuesta de la primera. Para cada operación nueva, una clave nueva.
Dónde se aplica
| Solicitud | |
|---|---|
POST /valuation/express y todas las herramientas (POST /valuation/report, POST /content/generate, POST /flyer/create, etc.) | sí |
POST /objects/{kind}: crear un inmueble | sí |
POST /leads: crear un lead | sí |
POST /match/leads/{id}/events: evento de Swipe Match | sí; la clave debe cumplir ^[A-Za-z0-9_.:-]{8,128}$, si no, se ignora |
POST /uploads, POST /chat/messages, POST /valuation/review/jobs/{id}/confirm | no (en el chat sirve para esto clientMessageId) |
En el SDK la clave es el último argumento del método.
Artículos relacionados
- Errores: qué repetir y cuándo.
- Límites y cobro: qué se cobra.