Preguntas frecuentes
Integración
Sección titulada «Integración»¿Puedo registrar mi URL por mi cuenta?
Sección titulada «¿Puedo registrar mi URL por mi cuenta?»No. Las suscripciones las registra IDBI. Siga los pasos de Primeros pasos.
¿Puedo usar http:// o una dirección local como localhost?
Sección titulada «¿Puedo usar http:// o una dirección local como localhost?»No. La URL debe usar HTTPS y resolverse por DNS a una dirección IP pública. Para probar su verificación sin recibir envíos reales, use el vector de prueba.
¿Cómo obtengo el secreto de mi suscripción?
Sección titulada «¿Cómo obtengo el secreto de mi suscripción?»IDPOS lo genera al registrar la suscripción e IDBI se lo entrega; después no se puede volver a consultar ni cambiar. Guárdelo de inmediato en un lugar seguro. Si lo perdió o sospecha que se expuso, comuníquese con IDBI: se registra una suscripción nueva, con un secreto nuevo, y se desactiva la anterior.
¿Cómo cambio mi URL o los eventos que recibo?
Sección titulada «¿Cómo cambio mi URL o los eventos que recibo?»Solicítelo a IDBI. Los cambios en la suscripción los realiza IDBI.
¿Por qué la firma no coincide?
Sección titulada «¿Por qué la firma no coincide?»La causa más común es verificar sobre el JSON reserializado y no sobre el cuerpo crudo. IDPOS firma los bytes exactos que envía. Por ejemplo, PHP escapa / como \/ y los caracteres no ASCII como \uXXXX, y otros lenguajes no. Revise también que el secreto sea el de la suscripción correcta y que el mensaje firmado sea {X-Webhook-Timestamp}.{cuerpo}. Consulte Errores frecuentes.
¿Qué respondo si la firma no coincide?
Sección titulada «¿Qué respondo si la firma no coincide?»Responda con un código distinto de 2xx (por ejemplo, 401) y no procese el evento. Consulte Autenticación y firma.
¿La firma es la misma en cada reintento?
Sección titulada «¿La firma es la misma en cada reintento?»No. X-Webhook-Timestamp y X-Webhook-Signature se recalculan en cada intento. X-Webhook-Id no cambia. Verifique siempre con las cabeceras de la petición que está recibiendo.
¿Qué tolerancia de reloj debo usar?
Sección titulada «¿Qué tolerancia de reloj debo usar?»300 segundos (5 minutos). Rechace los envíos cuyo X-Webhook-Timestamp difiera más que eso de la hora de su servidor.
¿Por qué debo comparar la firma en tiempo constante?
Sección titulada «¿Por qué debo comparar la firma en tiempo constante?»Una comparación normal termina en el primer carácter distinto y el tiempo que tarda puede filtrar información sobre la firma correcta. Use timingSafeEqual en Node.js, hash_equals en PHP o hmac.compare_digest en Python.
Entrega
Sección titulada «Entrega»¿Qué código debo responder?
Sección titulada «¿Qué código debo responder?»Cualquier código 2xx confirma la entrega. Cualquier otra respuesta, un error de conexión o un tiempo de espera agotado cuenta como envío fallido y se reintenta. Consulte Entrega y reintentos.
¿Cuánto tiempo tengo para responder?
Sección titulada «¿Cuánto tiempo tengo para responder?»30 segundos por defecto. Es un valor por suscripción, configurable entre 1 y 60 segundos. Responda primero y procese después, en segundo plano.
¿Qué pasa si mi servidor no estuvo disponible?
Sección titulada «¿Qué pasa si mi servidor no estuvo disponible?»IDPOS reintenta según el calendario de reintentos: hasta 5 intentos por defecto, con esperas de 60 segundos, 5 minutos, 15 minutos y 1 hora. Si el quinto intento falla, el evento no se reenvía de forma automática. IDBI puede reiniciar el envío de un evento fallido; en ese caso se vuelve a intentar con el mismo calendario.
¿Puedo recibir el mismo evento más de una vez?
Sección titulada «¿Puedo recibir el mismo evento más de una vez?»Sí. La entrega es «al menos una vez». Descarte los duplicados con el event_id del cuerpo, ya verificado: no cambia entre reintentos y es igual a la cabecera X-Webhook-Id, que no está firmada. Consulte Duplicados.
¿Los eventos llegan en orden?
Sección titulada «¿Los eventos llegan en orden?»No hay garantía de orden. No asuma que Orden aceptada (order.accepted) llega antes que Pago completo (order.paid_in_full) u Orden entregada (order.delivered). Consulte Orden de los eventos.
¿Debo responder 2xx a un evento que no reconozco?
Sección titulada «¿Debo responder 2xx a un evento que no reconozco?»Sí. Una respuesta distinta de 2xx provoca reintentos del mismo evento. Responda 2xx, registre el event_type desconocido e ignórelo.
¿Por qué los importes son texto y no números?
Sección titulada «¿Por qué los importes son texto y no números?»Los importes se envían como texto con un número fijo de decimales, por ejemplo "54.00". Conviértalos con una librería decimal y no con números de coma flotante.
¿Pueden agregarse campos nuevos?
Sección titulada «¿Pueden agregarse campos nuevos?»Sí. Los eventos pueden incorporar campos nuevos. Su integración debe ignorar los campos que no reconozca. Consulte Compatibilidad y versionado.
¿Por qué Orden entregada tiene otra estructura que Orden aceptada?
Sección titulada «¿Por qué Orden entregada tiene otra estructura que Orden aceptada?»Cada evento define su propio contenido. Orden entregada (order.delivered) envía una versión reducida de la orden, distinta de la de Orden aceptada (order.accepted). Consulte la tabla de campos.