REST · JSON · Bearer · OpenAPI 3.0
API REST para clientes enterprise
La API REST que les permite integrar las cotizaciones, las órdenes, el estatus de producción, las entregas y las facturas con su propio stack de operaciones — ERP, portal de cliente, mesa de servicio. Documentada en OpenAPI 3.0 con ejemplos en curl, Python y Node.js. El acceso se entrega a clientes con programa vigente y contrato de uso firmado.
Conceptos básicos: autenticación, base URL, formato
La API se autentica con un bearer token que entregamos al cliente con su programa. El token se rota cada noventa días o cuando el cliente lo solicita. La base URL de producción es https://api.corp-merch.com.mx/v1. La base URL del sandbox es https://sandbox.api.corp-merch.com.mx/v1. El sandbox tiene datos ficticios y reinicia cada lunes a las cero horas GMT-6.
El formato de intercambio es JSON con UTF-8. Las fechas y horas se manejan en formato ISO 8601 con zona horaria — preferimos YYYY-MM-DDTHH:MM:SS-06:00 para horario de CDMX. Los montos están en centavos de MXN — para representar cincuenta pesos con cincuenta centavos enviamos 5050. Los códigos de país son ISO 3166-1 alfa-2 — MX para México, US para Estados Unidos, CA para Canadá.
Endpoints principales
La API expone seis bloques de endpoints. El bloque de cotizaciones: POST /quotes para crear una cotización, GET /quotes/{id} para consultar el detalle, POST /quotes/{id}/approve para aprobar, POST /quotes/{id}/reject para rechazar con motivo. El bloque de órdenes: POST /orders para crear una orden a partir de una cotización aprobada, GET /orders/{id} para consultar el detalle, PATCH /orders/{id} para modificar campos permitidos antes de la producción, POST /orders/{id}/cancel para cancelar antes de la producción.
El bloque de estatus: GET /orders/{id}/status para consultar el estatus completo, GET /orders/{id}/status/history para el historial con timestamps, GET /orders/{id}/documents para los documentos asociados. El bloque de entregas: GET /orders/{id}/shipments para listar envíos, GET /shipments/{id} para el detalle, POST /shipments/{id}/confirm para confirmar la recepción cuando el cliente firma el acuse. El bloque de facturas: GET /orders/{id}/invoices para listar, GET /invoices/{id} para el detalle con el XML del CFDI 4.0 y el PDF. El bloque de catálogo: GET /catalog/products para listar productos, GET /catalog/products/{id} para el detalle con precios y existencias.
Ejemplo: crear una cotización
Para crear una cotización se envía una petición POST a /v1/quotes con el bearer token en el encabezado Authorization y un cuerpo JSON con los productos, cantidades, técnica de marcado y plazos. El endpoint devuelve un identificador de cotización y el detalle con precios en centavos de MXN antes de IVA, IVA desglosado, total y plazo de entrega por línea.
El cuerpo mínimo de una cotización incluye un arreglo de líneas con product_id, quantity, decoration con la técnica — screen, dtf, embroidery, laser — y delivery_address con el domicilio completo. Para líneas con personalización variable — número de colaborador, talla individual — se incluye el arreglo variables por línea. La cotización se entrega en menos de un minuto cuando el catálogo reconoce el producto y la dirección está dentro de la cobertura.
Ejemplo: consultar el estatus de una orden
Para consultar el estatus se envía una petición GET a /v1/orders/{id}/status con el bearer token. El endpoint devuelve el estatus actual — created, approved, in_production, quality_check, packed, shipped, delivered, invoiced, closed, canceled — y el porcentaje de avance por etapa. La respuesta incluye la fecha estimada de entrega con base en el calendario del cliente y del taller.
Para series con varias etapas — corte, confección, personalización, empaque, envío, entrega — el cliente recibe el desglose por etapa con el porcentaje de avance. Cuando una etapa se atrasa, el estatus devuelve el motivo — falta de materia prima, no conformidad, espera de confirmación del cliente — y la fecha estimada actualizada. La integración se mantiene consistente con los webhooks que disparan eventos por cambio de estatus.
Manejo de errores y reintentos
Los errores se devuelven con códigos HTTP estándar — 400 para solicitud mal formada, 401 para token ausente o inválido, 403 para recurso no permitido, 404 para recurso no encontrado, 409 para conflicto de estado, 422 para validación fallida, 429 para exceso de tasa, 500 para error interno. El cuerpo del error incluye code con el código legible por máquina, message con la descripción legible por humano y details con el arreglo de campos con error cuando aplica.
El límite de tasa es de sesenta solicitudes por minuto por token y de mil solicitudes por hora por token. Cuando se excede el límite, el endpoint devuelve 429 con el encabezado Retry-After indicando los segundos a esperar. Implementamos exponential backoff en el cliente con jitter para evitar el efecto de manada. Para clientes con volumen mayor, negociamos un límite superior al inicio del programa.
Buenas prácticas de integración
Recomendamos tres prácticas. Primero, usar el sandbox para desarrollo y pruebas antes de mover a producción. El sandbox tiene datos ficticios y se reinicia cada lunes. Segundo, suscribirse a los webhooks en lugar de sondear el estatus — los webhooks disparan al cambio de estatus sin que el cliente tenga que hacer polling. Tercero, validar las firmas HMAC SHA-256 de los webhooks antes de procesar el cuerpo para confirmar que el webhook proviene de la API.
Para clientes con stack serverless, los webhooks firman el cuerpo y se entregan con encabezados de timestamp y de identificador de evento. El cliente debe validar la firma, el timestamp — con tolerancia de cinco minutos — y el identificador para evitar duplicados por reintento. La documentación completa incluye una sección de referencia con los eventos disponibles y el formato del cuerpo.
Soporte y observabilidad
Para clientes con integración en producción, asignamos un responsable técnico del taller que responde dudas de integración en menos de cuatro horas hábiles y que participa en sesiones de pair programming cuando se requiere. El responsable técnico también atiende incidentes — respuesta a webhook perdido, desfase entre el portal y la API, dudas sobre una respuesta inesperada.
La API publica métricas operativas — disponibilidad, latencia p95, tasa de error — en un dashboard de status al que el cliente puede suscribirse. Para clientes con SLA exigente — banca, fintech, gobierno — entregamos un dashboard dedicado con métricas en tiempo real y un canal de comunicación directo para incidentes críticos. La página de status es accesible sin autenticación.
Solicite acceso al SDK
Si su equipo técnico requiere acceso al SDK para integrar cotizaciones, órdenes, estatus, entregas o facturas con su stack de operaciones, platiquemos. Les entregamos el bearer token, el acceso al sandbox y la documentación completa en formato del cliente.
La API REST y el SDK son entregados a clientes con programa vigente y contrato de uso firmado. La documentación puede actualizarse sin previo aviso; las versiones mayores se comunican con treinta días de anticipación. Corp-Merch.MX es un taller mexicano de producción de merch corporativo; operamos de manera independiente.