Integraciones y API

Dos formas de conectar otro sistema

Documentación técnica

La API es REST y responde en JSON. Su especificación OpenAPI 3.0 describe cada operación disponible, con sus parámetros y sus respuestas.

• Documentación interactiva (Swagger UI)

  Para leer y explorar cada operación desde el navegador.

• Especificación OpenAPI (JSON)

  Para generar un cliente o importarla en tu herramienta. Es un archivo grande.

Servidor: https://erp-backend.medine.tech. Es el único servidor publicado: cada petición trabaja con los datos reales de tu empresa.

Qué necesitas

Para usar la API de tu empresa necesitas una API key, el identificador de tu empresa y los permisos adecuados.

Crea una API key

1. Alguien de tu empresa con permiso para crear API keys entra al sistema y abre Configuración de la compañía › API Keys.
2. Elige el vencimiento («30 días», «1 año» o «Sin vencimiento») y marca «Solo lectura» si la integración solo va a consultar.
3. Copia la clave: se muestra una sola vez. Guárdala en un gestor de secretos, nunca en el código, en un correo ni en un chat.

Las API keys se crean, se revisan y se revocan solo en esa pantalla, con la sesión iniciada. La API no las gestiona.

Lo que puede hacer una API key

• Queda ligada a quien la crea y a una sola empresa.
• Actúa con los permisos vigentes de esa persona: si cambian sus permisos, cambia lo que puede hacer la API key.
• Deja de funcionar cuando vence, cuando la revocan o cuando esa persona deja de pertenecer a la empresa.
• Una API key de «Solo lectura» recibe 403 en cualquier operación que modifica datos.
• Solo sirve bajo /api/backoffice/{tenant}/ y para su propia empresa; en cualquier otra ruta, o con otra empresa, recibe 404.
• Algunas operaciones son exclusivas de la aplicación web y responden 403 a una API key.

Tu primera consulta

Empieza con una lectura que no cambia nada: los primeros 10 clientes de tu empresa. Funciona si la persona dueña de la API key puede ver clientes en el sistema.

1. Busca el identificador de tu empresa

Entra al sistema y mira la dirección del navegador: empieza con el identificador de tu empresa, un UUID.

https://erp.medine.tech/<identificador-de-tu-empresa>/…

Ese valor reemplaza a {tenant} en cada ruta. En los ejemplos usamos 00000000-0000-7000-8000-000000000000, un identificador de ejemplo.

2. Haz la consulta

curl "https://erp-backend.medine.tech/api/backoffice/00000000-0000-7000-8000-000000000000/sales/clients?per_page=10" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Accept: application/json" \
  -H "User-Agent: mi-integracion/1.0 (contacto@ejemplo.com)"

Authorization: Bearer TU_API_KEY

Reemplaza TU_API_KEY por tu API key completa.

Accept: application/json

Pide la respuesta en JSON.

User-Agent: mi-integracion/1.0 (contacto@ejemplo.com)

Nombra tu integración, su versión y un contacto. La red de borde puede rechazar las firmas de cliente genéricas con un 403 en texto plano: «Error code: 1010».

3. Lee la respuesta

Si todo está bien, la respuesta trae items (los clientes), total, per_page, current_page y meta. Si recibes un error, busca su código en «Respuestas de error».

Respuestas de error

Cada código dice qué pasó y qué hacer.

401 Credencial ausente o inválida

La API key falta, no es válida, venció o fue revocada.

Qué hacer: revisa la cabecera Authorization o crea una API key nueva.

{"message":"Unauthenticated."}

402 La suscripción no lo permite

La suscripción de la empresa o la confirmación de su titular no permiten la operación. El campo error_code dice cuál es el caso.

Qué hacer: comparte ese error_code con quien administra tu empresa.

403 Sin permiso

La persona dueña de la API key no tiene el permiso, la API key es de «Solo lectura» y la operación modifica datos, o la operación es exclusiva de la aplicación web.

Qué hacer: pide el permiso que falta o usa una API key sin «Solo lectura».

Si el 403 llega en texto plano con «Error code: 1010», lo rechazó la red de borde antes de llegar a la API: envía un User-Agent que nombre tu integración.

{"title":"Forbidden","status":403,"detail":"You do not have permission to access this resource."}

{"title":"Forbidden","status":403,"detail":"This operation requires session authentication."}

404 No encontrado

El recurso no existe, o la empresa de la ruta no es la de tu API key.

Qué hacer: revisa el identificador de la empresa y el del recurso.

{"message":"Recurso no encontrado"}

409 Conflicto

La operación choca con el estado actual de los datos: por ejemplo, el documento ya existe, el identificador ya se usó, se alcanzó un límite contratado o el canal de venta está inactivo. También responde 409 cuando la persona dueña de la API key no ha verificado su correo; en ese caso la respuesta trae el estado email_not_verified.

Qué hacer: lee el detalle de la respuesta y revisa el recurso antes de reintentar: repetir la misma petición no resuelve un conflicto. Si el estado es email_not_verified, esa persona verifica su correo y vuelves a intentarlo.

{"message":"Tu dirección de email no ha sido verificada.","status":"email_not_verified","detail":"Debes verificar tu email antes de acceder al sistema."}

422 Datos inválidos

Los datos que enviaste no pasan la validación.

Qué hacer: corrige los campos que señala la respuesta.

429 Demasiadas peticiones

Superaste el límite de una operación que lo aplica.

Qué hacer: espera un momento y vuelve a intentarlo.

{"message":"Too Many Attempts."}

Límites

• API de tu empresa: hoy no hay un límite general de peticiones por API key. Algunas operaciones tienen su propio límite y responden 429 cuando lo superas.
• Vitrina: 600 peticiones por minuto por Clave de Vitrina y 30 autenticaciones fallidas por minuto desde una misma dirección IP.

Programa tu integración para esperar y reintentar cuando reciba un 429, en cualquier operación.

Vitrina: otra credencial

Si tu empresa vende con la vitrina en línea, esa vitrina no usa una API key sino una Clave de Vitrina.

• Se emite para un canal de venta, no para una persona.
• Sirve solo para las operaciones bajo /api/storefront/, donde una API key nunca sirve.
• Se envía igual, en la cabecera Authorization: Bearer TU_CLAVE_DE_VITRINA, y empieza por mtsk_.
• Si la vitrina llama desde el navegador, la petición debe salir del origen registrado para su canal; si no, recibe 403 con origin_not_allowed.

La vitrina en línea está en versión inicial: la habilitamos contigo, a pedido. Si la necesitas, escríbenos.

Qué es público y qué no

• La documentación es pública; los datos de tu empresa, no. Toda operación sobre los datos de una empresa exige una credencial válida, y una API key solo llega a los de su propia empresa.
• Sin credencial no hay acceso: la API responde 401.
• «Try it out», en la documentación interactiva, envía peticiones reales a producción con la credencial que pegues. Para explorar, usa una API key de «Solo lectura».
• Quien tenga una API key actúa con los permisos de su dueño. Si se filtra, revócala en Configuración de la compañía › API Keys.

Contacto técnico

¿Tienes una duda sobre la API? Escríbenos con el nombre de tu integración, la operación que llamaste y el código que recibiste. Nunca incluyas tu API key.