Saltar a contenido

Integrar tu sistema con la API REST

Si tu sistema (un ERP, un punto de venta, un script) emite CFDI sin un asistente, usa la API REST de Cefidia. Tiene las mismas operaciones que el servidor MCP, con los mismos datos y los mismos errores: JSON sobre HTTPS en https://cefidia.com/v1.

1. Genera un token

En la aplicación, abre Conecta tu asistente y busca Token secreto. Escribe un nombre (por ejemplo, «ERP») y presiona Generar token. El token (cfd_…) se muestra una sola vez: cópialo y guárdalo en un lugar seguro.

  • El mismo token sirve para la API y para un asistente que no puede iniciar sesión.
  • Actúa solo en tu cuenta. Lo revocas desde la misma página y deja de funcionar en la siguiente llamada.
  • El CSD y la FIEL nunca pasan por la API: se suben en la aplicación.

2. Revisa que todo esté listo

curl -s https://cefidia.com/v1/status \
  -H 'Authorization: Bearer cfd_…'

La respuesta dice, por cada razón social, si puede timbrar y qué le falta (con la página para resolverlo).

3. Prepara el CFDI

Envía el CFDI completo como JSON (que refleja el XML de CFDI 4.0 uno a uno, complementos y addenda incluidos) en cfdi, o como XML sin sellar en xml:

curl -s https://cefidia.com/v1/documents \
  -H 'Authorization: Bearer cfd_…' \
  -H 'Content-Type: application/json' \
  -d '{"xml": "<cfdi:Comprobante …>…</cfdi:Comprobante>"}'

Cefidia revisa que sea un CFDI 4.0 y que el emisor (Emisor/@Rfc) sea una de tus razones sociales, y responde con el id del documento y un resumen.

4. Timbra

curl -s -X POST https://cefidia.com/v1/documents/<id>/stamp \
  -H 'Authorization: Bearer cfd_…' \
  -H 'Content-Type: application/json' \
  -d '{"send_to": "receiver"}'

En la API, timbrar y cancelar actúan en la misma llamada: la petición de tu sistema es la confirmación (en el asistente, en cambio, la persona confirma un resumen). La respuesta trae el folio fiscal y los enlaces al XML y al PDF. send_to es opcional: "receiver" envía el CFDI al correo del receptor guardado en tu directorio, o puedes dar una lista de hasta 5 direcciones.

  • Si el PAC rechaza el CFDI, la respuesta es 200 con el documento preparado y su rejection: el código del SAT, su significado y el campo. No se consume ningún timbre.
  • Repetir el timbrado de un documento ya timbrado devuelve el mismo documento; no se cobra otro timbre.
  • Repetir POST /v1/documents crea otro documento preparado: elimina el que no uses.

Timbrar un XML que ya sellaste

Si tu sistema sella sus CFDI con su propio CSD y solo necesitas llegar al PAC, envía el XML completo y sellado a POST /v1/signed-documents (en el asistente, la herramienta stamp_signed_xml):

  • Cefidia no lo revisa ni lo cambia: el XML que recibe es el que envía al PAC.
  • Tu razón social no necesita CSD en Cefidia, pero su RFC debe estar en tu cuenta. Para cancelar después, sí necesitas el CSD.
  • Si el PAC lo rechaza, recibes el motivo y no se guarda nada: corrige, vuelve a sellar y envía de nuevo.
  • El mismo XML (el mismo Sello) enviado otra vez devuelve el documento existente, sin otro timbre.

Todo lo demás

Cada operación del asistente tiene su ruta: razones sociales y logotipos, receptores, ligas de datos y piezas de carta porte, catálogos del SAT, cancelación, lista y detalle de documentos, descarga del SAT e importación de XML, y las de distribuidores. Consulta la referencia interactiva o descarga el documento OpenAPI 3.1 en https://cefidia.com/v1/openapi.json para generar un cliente.

Errores

Un error responde application/problem+json con code (un código estable, el mismo que recibe el asistente), detail (mensaje en español) y, cuando aplica, fields con la ruta y el problema de cada campo.

Estado Ejemplos de code
400 invalid_input, taxpayer_required
401 Token ausente, inválido o revocado
403 forbidden, insufficient_scope
404 not_found, taxpayer_not_found
409 invalid_state, csd_missing, csd_expired, limit_reached (sin timbres), setup_required
429 rate_limited, con Retry-After
502 pac_unavailable

Cada usuario tiene un límite de 120 llamadas por minuto, sumando la API y el asistente.

Revisa lo que enviaste

En la aplicación, Registros lista cada llamada de tu asistente y de tu sistema, y cada intercambio con el PAC, con la petición y la respuesta completas (sin credenciales). Filtra por tipo, herramienta, errores, fechas o conexión; tus llamadas aparecen con el nombre del token. Los registros se guardan 30 días.