marcos
5c4df590d4
Rebase del lado emisor de T2026-08-046 sobre esta rama. La entrega anterior partia
de feature/crm-cumplimiento-pdf (16-jul), 40 commits atras, y por eso construyo un
expediente PARALELO -- crm.expedientes con su propio generador de folio y su propia
migracion -- que duplicaba el que ya existe aqui. Dos expedientes y dos secuencias
peleando por el mismo namespace EXP no se fusionan; se tira el nuestro.
La estructura del expediente es de esta rama y no se toca: crm.cases es el
expediente, su folio vive en `reference` y el consecutivo lo reserva
crm/common/folios.py con bloqueo de fila. Nuestro aporte es SOLO la conexion:
- crm.cases gana seis columnas efc_* (espejo de EFC, nunca el handle) y nada mas;
- crm.efc_sync_outbox y crm.efc_file_outbox, el outbox transaccional, con
expediente_ref -> crm.cases.id;
- core/efc_client.py y crm/expediente_gateway/ (outbox, reintentos, barridos),
clonados del gateway Anexo22 -> EFC que ya corre en produccion;
- las ocho variables EFC_* en config. EFC_API_URL vacia = carril apagado.
Verificado contra la base real: next_folio(...,'EXP',None,with_direction=False)
devuelve EXP2026-08-001, identico al formato que el contrato con EFC exige, y
storage_token da CRM-{company}-{folio} de 22 caracteres sobre los 25 de
pedimento_app.
Se corrige un error del docstring de storage_token: decia que cabian companies de
7 digitos y son 6 (4+7+1+14 = 26 > 25). Ahora valida y falla ruidosamente en vez de
entregar un token recortado, que apuntaria a la carpeta de otro expediente y
mezclaria documentos en silencio.
El revision id de la migracion tirada (e6f7a8b9c0d1) chocaba con crm_catalog_items
de esta rama: dos migraciones distintas con el mismo id habrian roto alembic al
fusionar. La nueva es c5d6e7f8a9b0, aditiva sobre d4e5f6a7b8c9.
PENDIENTE: falta el pegamento que invocaba el carril desde los flujos de la app
(alta del provisional al mintear el folio, subida de documento -> outbox, rutas en
el router y UI). Por eso test_efc_outbox, test_gateway_rutas y tres casos de
test_contrato_efc todavia no colectan. El carril no esta cableado al router, asi
que la app funciona igual: backend y frontend responden 200.
Ref: T2026-08-046
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
183 lines
7.5 KiB
JSON
183 lines
7.5 KiB
JSON
{
|
|
"_meta": {
|
|
"nombre": "Contrato del carril CRM Agentes de Carga <-> EFC",
|
|
"ticket": "T2026-08-046",
|
|
"version": 1,
|
|
"por_que_existe": "CRM y EFC son dos repos con despliegue independiente. Nada obliga a que sus dos mitades del carril evolucionen juntas, y una ruta renombrada o una clave de payload que cambia solo se descubre en produccion, cuando un documento deja de llegar al expediente. Este archivo es la unica forma de que un cambio unilateral salga rojo en CI.",
|
|
"como_se_usa": "Cada repo afirma su lado contra ESTE archivo. El CRM en backend/tests/test_contrato_efc.py. EFC debe afirmar el suyo cuando aterricen sus fases 1-4, contra una copia identica byte a byte de este JSON; si las dos copias divergen, el contrato deja de servir para lo unico que sirve.",
|
|
"regla": "Cambiar algo aqui es cambiar el contrato: obliga a un PR en los DOS repos."
|
|
},
|
|
|
|
"carril_efc": {
|
|
"_nota": "Endpoints maquina-a-maquina que EXPONE EFC y CONSUME el CRM. Header obligatorio en todas: X-Api-Key.",
|
|
"header_autenticacion": "X-Api-Key",
|
|
"endpoints": {
|
|
"organizaciones_buscar": {
|
|
"metodo": "GET",
|
|
"path": "/api/v1/organization/integrations/crm/organizaciones/"
|
|
},
|
|
"organizaciones_resolver": {
|
|
"metodo": "POST",
|
|
"path": "/api/v1/organization/integrations/crm/organizaciones/resolver/",
|
|
"request_claves": ["tenant_slug", "tenant_name"],
|
|
"response_claves": ["id", "nombre", "rfc", "hub_tenant_slug", "is_active", "created"]
|
|
},
|
|
"expediente_crear": {
|
|
"metodo": "POST",
|
|
"path": "/api/v1/customs/integrations/crm/expedientes/",
|
|
"request_claves": [
|
|
"crm_tenant_slug",
|
|
"crm_company_id",
|
|
"crm_expediente_id",
|
|
"folio",
|
|
"storage_token"
|
|
],
|
|
"status_exito": [200, 201],
|
|
"_nota_status": "201 si el provisional es nuevo, 200 si ya existia. Las dos son exito: el carril es idempotente."
|
|
},
|
|
"expediente_completar": {
|
|
"metodo": "POST",
|
|
"path": "/api/v1/customs/integrations/crm/expedientes/{folio}/completar/"
|
|
},
|
|
"expediente_detalle": {
|
|
"metodo": "GET",
|
|
"path": "/api/v1/customs/integrations/crm/expedientes/{folio}/"
|
|
},
|
|
"documento_subir": {
|
|
"metodo": "POST",
|
|
"path": "/api/v1/record/integrations/crm/documentos/",
|
|
"content_type": "multipart/form-data",
|
|
"_nota_content_type": "Multipart, nunca base64: EFC declara parser_classes = [MultiPartParser].",
|
|
"form_claves": [
|
|
"organizacion_id",
|
|
"crm_company_id",
|
|
"crm_expediente_id",
|
|
"tipo",
|
|
"crm_document_ref"
|
|
],
|
|
"archivo_campo": "file",
|
|
"status_exito": [200, 201]
|
|
},
|
|
"documentos_listar": {
|
|
"metodo": "GET",
|
|
"path": "/api/v1/record/integrations/crm/documentos/list/"
|
|
},
|
|
"documento_descargar": {
|
|
"metodo": "GET",
|
|
"path": "/api/v1/record/integrations/crm/documentos/{doc_id}/descargar/"
|
|
},
|
|
"documento_eliminar": {
|
|
"metodo": "DELETE",
|
|
"path": "/api/v1/record/integrations/crm/documentos/{doc_id}/eliminar/"
|
|
},
|
|
"documento_reemplazar": {
|
|
"metodo": "PUT",
|
|
"path": "/api/v1/record/integrations/crm/documentos/{doc_id}/reemplazar/"
|
|
}
|
|
},
|
|
|
|
"formato_error": {
|
|
"forma": {"error": {"code": "<string>", "message": "<string>"}},
|
|
"_nota": "El worker del CRM ramifica por error.code, NUNCA por el texto del mensaje: un mensaje cambia con cualquier refactor del otro repo y con el se caeria la politica de reintentos sin que nada se vea roto."
|
|
},
|
|
|
|
"codigos_error": {
|
|
"400": [
|
|
"payload_invalido",
|
|
"pedimento_app_reservado",
|
|
"storage_token_invalido",
|
|
"efc_pedimento_app_incompleto",
|
|
"tipo_invalido",
|
|
"archivo_faltante",
|
|
"extension_no_permitida",
|
|
"archivo_demasiado_grande",
|
|
"espacio_insuficiente"
|
|
],
|
|
"403": ["documento_no_eliminable"],
|
|
"404": ["expediente_no_encontrado", "documento_no_encontrado"],
|
|
"409": [
|
|
"organizacion_no_utilizable",
|
|
"licencia_sin_espacio",
|
|
"expediente_ya_completado",
|
|
"pedimento_real_ya_existe",
|
|
"conflicto"
|
|
],
|
|
"502": ["error_storage"]
|
|
},
|
|
|
|
"codigos_con_significado_para_el_crm": {
|
|
"expediente_no_encontrado": {
|
|
"http": 404,
|
|
"efecto": "dispara el ensure-then-upload: el CRM crea el provisional y reintenta la subida UNA vez",
|
|
"_nota": "Si EFC renombra este code, el CRM deja de recuperarse solo y los documentos se quedan pendientes para siempre sin que nada falle a gritos. Es el code mas fragil del carril."
|
|
}
|
|
},
|
|
|
|
"reintentos": {
|
|
"reintentables": ["5xx", "timeout", "error_de_red"],
|
|
"no_reintentables": ["4xx"],
|
|
"_nota": "Un 4xx reintentado tres veces es tres veces el mismo error mas latencia. El corte esta en 500, no en 400."
|
|
}
|
|
},
|
|
|
|
"api_crm": {
|
|
"_nota": "Endpoints de usuario que expone el CRM. Todos con company_id obligatorio en query y usuario autenticado.",
|
|
"query_obligatorio": "company_id",
|
|
"endpoints": [
|
|
{"metodo": "GET", "path": "/expedientes"},
|
|
{"metodo": "GET", "path": "/expedientes/{expediente_id}"},
|
|
{"metodo": "POST", "path": "/expedientes/ensure"},
|
|
{"metodo": "POST", "path": "/expedientes/{expediente_id}/completar"},
|
|
{"metodo": "DELETE", "path": "/expedientes/{expediente_id}"},
|
|
{"metodo": "GET", "path": "/expedientes/{expediente_id}/documentos"},
|
|
{"metodo": "POST", "path": "/expedientes/{expediente_id}/documentos"},
|
|
{"metodo": "GET", "path": "/expedientes/{expediente_id}/documentos/{document_id}/archivo"},
|
|
{"metodo": "DELETE", "path": "/expedientes/{expediente_id}/documentos/{document_id}"},
|
|
{"metodo": "GET", "path": "/expediente-gateway/outbox"},
|
|
{"metodo": "POST", "path": "/expediente-gateway/outbox/{outbox_id}/retry"},
|
|
{"metodo": "GET", "path": "/expediente-gateway/metrics"}
|
|
],
|
|
|
|
"documento_response_prohibido": ["file_key", "file_url"],
|
|
"_nota_prohibido": "La copia local es de transito y se borra al confirmar la entrega a EFC. Exponerla invitaria al frontend a guardarse una referencia que va a dejar de existir; para abrir el archivo esta el proxy de descarga.",
|
|
|
|
"documento_response_claves_minimas": [
|
|
"expediente_id",
|
|
"doc_type",
|
|
"name",
|
|
"content_type",
|
|
"size_bytes",
|
|
"efc_sync_state",
|
|
"efc_document_ref"
|
|
],
|
|
|
|
"estados_sincronizacion": ["PENDING", "SYNCED", "FAILED"],
|
|
|
|
"descarga_documento": {
|
|
"tipo_respuesta": "streaming",
|
|
"traduccion_errores": {
|
|
"404_de_efc": 404,
|
|
"cualquier_otro_fallo_de_efc": 502,
|
|
"documento_de_otro_tenant": 404,
|
|
"documento_aun_no_entregado": 409
|
|
},
|
|
"_nota": "La asimetria es deliberada: un 404 de EFC significa que el documento realmente no esta; cualquier otro fallo es de la integracion, no del usuario. Y la traduccion tiene que ocurrir ANTES de que la respuesta empiece a salir, o llega tarde."
|
|
},
|
|
|
|
"reintento_outbox": {
|
|
"exito": {"status": "requeued", "id": "<int>"},
|
|
"fila_inexistente_o_de_otro_tenant": 404,
|
|
"_nota": "404 y no un 200 silencioso: es contrato con el frontend, que distingue 'no se pudo reencolar' de 'reencolado'."
|
|
},
|
|
|
|
"metricas_outbox_claves": ["pending", "sent", "failed"],
|
|
|
|
"folio": {
|
|
"formato": "EXP{YYYY}-{MM}-{NNN}",
|
|
"alcance_consecutivo": ["tenant", "company", "mes"],
|
|
"reinicia": "cada mes",
|
|
"_nota": "Al pasar de 999 crece a 4 digitos en vez de desbordar."
|
|
}
|
|
}
|
|
}
|