marcos
a1ed6e518d
Las pruebas del cliente verifican que el CRM se comporta bien contra el EFC que el cliente CREE que existe. Si EFC renombra una ruta o una clave del payload, esas pruebas siguen verdes y el carril se rompe en produccion: los dos repos se despliegan por separado y nada obliga a que sus mitades evolucionen juntas. Se agrega el contrato como dato -tests/contracts/efc_crm_contract.json- y su afirmacion del lado CRM: que cada operacion del cliente pegue en la ruta declarada, que el alta de expediente mande exactamente las claves acordadas -ni una de mas, que el serializer de EFC ignoraria en silencio, ni una de menos-, que la subida vaya en multipart con sus campos, que toda peticion lleve el header de autenticacion, que el code que dispara el ensure-then-upload siga siendo el mismo, y que las rutas del API de usuario registradas sean exactamente las del contrato en las dos direcciones. Fija tambien dos invariantes que ya costaron decisiones: que la respuesta de un documento nunca exponga la copia local -se borra al confirmar la entrega, asi que seria una referencia que va a dejar de existir- y que el cliente NO tenga metodo de borrado hacia EFC, para que nadie lo llame "porque estaba ahi". EFC debe afirmar su mitad contra una copia identica de este JSON cuando aterricen sus fases 1-4; mientras tanto, el lado del CRM ya no puede derivar en silencio. Refs: T2026-08-046 (verificacion 15.2)
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."
|
|
}
|
|
}
|
|
}
|