Cómo enviar facturas por API

Tu sistema nos entrega el XML del CFDI, el PDF de esa misma factura y la orden de compra. Nosotros leemos el comprobante. No hace falta teclear monto, fecha ni folio del CFDI.

Un XML por envío Orden de compra obligatoria PDF obligatorio, del mismo UUID Token de un solo uso al crearlo

Empezar

  1. Grupo más crea una credencial en la ficha del proveedor, sección Acceso de API, y te entrega el token. Empieza con gme_pvd_ y solo se muestra una vez. Si se pierde, se revoca y se crea otro. No se puede recuperar.
  2. Guarda el token en el secreto de tu ERP. No lo pongas en el código ni en un correo.
  3. En cada factura, manda el archivo XML, el PDF, la orden de compra y el encabezado Authorization: Bearer.
  4. El PDF va en el mismo envío. Tiene que ser la representación del mismo UUID. Sin PDF la respuesta es 400.
Este token no es el acceso al portal.

Quien entra con usuario y contraseña usa Carga de facturas. Esta API es para el sistema del proveedor. Las dos puertas dejan la factura en el mismo inventario, con reglas distintas.

Ambientes

La ruta es siempre POST /api/v1/proveedores/cfdi. El token de un ambiente no sirve en el otro.

UsoHost
Portal y API dedicados de proveedores (Operación) https://proveedores.everest.gme.mx
Respaldo / compatibilidad (Everest) https://everest.gme.mx
Pruebas de integración https://pruebas.everest.gme.mx

Crea el token en el mismo ambiente al que vas a enviar. Un token de pruebas no entra a operación.

Qué enviar

El cuerpo es multipart/form-data.

CampoObligatorioQué es
xml Sí El CFDI en XML. Uno por petición.
pdf Sí El PDF de ese mismo UUID, en el mismo envío. También en el reintento.
ordenCompra Sí La orden de compra de Grupo más. También va en el reintento del mismo XML.

La orden de compra lleva de 6 a 14 caracteres: 3 o 4 letras y después solo números. Ejemplos: ALD243, ALD386784, MNJF00036357. Puedes mandarla en minúsculas; la guardamos en mayúsculas. Un guion, un espacio o un texto que no tenga esa forma responde 400.

No mandes monto, fecha, UUID ni RFC como campos de texto.

Si vienen, se ignoran. La factura se lee del XML. La orden de compra sí es obligatoria, en el campo ordenCompra. Un ZIP u otro archivo responde 400. El XML puede pesar hasta 2 MB y el PDF hasta 10 MB.

Reglas

  1. Cada envío trae ordenCompra: de 6 a 14 caracteres, 3 o 4 letras y después solo dígitos.
  2. El RFC emisor del XML tiene que ser un RFC de la cuenta a la que pertenece el token.
  3. El RFC receptor tiene que ser un RFC de Grupo más que esté activo para recibir facturas.
  4. Cada envío trae el PDF del mismo UUID. Sin el archivo la respuesta es 400 pdf_ausente. Si el archivo llega vacío, 422 pdf_vacio. Si el UUID del PDF no es el del XML, 422 pdf_uuid_distinto.
  5. Si vuelves a mandar el mismo XML, la respuesta es 200 y el identificador no cambia. No se duplica la factura.
  6. Si el UUID ya existe y el XML es otro archivo, la respuesta es 409 uuid_xml_distinto. No se reemplaza el comprobante.
  7. Si esa orden de compra ya está en otra factura, la respuesta es 422 orden_compra_otro_uuid. No se guarda este CFDI. Volver a mandar el mismo UUID con la misma orden sí es válido.
  8. Las partidas del XML tienen que coincidir con las de la orden: mismos códigos, mismas cantidades y mismo precio. Si no, la respuesta es 422 y no se guarda la factura. Cada diferencia viene en errors, con el SKU y los dos valores. Una factura con menos partidas que la orden tampoco entra.
  9. Si la orden no tiene líneas, la respuesta es 422 orden_sin_lineas. Si no se puede leer la orden, 503 oc_no_disponible: reintenta.

Hay un tope de 60 envíos por minuto con la misma credencial. El siguiente responde 429. Espera un minuto y reintenta.

Ejemplos

Primera factura

curl -sS -X POST "https://pruebas.everest.gme.mx/api/v1/proveedores/cfdi" \
  -H "Authorization: Bearer gme_pvd_TU_TOKEN" \
  -F "ordenCompra=ALD386784" \
  -F "xml=@factura.xml;type=application/xml" \
  -F "pdf=@factura.pdf;type=application/pdf"

Una alta nueva responde 200:

{
  "id": "id-del-archivo",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "detail": "CFDI registrado"
}

El mismo XML y el mismo PDF otra vez

curl -sS -X POST "https://pruebas.everest.gme.mx/api/v1/proveedores/cfdi" \
  -H "Authorization: Bearer gme_pvd_TU_TOKEN" \
  -F "ordenCompra=ALD386784" \
  -F "xml=@factura.xml;type=application/xml" \
  -F "pdf=@factura.pdf;type=application/pdf"

Si el XML ya estaba y el contenido es el mismo, la respuesta es 200 y el id no cambia. Para operación, cambia el host a https://proveedores.everest.gme.mx y usa el token de ese ambiente.

Respuestas

Si sale bien, el cuerpo trae id, uuid y detail. Si falla una sola cosa, trae error, detail y errors con ese único caso. Si fallan varias, errors las lista todas, cada una con su código, y el HTTP es 422. No hay un código que signifique «varias cosas». Si el XML no se puede leer, no aparece un error de emisor ni de receptor. En el cuadre con la orden, el mismo código puede venir varias veces: una por cada SKU que no coincide.

El número HTTP no se puede partir más: no hay un estado distinto para cada causa. Cada número aparece una sola vez. Dentro van los error que lo comparten.

HTTPerror
400 orden_compra_ausente Falta la orden de compra.
xml_ausente Falta el XML.
pdf_ausente Falta el PDF.
401 token_ausente Falta el token.
token_mal_formado No empieza con gme_pvd_.
token_desconocido El token no existe.
token_revocado El token fue revocado.
409 uuid_xml_distinto Ese UUID ya existe con otro XML.
413 xml_demasiado_grande El XML pasa de 2 MB.
pdf_demasiado_grande El PDF pasa de 10 MB.
parte_demasiado_grande Un archivo del envío pasa el tope.
415 archivo_no_permitido Llegó un ZIP u otro archivo.
422 orden_compra_invalida La orden no tiene la forma pedida.
xml_vacio El XML llegó vacío.
pdf_vacio El PDF llegó vacío.
xml_ilegible El XML no es un CFDI legible.
cuenta_sin_rfc Tu cuenta no tiene RFC configurados.
emisor_ajeno El emisor no es de tu cuenta.
receptor_ajeno El receptor no es de Grupo más.
pdf_uuid_distinto El PDF no es de ese XML.
orden_compra_otro_uuid Esa orden ya está en otra factura.
orden_sin_lineas La orden no tiene líneas.
conflicto_oc_partidas El número de partidas no coincide.
conflicto_oc_sku Un código está solo en la factura o solo en la orden.
conflicto_oc_cantidades La cantidad de un código no coincide.
conflicto_oc_precio El precio de un código no coincide.
timbre_distinto El PDF y el XML no traen el mismo timbre.
ingesta_rechazada No se pudo registrar y no es ninguno de los casos de arriba.
429 rate_limit Más de 60 envíos en un minuto.
502 s3_error No se pudo guardar el archivo.
503 s3_sin_credenciales El servicio no puede guardar en este momento.
pdf_no_encolado Se guardó el archivo y no se encoló el PDF.
oc_no_disponible No se pudo leer la orden. Reintenta. No se guardó la factura.
Un reintento seguro es volver a mandar el mismo XML, el mismo PDF y la orden de compra.

Si la primera llamada se cortó y no viste la respuesta, repite el envío. Si ya había entrado, recibes 200 con el mismo id.

Guía para el integrador del proveedor. Grupo más ecommerce. El token no viaja en este documento.