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
200con el documento preparado y surejection: 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/documentscrea 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.