/v1, y /v1 es la única API pública: otras rutas que usa la consola de muveya no son un contrato público, pueden cambiar en cualquier momento y las integraciones no deben llamarlas.
El compromiso
- Dentro de
/v1, los cambios son aditivos. Una operación, un campo o un valor del que depende tu integración no se elimina ni se renombra dentro de/v1. - Un cambio incompatible necesita una versión nueva. Se publica como una nueva versión mayor en la ruta (
/v2), con un período de migración./v1nunca se modifica de forma incompatible. - El contrato se verifica en cada cambio. El contrato OpenAPI detrás de las páginas de Endpoints se genera desde el código de muveya, y cada cambio se compara con la versión anterior mediante una verificación automática de compatibilidad que rechaza los cambios incompatibles de la lista de abajo.
version que aparece dentro del documento OpenAPI es la revisión de ese documento. La versión de la API con la que te integras es el /v1 de la ruta.
Qué se considera incompatible
muveya considera incompatibles estos cambios en/v1, y no los hace dentro de /v1:
Qué puede cambiar dentro de /v1
Estos cambios son aditivos y pueden llegar en cualquier momento, anunciados en Novedades:
- Operaciones y recursos nuevos.
- Parámetros de consulta y encabezados nuevos opcionales.
- Campos nuevos opcionales en las respuestas.
- Valores nuevos en las enumeraciones de respuesta, por ejemplo un estado de pedido nuevo, un
typede movimiento de existencias nuevo o una clave de métrica de analítica nueva. - Valores nuevos de
codede error. - Scopes nuevos.
- Otra redacción en los textos para personas:
titleydetailde los errores,labeldel resumen gerencial, descripciones de esta referencia. - Valores operativos que la API informa en tiempo de ejecución, como el presupuesto de límite de uso en los encabezados de respuesta.
catalog.cost:read) no es un cambio del contrato: siempre estuvo documentado como opcional.
Escribe un cliente tolerante
1
Ignora los campos que no conoces
Interpreta solo los campos que usas. No falles cuando una respuesta trae un campo que no está en tu modelo.
2
Trata las enumeraciones como abiertas
Da a cada
switch sobre un estado, un tipo de movimiento o una clave de métrica una rama por defecto. Un valor nuevo no debe romper tu integración; regístralo y trátalo como “otro”.3
Trata los campos opcionales como opcionales
Un campo marcado como opcional puede no venir. Nunca se envía como
null en su lugar (salvo tres campos de analítica, value, averageHours y maxAgeHours, descritos en la referencia). Verifica que exista antes de leerlo.4
Evalúa el código y usa el estado como respaldo
Maneja los códigos de error que conoces y usa el estado HTTP para cualquier código que todavía no conozcas. Consulta Errores.
5
Nunca decidas según textos para personas
title, detail y label cambian con el idioma y la redacción. Usa claves, códigos e ids.6
No dependas del formato del cursor ni del orden de las claves
Los cursores son opacos y el orden de las claves JSON no tiene significado.
Obsolescencia
Hoy no hay ninguna operación ni campo de/v1 marcado como obsoleto, y ninguna respuesta trae encabezados de obsolescencia.
Cuando exista una /v2, /v1 tendrá un período de retiro anunciado. El retiro se publicará en Novedades antes de aplicarse, y muveya prevé indicarlo en las respuestas con los encabezados estándar Deprecation y Sunset.
Qué no está en /v1 hoy
Las funciones que no están documentadas en esta pestaña no están disponibles, por ejemplo crear o cambiar pedidos por la API, o los webhooks (consulta Webhooks). Si llegan, llegarán como cambios aditivos y se anunciarán en las novedades.
El único formato de clave de API que se emite hoy es mvy_test_ (consulta Autenticación).
Dónde se anuncian los cambios
- Novedades lista los cambios visibles para clientes, del más reciente al más antiguo.
- Las páginas de Endpoints se regeneran desde el contrato cada vez que cambia, en inglés, español y portugués.