# DeCAred · Power Automate · API 1.3

Estado: conector personalizado generado y comprobado localmente. Incluye las 28 operaciones del contrato, conservando los identificadores anteriores. **Pendiente importar, crear una conexión y probar en un entorno Microsoft**: Miguel aún no dispone de la cuenta correspondiente. No es un conector certificado del catálogo de Microsoft. Los ejemplos siguientes son recetas para crear flujos, no paquetes de solución importables.

## Importación

1. Con una cuenta y licencia que permita conectores personalizados, entra en Power Automate → Conectores personalizados → Importar un archivo OpenAPI.
2. Importa `apiDefinition.swagger.json` (Swagger 2.0). En Seguridad comprueba API key, cabecera `Authorization`.
3. Crea la conexión introduciendo **`Bearer dcr_…` completo**, con un espacio. Se pide una sola vez, en un campo secreto. No pongas la clave en acciones ni variables del flujo.
4. Si usas `paconn`, importa también `apiProperties.json`. Usa exactamente el mismo valor completo; no hace falta una política para añadir Bearer.
5. Prueba primero `GetCompany`. Concede solo los permisos del flujo. Las facultades de API 1.3 no se heredan de las claves generales `read`/`write`.

Referencia Microsoft: https://learn.microsoft.com/en-us/connectors/custom-connectors/define-openapi-definition

## Flujo: preparar → aprobación humana → confirmar

1. Disparador manual con ID de documento y campos que se vayan a modificar. Para emitir usa `getDraft`; para las demás acciones `GetDocument`. Conserva la revisión devuelta, sin inventarla ni incrementarla.
2. `prepareOperation`: envía acción, revisión y campos concretos. Ejemplo de mensaje interno:

```json
{"action":"message","revision":7,"body":"Texto que revisará la persona responsable","visibility":"internal"}
```

3. Conserva `data.id`, `data.confirmation_token`, `data.summary` y `data.expires_at` de **esa misma respuesta**. Activa Entradas/Salidas seguras en preparación, variables con token y confirmación. No incluyas el token ni la clave en la aprobación, correos o mensajes.
4. «Iniciar y esperar una aprobación»: muestra acción, documento, resumen exacto, datos, motivo, visibilidad y adjuntos. Asigna a un responsable real. Configura un tiempo de espera de **10 minutos**. Rechazo, cancelación o timeout terminan el flujo sin confirmar.
5. Rama Aprobado: verifica que `utcNow()` sea anterior a `data.expires_at`, consulta `getOperation` y comprueba `status=prepared`. Si caduca o cambia el contenido, prepara y aprueba otra propuesta; no reutilices una aprobación anterior.
6. `confirmOperation`, con el ID guardado y este cuerpo (token como contenido dinámico de la preparación):

```json
{"confirmed":true,"confirmation_token":"TOKEN_DE_LA_PROPUESTA_APROBADA"}
```

7. En Configuración de preparación y confirmación elige **Directiva de reintentos: Ninguna**. Desactiva ejecuciones concurrentes del mismo flujo si comparten el documento; conserva revisión e ID por ejecución. La API vuelve a comprobar permisos y revisión al confirmar.

Nunca conectes preparar directamente a confirmar con un `true` fijo sin una aprobación. La casilla de aprobación de un ejemplo manual no sustituye la identificación y autorización del aprobador en un flujo compartido.

## Campos de las ocho acciones

Todos llevan `action` y la `revision` obtenida al consultar. Son acciones de oficina para DeCA independientes de mercancías; no firman, no emiten cartas ni suplantan al conductor.

| action | Campos adicionales / condición | Permiso explícito |
|---|---|---|
| `issue` | Usa el borrador guardado; no enviar `data` | `documents:issue` |
| `correct` | `reason` (mínimo 5 caracteres), `data` con cambios nativos | `documents:correct` |
| `close` | El conductor ya debe haber comunicado finalización | `documents:close` |
| `annul` | `reason` (mínimo 5 caracteres) | `documents:annul` |
| `resend` | `accept_duplicate:true` solo tras revisar un resultado previo incierto y aceptar el duplicado | `documents:resend` |
| `report_issue` | `body`, `category`, `priority`; `urgent_reason` si es urgente | `issues:report` |
| `resolve_issue` | `issue_id`, `body` de resolución (mínimo 5 caracteres) | `issues:manage` |
| `message` | `body`, `visibility:internal` o `shared`; elegir expresamente | `messages:send` |

Los campos nativos y enumeraciones están en el Swagger y en https://decared.com/api/v1/openapi.json. `shipments` sustituye la lista completa. No mostrar notas internas a personas ajenas a la oficina autorizada.

## Recuperación y seguimiento

- Si se pierde la respuesta de confirmación, consulta **la misma operación**, con la misma conexión. `completed`: recuperar `result`; repetir la confirmación aprobada devuelve el resultado persistido. `executing`/`uncertain`: detener y conciliar manualmente; no volver a preparar el mismo efecto automáticamente.
- `409`: revisar estado/revisión y motivo. `422`: corregir campos y pedir otra aprobación. `403`: revisar alcance y creador activo, sin ampliar permisos automáticamente. `429`: respetar `Retry-After`; 120 peticiones/minuto/clave y 30 preparaciones/minuto/clave. Un timeout de escritura no demuestra que no se ejecutara.
- `getTracking` y sus seis colecciones permiten consultar entregas, interacciones, incidencias, historial, mensajes y adjuntos con `tracking:read`. Usa `page` y `per_page` (máximo 100) hasta `meta.last_page`.
- La descarga privada de adjuntos necesita `attachments:read`. El conector devuelve binario y la API verifica integridad; para custodiarlo fuera, verifica también su cabecera SHA-256.
- El disparador anterior conserva sus seis eventos documentales. No hay nuevos avisos de incidencias/mensajes; consulta el seguimiento periódicamente. No atribuyas validación HMAC al conector de Power Automate: necesita una pasarela que verifique la firma si esa comprobación forma parte de tu flujo.

## Adjuntos al preparar

La operación del conector usa JSON. Para añadir archivos usa una acción HTTP autenticada con multipart: misma ruta `POST /api/v1/documents/{id}/actions`, campos `action`, `revision` y los del caso; archivos con nombre `attachments[]`. Máximo tres JPEG/PNG/PDF, 1 MiB por archivo. No envíes base64 como JSON. La propuesta cifrada conserva los archivos para la confirmación; revisa sus nombres en el resumen. Esta variante multipart **no se ofrece como una acción nativa en este Swagger** y requiere configurar y probar la acción HTTP en Microsoft.

## Comprobaciones antes de uso real

Importación y conexión; borrador sin emitir; preparación sin efectos; rechazo/timeout sin confirmación; aprobación de propuesta exacta; caducidad; revisión obsoleta; recuperación del resultado ya completado; bloqueo de inciertos; paginación y descarga; clave sin permiso y creador inactivo. Usar entorno y destinatarios de prueba, sin firmas ni mensajes reales. Hasta completar estas pruebas en Microsoft no marcar la integración como validada allí.

Regenerar: `python integraciones/power-automate/generar.py`. Pruebas: `python -m unittest discover -s integraciones/power-automate -p "test_*.py"`.