Verificación de integración

GET /v1/companies/{company_id}/sandbox/integration-check dice qué ha hecho tu empresa en el sandbox, calculado a partir de sus datos reales, no de lo que tú o un agente digan. Es de solo lectura: no escribe nada ni gasta cuota. La misma verificación está en la herramienta get_integration_check del MCP y en el panel «Verificación de la integración» del portal, con los mismos resultados.

Solo funciona con una clave de sandbox: con otra responde 403 sandbox_only. Una empresa que no es tuya responde 404, igual que una inexistente.

curl -s -H "Authorization: Bearer $FOLIIOS_API_KEY" \
  "https://api.foliios.com/v1/companies/$FOLIIOS_COMPANY_ID/sandbox/integration-check"

from foliios_inicio import EMPRESA, llamar

estado, resultado, _ = llamar("GET", f"/v1/companies/{EMPRESA}/sandbox/integration-check")
assert estado == 200, resultado
for chequeo in resultado["derived"]:
    print(chequeo["id"], chequeo["status"], chequeo["evidence_expires_at"])
print("completa:", resultado["complete"])

La respuesta

{
  "company_id": "cmp_...",
  "evaluated_at": "2026-11-04T15:00:00Z",
  "complete": false,
  "derived": [
    {"id": "invoice_accepted", "status": "passed",
     "evidence": {"document_id": "...", "number": "SBX1", "at": "2026-11-04T14:50:00Z"},
     "evidence_expires_at": "2026-12-04T14:50:00Z"},
    {"id": "credit_and_debit_note", "status": "pending", "evidence": null, "evidence_expires_at": null},
    {"id": "contingency", "status": "pending", "evidence": null, "evidence_expires_at": null},
    {"id": "webhook_delivered", "status": "not_applicable", "evidence": null, "evidence_expires_at": null}
  ],
  "declared": [
    {"id": "rejection_corrected", "status": "declared"},
    {"id": "idempotency_replayed", "status": "declared"}
  ],
  "window": {"pages": 1, "truncated": false}
}

El contrato exacto está en la API v1.

Los cuatro chequeos derivados

Cada uno es passed (con evidence), pending o not_applicable.

Chequeo	Pasa cuando…	Cómo se hace
`invoice_accepted`	Hay una factura de la empresa aceptada.	Emitir una factura
`credit_and_debit_note`	Hay una nota crédito y una nota débito aceptadas cuya referencia (número y CUFE) es una factura aceptada de la misma empresa. Una referencia a una factura ajena no cuenta.	Notas crédito y débito
`contingency`	Hay un documento de la empresa que pasó por contingencia y terminó aceptado. Conserva la marca de que pasó por ella.	Contingencia, con el escenario `dian_unavailable`
`webhook_delivered`	Si la empresa tiene un endpoint de webhook, hay al menos una entrega `2xx`. Una redirección `3xx` no cuenta. Sin endpoint, es `not_applicable` y no bloquea.	Webhooks

complete es true si y solo si todos los chequeos aplicables están passed.

Los dos declarados

rejection_corrected (un rechazo corregido y reenviado) e idempotency_replayed (una Idempotency-Key repetida sin duplicar) no se pueden verificar: foliios no conserva el rastro. Vienen siempre como declared, el portal los muestra aparte y nunca cuentan en complete. Pruébalos tú (rechazos y reenvío, idempotencia) e infórmalos como no verificados.

La evidencia caduca

Una comprobación vale 30 días desde que ocurrió (evidence_expires_at). Con exactamente 30 días ya es pending.
Un reinicio del sandbox la borra: las comprobaciones vuelven a pending.
Si caduca, no es que tu integración se rompió: repite la tarea correspondiente.

Ventana de lectura

La consulta lee como máximo 5 páginas de 100 documentos aceptados, y se detiene en cuanto todo pasa. Si tu historial es largo y la evidencia está más atrás, una comprobación puede salir pending aunque la hayas hecho: window.truncated es true. En ese caso emite un documento nuevo para la tarea faltante.

Cuándo terminaste

La integración está terminada cuando complete es true. No antes, aunque tu programa parezca funcionar. Después, pasa a la habilitación. Si un agente de código integra el proyecto, este es el criterio con el que termina: ver el manual del agente.