Carrito

Bearer · scope carrito

Cotiza y genera órdenes, sube guías de envío, administra las direcciones de tus clientes y consulta los catálogos de apoyo (métodos de pago, usos de CFDI, fleteras, sucursales, países, estados y colonias).

POST/api/v1/carrito/generar

Cotizar / generar orden

Bearerscope: carrito

Cotiza un carrito con precios, descuentos y costo de envío ya calculados. En modo de prueba obtienes la cotización completa sin generar el pedido.

curl -X POST https://developers.syscom.mx/api/v1/carrito/generar \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "testmode": true,
    "tipo_entrega": "sucursal",
    "direccion": { "sucursal": "chihuahua", "atencion_a": "PRUEBA API" },
    "metodo_pago": "transferencia",
    "tipo_pago": "PUE",
    "moneda": "usd",
    "uso_cfdi": "G01",
    "productos": [{ "id": 210627, "cantidad": 1, "tipo": "nuevo" }]
  }'

Cuerpo de la petición

productosarrayrequerido

[{ "id": 223114, "cantidad": 2, "tipo": "nuevo" }, ...]Lista de objetos JSON, máximo 50 productos por orden: • id — ID del producto en SYSCOM, el mismo que devuelve /productos; número o texto numérico ("223114"). • cantidad — piezas de ese producto; entero desde 1, número o texto numérico. • tipo — condición de la pieza: nuevo o caja abierta (a, b, c); ver más en la Política Caja Abierta. Si algún producto no existe o no está a la venta, el pedido no se crea: responde 400 (productos_no_encontrados) indicando cuáles. Si algún producto no tiene existencia suficiente, el pedido no se crea.

tipo_entregastringrequerido

sucursal (recolección en sucursal SYSCOM), domicilio (envío a domicilio con fletera) u ocurre (envío para recoger en la paquetería), guia_cliente (adjunta tus propias guías).

direccionobject|string

Objeto (o string JSON) con la dirección. Los campos exigidos dependen de tipo_entrega. Todos aceptan texto o número (se convierten a texto). Con tipo_entrega = sucursal: • sucursal — texto, REQUERIDO. Sucursal de recolección; consulta las disponibles en GET /api/v1/carrito/sucursales y usa el valor de "codigo" de su respuesta (p.ej. "chihuahua"). • atencion_a — texto, opcional, max length 120. Quién recoge. Con tipo_entrega = domicilio u ocurre: • atencion_a — texto, requerido, max length 120. Quién recibe. • calle — texto, requerido, max length 100. • num_ext — texto, requerido, max length 20. • num_int — texto, opcional, max length 20. • colonia — texto, requerido, max length 100. • ciudad — texto, requerido, max length 100. • estado — texto, requerido, max length 4 (catálogo de estados). • pais — texto, requerido, max length 3 (catálogo de países). • codigo_postal — texto, requerido, max length 5 en México y 10 para otros países. • telefono — texto, requerido, max length 20.

fleterastring

Código de fletera (catálogo de fleteras). Obligatoria en entregas a domicilio y por ocurre (en ocurre debe ser terrestre: no se admiten las de día siguiente — estafeta_siguiente, dhl_siguiente — porque el paquete se recoge en la paquetería); en sucursal no se usa. dypaq solo aplica cuando la dirección de entrega tiene cobertura DYPAQ — puedes prevalidarlo con GET /api/v1/carrito/fleteras?codigo_postal=; sin cobertura responde 422 con error_code 9015 ('La fletera no tiene cobertura en la direccion ingresada.').

monedastring

usd (def.) o mxn.

uso_cfdistringrequerido

Código de uso de CFDI (catálogo de usos de CFDI).

metodo_pagostringrequerido

Clave del método de pago (catálogo de métodos de pago): transferencia, sucursal-*, credito-* (7/15/30/30+).

tipo_pagostring

PUE (def.) o PPD; afecta forma_pago. En crédito siempre sale PPD (el catálogo solo anuncia PPD en credito-*); en los demás métodos solo PUE (un PPD recibido cae a PUE en silencio).

orden_comprastring

Referencia de orden de compra del cliente (opcional).

ordenarflag

true → convierte la cotización en pedido real (genera folio_pedido y aparta existencias); requiere stock suficiente. Default: false (solo cotización).

testmodeflag

true → solo cotiza, no genera el pedido (recomendado para pruebas).

forzar_sucursalflag

true → fuerza a surtir todo desde una sola sucursal, IMPORTANTE: si la sucursal no cuenta con el stock necesario aparecerá error de stock insuficiente. Default: false (se consideran todos los almacenes).

pdf_guiafile

Solo en entregas a domicilio y enviando el body como multipart/form-data: adjunta tu guía prepagada, el pedido se envía con tu paquetería y no se cobra flete. jpg/png/jpeg/doc/docx/pdf, máx. 6 MB.

Códigos de estado

200

Cotización calculada (o error de validación de negocio en { error }).

400

Algún dato del pedido es inválido o falta: la respuesta incluye detalles[] con el campo, el problema y un ejemplo. También cuando un producto no existe o no está a la venta (code: productos_no_encontrados).

422

La dirección está bien formada pero no es válida contra el catálogo (país inexistente, código postal que no corresponde al estado, colonia fuera del CP), o la fletera no tiene cobertura en la dirección (error_code 9015). (Con fletera=guia_cliente la dirección no se valida.)

401

Token ausente, inválido o revocado.

403

Cuenta sin acceso o sin scope carrito.

405

Método no permitido (usar POST).

429

Límite de peticiones excedido.

501

Pedido real (sin testmode) deshabilitado en el servidor.

500

Error interno.

POST/api/v1/carrito/guia

Subir guía

Bearerscope: carrito

Sube tu guía de envío prepagada a tus pedidos: el pedido queda marcado para enviarse con tu paquetería (sin mensajería de SYSCOM). Acepta imágenes y PDF de hasta 6 MB.

curl -X POST https://developers.syscom.mx/api/v1/carrito/guia \
  -H 'Authorization: Bearer TU_TOKEN' \
  -F 'folio=000000' \
  -F '[email protected]'

Cuerpo de la petición

foliostringrequerido

Folio de tu pedido o cotización. También funciona el folio de un pedido que ya se procesó.

pdf_guiafilerequerido

Archivo de la guía (jpg/png/jpeg/doc/docx/pdf, máx. 6 MB).

Códigos de estado

200

Guía registrada (o { error } si: no encontramos ese folio en tu cuenta, el pedido tiene entrega en sucursal, o el formato del archivo es inválido).

400

folio vacío o ausente, o pdf_guia ausente.

401

Token ausente, inválido o revocado.

403

Cuenta sin acceso o sin scope carrito.

429

Límite de peticiones excedido.

500

Error interno.

GET/api/v1/carrito/direcciones

Direcciones de envío

Bearerscope: carrito

Lista las direcciones de envío guardadas del cliente.

curl 'https://developers.syscom.mx/api/v1/carrito/direcciones' \
  -H 'Authorization: Bearer TU_TOKEN'

Códigos de estado

200

Direcciones del cliente (arreglo).

401

Token ausente, inválido o revocado.

403

Cuenta sin acceso o sin scope carrito.

429

Límite de peticiones excedido.

500

Error interno.

POST/api/v1/carrito/direcciones

Crear dirección

Bearerscope: carrito

Guarda una nueva dirección de envío. Valida el país y, para México, el estado según el código postal.

curl -X POST https://developers.syscom.mx/api/v1/carrito/direcciones \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "atencion_a": "Juan Perez",
    "calle": "Av. Tecnologico",
    "num_ext": "1234",
    "colonia": "Centro",
    "ciudad": "Chihuahua",
    "estado": "CHIH",
    "pais": "MEX",
    "codigo_postal": "31000",
    "telefono": "6141234567"
  }'

Cuerpo de la petición

atencion_astringrequerido

Persona/atención. Max length 120.

callestringrequerido

Calle. Max length 100.

num_extstringrequerido

Número exterior. Max length 20.

num_intstring

Número interior (opcional). Max length 20.

coloniastringrequerido

Colonia. Max length 100.

ciudadstringrequerido

Ciudad. Max length 100.

estadostringrequerido

Código del estado: usa el valor de estado_sat que devuelve /carrito/estados para tu código postal (p.ej. CHIH para Chihuahua; NO es el código numérico SAT). Max length 4 en México y 60 en otros países; en México se valida contra el CP.

paisstringrequerido

Código de país, max length 3 (ver /carrito/paises, p.ej. MEX).

codigo_postalstringrequerido

Código postal. Max length 5 en México y 10 para otros países.

telefonostringrequerido

Teléfono. Max length 20.

Códigos de estado

200

Dirección creada.

400

Faltan parámetros obligatorios de la dirección.

422

País inexistente, o el código postal no corresponde al estado indicado.

401

Token ausente, inválido o revocado.

403

Cuenta sin acceso o sin scope carrito.

429

Límite de peticiones excedido.

500

Error interno.

PUT/api/v1/carrito/direcciones/{id}

Actualizar dirección

Bearerscope: carrito

Actualiza una dirección de envío. Debes enviar todos los datos, porque reemplaza la dirección completa.

curl -X PUT https://developers.syscom.mx/api/v1/carrito/direcciones/901 \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "atencion_a": "Juan Perez",
    "calle": "Av. Tecnologico",
    "num_ext": "1234",
    "colonia": "Centro",
    "ciudad": "Chihuahua",
    "estado": "CHIH",
    "pais": "MEX",
    "codigo_postal": "31000",
    "telefono": "6149876543"
  }'

Parámetros

idnumberrequerido

ID de la dirección.

Cuerpo de la petición

atencion_astringrequerido

Persona/atención. Max length 120.

callestringrequerido

Calle. Max length 100.

num_extstringrequerido

Número exterior. Max length 20.

num_intstring

Número interior (opcional). Max length 20.

coloniastringrequerido

Colonia. Max length 100.

ciudadstringrequerido

Ciudad. Max length 100.

estadostringrequerido

paisstringrequerido

Código de país, max length 3 (ver /carrito/paises).

codigo_postalstringrequerido

Código postal. Max length 5 en México y 10 para otros países.

telefonostringrequerido

Teléfono. Max length 20.

Códigos de estado

200

Dirección actualizada.

400

id inválido o faltan parámetros obligatorios.

422

País inexistente, o el código postal no corresponde al estado indicado.

401

Token ausente, inválido o revocado.

403

Cuenta sin acceso o sin scope carrito.

429

Límite de peticiones excedido.

500

Error interno.

DELETE/api/v1/carrito/direcciones/{id}

Eliminar dirección

Bearerscope: carrito

Elimina una dirección de envío del cliente.

curl -X DELETE https://developers.syscom.mx/api/v1/carrito/direcciones/901 \
  -H 'Authorization: Bearer TU_TOKEN'

Parámetros

idnumberrequerido

ID de la dirección.

Códigos de estado

200

Dirección eliminada.

400

id inválido.

401

Token ausente, inválido o revocado.

403

Cuenta sin acceso o sin scope carrito.

429

Límite de peticiones excedido.

500

Error interno.

GET/api/v1/carrito/pago

Métodos de pago

Bearerscope: carrito

Formas de pago disponibles para el pedido (transferencia, pago en sucursal, crédito, etc.), con su descuento y plazo.

curl 'https://developers.syscom.mx/api/v1/carrito/pago' \
  -H 'Authorization: Bearer TU_TOKEN'

Códigos de estado

200

Catálogo de métodos de pago.

401

Token ausente, inválido, expirado o revocado.

403

Cuenta sin acceso o scope `carrito` insuficiente.

429

Límite de peticiones excedido.

500

Error interno.

GET/api/v1/carrito/cfdi

Usos de CFDI

Bearerscope: carrito

Usos de CFDI disponibles para la facturación del pedido.

curl 'https://developers.syscom.mx/api/v1/carrito/cfdi' \
  -H 'Authorization: Bearer TU_TOKEN'

Códigos de estado

200

Catálogo de usos de CFDI.

401

Token ausente, inválido, expirado o revocado.

403

Cuenta sin acceso o scope `carrito` insuficiente.

429

Límite de peticiones excedido.

500

Error interno.

GET/api/v1/carrito/fleteras

Fleteras

Bearerscope: carrito

Paqueterías disponibles para el envío, indicando cuáles ofrecen entrega al día siguiente. Cada fletera incluye el campo `cobertura`: las nacionales cubren casi todo el país (`estandar`); DYPAQ depende del código postal — sin CP sale como `valide_codigo_postal` (aún no se sabe), y con un CP válido te confirma si tiene cobertura en esa zona (`si`/`no`). Así sabes antes de cotizar si DYPAQ aplica.

curl 'https://developers.syscom.mx/api/v1/carrito/fleteras' \
  -H 'Authorization: Bearer TU_TOKEN'

Parámetros de consulta

codigo_postalstring

Opcional. Código postal de la dirección de entrega (4-5 dígitos). Actualiza el cobertura de DYPAQ: si si cubre esa zona, no si no. Sin este param DYPAQ sale como valide_codigo_postal.

Códigos de estado

200

Catálogo de fleteras. DYPAQ siempre aparece al final: su `cobertura` es `valide_codigo_postal` sin CP, y `si`/`no` con un ?codigo_postal válido.

400

codigo_postal con formato inválido (debe ser de 4-5 dígitos).

401

Token ausente, inválido, expirado o revocado.

403

Cuenta sin acceso o scope `carrito` insuficiente.

429

Límite de peticiones excedido.

500

Error interno.

GET/api/v1/sucursales

Sucursales

Bearer

Lista las sucursales de Syscom en México, con su nombre e identificador.

curl 'https://developers.syscom.mx/api/v1/sucursales' \
  -H 'Authorization: Bearer TU_TOKEN'

Códigos de estado

200

Lista de sucursales.

401

Token ausente, inválido, expirado o revocado.

403

Cuenta sin acceso (gate de distribuidor).

429

Límite de peticiones excedido.

500

Error interno.

GET/api/v1/carrito/paises

Países

Bearerscope: carrito

Países disponibles para las direcciones de envío.

curl 'https://developers.syscom.mx/api/v1/carrito/paises' \
  -H 'Authorization: Bearer TU_TOKEN'

Códigos de estado

200

Catálogo de países.

401

Token ausente, inválido, expirado o revocado.

403

Cuenta sin acceso o scope `carrito` insuficiente.

429

Límite de peticiones excedido.

500

Error interno.

GET/api/v1/carrito/estados/{cp}

Estado por código postal

Bearerscope: carrito

Devuelve el estado y el municipio que corresponden a un código postal.

curl 'https://developers.syscom.mx/api/v1/carrito/estados/31000' \
  -H 'Authorization: Bearer TU_TOKEN'

Parámetros

cpstringrequerido

Código postal (4-5 dígitos).

Códigos de estado

200

Estado/municipio del código postal.

400

Código postal inválido (no 4-5 dígitos).

401

Token ausente, inválido, expirado o revocado.

403

Cuenta sin acceso o scope `carrito` insuficiente.

429

Límite de peticiones excedido.

500

Error interno.

GET/api/v1/carrito/colonias/{cp}

Colonias por código postal

Bearerscope: carrito

Lista las colonias de un código postal.

curl 'https://developers.syscom.mx/api/v1/carrito/colonias/31000' \
  -H 'Authorization: Bearer TU_TOKEN'

Parámetros

cpstringrequerido

Código postal (4-5 dígitos).

Códigos de estado

200

Colonias del código postal.

400

Código postal inválido (no 4-5 dígitos).

401

Token ausente, inválido, expirado o revocado.

403

Cuenta sin acceso o scope `carrito` insuficiente.

429

Límite de peticiones excedido.

500

Error interno.

AnteriorCategorías Siguiente Facturas